jboss seam reference 2.3（第4章）
jboss seam reference 2.3 Final
24.09.2012
第四章 从2.2迁移到2.3
在你开始Seam 2.3以前，有一些事情你应该注意。这个过程应该不是太痛苦——如果被卡住了，只是回来参考在Seam分发版中的更新Seam例子即可。
这个迁移指南假设你正在使用Seam2.2，如果你正从Seam 1.2 或 2.0迁移，请看jboss-seam-x.y.z.Final/seam2migration.txt 以及jboss-seam-x.y.z.Final/seam21migration.txt。
4.1 XML架构（Schemas）迁移
4.1.1 Seam架构迁移
使用Seam 2.2 XSDs的验证文件的XML架构应该被升级为引用2.3 XSDs，注意版本更改。当前的命名空间模式是 www.jboss.org/schema/seam/*，而schemaLocation URL 被改成了 www.jboss.org/schema/seam/*_-2.3.xsd， *处是Seam模块。
下面是2.2版本的一个组件声明例子的片断：
例子4.1 在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">
最终，2.3版的components.xml迁移声明：
例子4.2 被迁移的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">
接下来剩下的迁移步骤是pages.xml文件，以及仅需要架构被升级的的其他文件。
例子4.3 在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>
例子4.3 在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>
4.1.2. Java EE 6架构变化
Seam2.3升级还包括Java EE 6升级，所以你需要升级下面的描述符：
l 为使用JPA 2的persistence.xml
l为使用Servlet 3.0和网页应用程序的web.xml
l为使用企业Java 6应用程序的application.xml
lfaces-config.xml，如果你需要为JSF2指定某些高级配置（这个描述符文件并不是强制的，你不必使用/包括它在你的应用程序中）
用正确的版本改变了头部的例子如下所示：
例子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">
例子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">
例子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">
例子4.7 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">
4.2. Java EE 6升级
Seam 2.3能够集成在Java EE (从5到6)中的主要升级。你可以使用JPA 2持久化、EJB 3.1和Bean Validation。几乎所有EE 6技术升级需要改变XML架构声明。请看章节 4.1.2, “Java EE 6架构变化”。
4.2.1. 使用Bean Validation标准，而不是Hibernate Validator
Bean Validation是包含在Java EE 6中作为新技术的一个标准。Seam已经为验证使用了一个参考实现Hibernate Validator。
你需要把使用org.hibernate.validator.*的Hibernate validator注释迁移为javax.validation.constraint.* 对等物。例如Seam例子使用了许多下面的注释，而你可以使用这个列表作为一个帮助器（使用Bean Validation）：
org.hibernate.validator.Length 改为 javax.validation.constraint.Size,
org.hibernate.validator.NotNull 改为 javax.validation.constraint.NotNull,
org.hibernate.validator.Pattern 改为 javax.validation.constraint.Pattern.
4.2.2. JSF 1到JSF 2 Facelets模板的迁移
配置文件faces-config.xml并不需要是在你的应用程序中，所以对于简单地使用JSF2，你只需迁移web.xml。如果你无论如何想使用它，改变XML架构声明，如在例子 4.8，“faces-config.xml”中所述一样。
所有你的应用程序的JSF模板应该只使用facelets技术，因为JSP是过时了。
在facelet模板中，要求分别转换 <head>/<body>标签为<h:head>/<h:body>。
根据你使用的JSF组件，如Richfaces或Icefaces，在升级JSF 1.x 到JSF 2.x时，必定有某些差异。你可能需要升级整个库。有关这些变化，请参考任何组件框架的文档。本迁移并不包含这些迁移的步骤。
4.2.3. 迁移到JPA 2.0
使用JPA 2需要在 persistence.xml中改变版本为2.0，请看例子4.5，“persistence.xml”文件，并且如果你使用EAR，在 application.xml中的版本应该为6——请看例子 4.6，“, “application.xml”，或者，如果你只使用 WAR，在web.xml文件中的版本改为3.0——请看例子4.7，“web.xml”。
对开发人员重要的是，大多数应用程序可能只使用带有EJB3.1的WAR，所以不必打包应用程序员为EAR。
JPA 2.0 是向后兼容JPA 1.0，所以你不必迁移任何JPA注释或类。JPA 2.0是更像增强版的JPA 1.0。
4.2.4. 为资源使用兼容的JNDI
Java EE 6为创建可移植JNDI语法带来了新标准化的全局规则。所以，你必须改变所有JNDI 字符串，从_your_application_/#{ejbName}/local改为 java:app/_application-module-name_/#{ejbName}，就如在WEB-INF/components.xml中jndiPattern变化的例子，把：
seam-mail/#{ejbName}/local
改为
java:app/seam-mail-ejb/#{ejbName}
4.3. JBoss AS 7.1部署
4.3.1. 部署变化
下一级是你的目标运行时（runtime）的迁移。Seam 2.3使用JBoss AS 7作为默认目标运行时。
如果你正在JBoss AS 7.1中开发或测试默认数据源，你需要在你的persistence.xml中改变数据源，从java:/DefaultDS 和java:jboss/datasources/ExampleDS。
JBoss AS 7有一个重构的类加载模型。绑定的类加载或提供的库可以在jboss-deployment-structure.xml 或在 META-INF/MANIFEST.MF 文件中的Dependencies部分中被管理。本迁移文档更喜欢使用jboss-deployment-structure.xml文件，根据你的应用程序类型，它被放在你的WAR或 EAR应用程序的 META-INF目录中。
对于完整EAR项目， jboss-deployment-structure.xml将会被放在 _your_ear_/META-INF目录中。
对于Web（非ear）项目，jboss-deployment-structure.xml 将会被放在_your_war_/WEB-INF目录中。
基于Seam 2.3的应用程序的最小内容是：
<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>
详情请看JBoss AS 7文档。
4.3.2. 数据源迁移
你现在还可以包括任何数据源描述符（*-ds.xml）到你的项目的META-INF目录中，并且当部署到一个JBoss AS 7.1应用程序服务器时，该数据源将会被自动部署。虽然文件结构已经被改变。以前数据源文件是一个基于xml的文件，但是现在是一个基于IronJacamar的文件。 Iron-Jacamar是JBoss的 JCA (Java Connector Architecture)项目。下面的例子 4.9，“简单的Seam 2.2数据源描述符文件”是用于JBoss AS 4/5的旧数据源，而例子 4.10，“Ironjacamar数据源描述符文件”显示使用相同驱动、URL和证书转换到IronJacamar。
例子 4.9，“简单的Seam 2.2数据源描述符文件”
<?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>
例子 4.10，“Ironjacamar数据源描述符文件”
<?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>
4.4. 在测试框架中的变化
SeamTest和JBoss Embedded是遗留组件，并且有许多限制，我们不再像Seam 2.2中那样支持它了。
我们带来Arquillian作为JBoss Embedded的替代，你应该继承extendorg.jboss.seam.mock.JUnitSeamTest，而不是org.jboss.seam.mock.SeamTest，DBUnit 测试由org.jboss.seam.mock.DBJUnitSeamTest提供，而不是 org.jboss.seam.mock.DBUnitSeamTest。 由于TestNG框架和Arquillian的断言问题，我们使用JUnit作为首选测试框架。迁移到Junit和Arquillian进行以下步骤：
1. 添加
@RunWith(Arquillian.class)
注释你的测试类。
2. 你的测试类应该继承org.jboss.seam.mock.JUnitSeamTest，而不是org.jboss.seam.mock.SeamTest。
3. 添加一个方法，像
@Deployment(name="_your_test_name_")
@OverProtocol("Servlet 3.0")
public static org.jboss.shrinkwrap.api.Archive<?> createDeployment(){}
为创建测试部署档案。以下例子取自Registration例子测试套件。它导入了用"mvn package"构建的.ear档案， 添加了测试类给部署，并且用一个特定SeamTest版本替换WEB-INF/web.xml文件。
@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;
}
4. 创建一个特定SeamTest的 web.xml，包含了org.jboss.seam.mock.MockSeamListener，而不是普通的 org.jboss.seam.servlet.SeamListener。
<?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>
5. 为运行Arquillian 测试，添加arquillian.xml文件到你的类路径的根。该文件内容应该指定你的类路径到远程或管理容器，以及为 JVM 或 Arquillian指定某些选项。Arquillian文件的的例子是在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>
详情请看Seam参考文档的章节38.2，“集成测试Seam组件”。
4.5. 使用Maven的依赖变化
如上所述，“提供”平台现在是JBoss AS 7.1.x，因此所有包括在AS 7中Java EE 依赖现在都被标记为提供。
4.5.1. Seam材料单
材料单是在 <dependencyManagement> 部分中的一组依赖元素，其能够被用来导入到你的应用程序的maven构建中，并且能够声明你希望在你的应用程序中使用那个依赖和它们的版本。关于Seam BOM这种做法的好处是在这儿依赖和它们的版本是与Seam 2.3很好配合工作的推荐依赖。Seam BOM的用法在例子4.11，“Seam BOM用法”中被展示。Seam BOM被部署在JBoss Maven仓库
例子4.11，“Seam BOM用法”
<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>