Author: dhinojosa Date: 2012-09-15 23:53:38 -0400 (Sat, 15 Sep 2012) New Revision: 15144 Modified: branches/community/Seam_2_3/seam-migration-guide/seam_migration_guide.asc Log: added module dependency information 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-14 13:43:43 UTC (rev 15143) +++ branches/community/Seam_2_3/seam-migration-guide/seam_migration_guide.asc 2012-09-16 03:53:38 UTC (rev 15144) @@ -26,9 +26,9 @@ [[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. +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. -Taking the folder structure of the *registration* module in the *examples-ee6* folder of the Seam 2.3. distribution. The <<figure1,registration folder structure>> shown below shows the typical setup. +Taking the folder structure of the 'registration' module in the 'examples-ee6' folder of the Seam 2.3. distribution. The <<figure1,registration folder structure>> shown below shows the typical setup. .Typical ear project structure [[figure1]] @@ -37,13 +37,13 @@ The pom.xml in the bottom of the diagram is the parent pom that contains modules for `registration-ear`, `registration-web`, `registration-test`, and `registration-ejb`. It will also contain http://http://maven.apache.org/pom.html#Plugin_Management[plugin management] and http://maven.apache.org/guides/introduction/introduction-to-dependency-me... management] information for each of the submodules. Inside of each module, there is another child pom that has information on it's own dependencies and plugins. ==== Ear Module -The ear project submodule will typically contain all ear based configurations with no source files whatsoever. The module is short, since not much needs to be held within it. <<figure2, Figure 2>> contains the folder structure of what is contained inside of an ear module. The `src/main/application/META-INF` will store the configuration files necessary to create an ear file. Namely the `jboss-deployment-structure.xml` and any `*-ds.xml` iron-jacamar database descriptor file that is required for deployment. +The ear project submodule will typically contain all ear based configurations with no source files whatsoever. The module is short, since not much needs to be held within it. <<figure2, Figure 2>> contains the folder structure of what is contained inside of an ear module. The 'src/main/application/META-INF' will store the configuration files necessary to create an ear file. Namely the `jboss-deployment-structure.xml` and any `*-ds.xml` iron-jacamar database descriptor file that is required for deployment. .ear module [[figure2]] image::ear_module.png[Ear Module Structure,scaledwidth="50%",scaledheight="50%"] -First a *jboss-deployment-structure.xml* is required. +First a 'jboss-deployment-structure.xml' is required. 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. @@ -88,15 +88,16 @@ ==== Web Module To convert a web module see <<upgradingweb, Upgrading Web>> +[[eartestmodule]] ==== Test Module -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. +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 file 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. For upgrading purposes copy all existing SeamTest code and place it into the 'src/test/java' folder, from this point on some package conversion and set up is required, so for more information on upgrading `SeamTest` ! to Arquillian tests and setting up Arquillian in your Seam 2.3 project see the <<arquillian, Arquillian>> section further down this document. .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 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. @@ -105,23 +106,90 @@ image::war_folder.png[War Folder Structure,scaledwidth="50%",scaledheight="50%"] ==== Web Module -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 . +To convert a web module see <<upgradingweb, Upgrading Web>> first, and then come back. Once done, a 'jboss-deployment-descriptor.xml' needs to be added into the 'src/main/webapp/WEB-INF' directory 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 look like <<figure6, Figure 6>>. +.Typical War Module Structure +[[figure6]] +image::war_with_config_module.png[War Module Structure within a War Project,scaledwidth="50%",scaledheight="50%"] + ==== Test Module -Test stuff +The test module here does the same thing as was stated in <<eartestmodule, the test module in the ear section>>, it is meant to house former `SeamTest` as a new Arquillian based test in the 'src/test/java' folder. An 'arquillian.xml' file is also required to be placed in the 'src/test/resources-integration' folder. For a refresher, the test module should look like <<figure4, Figure 4>> above. == Dependencies -Dependencies +In each of the maven modules, the dependencies that used depends on what type of module you are creating and what you need. For example, most web based libraries will be required for the web modules, dependencies that are shared are typically stored in the ear module. The parent `pom` file will typically have dependency that would also be optionally shared by other modules in the application. Before breaking down what is required for all diffent modules, ear, web, ejb, and parent, a definition of a bill of materials or _BOM_ is in order. === Bill of Materials -Bill of Materials +A bill of materials is a set of `<dependencyManagement>` elements that can be used to import into a module of your choice and be able to declare which dependencies that you wish to use in your application. The nice thing about the bill of materials is that the dependencie and their versions are the recommended dependencies that would work well with Seam 2.3. This takes the guess work out of which dependencies would react best with the others. The bill of materials used for Seam 2.3 can be found at the maven `groupID`, `org.jboss.seam`, the `artifactID`, `bom` and the version would be whatever version of Seam 2.3 you are using. The bill of materials is on maven central as well as JBoss repositories. In the next section, when defining the parent pom we make use of importing the Seam 2.3 bill of materials. +=== Parent Pom Dependencies +Within the parent pom file, declare a `<dependencyManagement>` element that will house the dependencies that will be used by the child projects (war, ejb, tests). Please note the `<scope>import</scope>` that is used that allows Maven to import all the dependencies into the parent to treat it as its own set of dependencies. <<listing15, Listing 15>> shows a clip of what the `<dependencyManagement>` element will look like. Remember that `<dependencyManagement>` is a direct descendant of the `<project>` element and is not included in the `<build>` element. Once this is established all child projects can use the version of the dependencies as stated in the bill of materials. + +You may choose in the parent to set up some `<dependencies>` outside of `<dependencyManagement>` if there are some hard dependencies that you wish for your child projects to use. + +.Listing 15: Sample dependency management setting in the parent pom module +[[listing15]] +---- +... +<dependencyManagement> + <dependencies> + <dependency> + <groupId>org.jboss.seam</groupId> + <artifactId>bom</artifactId> + <version>2.3.0.Final</version> + <type>pom</type> + <scope>import</scope> + </dependency> + <dependency> + <groupId>org.richfaces</groupId> + <artifactId>richfaces-bom</artifactId> + <version>4.2.2.Final</version> + <type>pom</type> + <scope>import</scope> + </dependency> + </dependencies> +</dependencyManagement> +... +---- + +=== Ear Module Dependencies +Inside of the 'pom.xml' file for ear module's the only dependencies that are required are the child dependencies that are needed by the ear file and the maven ear plugin. In the blog example, as seen in <<listing16, Listing 16>>, the ear module depends on the web module it will contain, the ejb module it will contain, and the JBoss Seam 2.3 dependency that it relies since both the war file and the ejb jar file will require the seam 2.3 core classes to loaded. This uses the arbitrary version, `1.0-SNAPSHOT`. This version will be whatever version of project you are on. Take note that each of these dependencies have a `<type>` element that declares the type of dependency that is required, this will be used by the Maven ear plugin that creates the ear file during Maven's `package` phase in the default lifecycle. One last note, notice that there is no version set for `org.jboss.seam:jboss-seam` this is because the version was already establish by the bill of materials as was *im! ported* in the parent pom. Since the ear module is a child of the parent pom, if a dependency is required, then only the groupId and artifactId is required, the rest of the information can be optionally left out. + +.Listing 16: Sample dependency list in an ear module +[[listing16]] +---- +<dependencies> + <dependency> + <groupId>org.jboss.seam.examples-ee6.blog</groupId> + <artifactId>blog-web</artifactId> + <version>1.0-SNAPSHOT</version> + <type>war</type> + </dependency> + <dependency> + <groupId>org.jboss.seam.examples-ee6.blog</groupId> + <artifactId>blog-ejb</artifactId> + <version>1.0-SNAPSHOT</version> + <type>ejb</type> + </dependency> + <dependency> + <groupId>org.jboss.seam</groupId> + <artifactId>jboss-seam</artifactId> + <type>ejb</type> + <scope>compile</scope> + </dependency> +</dependencies> +---- + +=== EJB Module Dependencies +EJB Module Dependencies here + + + == 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. +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]] @@ -140,13 +208,13 @@ </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 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. +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. +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]] @@ -198,7 +266,7 @@ 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. +'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]] @@ -225,7 +293,7 @@ </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. +Upgrading 'pages.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]] @@ -337,7 +405,7 @@ </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. +'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]]