[seam-commits] Seam SVN: r8500 - in trunk: examples/wicket/resources/WEB-INF and 5 other directories.

seam-commits at lists.jboss.org seam-commits at lists.jboss.org
Sun Jul 27 14:54:49 EDT 2008


Author: pete.muir at jboss.org
Date: 2008-07-27 14:54:48 -0400 (Sun, 27 Jul 2008)
New Revision: 8500

Added:
   trunk/doc/Seam_Reference_Guide/en-US/Wicket.xml
   trunk/src/main/org/jboss/seam/wicket-2.1.xsd
   trunk/src/wicket/org/jboss/seam/wicket/WebApplication.java
   trunk/src/wicket/org/jboss/seam/wicket/package-info.java
Modified:
   trunk/doc/Seam_Reference_Guide/en-US/master.xml
   trunk/examples/wicket/resources/WEB-INF/components.xml
   trunk/examples/wicket/src/web/org/jboss/seam/example/wicket/Book.java
   trunk/examples/wicket/src/web/org/jboss/seam/example/wicket/WicketBookingApplication.java
   trunk/src/main/org/jboss/seam/web/WicketFilter.java
   trunk/src/wicket/org/jboss/seam/wicket/SeamWebApplication.java
   trunk/src/wicket/org/jboss/seam/wicket/web/WicketFilterInstantiator.java
Log:
Initial pass at Wicket documentation

