[gatein-commits] gatein SVN: r8974 - epp/docs/branches/5.2/Reference_Guide/en-US/modules/PortalDevelopment.

[do-not-reply at jboss.org]

Author: smumford
Date: 2012-11-29 21:05:39 -0500 (Thu, 29 Nov 2012)
New Revision: 8974

Modified:
   epp/docs/branches/5.2/Reference_Guide/en-US/modules/PortalDevelopment/PortalLifecycle.xml
Log:
BZ#807499: Added SME approved content regarding advanced WCI features

Modified: epp/docs/branches/5.2/Reference_Guide/en-US/modules/PortalDevelopment/PortalLifecycle.xml
===================================================================
--- epp/docs/branches/5.2/Reference_Guide/en-US/modules/PortalDevelopment/PortalLifecycle.xml	2012-11-28 20:39:30 UTC (rev 8973)
+++ epp/docs/branches/5.2/Reference_Guide/en-US/modules/PortalDevelopment/PortalLifecycle.xml	2012-11-30 02:05:39 UTC (rev 8974)
@@ -28,6 +28,86 @@
          <para>
             During deployment, JBoss Enterprise Portal Platform will automatically and transparently inject a servlet into the portlet application to be able to interact with it. This feature is dependent on the underlying servlet container but will work out of the box on the proposed bundles.
          </para>
+          
+         <section>
+            <title>Advanced WCI Registration</title>
+             
+            <para>
+               JBoss Portal Platform integrates with the web container to perform tasks such as automatic detection and registration of web applications. This is used by the portal container to detect when portlets are deployed and is accomplished through the WCI (Web Container Integration) component.
+            </para>
+             
+            <para>
+               Some applications, especially Spring based portlets, may have requirements that specific servlets be started before any portlets are initialized. Although portlets and servlet initialization order are meant to be independent of each other, JBoss Portal Platform does have a way to get around these limitations imposed by these specific third party applications.
+            </para>
+             
+            <para>
+               As a workaround to this issue, two new, advanced features have been integrated into the WCI component;
+            </para>
+             
+            <variablelist>
+               <title></title>
+                
+               <varlistentry>
+                  <term>Disabling Automatic registration</term>
+                   
+                  <listitem>
+                     <para>
+                        By default WCI will register all web applications and the portlet container will then analyse the registered applications and initialize any portlets contained. If you do not wish for your web application to be automatically registered by the WCI component you can disable this feature. By disabling this feature you can prevent the automatic initialization of the portlet and specify later when you want it to be initialized.
+                     </para>
+                      
+                     <para>
+                        This is done by setting the <parameter>gatein.wci.native.DisableRegistration</parameter> context-param to <literal>true</literal> in the <filename>web.xml</filename> file of the application, as shown below:
+                     </para>
+<programlisting language="XML" role="XML"><![CDATA[<!-- Disable the Native Application Registration -->
+   <context-param>
+    <param-name>gatein.wci.native.DisableRegistration</param-name>
+    <param-value>true</param-value>
+  </context-param>
+]]></programlisting>
+                  </listitem>
+               </varlistentry>
+                
+               <varlistentry>
+                  <term>Manual application deployment.</term>
+                   
+                  <listitem>
+                     <para>
+                        If you have disabled the automatic registration of your application in the first step, the portal container will not know about any of the portlets contained and will not be able to initialize them. WCI does have a servlet which can be used to manually register the web application. Since servlets can specify when they are deployed with regards to other servlets, we can use this to specify that the web application gets registered by WCI after another servlet has already been started. This means that the a servlet, for example the Spring servlet, can be initialized before any of the portlets.
+                     </para>
+                      
+                     <para>
+                        Below is an example web.xml file configured to ensure the MyCustomServlet will be initialised before the webapp is registered by WCI:
+                     </para>
+<programlisting language="XML" role="XML"><![CDATA[<!-- Disable the Native Application Registration -->
+   <context-param>
+    <param-name>gatein.wci.native.DisableRegistration</param-name>
+    <param-value>true</param-value>
+   </context-param>
+]]></programlisting>
+<programlisting language="XML" role="XML"><![CDATA[<!-- Register the Web Application Manually -->
+   <servlet>
+    <servlet-name>GateInServlet</servlet-name>
+    <servlet-class>org.gatein.wci.api.GateInServlet</servlet-class>
+    <load-on-startup>1</load-on-startup>
+   </servlet>
+]]></programlisting>
+<programlisting language="XML" role="XML"><![CDATA[<!-- Custom Servlet which will be initalised before the webapp is registered in WCI -->
+  <servlet>
+    <servlet-name>MyCustomServlet</servlet-name>
+    <servlet-class>my.custom.Servlet</servlet-class>
+    <load-on-startup>0</load-on-startup>
+  </servlet>
+]]></programlisting>
+<programlisting language="XML" role="XML"><![CDATA[<!-- Servlet Mapping for the Manual Registration -->
+  <servlet-mapping>
+    <servlet-name>GateInServlet</servlet-name>
+    <url-pattern>/gateinservlet</url-pattern>
+  </servlet-mapping>
+]]></programlisting>
+                  </listitem>
+               </varlistentry>
+            </variablelist>
+         </section>
       </section>
 <!--            
 TODO: Define the added listener