11:05 a.m.
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