Software Público Brasileiro

<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN"
   "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd"  [ ]>
<chapter id="viewlayers">

   <title>Alternative view layers</title>

   <section>
      <title>Wicket CDI integration</title>

      <para>
         Weld provides integration between the Apache Wicket web framework and CDI.  This functionality is provided by
         the <literal>weld-wicket</literal> extension module, which naturally must be on the classpath of the Wicket
         application.
      </para>

      <para>
         This section describes some of the utilities provided by the Wicket extension module to support the CDI
         integration.
      </para>
      
      <section>
         <title>The <literal>WebApplication</literal> class</title>
         
         <para>
            Each wicket application must have a <literal>WebApplication</literal> subclass; Weld provides, for your
            utility, a subclass of this which sets up the Wicket CDI integration. You should subclass
            <literal>org.jboss.weld.wicket.WeldApplication</literal>.
         </para>
         
         <note>
            <para>
               If you would prefer not to subclass <literal>WeldApplication</literal>, you can manually add a (small!)
               number of overrides and listeners to your own <literal>WebApplication</literal> subclass. The JavaDocs of
               <literal>WeldApplication</literal>detail this.
            </para>
         </note>
         
         <para>
            For example:
         </para>
         <programlisting><![CDATA[public class SampleApplication extends WeldApplication {
   @Override
   public Class getHomePage() {
      return HomePage.class;
   }
}]]></programlisting>
      </section>
      
      <section id="wicketContexts">
         <title>Conversations with Wicket</title>
         <para>
            Wicket can also take advantage of the conversation scope from CDI,
            provided by the Wicket extension 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 in JSF applications, a conversation <emphasis>always</emphasis> exists for any request to Wicket, but its
               lifetime is only that of the current request unless it is marked as <emphasis>long-running</emphasis>.
               The boundaries of a long-running conversation are controlled in the same way as in JSF applications,
               by injecting the <literal>Conversation</literal> instance and invoking either the
               <literal>begin()</literal>
               or <literal>end()</literal> methods:
            </para>

            <programlisting role="JAVA"><![CDATA[private @Inject Conversation conversation;
...
// begin a conversation
conversation.begin();
...
// end a conversation
conversation.end();]]></programlisting> 

         </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>

<!--
vim:et:ts=3:sw=3:tw=120
-->
</chapter>