Added: trunk/doc/Seam_Reference_Guide/en-US/Wicket.xml
===================================================================
--- trunk/doc/Seam_Reference_Guide/en-US/Wicket.xml	                        (rev 0)
+++ trunk/doc/Seam_Reference_Guide/en-US/Wicket.xml	2008-07-27 18:54:48 UTC (rev 8500)
@@ -0,0 +1,265 @@
+<?xml version="1.0" standalone="no"?>
+<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.3//EN" "http://www.oasis-open.org/docbook/xml/4.3/docbookx.dtd" [
+]>
+
+<chapter id="wicket">
+   <title>Writing your presentation layer using Apache Wicket</title>
+
+   <para>
+      Seam supports Wicket as an alternative presentation layer to JSF. Take a 
+      look at the <code>wicket</code> example in Seam which shows the Booking
+      Example ported to Wicket.
+   </para>
+
+   <note>
+      <para>
+         Wicket support is new to Seam, so some features which are
+         available in JSF are not yet available when you use Wicket
+         (e.g. pageflow). You'll also notice that the documentation is
+         very JSF-centric and needs reorganization to reflect the first
+         class support for Wicket.
+      </para>
+   </note>
+   
+   <section>
+      <title>Adding Seam to your wicket application</title>
+      
+      <para>
+          The features added to your Wicket application can be split into two 
+          categories: bijection and orchestration; these are discussed in detail
+          below.
+      </para>
+      
+      <para>
+         Extensive use of inner classes is common when building Wicket 
+         applications, with the component tree being built in the constructor.
+         Seam fully supports the use of annotation based control in inner 
+         classes and constructors (unlike regular Seam components).
+      </para>
+      
+      <para>
+         Annotations are processed <emphasis>after</emphasis> any call to
+         a superclass. This mean's that any injected attributes cannot be
+         passed as an argument in a call to <code>this()</code> or 
+         <code>super()</code>.
+      </para>
+      
+      <note>
+         <para>
+            We are working to improve this.
+         </para>
+      </note>
+      
+      <para>
+         When a method is called in an inner class, bijection occurs for any
+         class which encloses it. This allows you to place your bijected
+         variables in the outer class, and refer to them in any inner class.
+      </para>
+      
+      <section>
+         <title>Bijection</title>
+         
+         <para>
+            A Seam enabled Wicket application has full access to the all the 
+            standard Seam contexts (<code>EVENT</code>, <code>CONVERSATION</code>,
+            <code>SESSION</code>, <code>APPLICATION</code> and
+            <code>BUSINESS_PROCESS</code>).
+         </para>
+         
+         <para>
+            To access Seam component's from Wicket, you just need to inject it
+            using <code>@In</code>:
+         </para>
+         
+         <programlisting role="JAVA"><![CDATA[@In(create=true)
+private HotelBooking hotelBooking;]]></programlisting>
+
+         <tip>
+            <para>
+               As your Wicket class isn't a full Seam component, there is no
+               need to annotate it <code>@Name</code>.
+            </para>
+         </tip>
+         
+         <para>
+            You can also outject an object into the Seam contexts from a Wicket
+            component:
+         </para>
+         
+         <programlisting role="JAVA"><![CDATA[@Out(scope=ScopeType.EVENT, required=false)
+private String verify;]]></programlisting>
+
+         <para>
+            TODO Make this more use case driven
+         </para>
+      
+      </section>
+      
+      <section>
+         <title>Orchestration</title>
+         
+         <para>
+            You can secure a Wicket component by using the 
+            <code>@Restrict</code> annotation. This can be placed on the outer
+            component or any inner components. If <code>@Restrict</code> is
+            specified, the component will automatically be restricted to logged
+            in users. You can optionally use an EL expression in the 
+            <code>value</code> attribute to specify a restriction to be applied.
+            For more refer to the <xref linkend="security"/>.
+         </para>
+         
+         <para>
+            For example:
+         </para>
+         
+         <programlisting><![CDATA[@Restrict
+public class Main extends WebPage {
+
+   ...]]></programlisting>
+         
+         <tip>
+            <para>
+               Seam will automatically apply the restriction to any nested
+               classes.
+            </para>
+            <para>
+               TODO - Implement this (See JBSEAM-3192) 
+            </para>
+         </tip>
+         
+         <para>
+            You can demarcate conversations from within a Wicket component
+            through the use of <code>@Begin</code> and <code>@End</code>. The
+            semantics for these annotations are the same as when used in a Seam
+            component. You can place <code>@Begin</code> and <code>@End</code>
+            on any method.
+         </para>
+         
+         <note>
+            <para>
+               The deprecated <code>ifOutcome</code> attribute is not supported.
+            </para>
+         </note>
+         
+         <para>
+            For example:
+         </para>
+         
+         <programlisting><![CDATA[item.add(new Link("viewHotel") {
+
+   @Override
+   @Begin
+   public void onClick() {
+      hotelBooking.selectHotel(hotel);
+      setResponsePage(org.jboss.seam.example.wicket.Hotel.class);
+   }
+};]]></programlisting>
+
+         <para>
+            If you want to further decouple your application classes, you can 
+            use Seam events. Of course, you can raise an event using
+            <code>Events.instance().raiseEvent("foo")</code>. Alternatively, you
+            can annotate a method <code>@RaiseEvent("foo")</code>; if the method
+            returns a non-null outcome without exception, the event will be
+            raised.
+         </para>
+         
+         <para>
+            You can also control tasks and processes in Wicket classes through
+            the use of <code>@CreateProcess</code>, <code>@ResumeTask</code>,
+            <code>@BeginTask</code>, <code>@EndTask</code>, 
+            <code>@StartTask</code> and <code>@Transition</code>.
+         </para>   
+         
+         <para>
+            TODO - Implement BPM control - JBSEAM-3194
+         </para>
+      </section>
+      
+   </section>
+
+   <section>
+      <title>Setting up your project</title>
+      
+      <para>
+         To enable bijection and orchestration control via annotations in Wicket
+         you must place your classes in <code>WEB-INF/wicket</code>. Seam needs
+         to instrument the bytecode of your Wicket classes to be able to
+         intercept the annotations you use. 
+      </para>
+      
+      <note>
+         <para>
+            Currently only bytecode instrumentation using a custom classloader
+            which reads classes in <code>WEB-INF/wicket</code> is supported. In the 
+            an Ant task or Maven plugin may be developed to support bytecode
+            instrumentation when the project artifacts are built. 
+         </para>
+      </note>
+      
+      <section>
+         <title>Defining the Application</title>
+      
+         <para>
+            A Wicket web application which uses Seam should use 
+            <code>SeamWebApplication</code> as the base class; this creates hooks
+            into the Wicket lifecycle allowing Seam to automagically propagate the
+            conversation as needed. It also adds status messages to the page.
+         </para>
+         
+         <para>
+            For example:
+         </para>
+         
+         <para>
+            The <code>SeamAuthorizationStrategy</code> delegates authorization
+            to Seam Security, allowing the use of <code>@Restrict</code> on Wicket
+            components. <code>SeamWebApplication</code> installs the authorization
+            strategy for you. You can specify the login page by implementing the
+            <code>getLoginPage()</code> method. 
+         </para>
+         
+         <para>
+            You'll also need to set the home page of the application by 
+            implementing the <code>getHomePage()</code> method.
+         </para>
+         
+         <programlisting role="JAVA"><![CDATA[public class WicketBookingApplication extends SeamWebApplication {
+
+   @Override
+   public Class getHomePage() {
+      return Home.class;
+   }
+
+   @Override
+   protected Class getLoginPage() {
+      return Home.class;
+   }
+   
+}
+]]></programlisting>
+         
+         <para>
+            Seam automatically installs the Wicket filter for you (ensuring that
+            it is inserted in the correct place for you). But you still need to 
+            tell Wicket which <code>WebApplication</code> class to use:
+         </para>
+         
+         <programlisting role="XML"><![CDATA[<components xmlns="http://jboss.com/products/seam/components"
+            xmlns:wicket="http://jboss.com/products/seam/wicket"
+         
+         <wicket:web-application application-class="org.jboss.seam.example.wicket.WicketBookingApplication" />
+</components]]></programlisting>
+         
+         <tip>
+            <para>
+               Take a look at the Wicket documentation for more on authorization
+               strategies and other methods you can override on the
+               <code>Application</code> class.
+            </para>
+         </tip>
+      </section>
+
+   </section>
+
+</chapter>


Property changes on: trunk/doc/Seam_Reference_Guide/en-US/Wicket.xml
___________________________________________________________________
Name: svn:executable
   + *
Name: svn:mime-type
   + text/plain

Modified: trunk/doc/Seam_Reference_Guide/en-US/master.xml
===================================================================
--- trunk/doc/Seam_Reference_Guide/en-US/master.xml	2008-07-27 12:43:35 UTC (rev 8499)
+++ trunk/doc/Seam_Reference_Guide/en-US/master.xml	2008-07-27 18:54:48 UTC (rev 8500)
@@ -15,6 +15,7 @@
     <xi:include href= "Persistence.xml" xmlns:xi="http://www.w3.org/2001/XInclude" />
     <xi:include href= "Validation.xml" xmlns:xi="http://www.w3.org/2001/XInclude" />
     <xi:include href= "Groovy.xml" xmlns:xi="http://www.w3.org/2001/XInclude" />
+    <xi:include href= "Wicket.xml" xmlns:xi="http://www.w3.org/2001/XInclude" />
     <xi:include href= "Framework.xml" xmlns:xi="http://www.w3.org/2001/XInclude" />
     <xi:include href= "Drools.xml" xmlns:xi="http://www.w3.org/2001/XInclude" />
     <xi:include href= "Security.xml" xmlns:xi="http://www.w3.org/2001/XInclude" />

Modified: trunk/examples/wicket/resources/WEB-INF/components.xml
===================================================================
--- trunk/examples/wicket/resources/WEB-INF/components.xml	2008-07-27 12:43:35 UTC (rev 8499)
+++ trunk/examples/wicket/resources/WEB-INF/components.xml	2008-07-27 18:54:48 UTC (rev 8500)
@@ -4,11 +4,13 @@
             xmlns:security="http://jboss.com/products/seam/security"
             xmlns:transaction="http://jboss.com/products/seam/transaction"
             xmlns:web="http://jboss.com/products/seam/web"
+            xmlns:wicket="http://jboss.com/products/seam/wicket"
             xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
             xsi:schemaLocation=
                 "http://jboss.com/products/seam/core http://jboss.com/products/seam/core-2.1.xsd
                  http://jboss.com/products/seam/transaction http://jboss.com/products/seam/transaction-2.1.xsd
                  http://jboss.com/products/seam/web http://jboss.com/products/seam/web-2.1.xsd
+                 http://jboss.com/products/seam/wicket http://jboss.com/products/seam/wicket-2.1.xsd
                  http://jboss.com/products/seam/security http://jboss.com/products/seam/security-2.1.xsd
                  http://jboss.com/products/seam/components http://jboss.com/products/seam/components-2.1.xsd">
 
@@ -22,7 +24,6 @@
 
     <security:identity authenticate-method="#{authenticator.authenticate}"/>
     
-    <!-- TODO Move this onto a wicekt namespace -->
-    <web:wicket-filter application-class="org.jboss.seam.example.wicket.WicketBookingApplication" />
+    <wicket:web-application application-class="org.jboss.seam.example.wicket.WicketBookingApplication" />
 
 </components>

Modified: trunk/examples/wicket/src/web/org/jboss/seam/example/wicket/Book.java
===================================================================
--- trunk/examples/wicket/src/web/org/jboss/seam/example/wicket/Book.java	2008-07-27 12:43:35 UTC (rev 8499)
+++ trunk/examples/wicket/src/web/org/jboss/seam/example/wicket/Book.java	2008-07-27 18:54:48 UTC (rev 8500)
@@ -1,19 +1,3 @@
-/*
- * Licensed to the Apache Software Foundation (ASF) under one or more
- * contributor license agreements.  See the NOTICE file distributed with
- * this work for additional information regarding copyright ownership.
- * The ASF licenses this file to You under the Apache License, Version 2.0
- * (the "License"); you may not use this file except in compliance with
- * the License.  You may obtain a copy of the License at
- *
- *      http://www.apache.org/licenses/LICENSE-2.0
- *
- * Unless required by applicable law or agreed to in writing, software
- * distributed under the License is distributed on an "AS IS" BASIS,
- * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
- * See the License for the specific language governing permissions and
- * limitations under the License.
- */
 package org.jboss.seam.example.wicket;
 
 import java.util.Arrays;

Modified: trunk/examples/wicket/src/web/org/jboss/seam/example/wicket/WicketBookingApplication.java
===================================================================
--- trunk/examples/wicket/src/web/org/jboss/seam/example/wicket/WicketBookingApplication.java	2008-07-27 12:43:35 UTC (rev 8499)
+++ trunk/examples/wicket/src/web/org/jboss/seam/example/wicket/WicketBookingApplication.java	2008-07-27 18:54:48 UTC (rev 8500)
@@ -7,7 +7,8 @@
 /**
  * Port of Booking Application to Wicket
  */
-public class WicketBookingApplication extends SeamWebApplication {
+public class WicketBookingApplication extends SeamWebApplication 
+{
 
 	@Override
 	public Class getHomePage() 

Modified: trunk/src/main/org/jboss/seam/web/WicketFilter.java
===================================================================
--- trunk/src/main/org/jboss/seam/web/WicketFilter.java	2008-07-27 12:43:35 UTC (rev 8499)
+++ trunk/src/main/org/jboss/seam/web/WicketFilter.java	2008-07-27 18:54:48 UTC (rev 8500)
@@ -75,10 +75,6 @@
          {
             parameters.put( "applicationClassName", getApplicationClass() );
          }
-         else
-         {
-            throw new IllegalStateException("Must set application-class in <web:wicket-filter /> in components.xml");
-         }
          if ( getUrlPattern() != null )
          {
             parameters.put("filterMappingUrlPattern", getUrlPattern());

Added: trunk/src/main/org/jboss/seam/wicket-2.1.xsd
===================================================================
--- trunk/src/main/org/jboss/seam/wicket-2.1.xsd	                        (rev 0)
+++ trunk/src/main/org/jboss/seam/wicket-2.1.xsd	2008-07-27 18:54:48 UTC (rev 8500)
@@ -0,0 +1,23 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<xs:schema xmlns:xs="http://www.w3.org/2001/XMLSchema" elementFormDefault="qualified"
+    targetNamespace="http://jboss.com/products/seam/wicket"
+    xmlns:wicket="http://jboss.com/products/seam/wicket"
+    xmlns:components="http://jboss.com/products/seam/components" attributeFormDefault="unqualified">
+    
+    <xs:import namespace="http://jboss.com/products/seam/components" schemaLocation="components-2.1.xsd"/>
+    
+    <xs:element name="web-application">
+        <xs:annotation>
+            <xs:documentation></xs:documentation>
+        </xs:annotation>
+        <xs:complexType>
+            <xs:attributeGroup ref="components:attlist.component" />
+            <xs:attributeGroup ref="wicket:attlist.webApplication" />
+        </xs:complexType>
+    </xs:element>
+   
+    <xs:attributeGroup name="attlist.webApplication">
+        <xs:attribute name="application-class" type="components:string" />
+    </xs:attributeGroup>
+
+</xs:schema>


Property changes on: trunk/src/main/org/jboss/seam/wicket-2.1.xsd
___________________________________________________________________
Name: svn:mime-type
   + text/plain

Modified: trunk/src/wicket/org/jboss/seam/wicket/SeamWebApplication.java
===================================================================
--- trunk/src/wicket/org/jboss/seam/wicket/SeamWebApplication.java	2008-07-27 12:43:35 UTC (rev 8499)
+++ trunk/src/wicket/org/jboss/seam/wicket/SeamWebApplication.java	2008-07-27 18:54:48 UTC (rev 8500)
@@ -23,8 +23,6 @@
 /**
  * The base class for Seam Web Applications
  * 
- * TODO Remove the need to extend this
- * 
  * @author Pete Muir
  *
  */

Added: trunk/src/wicket/org/jboss/seam/wicket/WebApplication.java
===================================================================
--- trunk/src/wicket/org/jboss/seam/wicket/WebApplication.java	                        (rev 0)
+++ trunk/src/wicket/org/jboss/seam/wicket/WebApplication.java	2008-07-27 18:54:48 UTC (rev 8500)
@@ -0,0 +1,43 @@
+package org.jboss.seam.wicket;
+
+import static org.jboss.seam.ScopeType.APPLICATION;
+
+import org.jboss.seam.Component;
+import org.jboss.seam.annotations.Install;
+import org.jboss.seam.annotations.Name;
+import org.jboss.seam.annotations.Scope;
+import org.jboss.seam.annotations.intercept.BypassInterceptors;
+import org.jboss.seam.contexts.Contexts;
+
+ at Name("org.jboss.seam.wicket.WebApplication")
+ at Scope(APPLICATION)
+ at Install(precedence=21, classDependencies="org.apache.wicket.Application")
+ at BypassInterceptors
+public class WebApplication
+{
+   
+   private String applicationClass;
+   
+   public String getApplicationClass()
+   {
+      return applicationClass;
+   }
+   
+   public void setApplicationClass(String applicationClass)
+   {
+      this.applicationClass = applicationClass;
+   }
+   
+   public static WebApplication instance()
+   {
+      if (Contexts.isApplicationContextActive())
+      {
+         return (WebApplication) Component.getInstance(WebApplication.class);
+      }
+      else
+      {
+         throw new IllegalStateException("Application context is not active");
+      }
+   }
+
+}


Property changes on: trunk/src/wicket/org/jboss/seam/wicket/WebApplication.java
___________________________________________________________________
Name: svn:mime-type
   + text/plain

Added: trunk/src/wicket/org/jboss/seam/wicket/package-info.java
===================================================================
--- trunk/src/wicket/org/jboss/seam/wicket/package-info.java	                        (rev 0)
+++ trunk/src/wicket/org/jboss/seam/wicket/package-info.java	2008-07-27 18:54:48 UTC (rev 8500)
@@ -0,0 +1,9 @@
+/**
+ * A set of classes and Seam component for supporting Wicket
+ */
+ at Namespace(value="http://jboss.com/products/seam/wicket", prefix="org.jboss.seam.wicket")
+ at AutoCreate
+package org.jboss.seam.wicket;
+
+import org.jboss.seam.annotations.AutoCreate;
+import org.jboss.seam.annotations.Namespace;


Property changes on: trunk/src/wicket/org/jboss/seam/wicket/package-info.java
___________________________________________________________________
Name: svn:mime-type
   + text/plain

Modified: trunk/src/wicket/org/jboss/seam/wicket/web/WicketFilterInstantiator.java
===================================================================
--- trunk/src/wicket/org/jboss/seam/wicket/web/WicketFilterInstantiator.java	2008-07-27 12:43:35 UTC (rev 8499)
+++ trunk/src/wicket/org/jboss/seam/wicket/web/WicketFilterInstantiator.java	2008-07-27 18:54:48 UTC (rev 8500)
@@ -4,6 +4,10 @@
 package org.jboss.seam.wicket.web;
 
 import static org.jboss.seam.annotations.Install.BUILT_IN;
+
+import java.util.HashMap;
+import java.util.Map;
+
 import javassist.CannotCompileException;
 import javassist.NotFoundException;
 
@@ -18,6 +22,10 @@
 import org.jboss.seam.annotations.Scope;
 import org.jboss.seam.annotations.Unwrap;
 import org.jboss.seam.annotations.intercept.BypassInterceptors;
+import org.jboss.seam.util.Reflections;
+import org.jboss.seam.web.FilterConfigWrapper;
+import org.jboss.seam.wicket.WebApplication;
+import org.jboss.seam.wicket.SeamWebApplication;
 import org.jboss.seam.wicket.ioc.JavassistInstrumentor;
 
 @Name("org.jboss.seam.wicket.web.wicketFilterInstantiator")
@@ -36,8 +44,9 @@
          private ClassLoader classLoader;
          
          @Override
-         public void init(final FilterConfig filterConfig) throws ServletException
+         public void init(FilterConfig filterConfig) throws ServletException
          {
+            Map<String, String> parameters = new HashMap<String, String>();
             try
             {
                JavassistInstrumentor javassistInstrumentor = new JavassistInstrumentor(filterConfig.getServletContext());
@@ -55,8 +64,20 @@
             catch (ClassNotFoundException e)
             {
                throw new ServletException(e);
-            }     
-            super.init(filterConfig);
+            }
+            if (filterConfig.getInitParameter("applicationClassName") == null)
+            {
+               String applicationClass = WebApplication.instance().getApplicationClass();
+               if (applicationClass != null)
+               {
+                  parameters.put("applicationClassName", applicationClass); 
+               }
+               else
+               {
+                  throw new IllegalStateException("Must set application-class using <wicket:web-application /> in components.xml");
+               }
+            }
+            super.init(new FilterConfigWrapper(filterConfig, parameters));
          }
          
          @Override




More information about the seam-commits mailing list