SeamFramework.orgCommunity Documentation
Before you get started with Seam 2.3, there are a few things you should be aware of. This process should not be too painful - if you get stuck, just refer back to the updated Seam examples in Seam distribution.
This migration guide assumes you are using Seam 2.2, if you are migrating from
Seam 1.2 or 2.0, see the jboss-seam-x.y.z.Final/seam2migration.txt
and jboss-seam-x.y.z.Final/seam21migration.txt
guide as well.
XML schemas for validation Files that use the Seam 2.2 XSDs should be updated to refer to
the 2.3 XSDs, notice the version change. Current namespace pattern is www.jboss.org/schema/seam/*
and schemaLocation URL was changed to www.jboss.org/schema/seam/*_-2.3.xsd
, where *
is Seam module.
Following snippet is an example of component declaration for 2.2 version:
Example 4.1. Before migration of Seam components.xml
<?xml version="1.0" encoding="UTF-8"?>
<components xmlns="http://jboss.com/products/seam/components"
xmlns:core="http://jboss.com/products/seam/core"
xmlns:persistence="http://jboss.com/products/seam/persistence"
xmlns:security="http://jboss.com/products/seam/security"
xmlns:theme="http://jboss.com/products/seam/theme"
xmlns:cache="http://jboss.com/products/seam/cache"
xmlns:web="http://jboss.com/products/seam/web"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xsi:schemaLocation=
"http://jboss.com/products/seam/core http://jboss.com/products/seam/core-2.2.xsd
http://jboss.com/products/seam/persistence http://jboss.com/products/seam/persistence-2.2.xsd
http://jboss.com/products/seam/security http://jboss.com/products/seam/security-2.2.xsd
http://jboss.com/products/seam/theme http://jboss.com/products/seam/theme-2.2.xsd
http://jboss.com/products/seam/cache http://jboss.com/products/seam/cache-2.2.xsd
http://jboss.com/products/seam/web http://jboss.com/products/seam/web-2.2.xsd
http://jboss.com/products/seam/components http://jboss.com/products/seam/components-2.2.xsd">
And finally migrated declaration of components.xml
for 2.3 version:
Example 4.2. Migrated components.xml
<?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">
Next remainning migration step is pages.xml
file(s) as well as other files only requires that the schemas be upgraded.
Example 4.3. Before migration of Seam pages.xml
<?xml version="1.0" encoding="UTF-8"?>
<pages xmlns="http://jboss.com/products/seam/pages"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xsi:schemaLocation="http://jboss.com/products/seam/pages http://jboss.com/products/seam/pages-2.2.xsd">
...
</pages>
Example 4.4. After migration of Seam pages.xml
<?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.3.xsd">
...
</pages>
Seam 2.3 technology upgrade includes also Java EE 6 upgrade so you need to update the following descriptors
persistence.xml
for using JPA 2web.xml
for using Servlet 3.0 and Web application application.xml
for using Enterprise Java 6 applicationfaces-config.xml
if you need to specify some advanced configuration for JSF 2
(this desciptor file is not mandatory, you don't have to use/include it in your application)Examples of changed headers with correct versions are the following:
Example 4.5. persistence.xml
<persistence xmlns="http://java.sun.com/xml/ns/persistence"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xsi:schemaLocation="http://java.sun.com/xml/ns/persistence http://java.sun.com/xml/ns/persistence/persistence_2_0.xsd"
version="2.0">
Example 4.6. application.xml
<application 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/application_6.xsd"
version="6">
Example 4.7. web.xml
<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_3_0.xsd"
version="3.0">
Example 4.8. faces-config.xml
<?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">
Seam 2.3 can integrate with the major upgrades in Java EE (from 5 to 6). You can use persistence with JPA 2, EJB 3.1 and Bean Validation. Almost all EE 6 technology upgrade requires to change XML schema declaration. See Section 4.1.2, “Java EE 6 schema changes”
Bean Validation is a standard included in Java EE 6 as new technology. Seam already uses for validation Hibernate Validator which is a reference implementation.
You need to migrate from using of org.hibernate.validator.*
Hibernate validator annotations to javax.validation.constraint.*
equivalent
for instance Seam examples used a lot of the following annotations and you can use this list as a helper (Using Bean Validation):
org.hibernate.validator.Length
to javax.validation.constraint.Size
,org.hibernate.validator.NotNull
to javax.validation.constraint.NotNull
,org.hibernate.validator.Pattern
to javax.validation.constraint.Pattern
.Configuration file faces-config.xml
is not required to be in your application, so for simple using of JSF 2 you need to migrate only web.xml
.
If you anyway would like to have it, change the XML schema declaration as is described in Example 4.8, “faces-config.xml”.
All your application JSF templates should use only facelets technology as JSP is deprecated.
In facelet templates there are required to convert <head>
/<body>
tags to ><h:head>
/<h:body>
respectively.
Depending on what JSF components that you use like Richfaces or Icefaces, there has to 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. This migration doesn't cover these migration steps.
Using JPA 2 requires to change version to 2.0 in persistence.xml
, see Example 4.5, “persistence.xml” file and version in application.xml
should be 6
if you are using EAR - see Example 4.6, “application.xml” or version in web.xml
file change to 3.0 if you use only WAR - look at Example 4.7, “web.xml”.
What is important for developers, most application can use just WAR with EJB 3.1 and doesn't have to package application as EAR.
JPA 2.0 is backward compatible with JPA 1.0, so you don't have to migrate any JPA annotation or classes. JPA 2.0 is more like enhancement to JPA 1.0.
Java EE 6 brings new standardized global rules for creating portable JNDI syntax. So you have to change all JNDI strings from
_your_application_/#{ejbName}/local
to java:app/_application-module-name_/#{ejbName}
like
for instance in WEB-INF/components.xml
change of jndiPattern
from:
seam-mail/#{ejbName}/localto
java:app/seam-mail-ejb/#{ejbName}
Next level is migration of your target runtime. Seam 2.3 uses JBoss AS 7 as default target runtime.
If you are using for development or testing default datasource in JBoss AS 7.1,
you need to change datasource JNDI in your persistence.xml
from java:/DefaultDS
to java:jboss/datasources/ExampleDS
.
JBoss AS 7 has got refactored classloading model. Classloading of bundled or provided libraries can be managed in
jboss-deployment-structure.xml
or in META-INF/MANIFEST.MF
file in section Dependencies
. This migration documentation prefers using of jboss-deployment-structure.xml
file, which should be placed in META-INF
directory of your WAR or EAR application according to your application type.
For full EAR projects, the jboss-deployment-structure.xml
will be located in the _your_ear_/META-INF
directory.
For Web (non-ear) projects, the jboss-deployment-structure.xml
will be located in the _your_war_/WEB-INF
directory.
Minimal content for Seam 2.3 based application is:
<jboss-deployment-structure xmlns="urn:jboss:deployment-structure:1.0">
<deployment>
<dependencies>
<module name="org.dom4j" export="true"/>
<module name="org.apache.commons.collections" export="true"/>
<module name="javax.faces.api" export="true"/> <!-- keep there only if you use JSF as view technology -->
</dependencies>
</deployment>
</jboss-deployment-structure>
More details are described in JBoss AS 7 documentation.
You can also include now any database descriptor (*-ds.xml) files into your project in the META-INF
directory, and 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 datasource file was a simple xml based file, but now is an IronJacamar based file. Iron-Jacamar is the JBoss' JCA (Java Connector Architecture) project. Below on Example 4.9, “Sample Seam 2.2 Datasource Descriptor File” is the former datasource for JBoss AS 4/5, and Example 4.10, “Ironjacamar Datasource Descriptor File” shows the conversion to IronJacamar using the same driver, url, and credentials.
Example 4.9. Sample Seam 2.2 Datasource Descriptor File
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE datasources
PUBLIC "-//JBoss//DTD JBOSS JCA Config 1.5//EN"
"http://www.jboss.org/j2ee/dtd/jboss-ds_1_5.dtd">
<datasources>
<local-tx-datasource>
<jndi-name>seamdiscsDatasource</jndi-name>
<connection-url>jdbc:hsqldb:.</connection-url>
<driver-class>org.hsqldb.jdbcDriver</driver-class>
<user-name>sa</user-name>
<password></password>
</local-tx-datasource>
</datasources>
Example 4.10. Ironjacamar Datasource Descriptor File
<?xml version="1.0" encoding="UTF-8"?>
<datasources xmlns="http://www.jboss.org/ironjacamar/schema">
<datasource
jndi-name="java:/jboss/seamdiscsDatasource"
enabled="true"
use-java-context="true" pool-name="seamdiscs">
<connection-url>jdbc:hsqldb:.</connection-url>
<driver>org.hsqldb.jdbcDriver</driver>
<security>
<user-name>sa</user-name>
<password></password>
</security>
</datasource>
</datasources>
SeamTest and JBoss Embedded are legacy components and have many limitations and we doesn't support it like we did in Seam 2.2.
We now bring Arquillian as the replacement of JBoss Embedded and you should extend
org.jboss.seam.mock.JUnitSeamTest
instead of org.jboss.seam.mock.SeamTest
,
DBUnit testing is provided by org.jboss.seam.mock.DBJUnitSeamTest
instead of org.jboss.seam.mock.DBUnitSeamTest
.
Due assertion issues with TestNG framework and Arquillian, we use JUnit as preferred test framework. Migration to Junit and
Arquillian goes in the following steps:
@RunWith(Arquillian.class)annotation to your test class.
org.jboss.seam.mock.JUnitSeamTest
instead of org.jboss.seam.mock.SeamTest
.@Deployment(name="_your_test_name_")for creating test deployment archive. The following example is taken from Registration example testsuite. It imports the .ear archive buit with "mvn package", adds the test class to the deployment and replaces the WEB-INF/web.xml file with a SeamTest-specific version.
@OverProtocol("Servlet 3.0")
public static org.jboss.shrinkwrap.api.Archive<?> createDeployment(){}
@Deployment(name="RegisterTest")
@OverProtocol("Servlet 3.0")
public static Archive<?> createDeployment()
{
EnterpriseArchive er = ShrinkWrap.create(ZipImporter.class, "seam-registration.ear").importFrom(new File("../registration-ear/target/seam-registration.ear"))
.as(EnterpriseArchive.class);
WebArchive web = er.getAsType(WebArchive.class, "registration-web.war");
web.addClasses(RegisterTest.class);
// Install org.jboss.seam.mock.MockSeamListener
web.delete("/WEB-INF/web.xml");
web.addAsWebInfResource("web.xml");
return er;
}
<?xml version="1.0" ?>
<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">
<listener>
<listener-class>org.jboss.seam.mock.MockSeamListener</listener-class>
</listener>
</web-app>
arquillian.xml
file into root of your classpath for running Arquillian test(s). The file content should specify path to
remote or managed container and some specific options for JVM or Arquillian. The example of arquillian file is at
jboss-seam-x.y.z.Final/examples/booking/booking-tests/src/test/resources-integration/arquillian.xml
:
<?xml version="1.0" encoding="UTF-8"?>
<arquillian xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xmlns="http://jboss.org/schema/arquillian"
xsi:schemaLocation="http://jboss.org/schema/arquillian http://jboss.org/schema/arquillian/arquillian_1_0.xsd">
<engine>
<property name="deploymentExportPath">target/</property>
</engine>
<container qualifier="jboss" default="true">
<configuration>
<property name="javaVmArguments">-Xmx1024m -XX:MaxPermSize=512m</property>
<property name="jbossHome">target/jboss-as-${version.jbossas7}</property>
</configuration>
</container>
</arquillian>
More details in Seam reference documentation guide in Section 38.2, “Integration testing Seam components”.
The "provided" platform is now JBoss AS 7.1.x as is written above, therefore all Java EE dependencies included in AS 7 are now marked as provided.
A Bill of materials is a set of dependeny elements in <dependencyManagement>
section that can be used to import into your application maven build and be able to declare which dependencies and their versions that you wish to use in your application. The nice thing about the Seam BOM is that the dependencies and their versions are there recommended dependencies that would work well with Seam 2.3. The usage of Seam BOM is shown in Example 4.11, “Seam BOM usage”. The Seam BOM is deployed in JBoss Maven repository.
Example 4.11. Seam BOM usage
<dependencyManagement>
<dependencies>
<dependency>
<groupId>org.jboss.seam</groupId>
<artifactId>bom</artifactId>
<version>2.3.0.Final</version>
<type>pom</type>
<scope>import</scope>
</dependency>
...
</dependencies>
</dependencyManagement>
<dependencies>
<dependency>
<groupId>org.jboss.seam</groupId>
<artifactId>jboss-seam</artifactId>
<type>ejb</type>
<dependency>
...
</dependencies>