[seam-commits] Seam SVN: r15138 - branches/community/Seam_2_3/seam-migration-guide.

Author: dhinojosa Date: 2012-09-13 17:26:57 -0400 (Thu, 13 Sep 2012) New Revision: 15138 Modified: branches/community/Seam_2_3/seam-migration-guide/seam_migration_guide.asc Log: rearranged items Modified: branches/community/Seam_2_3/seam-migration-guide/seam_migration_guide.asc =================================================================== --- branches/community/Seam_2_3/seam-migration-guide/seam_migration_guide.asc 2012-09-13 18:04:04 UTC (rev 15137) +++ branches/community/Seam_2_3/seam-migration-guide/seam_migration_guide.asc 2012-09-13 21:26:57 UTC (rev 15138) @@ -23,6 +23,7 @@ The following are description on how to organize Seam 2.3 project in the Maven build tool environment. +[[earprojectorganization]] === Ear Project Organization The folder organization of Seam 2.3 in Maven typically consists of one main project, the `pom` project. The `pom` project in Maven, is the project that doesn't have any source files onto itself but contains the projects that are required for the build. In an ear based project. Inside of the `pom` ear based project folder contains three subfolders one for the ear project, one for the war project, one for the arquillian (formerly seam test) project, and one for the ejb project. Given a parent `pom` project called `myproject`, some ideas for the the subfolders would include `myproject-ear`, `myproject-web`, `myproject-test`, and `myproject-ejb`. You can refer to the examples in the *examples-ee6* folder for some general ideas as to how to create the folder organization for your Seam 2.3 project. @@ -42,25 +43,8 @@ [[figure2]] image::ear_module.png[Ear Module Structure,scaledwidth="50%",scaledheight="50%"] -The `jboss-deployment-structure.xml` file contains what resources will be made available by the Jboss 7.1.1 server modules. In order to investigate what modules are available by your Jboss server navigate to the `modules` directory on whatever server type you will be running. If you are a running a `standalone` server then the modules directory will be located in the `$JBOSS_HOME/server/standalone/modules` directory. If you wish to call up the dependencies so that they are in use for your project, and so that you do not have to package those dependencies select which server libraries should be used in your project. `export` means that the dependencies will be exported, so any module that depends on this module will also get access to the dependency. See https://docs.jboss.org/author/display/AS7/Class+Loading+in+AS7[Classloading in AS7] for more information jboss-deployment-structure. <<listing1, Listing1>> shows an example of the jboss-deployment-structure.xml that makes ! use of system dependencies where export="true" will make them available to any dependency jar and war files within the ear file. +First a *jboss-deployment-structure.xml* is required. -.Listing 1: Sample jboss-deployment-structure.xml -[[listing1]] ----- -<jboss-deployment-structure xmlns="urn:jboss:deployment-structure:1.0"> - <deployment> - <dependencies> - <module name="org.hibernate" export="true"/> - <module name="javax.faces.api" export="true"/> - <module name="com.sun.jsf-impl" export="true"/> - <module name="org.apache.commons.collections" export="true"/> - <module name="org.dom4j" export="true"/> - <module name="org.antlr" export="true"/> - </dependencies> - </deployment> -</jboss-deployment-structure> ----- - You can also include now any database descriptor (*-ds.xml) files into your project in the META-INF directory, and they the data source will be deployed automatically when deployed to a JBoss AS 7.1 Application Server. The structure of the file though has changed. Before the ds.xml file was a simple xml based file, but now is an https://www.jboss.org/ironjacamar[Iron-Jacamar] based file. Iron-Jacamar is the Jboss' JCA (Java Connector Architecture) project. Below on <<listing2,Listing 2>> is the former datasource in 2.2, and <<listing3,Listing 3>> shows the conversion to Iron Jacamar using the same driver, url, and credentials. .Listing 2: Sample Seam 2.2 Datasource Descriptor File @@ -102,16 +86,26 @@ ---- ==== Web Module -Web stuff +To convert a web module see <<upgradingweb, Upgrading Web>> ==== Test Module -Test stuff +The test module will house former SeamTests which will now be upgraded to Arquillian based Seam Tests. The layout of the test module is simple as seen in <<figure4, Figure 4>>. All tests will be placed in the `src/test/java` folder, all resources that are required either to enhance or override current setting should be placed in the `src/test/resources/` folder. Placing source files in the `src/main/java` folder is unnecessary, since these integration tests will be using the ear, war, ejb class and jar files in their respective maven projects. A new folder is required for arquillian testing, *arquillian.xml* and should be located in the `src/test/resources-integration` folder. Though where this file gets placed is up to you, this has become also a convention. +.Test module +[[figure4]] +image::test_module.png[Ear Module Structure,scaledwidth="50%",scaledheight="50%"] + +For more information on upgrading Seam Tests to Arquillian and setting up Arquillian in your Seam 2.3 project see the <<arquillian, Arquillian>> section further down this document. + === War Project Organization -War proj stuff +If you choose not run Seam 2.3 as an ear, but as a war. A war project typically will include a parent `pom` project as mentioned in <<earprojectorganization, Ear Project Organization>> and a web project that is located inside of the `pom` project with typically the same name of the project but with "-web" extended on the name of the project, see. Though the naming is not mandatory, it has become somewhat of a convention. For an example folder layout, see <<figure5, Figure 5>> for an example folder setup of a war based project. +.Typical War Project Structure +[[figure5]] +image::war_folder.png[War Folder Structure,scaledwidth="50%",scaledheight="50%"] + ==== Web Module -Web stuff +To convert a web module see <<upgradingweb, Upgrading Web>> first the come back. Once done, a *jboss-deployment-descriptor.xml* needs to be added into the `src/main/webapp/WEB-INF` so that JBoss 7.1 can determine which dependencies to include for your project. For more information about *jboss-deployment-descriptor.xml* see <<jbossdeploymentstructure, JBoss Deployment Structure>> on how to provide Jboss with information about server dependencies. The end result, is a web module that would like the . ==== Test Module Test stuff @@ -125,6 +119,254 @@ == Using Ant Using Ant +[[jbossdeploymentstructure]] +== JBoss Deployment Structure +The *jboss-deployment-structure.xml* file contains what resources will be made available by the Jboss 7.1.1 server modules. In order to investigate what modules are available by your Jboss server navigate to the `modules` directory on whatever server type you will be running. If you are a running a `standalone` server then the modules directory will be located in the `$JBOSS_HOME/server/standalone/modules` directory. If you wish to call up the dependencies so that they are in use for your project, and so that you do not have to package those dependencies select which server libraries should be used in your project. `export` means that the dependencies will be exported, so any module that depends on this module will also get access to the dependency. See https://docs.jboss.org/author/display/AS7/Class+Loading+in+AS7[Classloading in AS7] for more information jboss-deployment-structure. <<listing1, Listing1>> shows an example of the jboss-deployment-structure.xml that makes ! use of system dependencies where export="true" will make them available to any dependency jar and war files within the ear file. + +.Listing 1: Sample jboss-deployment-structure.xml +[[listing1]] +---- +<jboss-deployment-structure xmlns="urn:jboss:deployment-structure:1.0"> + <deployment> + <dependencies> + <module name="org.hibernate" export="true"/> + <module name="javax.faces.api" export="true"/> + <module name="com.sun.jsf-impl" export="true"/> + <module name="org.apache.commons.collections" export="true"/> + <module name="org.dom4j" export="true"/> + <module name="org.antlr" export="true"/> + </dependencies> + </deployment> +</jboss-deployment-structure> +---- + +For full ear projects, the *jboss-deployment-structure.xml* will be located in the `src/main/resources/META-INF` directory of the ear module. + +For web (non-ear) projects, the *jboss-deployment-structure.xml* will be located in the `src/main/webapp/WEB-INF` directory of the war module. + +[[upgradingweb]] +== Upgrading Web Modules +The contents of the web module as shown in <<figure3, Figure 3>> displays a sample layout for the web module that would be located inside of the project parent `pom` module. The organization is straight-forward, even moreso for those who are already familiar with maven. Inside of the web project, the folder `src/main/webapp` would store all the .xhtml, .css, and other web based files, while `src/main/webapp/WEB-INF` would house all web configurations required for deployment. To succesfully migrate from Seam 2.3 from Seam 2.2, components.xml, faces-config.xml, pages.xml and any addition page files schemas will need to be upgraded. Finally, all .xhtml files will also need be upgraded by replacing all `<head>`, and `<body>` tags to `<h:head>` and `<h:body>` respectively. + +.war module +[[figure3]] +image::war_module.png[Ear Module Structure,scaledwidth="50%",scaledheight="50%"] + +In components.xml, the only real change is to upgrade the schemas used within the components to version 2.3. <<listing4, Listing 4>> and <<listing5, Listing 5>> show the contrast between both files. + +.Listing 4: Sample Seam 2.2 header of components.xml +[[listing4]] +---- +<?xml version="1.0" encoding="UTF-8"?> +<components xmlns="http://jboss.org/schema/seam/components" + xmlns:core="http://jboss.org/schema/seam/core" + xmlns:persistence="http://jboss.org/schema/seam/persistence" + xmlns:security="http://jboss.org/schema/seam/security" + xmlns:theme="http://jboss.org/schema/seam/theme" + xmlns:cache="http://jboss.org/schema/seam/cache" + xmlns:web="http://jboss.org/schema/seam/web" + xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" + xsi:schemaLocation= + "http://jboss.org/schema/seam/core http://jboss.org/schema/seam/core-2.2.xsd + http://jboss.org/schema/seam/persistence http://jboss.org/schema/seam/persistence-2.2.xsd + http://jboss.org/schema/seam/security http://jboss.org/schema/seam/security-2.2.xsd + http://jboss.org/schema/seam/theme http://jboss.org/schema/seam/theme-2.2.xsd + http://jboss.org/schema/seam/cache http://jboss.org/schema/seam/cache-2.2.xsd + http://jboss.org/schema/seam/web http://jboss.org/schema/seam/web-2.2.xsd + http://jboss.org/schema/seam/components http://jboss.org/schema/seam/components-2.2.xsd"> +---- + +.Listing 5: Sample Seam 2.3 header of components.xml +[[listing5]] +---- +<?xml version="1.0" encoding="UTF-8"?> +<components xmlns="http://jboss.org/schema/seam/components" + xmlns:core="http://jboss.org/schema/seam/core" + xmlns:persistence="http://jboss.org/schema/seam/persistence" + xmlns:security="http://jboss.org/schema/seam/security" + xmlns:theme="http://jboss.org/schema/seam/theme" + xmlns:cache="http://jboss.org/schema/seam/cache" + xmlns:web="http://jboss.org/schema/seam/web" + xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" + xsi:schemaLocation= + "http://jboss.org/schema/seam/core http://jboss.org/schema/seam/core-2.3.xsd + http://jboss.org/schema/seam/persistence http://jboss.org/schema/seam/persistence-2.3.xsd + http://jboss.org/schema/seam/security http://jboss.org/schema/seam/security-2.3.xsd + http://jboss.org/schema/seam/theme http://jboss.org/schema/seam/theme-2.3.xsd + http://jboss.org/schema/seam/cache http://jboss.org/schema/seam/cache-2.3.xsd + http://jboss.org/schema/seam/web http://jboss.org/schema/seam/web-2.3.xsd + http://jboss.org/schema/seam/components http://jboss.org/schema/seam/components-2.3.xsd"> +---- + +*faces-config.xml* has always been essentially a non-player with seam with no continous active configuration whatsoever. The roles of this file stays the same, but there is two simple items that need to be performed to upgrade it to JSF 2.1 and for it to work with Seam 2.3. First upgrade the schema from version 1.0, 1.1, or 1.2 to version 2.1 which is the latest JSF version. Next, change the `version` of the faces-config element itself. Lastly, remove the `<view-handler>` element that was once required for JBoss Seam 2.2, as it is no longer required for JBoss Seam 2.3. <<listing6, Listing 6>> and <<listing7, Listing 7>> shows the upgrade changes. + +.Listing 6: Sample Seam 2.2 faces-config.xml +[[listing6]] +---- +<?xml version="1.0" encoding="UTF-8"?> +<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"> + <application> + <view-handler>com.sun.facelets.FaceletViewHandler</view-handler> + </application> +</faces-config> +---- + +.Listing 7: Sample Seam 2.3 faces-config.xml +[[listing7]] +---- +<?xml version="1.0" encoding="UTF-8"?> +<faces-config version="2.1" + 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_2_1.xsd"> +</faces-config> +---- + +Upgrading *page.xml* files as well as other files only requires that the schemas be upgraded. <<listing8, Listing 8>> and <<listing9, Listing 9>> shows the upgrade changes. + +.Listing 8: Sample Seam 2.2 pages.xml +[[listing8]] +---- +<?xml version="1.0" encoding="UTF-8"?> +<pages xmlns="http://jboss.org/schema/seam/pages" + xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" + xsi:schemaLocation="http://jboss.org/schema/seam/pages http://jboss.org/schema/seam/pages-2.2.xsd"> + ... +</pages> +---- + +.Listing 9: Sample Seam 2.3 pages.xml +[[listing9]] +---- +<pages xmlns="http://jboss.org/schema/seam/pages" + xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" + xsi:schemaLocation="http://jboss.org/schema/seam/pages http://jboss.org/schema/seam/pages-2.3.xsd"> + ... +</pages> +---- + +Finally, all .xhtml files will need to be upgraded to JSF 2.1. While most of what was done in 1.2 can remain the same, you will be experiencing errors if certain elements are not upgraded. <<listing10, Listing 10>> and <<listing11, Listing 11>> shows the difference between the same file that has been upgraded. First, the `<body>` tag is renamed to `<h:body>` in the both the opening tag and the closing tag while `<head>` will need to be converted `<h:head>`. + +.Listing 10: Sample Seam 2.2 xhtml file (template.xhtml in blog example) +[[listing10]] +---- +<?xml version="1.0" encoding="utf-8"?> +<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" + "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"> +<html xmlns="http://www.w3.org/1999/xhtml" + xmlns:ui="http://java.sun.com/jsf/facelets" + xmlns:h="http://java.sun.com/jsf/html" + xmlns:f="http://java.sun.com/jsf/core" + xml:lang="en" + lang="en"> + +<f:view> + <head> + <meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /> + <title>#{blog.name}</title> + <link href="#{theme.css}" rel="stylesheet" type="text/css" /> + <link rel="alternate" + type="application/atom+xml" + title="atom" + href="#{request.contextPath}/seam/index.xml" /> + </head> + <body> + <div id="menu"> + <ui:include src="menu.xhtml"/> + </div> + <div id="container"> + <h1>#{blog.name}</h1> + <h2>#{blog.description}</h2> + <ui:insert name="content"/> + <div class="blogEntry"> + #{blog.name}: + <ui:include src="nav.xhtml"/> + <br/> + Total pageviews: #{blog.hitCount.pageviews} + </div> + </div> + </body> +</f:view> +</html> +---- + +.Listing 11: Sample Seam 2.3 xhtml file (template.xhtml in blog example) +[[listing11]] +---- +<?xml version="1.0" encoding="utf-8"?> +<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" + "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"> +<html xmlns="http://www.w3.org/1999/xhtml" + xmlns:ui="http://java.sun.com/jsf/facelets" + xmlns:h="http://java.sun.com/jsf/html" + xmlns:f="http://java.sun.com/jsf/core" + xml:lang="en" + lang="en"> + +<f:view> + <h:head> + <meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /> + <title>#{blog.name}</title> + <link href="#{theme.css}" rel="stylesheet" type="text/css" /> + <link rel="alternate" + type="application/atom+xml" + title="atom" + href="#{request.contextPath}/seam/index.xml" /> + + </h:head> + <h:body> + <div id="menu"> + <ui:include src="menu.xhtml"/> + </div> + <div id="container"> + <h1>#{blog.name}</h1> + <h2>#{blog.description}</h2> + <ui:insert name="content"/> + <div class="blogEntry"> + #{blog.name}: + <ui:include src="nav.xhtml"/> + <br/> + Total pageviews: #{blog.hitCount.pageviews} + </div> + </div> + </h:body> +</f:view> +</html> +---- + +*web.xml* files only require an update in the schema that they use in the first element of the file. <<listing12, Listing 12>> and <<listing13, Listing 13>> shows the difference between the *web.xml* file that has been upgraded. + +.Listing 12: Sample Seam 2.2 web.xml file +[[listing12]] +---- +<?xml version="1.0" encoding="UTF-8"?> +<web-app version="2.5" + 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"> + .... +</web-app> +---- + +.Listing 13: Sample Seam 2.3 xhtml file (template.xhtml in blog example) +[[listing13]] +---- +<?xml version="1.0" encoding="UTF-8"?> +<web-app version="3.0" + 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_3_0.xsd"> + .... +</web-app> +---- + +IMPORTANT: Depending on what JSF components that you use, there may be some differences when upgrading from JSF 1.x to JSF 2.x. You may need to upgrade libraries entirely. Consult any component framework documentation on those changes. + + + [[arquillian]] == Arquillian Seam Test migration to Arquillian Testing.