[webbeans-commits] Webbeans SVN: r2514 - doc/trunk/reference/en-US.
webbeans-commits at lists.jboss.org
webbeans-commits at lists.jboss.org
Sun Apr 19 15:56:41 EDT 2009
Author: pete.muir at jboss.org
Date: 2009-04-19 15:56:39 -0400 (Sun, 19 Apr 2009)
New Revision: 2514
Added:
doc/trunk/reference/en-US/viewlayers.xml
Modified:
doc/trunk/reference/en-US/master.xml
doc/trunk/reference/en-US/ri.xml
doc/trunk/reference/en-US/scopescontexts.xml
Log:
reorganize wicket docs
Modified: doc/trunk/reference/en-US/master.xml
===================================================================
--- doc/trunk/reference/en-US/master.xml 2009-04-19 09:55:50 UTC (rev 2513)
+++ doc/trunk/reference/en-US/master.xml 2009-04-19 19:56:39 UTC (rev 2514)
@@ -79,6 +79,7 @@
<xi:include href="environments.xml" xmlns:xi="http://www.w3.org/2001/XInclude" />
<xi:include href="extensions.xml" xmlns:xi="http://www.w3.org/2001/XInclude" />
+ <xi:include href="viewlayers.xml" xmlns:xi="http://www.w3.org/2001/XInclude" />
</part>
Modified: doc/trunk/reference/en-US/ri.xml
===================================================================
--- doc/trunk/reference/en-US/ri.xml 2009-04-19 09:55:50 UTC (rev 2513)
+++ doc/trunk/reference/en-US/ri.xml 2009-04-19 19:56:39 UTC (rev 2514)
@@ -676,135 +676,213 @@
<section id="numberguessWicket">
<title>The numberguess example in Apache Wicket</title>
- <para>Although the JSR299 specification includes detailed information on how WebBeans integrates
- with Java Server Faces, it is possible to use WebBeans injection, as well as the WebBeans conversational
- context, with other web frameworks. In this section, we'll look at the module which allows integration of
- WebBeans with the Apache Wicket framework. This documentation assumes that you have some familiarity
- with Wicket; if not, please visit <ulink url="http://wicket.apache.org/">http://wicket.apache.org/</ulink>
- to learn more. In this section we'll look at the previous "numberguess" example as implemented with Wicket.
- We'll look at the conversational aspects of the Wicket/WebBeans integration in <xref linkend="wicketContexts"/></para>
+ <para>
+ Whilst JSR-299 specifies integration with Java ServerFaces, Web
+ Beans allows you to inject into Wicket components, and also allows
+ you to use a conversation context with Wicket. In this section,
+ we'll walk you through the Wicket version of the numberguess
+ example.
+ </para>
+
+ <note>
+ <para>
+ You may want to review the Wicket documentation at
+ <ulink url="http://wicket.apache.org/">http://wicket.apache.org/</ulink>.
+ </para>
+ </note>
- <para>Like the previous example, the Wicket WebBeans examples make use of the <literal>webbeans-servlet</literal> module.
- The use of the <ulink url="http://jetty.mortbay.org/">Jetty servlet container</ulink> is common in the Wicket community,
- and is chosen here as the runtime container in order to facilitate comparison between the standard Wicket examples and these examples,
- and also to show how the webbeans-servlet integration is not dependent upon tomcat as the servlet container. Since we
- are deploying to a servlet container, we are also building as a WAR. In addition, these examples make use of the Eclipse IDE,
- although instructions are also given to deploy the application from the command line.</para>
+ <para>
+ Like the previous example, the Wicket WebBeans examples make use of
+ the <literal>webbeans-servlet</literal> module. The use of the
+ <ulink url="http://jetty.mortbay.org/">Jetty servlet container</ulink>
+ is common in the Wicket community, and is chosen here as the
+ runtime container in order to facilitate comparison between the
+ standard Wicket examples and these examples, and also to show how
+ the webbeans-servlet integration is not dependent upon Tomcat as the
+ servlet container.
+ </para>
+
+ <para>
+ These examples make use of the Eclipse IDE; instructions are also
+ given to deploy the application from the command line.
+ </para>
- <section>
- <title>Creating the eclipse project</title>
- <para>To generate an eclipse project from the example, use apache maven and the eclipse:eclipse
- plugin:
- <programlisting><![CDATA[cd examples/wicket/numberguess
-mvn eclipse:eclipse -DdownloadSources]]></programlisting>
- Then, from eclipse, choose <literal>File -> Import -> General -> Existing Projects into Workspace</literal>, choose
- the root directory of the numberguess example, and click finish. This should result in a project in
- your workspace named <literal>webbeans-wicket-numberguess</literal>:
- <mediaobject>
- <imageobject>
- <imagedata fileref="images/wicket-numberguess-project.png" format="png"/>
- </imageobject>
- </mediaobject>
- </para>
- </section>
+ <section>
+ <title>Creating the Eclipse project</title>
+
+ <para>
+ To generate an Eclipse project from the example:
+ </para>
+
+ <programlisting><![CDATA[cd examples/wicket/numberguess
+mvn eclipse:eclipse]]></programlisting>
+
+ <para>
+ Then, from eclipse, choose <emphasis>File -> Import -> General -> Existing Projects into Workspace</emphasis>,
+ select the root directory of the numberguess example, and click
+ finish. This will create a project in your workspace called
+ <literal>webbeans-wicket-numberguess</literal>
+ </para>
- <section>
- <title>Running the example from eclipse</title>
- <para>This project follows the <literal>wicket-quickstart</literal>
- approach of creating an instance of <literal>jetty</literal> through a <literal>Start</literal>
- class. So running the example is as simple as right-clicking on that Start class in src/test/java in the package
- explorer and choosing "Run as Java Application." You should then see console output related to jetty starting up,
- and then be able to hit <literal>http://localhost:8080</literal> to view the app. To stop the app, switch to the Console
- View and click the red stop square. One can also debug in the same fashion, by choosing "Debug as Java Application" when right-clicking.
- </para>
- </section>
- <section>
- <title>Running the example from the command line in Jboss or Tomcat</title>
- <para>This example can also be deployed from the command line in a fashion similar to the other examples. Assuming you have set up the
- <literal>build.properties</literal> file in the <literal>examples</literal> directory to specify the location of Jboss or Tomcat, as previously
- described, you can simply run <literal>ant deploy</literal> from the <literal>examples/wicket/numberguess</literal> directory, and access
- the application at <literal>http://localhost:8080/webbeans-numberguess-wicket</literal>.
- </para>
- </section>
+ <mediaobject>
+ <imageobject>
+ <imagedata fileref="images/wicket-numberguess-project.png" format="PNG"/>
+ </imageobject>
+ </mediaobject>
+ </section>
- <section>
- <title>Understanding the code</title>
- <para>While JSF uses unified EL expressions to bind view layer components in jsp or xhtml to
- WebBeans, Wicket keeps a stricter separation of concerns in place. The markup is plain html with
- a one-to-one mapping between html elements and the view components, which are constructed in java code. All
- view logic, including binding of components to models and controlling the response of view actions,
- is handled in java code. Therefore, the integration of WebBeans with Wicket takes place through annotated
- injections of WebBeans into your WebPage subclass (or into other custom wicket component subclasses.)</para>
+ <section>
+ <title>Running the example from Eclipse</title>
+
+ <para>
+ This project follows the <literal>wicket-quickstart</literal>
+ approach of creating an instance of Jetty in the
+ <literal>Start</literal> class. So running the example is as
+ simple as right-clicking on that Start class in
+ <literal>src/test/java</literal> in the
+ <emphasis>Package Explorer</emphasis> and choosing
+ <emphasis>Run as Java Application</emphasis>. You should
+ see console output related to Jetty starting up; then visit able
+ <literal>http://localhost:8080</literal> to view the app. To
+ debug choose <emphasis>Debug as Java Application</emphasis>.
+ </para>
+ </section>
+
+ <section>
+ <title>Running the example from the command line in JBoss AS or Tomcat</title>
+
+ <para>
+ This example can also be deployed from the command line in a
+ (similar to the other examples). Assuming you have set up the
+ <literal>build.properties</literal> file in the
+ <literal>examples</literal> directory to specify the location of
+ JBoss AS or Tomcat, as previously described, you can run
+ <literal>ant deploy</literal> from the
+ <literal>examples/wicket/numberguess</literal> directory, and
+ access the application at
+ <literal>http://localhost:8080/webbeans-numberguess-wicket</literal>.
+ </para>
+ </section>
+
+ <section>
+ <title>Understanding the code</title>
+
+ <para>
+ JSF uses Unified EL expressions to bind view layer components in
+ JSP or Facelet views to beans, Wicket defines it's components in
+ Java. The markup is plain html with a one-to-one mapping between
+ html elements and the view components. All view logic, including
+ binding of components to models and controlling the response of
+ view actions, is handled in Java. The integration of Web Beans
+ with Wicket takes advantage of the same binding annotations used
+ in your business layer to provide injection into your WebPage
+ subclass (or into other custom wicket component subclasses).
+ </para>
- <para>The code in the wicket numberguess example is very similar to the JSF-based numberguess example described previously. The business logic
- components (Game, Generator, MaxNumber, etc.) are the same. Differences include the following:</para>
- <itemizedlist>
- <listitem><para>Each wicket application must have a <literal>WebApplication</literal> subclass,
- and in the case of the Wicket/WebBeans integration, this class should subclass <literal>
- org.jboss.webbeans.wicket.WebBeansApplication</literal>. (If you would prefer not to subclass
- WebBeansApplication, you can manually add the small number of overrides and listeners to your own WebApplication
- subclass. See the javadocs on WebBeansApplication for details.) In our case, our application class is called<literal>
- SampleApplication</literal>:
- <programlisting><![CDATA[public class SampleApplication extends WebBeansApplication
-{
+ <para>
+ The code in the wicket numberguess example is very similar to the
+ JSF-based numberguess example. The business layer is identical!
+ </para>
+
+ <para>
+ Differences are:
+ </para>
+ <itemizedlist>
+ <listitem>
+ <para>
+ Each wicket application must have a
+ <literal>WebApplication</literal> subclass, In our case,
+ our application class is
+ <literal>SampleApplication</literal>:
+ </para>
+ <programlisting><![CDATA[public class SampleApplication extends WebBeansApplication {
@Override
- public Class getHomePage()
- {
+ public Class getHomePage() {
return HomePage.class;
}
-}]]></programlisting>This class specifies which page wicket should treat as our HomePage,
-in our case, <literal>HomePage.class</literal></para>
- </listitem>
- <listitem>
- <para>In <literal>HomePage</literal> we see typical wicket code to set up page elements. The
- bits that are interesting with respect to WebBeans are the injection of the <literal>Game</literal>
- WebBean the top of the class</para>
- <programlisting><![CDATA[ @Current Game game;]]></programlisting> which is then used later in,
- for example, the code for submitting a guess:<programlisting><![CDATA[final Component guessButton = new AjaxButton("GuessButton") {
+}]]></programlisting>
+ <para>
+ This class specifies which page wicket should treat as our
+ home page, in our case, <literal>HomePage.class</literal>
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ In <literal>HomePage</literal> we see typical wicket code
+ to set up page elements. The bit that is interesting is
+ the injection of the <literal>Game</literal> bean:
+ </para>
+
+ <programlisting><![CDATA[ @Current Game game;]]></programlisting>
+
+ <para>
+ The <literal>Game</literal> bean is can then be used, for
+ example, by the code for submitting a guess:
+ </para>
+
+ <programlisting><![CDATA[final Component guessButton = new AjaxButton("GuessButton") {
protected void onSubmit(AjaxRequestTarget target, Form form) {
- if (game.check()) {]]></programlisting>This injection is a proxy which holds a transient reference to the actual
- Game WebBean, and is therefore safe with respect to the serialization of the wicket page. Actual
- storage of the bean is in the session, and is managed by WebBeans. Note that Wicket components, like the HomePage and its
- subcomponents, are <emphasis>not</emphasis> WebBeans. Their construction is handled directly by wicket (for
- the page itself) and by the example code (for the nested page elements), and not by the WebBeans
- Manager. However, the <literal>
- webbeans-wicket</literal> integration takes care of injecting dependencies into the page for us. This
- injection occurs through an <literal>IComponentInstantiationListener</literal> which is
- registered by the <literal>WebbeansWebApplication</literal>. This means that although wicket
- components can have injections, they <emphasis>cannot</emphasis> use interceptors and the other features
- of real WebBeans. The delegate beans used by the wicket code can of course be full WebBeans,
- as the <literal>Game</literal> bean is in this example.</listitem>
- <listitem><para>Note that this example also uses ajax for processing of button events, and
- dynamically hides buttons that are no longer revelant, for example when the user has won the game.</para></listitem>
+ if (game.check()) {]]></programlisting>
+
+ <note>
+ <para>
+ All injections may be serialized; actual storage of the
+ bean is managed by JSR-299. Note that Wicket
+ components, like the HomePage and it subcomponents, are
+ <emphasis>not</emphasis> JSR-299 beans.
+ </para>
+ <para>
+ Wicket components allow injection, but they
+ <emphasis>cannot</emphasis> use interceptors, decorators
+ and lifecycle callbacks such as
+ <literal>@PostConstruct</literal> or
+ <literal>@Initializer</literal> methods.
+ </para>
+ </note>
+ </listitem>
+ <listitem>
+ <para>
+ The example uses AJAX for processing of button events, and
+ dynamically hides buttons that are no longer relevant, for
+ example when the user has won the game.
+ </para>
+ </listitem>
- <listitem><para>In order to activate wicket for this webapp, the Wicket filter is added to web.xml, and our application class is specified:
- <programlisting><![CDATA[ <filter>
- <filter-name>wicket.numberguess-example</filter-name>
- <filter-class>org.apache.wicket.protocol.http.WicketFilter</filter-class>
- <init-param>
- <param-name>applicationClassName</param-name>
- <param-value>org.jboss.webbeans.examples.wicket.SampleApplication</param-value>
- </init-param>
+ <listitem>
+ <para>
+ In order to activate wicket for this webapp, the Wicket
+ filter is added to web.xml, and our application class is
+ specified:
+ </para>
+ <programlisting><![CDATA[<filter>
+ <filter-name>wicket.numberguess-example</filter-name>
+ <filter-class>org.apache.wicket.protocol.http.WicketFilter</filter-class>
+ <init-param>
+ <param-name>applicationClassName</param-name>
+ <param-value>org.jboss.webbeans.examples.wicket.SampleApplication</param-value>
+ </init-param>
</filter>
<filter-mapping>
- <filter-name>wicket.numberguess-example</filter-name>
- <url-pattern>/*</url-pattern>
+ <filter-name>wicket.numberguess-example</filter-name>
+ <url-pattern>/*</url-pattern>
</filter-mapping>
<listener>
- <listener-class>org.jboss.webbeans.environment.servlet.Listener</listener-class>
-</listener>]]></programlisting>Note that the servlet listener is also added, as in the tomcat example, in order to boostrap
-WebBeans when jetty starts, and to hook WebBeans into the jetty servlet request and session lifecycles.</para>
-</listitem>
+ <listener-class>org.jboss.webbeans.environment.servlet.Listener</listener-class>
+</listener>]]></programlisting>
+ <para>
+ Note that the servlet listener is also added, as in the
+ Tomcat example, in order to boostrap Web Beans when Jetty
+ starts, and to hook Web Beans into the Jetty servlet
+ request and session lifecycles.
+ </para>
+ </listitem>
- </itemizedlist>
-
-
- </section>
-
+ </itemizedlist>
+ </section>
+ </section>
</section>
- </section>
<section>
<title>The translator example</title>
Modified: doc/trunk/reference/en-US/scopescontexts.xml
===================================================================
--- doc/trunk/reference/en-US/scopescontexts.xml 2009-04-19 09:55:50 UTC (rev 2513)
+++ doc/trunk/reference/en-US/scopescontexts.xml 2009-04-19 19:56:39 UTC (rev 2514)
@@ -246,148 +246,8 @@
<programlisting role="JAVA">conversation.setTimeout(timeoutInMillis);</programlisting>
</section>
-
- <section id="wicketContexts">
- <title>Conversations using Wicket</title>
- <para>The conversation scope can also be used in WebBeans with the Apache Wicket web framework, through the
- <literal>webbeans-wicket</literal> module. This module takes care of:
- <itemizedlist>
- <listitem><para>Setting up the conversation context at the beginning of a wicket request, and tearing it down afterwards</para></listitem>
- <listitem><para>Storing the id of any long-running conversation in Wicket's WebPage metadata when the page response is complete</para></listitem>
- <listitem><para>Activating the correct long-running conversation based upon which page is being accessed</para></listitem>
- <listitem><para>Propagating the conversation context for any long-running conversation to new pages</para></listitem>
- </itemizedlist> </para>
- <section>
- <title>Starting and stopping conversations in Wicket</title>
- <para>As in WebBeans JSF applications, a conversation <emphasis>always</emphasis> exists for any request, but its lifetime is only that of the current request unless it is marked as
- <emphasis>long-running</emphasis>. For Wicket applications this is accomplished exactly as in JSF applications, by injecting the <literal>@Current Conversation</literal> and then
- invoking <literal>conversation.begin()</literal>. Likewise, conversations are ended with <literal>conversation.end()</literal>
- </para>
- </section>
-
- <section>
- <title>Long running conversation propagation in Wicket</title>
- <para>
- When a conversation is marked as long-running, the id of that conversation will be stored in Wicket's WebPage metadata for the current page.
- In addition, if a new page is created and set as the response target through <literal>setResponsePage</literal>, this new page will also participate
- in this conversation. This occurs for both directly instantiated pages, i.e. <literal>setResponsePage(new OtherPage())</literal> as well as for
- bookmarkable pages created with <literal>setResponsePage(OtherPage.class)</literal> where <literal>OtherPage.class</literal> is mounted as bookmarkable
- from your <literal>WebApplication</literal> subclass (or through annotations.) In the latter case, because the new page instance is not created until after
- a redirect, the conversation id will be propagated through a request parameter, and then stored in page metadata after the redirect.
- </para>
- </section>
- <section>
- <title>The Wicket Conversations Example</title>
- <para>In <literal>examples/wicket/conversations</literal> there is an example application for using conversations from Wicket. To setup and run the
- application, follow the examples in <xref linkend="numberguessWicket"/>. If running within eclipse, the application is available at <literal>http://localhost:8080</literal>,
- and if running within an external container, the app is available at <literal>http://localhost:8080/webbeans-conversations-wicket</literal>.
- </para>
- <section>
- <title>Using the application</title>
- <para>The <emphasis>conversations</emphasis> application is simply an interface to begin and end conversations, switch between them, and store a single piece of data in each.
- The interface looks like the following:
- <mediaobject>
- <imageobject>
- <imagedata fileref="images/wicket-conversations-snap.png" format="PNG"/>
- </imageobject>
- </mediaobject></para>
- <para>
- The menu at the top will show the list of long-running conversations, along with data about each,
- as well as the active conversation (even if it is not long running.) The currently selected item
- of this menu is the current conversation for the last request that was processed. Changing this menu
- changes the current conversation. The "Data in conversation" text box and the submit
- button labeled "Change Value" allow you to change a piece of string data associated
- with the conversation. The "begin" button marks the conversation as long running.
- The "noop" button submits the form without changing the state of the conversation.
- The "end" button ends the current conversation. The "longop" button
- executes a method that takes a few seconds, which can be used to play with conversation timeouts and
- synchronization/locking. The "Abandon" link redirects to the HomePage without propagating
- the conversation, thus starting a new temporary conversation. The conversation that has been abandoned
- can be rejoined by selecting it in the popup.</para>
- </section>
- <section>
- <title>Understanding the code</title>
- <para>As in <xref linkend="numberguessWicket"/>, there is boilerplate code in the
- SampleApplication, as well as in web.xml, to ensure correct integration of Wicket and Webbeans.
- Other pieces of this application include:</para>
- <itemizedlist>
- <listitem><para>The <literal>Conversations</literal> class exists to allow configuration of the conversation
- timeout for the current session<programlisting><![CDATA[@Produces
- at ConversationInactivityTimeout
- at Example
-public static long getConversationTimeoutInMilliseconds()
-{
- return 600000;
-}]]></programlisting>The <literal>Example</literal> deployment type is used to illustrate
-custom deployment types. It is defined in Example.java:<programlisting><![CDATA[@Target( { TYPE, METHOD, FIELD })
- at Retention(RUNTIME)
- at Documented
- at DeploymentType
-public @interface Example
-{
-}]]></programlisting> and is activated in <literal>WEB-INF/beans.xml</literal>:
-<programlisting><![CDATA[<Beans xmlns="urn:java:ee" xmlns:conversations="urn:java:org.jboss.webbeans.examples.conversations">
- <Deploy>
- <Standard />
- <Production />
- <conversations:Example />
- </Deploy>
-</Beans>]]></programlisting></para></listitem>
-<listitem><para>The <literal>Data</literal> class is our conversational component that stores a
-single string:<programlisting><![CDATA[@ConversationScoped
- at Named
-public class Data implements Serializable
-{
- private String data;
- public String getData()
- {
- return data;
- }
-
- public void setData(String data)
- {
- this.data = data;
- }
-}]]></programlisting></para></listitem>
-<listitem><para>The <literal>HomePage</literal> class is where
-the brunt of the work takes place. It injects the WebBeans-provided <literal>ConversationManager</literal>
-component in order to access the list of long-running conversations, injects the current <literal>Conversation</literal>
-in order to allow control over whether that conversation is long-running, and injects the <literal>Data</literal>
-component to allow its manipulation by the textfield:<programlisting><![CDATA[/**
-* These are injections for displaying information about existing conversations to the user
-*/
- at Current ConversationManager conversationManager;
- at Current Conversation currentConversation;
-
-/**
-* This is our conversational data component, to illustrate how data is used in conversations and
-* exists per-conversation.
-*/
- at Current Data data;
-]]></programlisting>The data component is referenced by the wicket TextField using a
-<literal>PropertyModel</literal>:<programlisting><![CDATA[form.add(new TextField("dataField", new PropertyModel(this, "data.data")));]]></programlisting>
-This means that for each page, the text field is referring to the "data" property of the "Data" bean that is specific to
-the conversation that is active for the request, whether that be a transient conversation that is created for the request
-or a long-running conversation associated with the page. If one types data into the text field
-and clicks <literal>Change Value</literal>
-when a long-running conversation is not started, and then clicks <literal>noop</literal>, the
-value in the text field disappears, because it was associated with a transient conversation, and
-upon redirect, the new conversation had a different Data object, which had the default (empty) value.</para>
-<para>As you can see by the other code in this example, conversations are started and ended programmatically,
-and no WebBeans-specific code is necessary to propagate the conversation. The only exception to this
-is in the code to <emphasis>switch</emphasis> conversations, which is not a typical operation in real scenarios.
-In this case, a conversation id (<literal>cid</literal>) request parameter is passed to the <literal>setResponsePage</literal>
-invocation, and this explicit conversation id will override the id that the wicket/webbeans integration
-code would normally generate in order to propagate the current conversation, and hence the specified
-conversation will be active upon redirect.</para>
-</listitem>
-</itemizedlist>
-
</section>
-</section>
-</section>
-</section>
<section>
<title>The dependent pseudo-scope</title>
Added: doc/trunk/reference/en-US/viewlayers.xml
===================================================================
--- doc/trunk/reference/en-US/viewlayers.xml (rev 0)
+++ doc/trunk/reference/en-US/viewlayers.xml 2009-04-19 19:56:39 UTC (rev 2514)
@@ -0,0 +1,113 @@
+<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.3//EN" "http://www.oasis-open.org/docbook/xml/4.3/docbookx.dtd" [ ]>
+
+<chapter id="viewlayers">
+ <title>Alternative view layers</title>
+
+ <section>
+ <title>Using Web Beans with Wicket</title>
+
+ <section>
+ <title>The <literal>WebApplication</literal> class</title>
+
+ <para>
+ Each wicket application must have a
+ <literal>WebApplication</literal> subclass; Web Beans provides, for
+ your utility, a subclass of this which sets up the Wicket/JSR-299
+ integration. You should subclass
+ <literal>org.jboss.webbeans.wicket.WebBeansApplication</literal>.
+ </para>
+
+ <note>
+ <para>
+ If you would prefer not to subclass
+ <literal>WebBeansApplication</literal>, you can manually add a
+ (small!) number of overrides and listeners to your own
+ <literal>WebApplication</literal> subclass. The javadocs of
+ <literal>WebBeansApplication</literal>detail this.
+ </para>
+ </note>
+
+ <para>
+ For example:
+ </para>
+ <programlisting><![CDATA[public class SampleApplication extends WebBeansApplication {
+ @Override
+ public Class getHomePage() {
+ return HomePage.class;
+ }
+}]]></programlisting>
+ </section>
+
+ <section id="wicketContexts">
+ <title>Conversations with Wicket</title>
+ <para>
+ The conversation scope can be used in Web Beans with the Apache
+ Wicket web framework, through the <literal>webbeans-wicket</literal>
+ module. This module takes care of:
+ </para>
+ <itemizedlist>
+ <listitem>
+ <para>
+ Setting up the conversation context at the beginning of a
+ Wicket request, and tearing it down afterwards
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ Storing the id of any long-running conversation in Wicket's
+ metadata when the page response is complete
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ Activating the correct long-running conversation based upon
+ which page is being accessed
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ Propagating the conversation context for any long-running conversation to new pages
+ </para>
+ </listitem>
+ </itemizedlist>
+
+ <section>
+ <title>Starting and stopping conversations in Wicket</title>
+ <para>
+ As JSF applications, a conversation
+ <emphasis>always</emphasis> exists for any request, but its
+ lifetime is only that of the current request unless it is
+ marked as <emphasis>long-running</emphasis>. For Wicket
+ applications this is accomplished as in JSF applications, by
+ injecting the <literal>@Current Conversation</literal> and
+ then invoking <literal>conversation.begin()</literal>.
+ Likewise, conversations are ended with
+ <literal>conversation.end()</literal>
+ </para>
+ </section>
+
+ <section>
+ <title>Long running conversation propagation in Wicket</title>
+ <para>
+ When a conversation is marked as long-running, the id of that
+ conversation will be stored in Wicket's metadata for the current
+ page. If a new page is created and set as the response target
+ through <literal>setResponsePage</literal>, this new page will
+ also participate in this conversation. This occurs for both
+ directly instantiated pages
+ (<literal>setResponsePage(new OtherPage())</literal>), as well as
+ for bookmarkable pages created with
+ <literal>setResponsePage(OtherPage.class)</literal> where
+ <literal>OtherPage.class</literal> is mounted as bookmarkable
+ from your <literal>WebApplication</literal> subclass (or through
+ annotations). In the latter case, because the new page instance
+ is not created until after a redirect, the conversation id will
+ be propagated through a request parameter, and then stored in
+ page metadata after the redirect.
+ </para>
+ </section>
+ </section>
+
+ </section>
+
+</chapter>
\ No newline at end of file
Property changes on: doc/trunk/reference/en-US/viewlayers.xml
___________________________________________________________________
Name: svn:mime-type
+ text/plain
More information about the weld-commits
mailing list