Author: denis.forveille Date: 2010-07-05 20:36:45 -0400 (Mon, 05 Jul 2010) New Revision: 13331 Modified: branches/community/Seam_2_2/doc/Seam_Reference_Guide/en-US/Websphere.xml Log: Make this chapter appear correctly in HTML + light refresh JBSEAM-4671 Modified: branches/community/Seam_2_2/doc/Seam_Reference_Guide/en-US/Websphere.xml =================================================================== --- branches/community/Seam_2_2/doc/Seam_Reference_Guide/en-US/Websphere.xml 2010-07-06 00:04:23 UTC (rev 13330) +++ branches/community/Seam_2_2/doc/Seam_Reference_Guide/en-US/Websphere.xml 2010-07-06 00:36:45 UTC (rev 13331) @@ -27,8 +27,8 @@ <ulink url="http://www.ibm.com/developerworks/downloads/ws/was"> WebSphere Application Server V7</ulink> </para> <para> - WebSphere v7.0.0.5 is the minimal recommended version of WebSphere v7 to use - with Seam. Earlier versions of WebSphere have bugs in the EJB container that will + WebSphere v7.0.0.5 is the minimal version of WebSphere v7 to use + with Seam. WAS v7.0.0.9 is highly recommended. Earlier versions of WebSphere have bugs in the EJB container that will cause various exceptions to occur at runtime. </para> @@ -43,9 +43,10 @@ <para> This is a bug in WebSphere v7.0.0.5. WebSphere does not conform to the EJB 3.0 specs as it does not allow to perform a lookup on "java:comp/EJBContext" in callback methods. - This problem is associated with APAR PK98746 at IBM. - IBM plans to include the fix with v7.0.0.9.In the meantime, an eFix for this APAR can be requested to IBM. </para> + <para> + This problem is associated with APAR PK98746 at IBM and is corrected in v7.0.0.9. + </para> </listitem> </varlistentry> @@ -59,8 +60,9 @@ necessary and performs the correct actions in these cases. The problem is that even if the exception is handled by Seam, WebSphere prints the traceback of the exception in SystemOut. Those messages are harmless and can safely be ignored. - This problem is associated with APAR PK97995 at IBM. - They plan to provides a fix with v7.0.0.9 that will suppress the print of those tracebacks if the exception is catched by the application. + </para> + <para> + This problem is associated with APAR PK97995 at IBM and is corrected in v7.0.0.9. </para> </listitem> </varlistentry> @@ -129,16 +131,16 @@ <para> In order to use component injection, Seam needs to know how to lookup for session beans bound to the JNDI name space. Seam provides two mechanisms to configure the way it will search for such resources: - <itemizedlist><listitem>The global <literal>jndi-pattern</literal> switch on the <literal>&lt;core:init&gt;</literal>tag in <literal>components.xml</literal>. - The switch can use a special placeholder "<literal>#{ejbName}</literal>" that resolves to the unqualified name of the EJB - </listitem> - <listitem> - <para> - The <literal>@JndiName</literal> annotation - </para> - </listitem> - </itemizedlist> </para> + <itemizedlist> + <listitem> + The global <literal>jndi-pattern</literal> switch on the <literal>&lt;core:init&gt;</literal>tag in <literal>components.xml</literal>. + The switch can use a special placeholder "<literal>#{ejbName}</literal>" that resolves to the unqualified name of the EJB + </listitem> + <listitem> + The <literal>@JndiName</literal> annotation + </listitem> + </itemizedlist> <para> <xref linkend="config.integration.ejb.container"/> gives detailed explanations on how those mechanisms work. </para> @@ -154,35 +156,33 @@ <para> As explained before, Seam needs to lookup for session bean as they appear in JNDI. Basically, there are three strategies, in order of complexity: - <itemizedlist><listitem>Specify which JNDI name Seam must use for each session bean using the <literal>@JndiName</literal> annotation in the java source file, - </listitem> - <listitem> - Override the default session bean names generated by WebSphere to conform to the <literal>jndi-pattern</literal> attribute, - </listitem> - <listitem> - Use EJB references. - </listitem> - </itemizedlist> </para> + <itemizedlist> + <listitem> + Specify which JNDI name Seam must use for each session bean using the <literal>@JndiName</literal> annotation in the java source file, + </listitem> + <listitem> + Override the default session bean names generated by WebSphere to conform to the <literal>jndi-pattern</literal> attribute, + </listitem> + <listitem> + Use EJB references. + </listitem> + </itemizedlist> <section id="was.strategy1"> <title>Strategy 1: Specify which JNDI name Seam must use for each Session Bean</title> - <para> - This strategy is the simplest and fastest one regarding development. It uses the WebSphere v7 default binding mechanism. To use this strategy: - <itemizedlist> - <listitem> - Add a <literal>@JndiName("ejblocal:&lt;package.qualified.local.interface.name&gt;)</literal> annotation to each session bean that is a Seam component. - </listitem> - <listitem> - <para> - In <literal>components.xml</literal>, add the following line: - <programlisting role="XML"><![CDATA[<core:init jndi-name="java:comp/env/#{ejbName}" />]]></programlisting> - </para> - </listitem> - <listitem> - <para > - Add a file named <literal>WEB-INF/classes/seam-jndi.properties</literal> in the web module with the following content: - <programlisting>com.ibm.websphere.naming.hostname.normalizer=com.ibm.ws.naming.util.DefaultHostnameNormalizer + This strategy is the simplest and fastest one regarding development. It uses the WebSphere v7 default binding mechanism. To use this strategy: + <itemizedlist> + <listitem> + Add a <literal>@JndiName("ejblocal:&lt;package.qualified.local.interface.name&gt;)</literal> annotation to each session bean that is a Seam component. + </listitem> + <listitem> + In <literal>components.xml</literal>, add the following line: + <programlisting language="xml" role="XML"><![CDATA[<core:init jndi-name="java:comp/env/#{ejbName}" />]]></programlisting> + </listitem> + <listitem> + Add a file named <literal>WEB-INF/classes/seam-jndi.properties</literal> in the web module with the following content: + <programlisting>com.ibm.websphere.naming.hostname.normalizer=com.ibm.ws.naming.util.DefaultHostnameNormalizer java.naming.factory.initial=com.ibm.websphere.naming.WsnInitialContextFactory com.ibm.websphere.naming.name.syntax=jndi com.ibm.websphere.naming.namespace.connection=lazy @@ -195,21 +195,17 @@ com.ibm.websphere.naming.jndicache.cachename=providerURL java.naming.provider.url=corbaloc:rir:/NameServiceServerRoot java.naming.factory.url.pkgs=com.ibm.ws.runtime:com.ibm.ws.naming</programlisting> - </para> - </listitem> - <listitem> - <para> - At the end of <literal>web.xml</literal>, add the following lines: - <programlisting role="XML"><![CDATA[<ejb-local-ref> + </listitem> + <listitem> + At the end of <literal>web.xml</literal>, add the following lines: + <programlisting role="XML"><![CDATA[<ejb-local-ref> <ejb-ref-name>EjbSynchronizations</ejb-ref-name> <ejb-ref-type>Session</ejb-ref-type> <local-home></local-home> <local>org.jboss.seam.transaction.LocalEjbSynchronizations</local> </ejb-local-ref>]]></programlisting> - </para> - </listitem> - </itemizedlist> - </para> + </listitem> + </itemizedlist> <para> That's all folks! No need to update any file during the development, nor to define any EJB to EJB or web to EJB reference! </para> @@ -225,11 +221,11 @@ However, WebSphere provides a way to override the name of each bean. <para> To use this strategy: - <itemizedlist> - <listitem> - <para> - Add a file named <literal>META-INF/ibm-ejb-jar-ext.xml</literal> in the EJB module and add an entry for each session bean like this: - <programlisting role="XML"><![CDATA[<?xml version="1.0" encoding="UTF-8"?> + </para> + <itemizedlist> + <listitem> + Add a file named <literal>META-INF/ibm-ejb-jar-ext.xml</literal> in the EJB module and add an entry for each session bean like this: + <programlisting role="XML"><![CDATA[<?xml version="1.0" encoding="UTF-8"?> <ejb-jar-bnd xmlns="http://websphere.ibm.com/xml/ns/javaee" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" @@ -241,33 +237,25 @@ <session name="BookingListAction" simple-binding-name="BookingListAction" /> </ejb-jar-bnd>]]></programlisting> - WebSphere will then bind the <literal>AuthenticatorAction</literal> EJB to the <literal>ejblocal:AuthenticatorAction</literal> JNDI name - </para> - </listitem> - <listitem> - <para> - In <literal>components.xml</literal>, add the following line: - <programlisting role="XML"><![CDATA[<core:init jndi-name="ejblocal:#{ejbName}" />]]></programlisting> - </para> - </listitem> - <listitem> - <para> - Add a file named <literal>WEB-INF/classes/seam-jndi.properties</literal> as described in strategy 1 - </para> - </listitem> - <listitem> - <para> - In <literal>web.xml</literal>, add the following lines (Note the different <literal>ejb-ref-name</literal> value): - <programlisting role="XML"><![CDATA[<ejb-local-ref> + WebSphere will then bind the <literal>AuthenticatorAction</literal> EJB to the <literal>ejblocal:AuthenticatorAction</literal> JNDI name + </listitem> + <listitem> + In <literal>components.xml</literal>, add the following line: + <programlisting role="XML"><![CDATA[<core:init jndi-name="ejblocal:#{ejbName}" />]]></programlisting> + </listitem> + <listitem> + Add a file named <literal>WEB-INF/classes/seam-jndi.properties</literal> as described in strategy 1 + </listitem> + <listitem> + In <literal>web.xml</literal>, add the following lines (Note the different <literal>ejb-ref-name</literal> value): + <programlisting role="XML"><![CDATA[<ejb-local-ref> <ejb-ref-name>ejblocal:EjbSynchronizations</ejb-ref-name> <ejb-ref-type>Session</ejb-ref-type> <local-home></local-home> <local>org.jboss.seam.transaction.LocalEjbSynchronizations</local> </ejb-local-ref>]]></programlisting> - </para> - </listitem> - </itemizedlist> - </para> + </listitem> + </itemizedlist> <para> Compared to the first strategy, this strategy requires to maintain an extra file (<literal>META-INF/ibm-ejb-jar-ext.xml</literal>), @@ -285,9 +273,7 @@ <programlisting role="XML"><![CDATA[<core:init jndi-name="java:comp/env/#{ejbName}" />]]></programlisting> </listitem> <listitem> - <para> - Follow the instructions in <xref linkend="config.integration.ejb.container"/> to declare the references from web to EJB and from EJB to EJB - </para> + Follow the instructions in <xref linkend="config.integration.ejb.container"/> to declare the references from web to EJB and from EJB to EJB </listitem> </itemizedlist> <para> @@ -302,7 +288,6 @@ <section id="websphere-timeout-section"> <title>Configuring timeouts for Stateful Session Beans</title> - <para> A timeout value has to be set for each stateful session bean used in the application because stateful bean must not expire in WebSphere while Seam might still need them. At the time of writing this document, WebSphere does not provide a way to configure a global timeout at neither the cluster, @@ -320,7 +305,6 @@ <session name="ChangePasswordAction"><time-out value="605"/></session> </ejb-jar-ext>]]></programlisting> - </para> <para> The <literal>time-out</literal> is expressed in seconds and must be higher than the Seam conversation expiration timeout and a few minutes higher than the user's HTTP session timeout (The session expiration timeout can trigger a few minutes @@ -363,16 +347,14 @@ The steps below are for the WAS version stated above.The ports are the default values, if you changed them, you must substitute the values. <orderedlist> <listitem> - Log in to the administration console - <programlisting><![CDATA[http://localhost:9060/admin]]></programlisting> - Enter your userid annd/or your password if security is enabled for the console. + Log in to the administration console + <programlisting><![CDATA[http://localhost:9060/admin]]></programlisting> + Enter your userid annd/or your password if security is enabled for the console. </listitem> <listitem> - <para> - Go to the <literal>WebSphere enterprise applications</literal> menu option under the <literal>Applications --> Application Type</literal> - left side menu. - </para> + Go to the <literal>WebSphere enterprise applications</literal> menu option under the <literal>Applications --> Application Type</literal> + left side menu. </listitem> <listitem> @@ -414,7 +396,7 @@ <itemizedlist> <listitem> <para> - Select the <literal>Deploy enterprise beans and Allow EJB reference targets to resolve automatically</literal> + Select the "<literal>Allow EJB reference targets to resolve automatically</literal>" check boxes at the bottom of the page. This will let WebSphere use its simplified JNDI reference mapping. </para> </listitem>