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

Author: pete.muir(a)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=&quot;JAVA&quot;&gt;&lt;![CDATA[(a)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; + +(a)Name(&quot;org.jboss.seam.wicket.WebApplication&quot;) +@Scope(APPLICATION) +@Install(precedence=21, classDependencies="org.apache.wicket.Application") +@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 + */ +@Namespace(value="http://jboss.com/products/seam/wicket", prefix="org.jboss.seam.wicket") +@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