Author: manaRH Date: 2008-11-07 08:15:03 -0500 (Fri, 07 Nov 2008) New Revision: 9526 Modified: branches/enterprise/JBPAPP_4_3_FP01/doc/Seam_Reference_Guide/en-US/Migration.xml branches/enterprise/JBPAPP_4_3_FP01/seam2migration.txt Log: JBPAPP-1166 Modified: branches/enterprise/JBPAPP_4_3_FP01/doc/Seam_Reference_Guide/en-US/Migration.xml =================================================================== --- branches/enterprise/JBPAPP_4_3_FP01/doc/Seam_Reference_Guide/en-US/Migration.xml 2008-11-07 11:53:51 UTC (rev 9525) +++ branches/enterprise/JBPAPP_4_3_FP01/doc/Seam_Reference_Guide/en-US/Migration.xml 2008-11-07 13:15:03 UTC (rev 9526) @@ -94,23 +94,27 @@ <para> Due to an incompatibility between Seam and MyFaces, you had to use client side state saving in Seam 1.2. Switching to the JSF RI - 1.2 lifts this restriction. + 1.2 lifts this restriction. So remove the context param javax.faces.STATE_SAVING_METHOD. </para> </note> - </section> <section> - <title>Migrating <literal>web.xml</literal> and <literal>faces-config.xml</literal> to Seam 2</title> - + <title>Migrating <literal>web.xml</literal> to Seam 2</title> + <para> - First you should migrate - <literal>web.xml</literal> - and - <literal>faces-config.xml</literal> - files from DTD to XSD format, if you already haven't done it. It is - relevant for Seam users before version 1.2. - </para> + First change the <literal>web-app</literal> version from 2.4 to 2.5. + There is also change in j2ee to javaee in namespace URL. Declaration of the <literal>web.xml</literal> + should look like:</para> + +<programlisting role="XML"><![CDATA[<web-app xmlns="http://java.sun.com/xml/ns/javaee" + xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" + xsi:schemaLocation=" + http://java.sun.com/xml/ns/javaee + http://java.sun.com/xml/ns/javaee/web-app_2_5.xsd" + version="2.5"> + ... +</web-app>]]></programlisting> <para> In your Seam 1.2 app you may have specified some Seam specific @@ -151,7 +155,7 @@ </para> <para> - Finally, you should have the Seam resouce servlet (just as you did + Finally, you should have the Seam resource servlet (just as you did in Seam 1.2): </para> @@ -184,7 +188,6 @@ <url-pattern>*.seam</url-pattern> </filter-mapping>-->]]></programlisting> - <para> Next, we'll describe the changes you need to make to your JSF <literal>ViewHandler</literal> configuration. Previously the @@ -209,14 +212,23 @@ <param-value>org.jboss.seam.ui.facelet.SeamFaceletViewHandler</param-value> </context-param>-->]]></programlisting> - <para> - And that <literal>FaceletViewHandler</literal> is set in - <literal>faces-config.xml</literal>: + + </section> + + <section> + <title>Migrating <literal>faces-config.xml</literal> to Seam 2</title> + + <para>Remove the DTD on the document and add the XML Schema declarations to the + root tag: </para> - - <programlisting role="XML"><![CDATA[<application> - <view-handler>com.sun.facelets.FaceletViewHandler</view-handler> -</application>]]></programlisting> +<programlisting role="XML"><![CDATA[<faces-config version="1.2" + xmlns="http://java.sun.com/xml/ns/javaee" + xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" + xsi:schemaLocation=" + http://java.sun.com/xml/ns/javaee + http://java.sun.com/xml/ns/javaee/web-facesconfig_1_2.xsd"> + ... +</faces-config>]]></programlisting> <para> Seam 1.2 required you to specify either the @@ -239,13 +251,21 @@ </para> <programlisting role="XML"><![CDATA[<core:init transaction-management-enabled="false"/>]]></programlisting> - + <para> To workaround a bug, you may have specified <literal>SeamELResolver</literal> in <literal>faces-config.xml</literal>. This is no longer required. </para> + <para> + Finally remove <literal>FaceletViewHandler</literal> configuration: + </para> + + <programlisting role="XML"><![CDATA[<application> + <view-handler>com.sun.facelets.FaceletViewHandler</view-handler> +</application>]]></programlisting> + </section> <section> @@ -321,8 +341,6 @@ <important> <para> - Migrate all configuration XML file from DTD to XSD format if you use an old Seam - DTD configuration formats. Don't forget to update the XSD's in <literal>pages.xml</literal> and <literal>components.xml</literal> to point at the ones for Seam 2. Just change the suffix from <literal>-1.2.xsd</literal> to @@ -340,10 +358,6 @@ packages. </para> - <para>Also please be sure that you have already migrated your components.xml - file from DTD to XSD format. - </para> - <para> You'll need to update both your <literal>components.xml</literal> and any references in Java code. @@ -1289,7 +1303,7 @@ <para> If you are using RichFaces or Ajax4jsf, a major reorganization of - the project has occurred. <literal>ajax4jsf.jar</literal> and + the project has occurred. The jars <literal>ajax4jsf.jar</literal> and <literal>richfaces.jar</literal> have been replaced by <literal>richfaces-api.jar</literal> (which should go in your ear <literal>lib/</literal> directory), @@ -1299,6 +1313,11 @@ </para> <para> + &lt;s:selectDate&gt; has been deprecated in favor of &lt;rich:calendar&gt;. No more + development will be done on &lt;s:selectDate&gt;. You can remove the styles related + to the data picker from your stylesheet to save on unnecessary bandwidth use. + </para> + <para> You should check the RichFaces documentation for more information on parameter name changes and namespace changes. </para> @@ -1310,20 +1329,84 @@ <para> As most JSF component sets provide a date selector, the Seam date - selector (<literal>s:selectDate</literal> has been deprecated. You + selector (&lt;s:selectDate&gt;) has been deprecated. You should replace it with the date selector from the component set you use. </para> <para> - <literal>&lt;s:decorate/&gt;</literal> has become a naming container. + Selector &lt;s:decorate/&gt; has become a naming container. Therefore client ids have changed from <literal>fooForm:fooInput</literal> to - <literal>fooForm:foo:fooInput</literal> (assuming your - <literal>&lt;s:decorate&gt;</literal> has foo as an id). - </para> + <literal>fooForm:foo:fooInput</literal>, assuming the following declaration:</para> + + <programlisting role="XML"><![CDATA[<h:form id="fooForm"> + <s:decorate id="foo"> + <h:inputText id="fooInput" value="#{bean.property}"/> + </s:decorate> +</h:form>]]></programlisting> + + <para>If you don't provide an id to &lt;s:decorate&gt;, one will be generated by JSF.</para> </section> + + <section> + <title>Changes to seam-gen</title> + + <para>There was a change in seam-gen regarding + how the generated classes are organized when generate-entities is + executed.</para> + + <variablelist> + <varlistentry> + <term>Old way:</term> + <listitem><para>src/model/com/domain/projectname/model/EntityName.java</para></listitem> + <listitem><para>src/action/com/domain/projectname/model/EntityNameHome.java</para></listitem> + <listitem><para>src/action/com/domain/projectname/model/EntityNameList.java</para></listitem> + </varlistentry> + + <varlistentry><term>New way:</term> + <listitem><para>src/model/com/domain/projectname/model/EntityName.java</para></listitem> + <listitem><para>src/action/com/domain/projectname/action/EntityNameHome.java</para></listitem> + <listitem><para>src/action/com/domain/projectname/action/EntityNameList.java</para></listitem> + </varlistentry> + </variablelist> + + + <para>Home and Query objects are <quote>action</quote> components, not <quote>model</quote> components + and are therefore placed in the action package. This change makes the + conventions followed by generate-entities consistent with the conventions + used in the new-entity command.</para> + + <para>Remember, model classes are kept separate because they cannot be hot reloaded.</para> + + <para>Due to the change from JBoss Embeddable EJB3 to JBoss Embedded for testing, + it is recommended that you generate a project using seam-gen from Seam 2 + and borrow the <literal>build.xml</literal> file from that project. If you have made + significant changes to the <literal>build.xml</literal> in your project, you may want to focus + on just migrating the test-related targets.</para> + + <para>In order for tests to work under JBoss Embedded, you need to change the + value of the &lt;datasource&gt; element in <literal>resources/META-INF/persistence-test.xml</literal> + (or <literal>persistence-test-war.xml</literal>) to <literal>java:/DefaultDS</literal>. The alternative is to + deploy a <literal>*-ds.xml</literal> file to the <literal>bootstrap/deploy</literal> folder and use the JNDI name + defined by that file.</para> + + <para>If you use the <literal>build.xml</literal> from a Seam 2 seam-gen project, you will also need + the <literal>deployed-*.list</literal> file(s). These files define which JAR files are packaged + in the EAR or WAR. They were introduced to externalize this set of JARS from + the <literal>build.xml</literal> file.</para> + + <para>To accommodate a change in the RichFaces panel, you need to add the following + style to your stylesheet. Otherwise, you're search criteria block in pages + created by generate-entities will bleed into the table of results.</para> + +<programlisting><![CDATA[.rich-stglpanel-body { + overflow: auto; +}]]></programlisting> + + + </section> </section> </chapter> Modified: branches/enterprise/JBPAPP_4_3_FP01/seam2migration.txt =================================================================== --- branches/enterprise/JBPAPP_4_3_FP01/seam2migration.txt 2008-11-07 11:53:51 UTC (rev 9525) +++ branches/enterprise/JBPAPP_4_3_FP01/seam2migration.txt 2008-11-07 13:15:03 UTC (rev 9526) @@ -1,6 +1,6 @@ Seam 2.0 Migration Guide ======================== -Before you get started with Seam2, you'll need to make a few changes to +Before you get started with Seam 2, you'll need to make a few changes to your existing code and configuration. This process should not be too painful - if you get stuck, just refer back to the updated Seam examples. @@ -12,23 +12,49 @@ you'll need to make some changes to web.xml: * remove the MyFaces StartupServletContextListener -* remove the Ajax4JSF filter and mappings +* remove the Ajax4JSF filter, mappings, and + org.ajax4jsf.VIEW_HANDLERS context parameter * rename org.jboss.seam.web.SeamFilter to org.jboss.seam.servlet.SeamFilter +* rename org.jboss.seam.servlet.ResourceServlet to + org.jboss.seam.servlet.SeamResourceServlet +* change the web-app version from 2.4 to 2.5 + also change j2ee to javaee in namespace URL +<web-app xmlns="http://java.sun.com/xml/ns/javaee" + xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" + xsi:schemaLocation=" + http://java.sun.com/xml/ns/javaee + http://java.sun.com/xml/ns/javaee/web-app_2_5.xsd" + version="2.5"> + ... +</web-app> -Also note that for the JSF RI, client-side state saving is not required. +Since Seam 1.2, you didn't need any declarations of SeamExceptionFilter +or SeamRedirectFilter in web.xml, just a single declaration of SeamFilter. +Make sure you've already made that change. +Also note that for the JSF RI, client-side state saving, defined by +the context param javax.faces.STATE_SAVING_METHOD, is not required +and can be removed (server is the default). + You'll also need to make some changes to faces-config.xml: -* Remove the (Tranactional)SeamPhaseListener declaration +* Remove the TranactionalSeamPhaseListener or SeamPhaseListener declaration, + whichever is currently in use * Remove the SeamELResolver declaration, if you have one * Change the declaration of SeamFaceletViewHandler to the standard - com.sun.facelets.FaceletViewHandler + com.sun.facelets.FaceletViewHandler (and make sure it's enabled) +* Remove the DTD on the document and add the XML Schema declarations to the + root tag (<faces-config>) +<faces-config version="1.2" + xmlns="http://java.sun.com/xml/ns/javaee" + xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" + xsi:schemaLocation=" + http://java.sun.com/xml/ns/javaee + http://java.sun.com/xml/ns/javaee/web-facesconfig_1_2.xsd"> + ... +</faces-config> -Since Seam 1.2, you didn't need any declarations of SeamExceptionFilter -or SeamRedirectFilter in web.xml, just a single declaration of SeamFilter. -Make sure you've already made that change. - Code migration -------------- Seam's built-in components have undergone a major reorganization designed @@ -38,6 +64,7 @@ * Persistence-related components moved to org.jboss.seam.persistence * jBPM related components moved to org.jboss.seam.bpm * JSF-related components moved org.jboss.seam.faces + most significantly org.jboss.seam.faces.FacesMessages * Servlet-related components have moved to org.jboss.seam.web * Components related to asynchronicity moved to org.jboss.seam.async * i18n-related components moved to org.jboss.seam.international @@ -79,29 +106,57 @@ You'll need to update your components.xml file to reflect the new schemas and namespaces. Take a look at the Seam examples if you're unsure of -exactly what you need to do. +exactly what you need to do. Specifically, you are changing the namespace +URLs to match the Seam version (i.e., 2.0 or 2.1). -Finally, some declarations must be removed completely: +Some declarations have moved or must be removed completely: -* remove <conversation-is-long-running-parameter> from <core:init/> +* replace <core:managed-persistence-context> and <core:entity-manager-factory> with + <persistence:managed-persistence-context> and + <persistence:entity-manager-factory>, respectively +* remove conversation-is-long-running-parameter attribute from <core:manager/> * remove <core:ejb/> * remove <core:microcontainer/> -* replace <core:transaction-listener/> with - <transaction:ejb-transaction/> +* replace <core:transaction-listener/> with <transaction:ejb-transaction/> * replace <core:resource-bundle/> with <core:resource-loader/> -Note: Seam transaction management is now enabled by default. If you want - to disable use of Seam-managed transactions, use the following: +Note: Seam transaction management is now enabled by default. It's now + controlled in components.xml rather than by a JSF phase listener + declaration in faces-config.xml. If you want to disable use of + Seam-managed transactions, use the following: - <core:init transaction-management-enabled="false"/> + <core:init transaction-management-enabled="false"/> -Note: The expression attribute on event action's has been deprecated in favor of - execute e.g.: +Note: The expression attribute on event action's has been deprecated in favor + of execute, e.g. - <event type="org.jboss.seam.notLoggedIn"> + <event type="org.jboss.seam.security.notLoggedIn"> <action execute="#{redirect.captureCurrentView}"/> </event> + <event type="org.jboss.seam.loginSuccessful"> + <action execute="#{redirect.returnToCapturedView}"/> + </event> +In 2.1 the security events use the prefix org.jboss.seam.security instead of +just org.jboss.seam (e.g. org.jboss.seam.security.notLoggedIn). Note that the +event org.jboss.seam.security.loginSuccessful event should be used in place of +org.jboss.seam.postAuthenticate for returning to the captured view. + +Migration to JBoss Embedded +--------------------------- +Support for deployment to JBoss Embeddable EJB3 and JBoss Microcontainer +has been removed. Instead, the new JBoss Embedded distribution gives you +a full set of EE-compatible APIs with simplified deployment. + +For testing, you need the jars in Seam's lib/ directory, together with the +bootstrap/ directory in your classpath. SeamTest will automatically start +the container. You can remove any references or artifacts related to the +JBoss Embeddable EJB3 (e.g., embedded-ejb folder and jboss-beans.xml). Refer +to the Seam examples or seam-gen if you have trouble. + +Note that JBoss Embedded is able to bootstrap a datasource from a -ds.xml +file, so there is no longer a need for jboss-beans.xml. + Migration to JBPM 3.2 --------------------- If you are using JBPM for business processes (not just pageflows), you need @@ -111,12 +166,13 @@ Migration to RichFaces 3.1 -------------------------- If you are using RichFaces or Ajax4jsf, a major reorganisation of the codebase -has occurred. ajax4jsf.jar and richfaces.jar have been replaced by +has occurred. The JARs ajax4jsf.jar and richfaces.jar have been replaced by richfaces-api.jar (which should go in your ear lib/ directory) and richfaces-impl.jar and richfaces-ui.jar (both of which go in WEB-INF/lib). -s:selectDate has been deprecated in favor of rich:calendar. No more -development will be done on s:selectDate. +<s:selectDate> has been deprecated in favor of <rich:calendar>. No more +development will be done on <s:selectDate>. You can remove the styles related +to the data picker from your stylesheet to save on unnecessary bandwidth use. You should check the RichFaces documentation for more information on parameter name changes and namespace changes. @@ -130,10 +186,16 @@ Changes to Seam UI ------------------ -* s:decorate has become a naming container. Therefore client ids have changed - from fooForm:fooInput to fooForm:foo:fooInput (assuming your s:decorate has - foo as an id. +* <s:decorate> has become a naming container. Therefore client ids have changed + from fooForm:fooInput to fooForm:foo:fooInput, assuming the following declaration +<h:form id="fooForm"> + <s:decorate id="foo"> + <h:inputText id="fooInput" value="#{bean.property}"/> + </s:decorate> +</h:form> +If you don't provide an id to <s:decorate>, one will be generated by JSF. + Changes to seam-gen ------------------- @@ -155,7 +217,32 @@ Home and Query objects are "action" components, not "model" components and are therefore placed in the action package. This change makes the -convensions followed by generate-entities consistent with the convensions +conventions followed by generate-entities consistent with the convensions used in the new-entity command. Remember, model classes are kept separate because they cannot be hot reloaded. + +Due to the change from JBoss Embeddable EJB3 to JBoss Embedded for testing, +it is recommended that you generate a project using seam-gen from Seam 2 +and borrow the build.xml file from that project. If you have made +significant changes to the build.xml in your project, you may want to focus +on just migrating the test-related targets. + +In order for tests to work under JBoss Embedded, you need to change the +value of the <datasource> element in resources/META-INF/persistence-test.xml +(or persistence-test-war.xml) to java:/DefaultDS. The alternative is to +deploy a -ds.xml file to the bootstrap/deploy folder and use the JNDI name +defined by that file. + +If you use the build.xml from a Seam 2 seam-gen project, you will also need +the deployed-*.list file(s). These files define which JAR files are packaged +in the EAR or WAR. They were introduced to externalize this set of JARS from +the build.xml file. + +To accomodate a change in the RichFaces panel, you need to add the following +style to your stylesheet. Otherwise, you're search criteria block in pages +created by generate-entities will bleed into the table of results. + +.rich-stglpanel-body { + overflow: auto; +}