第 3 章 移植您的应用程序

1. 首先，查看您的应用程序的软件包结构及其依赖关系。详情请参考 第 3.1.2.3 节 “根据类加载的修改更新应用程序的依赖关系”。
2. 如果您的应用程序使用了日志，您需要制定正确的模块依赖关系。请查看 第 3.1.4.1 节 “修改日志依赖关系” 里的相关细节。
3. 由于模块化类加载的修改，您可能需要修改 EAR 或 WAR 的软件包结构。详情请参考 第 3.1.5.1 节 “修改 EAR 和 WAR 的打包”。

过程 3.1. 了解模块依赖关系

1. 了解隐性依赖关系

   服务器里的部署者隐性地自动添加一些常用的模块依赖关系，如javax.api 和 sun.jdk。这使得类在运行时对于部署可见，并让开发人员不用显性地添加依赖关系。关于如何和何时添加这些隐性的依赖关系，请查看 https://access.redhat.com/site/documentation/JBoss_Enterprise_Application_Platform/ 上的《JBoss EAP 6 开发指南》里的『类记载和模块』章节的『隐性模块依赖关系』。

2. 了解显性依赖关系

   对于其他类，模块必须显性地指定，否则缺失的依赖关系会导致部署或运行时错误。如果缺失了依赖关系，您可以在服务器日志里看到 ClassNotFoundExceptions 或 NoClassDefFoundErrors 跟踪信息。如果多于一个模块加载了相同的 JAR 或一个模块加载的类扩展了不同模块加载的类，您会在服务器日志里看到 ClassCastExceptions。要显性地制定依赖关系，请修改 MANIFEST.MF 或创建一个 JBoss 专有的部署描述符文件 jboss-deployment-structure.xml。关于模块依赖关系的更多信息，请查看 https://access.redhat.com/site/documentation/JBoss_Enterprise_Application_Platform/《JBoss EAP 6 开发指南》里的『开发应用程序起步』章节的『类记载和模块概述』。

过程 3.2. 修改 ResourceBundle 属性的位置

1. 如果您在开发 WAR 归档，您必须将这些属性包裹至 WAR 的 WEB-INF/classes/ 目录里。
2. 如果您想要 EAP 里所有组件都可以访问这些属性，那您必须将其打包到 JAR 的根目录并将 JAR 放入 EAR 的 lib/ 目录下。

过程 3.3. 创建自定义模块

1. 创建和填充 module/ 目录结构。
   1. 在 EAP_HOME/module 目录下创建一个目录结构来包含文件和 JAR。例如：

      $ cd EAP_HOME/modules/ 
      $ mkdir -p myorg-conf/main/properties

   2. 将属性文件移到您在前一步骤里创建的 EAP_HOME/modules/myorg-conf/main/properties/ 目录里。
   3. 在 EAP_HOME/modules/myorg-conf/main/ 目录里创建一个包含下列 XML 内容的 module.xml 文件：

      <module xmlns="urn:jboss:module:1.1" name="myorg-conf">
          <resources>
              <resource-root path="properties"/>
          </resources>
      </module>
      
      

2. 修改服务器配置文件里的 ee 子系统。您可以使用 JBoss CLI 或手动编辑这个文件。
   • 按照下列步骤使用 JBoss CLI 来修改服务器配置文件。
     1. 启动服务器并连接至管理 CLI。
        • 对于 Linux，输入下列命令：

          $ EAP_HOME/bin/jboss-cli.sh --connect
          

        • 对于 Windows，输入下列命令：

          C:\>EAP_HOME\bin\jboss-cli.bat --connect
          

        您应该看到下面的结果：

        Connected to standalone controller at localhost:9999

     2. 要在 ee 子系统里创建 myorg-conf<global-modules> 元素，输入下列命令：

        /subsystem=ee:write-attribute(name=global-modules, value=[{"name"=>"myorg-conf","slot"=>"main"}])
        

        您应该看到下面的结果：

        {"outcome" => "success"}
        

   • 如果您向手动编辑服务器配置文件，请按照下列步骤进行。
     1. 停止服务器并打开服务器配置文件。如果您使用的是独立服务器，这个文件是 EAP_HOME/standalone/configuration/standalone.xml，如果是受管域，这个文件是 EAP_HOME/domain/configuration/domain.xml。
     2. 找到 ee 子系统并为 myorg-conf 添加全局模块。下面是 ee 子系统元素的例子，已经进行修改并包含了 myorg-conf 元素：

        <subsystem xmlns="urn:jboss:domain:ee:1.0" >            
            <global-modules>
                <module name="myorg-conf" slot="main" />            
            </global-modules>
        </subsystem>
        
        

3. 假设您复制了一个名为 my.properties 的文件到正确的模块位置，您现在可以使用下面的代码来加载属性文件了：

   Thread.currentThread().getContextClassLoader().getResource("my.properties");
   

过程 3.4. 更新程序日志代码

1. 第 3.1.4.2 节 “为第三方日志框架更新应用程序代码”
2. 第 3.1.4.3 节 “修改代码以使用新的 JBoss Logging 框架”

过程 3.5. 配置 JBoss EAP 6 以使用 log4j.properties 或 log4j.xml 文件

1. 用下列内容创建一个 jboss-deployment-structure.xml 文件：

   <jboss-deployment-structure>
       <deployment>
           <!-- Exclusions allow you to prevent the server from automatically adding some dependencies -->
           <exclusions>
               <module name="org.apache.log4j" />
           </exclusions>
       </deployment>
   </jboss-deployment-structure>
   
   

2. 如果您在部署 WAR，请将 jboss-deployment-structure.xml 文件放入 META-INF/ 或 WEB-INF/ 目录；如果是部署 EAR，则请放入 META-INF/ 目录。如果您的部署包含了依赖的子部署，您必须在每个子部署里排除这些模块。
3. 在 EAR 的 lib/ 或 WAR 部署的 WEB-INF/classes/ 里包含 log4j.properties 或 log4j.xml 文件。如果您想将文件放到 lib/ 目录里，您必须在 jboss-deployment-structure.xml 文件里指定 <resource-root> 路径。

   <jboss-deployment-structure>
       <deployment>
           <!-- Exclusions allow you to prevent the server from automatically adding some dependencies -->
           <exclusions>
               <module name="org.apache.log4j" />
           </exclusions>
           <resources>
               <resource-root path="lib" />
           </resources>
       </deployment>
   </jboss-deployment-structure>
   
   

4. 用下列 runtime 参数启动 JBoss EAP 6 服务器以防止在部署应用程序时控制台出现 ClassCastException。

   -Dorg.jboss.as.logging.per-deployment=false

5. 部署您的应用程序

过程 3.6. 配置 JBoss EAP 6.3 或更新版本的日志依赖关系

1. 用下列 runtime 参数启动 JBoss EAP 6 服务器以防止在部署应用程序时控制台出现 ClassCastException。

   -Dorg.jboss.as.logging.per-deployment=false

2. 打开终端窗口并连接至管理 CLI。
   • 对于 Linux，输入下列命令：

     $ EAP_HOME/bin/jboss-cli.sh --connect
     

   • 对于 Windows，输入下列命令：

     C:\>EAP_HOME\bin\jboss-cli.bat --connect
     

3. 修改日志子系统里的 add-logging-api-dependencies 属性。
   这个属性控制容器是否添加隐性的 logging API 依赖关系到部署里。

   • 如果为 true（默认值），将添加所有隐性的 logging API 依赖关系。
   • 如果设置为 false，依赖关系不会添加到部署里。
   要排除第三方的日志框架依赖关系，您必须用下列命令设置这个属性为 false。

   /subsystem=logging:write-attribute(name=add-logging-api-dependencies, value=false)

   这个命令添加了 <add-logging-api-dependencies> 元素到 standalone.xml 配置文件的 logging 子系统里。

   <subsystem xmlns="urn:jboss:domain:logging:1.4">
       <add-logging-api-dependencies value="false"/>
       ....
   </subsystem>
   
   

4. 部署您的应用程序

过程 3.7. 修改代码和依赖关系以使用新的 JBoss Logging 框架

1. 修改您的导入和日志代码

   下面是一个使用新的 JBoss Logging 框架的例子：

   import org.jboss.logging.Level;
   import org.jboss.logging.Logger;
   
   private static final Logger logger = Logger.getLogger(MyClass.class.toString());
   
   if(logger.isTraceEnabled()) {
       logger.tracef("Starting...", subsystem);
   }
   

2. 添加日志依赖关系

   包含 JBoss Logging 类的 JAR 位于名为 org.jboss.logging 的模块。您的 MANIFEST-MF 文件应该类似要：

   Manifest-Version: 1.0
   Dependencies: org.jboss.logging
   

   关于如何查找模块依赖关系的更多信息，请参考 第 3.1.2.3 节 “根据类加载的修改更新应用程序的依赖关系” and 第 4.2.1 节 “调试和解决移植问题”。

过程 3.8. 修改归档的打包

1. 打包 WAR

   WAR 是一个模块，它里面的所有类都用相同的类加载器加载。这意味着打包在 WEB-INF/lib/ 目录里的类将和 WEB-INF/classes 里的一样被对待。

2. 打包 EAR

   EAR 由多个模块组成。EAR/lib/ 目录是一个单个的模块且 EAR 里每个 WAR 或 EJB JAR 都是一个独立的模块。除非定义了显性的依赖关系，类不能访问 EAR 里其他模块里的类。子部署总是对父部署有着自动的依赖关系，这让它们可以访问 EAR/lib/ 目录里的类。然而，子部署并不总由自动的依赖关系来允许它们访问彼此。这个行为是通过设置 ee 子系统配置里的 <ear-subdeployments-isolated> 元素来控制的：

   <subsystem xmlns="urn:jboss:domain:ee:1.0" >            
     <ear-subdeployments-isolated>false</ear-subdeployments-isolated>
   </subsystem>
   

   在默认情况下，它被设置为 false，这允许子部署查看属于 EAR 里其他子部署的类。
   关于类加载的更多信息，请参考 https://access.redhat.com/site/documentation/JBoss_Enterprise_Application_Platform/ 上的《JBoss 开发指南》里的『类加载和模块』章节。

1. 如果您的应用程序使用了数据源，请参考： 第 3.1.6.2 节 “更新数据源配置”。
2. 如果您的应用程序使用了 JPA 且捆绑了 Hibernate JAR，请参考下列移植选项： 第 3.1.6.4 节 “为 Hibernate 或 JPA 配置数据源”。
3. 如果您的应用程序使用了资源适配器，请参考： 第 3.1.6.5 节 “更新资源适配器配置”。
4. 关于如何配置基本安全性，请参考： 第 3.1.7.1 节 “应用程序安全性的修改”。

过程 3.9. 安装和配置 JDBC 驱动

1. 安装 JDBC 驱动。

   1. 将 JDBC 驱动作为部署安装。

      这是我们推荐的安装驱动的方法。当 JDBC 驱动作为部署安装时，它会被部署为常规的 JAR。如果 JBoss EAP 实例作为独立服务器运行，请将兼容 JDBC 4.0 的 JAR 复制到 EAP_HOME/standalone/deployments/ 目录。对于受管域，您必须使用管理控制台或管理 CLI 将 JAR 部署到服务器组里。
      下面是一个安装为独立服务器的部署的 MySQL JDBC 驱动示例：

      $cp mysql-connector-java-5.1.15.jar EAP_HOME/standalone/deployments/

      任何兼容 JDBC 4.0 的驱动都自动会被承认且根据名称和版本安装至系统里。兼容 JDBC 4.0 的 JAR 都包含一个名为 META-INF/services/java.sql.Driver 的文本文件，它指定驱动类的名称。如果这个驱动不兼容 JDBC 4.0，它可以用下列方法来部署：

      • 创建并添加 java.sql.Driver 文件到 META-INF/services/ 路径下的 JAR。这个文件应该包含驱动类的名称，例如：

        com.mysql.jdbc.Driver

      • 在 deployment 目录里创建一个 java.sql.Driver 文件。对于作为独立服务器运行的 JBoss EAP 6 实例，这个文件应该位于：EAP_HOME/standalone/deployments/META-INF/services/java.sql.Driver。如果服务器位于受管服务器，您必须使用管理控制台或管理 CLI 来部署这个文件。
      这种方法的优点是：

      • 因为不需要定义模块，所以这是最简单的方法。
      • 当服务器运行在受管域里时，使用这个方法的部署将自动传播到域里的所有服务器。这意味着管理员不需要手动分发这个驱动 JAR。

      这种方法的缺点是：

      • 如果 JDBC 驱动由多个 JAR 组成，如驱动 JAR 以及依赖的许可证 JAR 或本地化 JAR，您不能将驱动安装为部署。您必须将其安装为核心模块。
      • 如果这个驱动不兼容 JDBC 4.0，您必须创建一个包含驱动类名的文件并导入至 JAR 或覆盖到 deployments/ 目录。

   2. 将 JDBC 驱动安装为核心模块。

      要将 JDBC 驱动安装为核心模块，您必须在 EAP_HOME/modules/ 下创建一个文件路径结构。这个结构包含 JDBC 驱动 JAR，任何其他供应商许可证或本地化 JAR，以及一个定义模块的 module.xml 文件。

      • 将 MySQL JDBC 驱动安装为核心模块

        1. 创建一个目录结构 EAP_HOME/modules/com/mysql/main/
        2. 在 main/ 子目录里，创建一个包含下列为 MySQL JDBC 驱动定义的 module.xml 文件：

           <?xml version="1.0" encoding="UTF-8"?>
           <module xmlns="urn:jboss:module:1.0" name="com.mysql">
           <resources>
               <resource-root path="mysql-connector-java-5.1.15.jar"/>
           </resources>
           <dependencies>
               <module name="javax.api"/>
           </dependencies>
           </module>
           
           
           

           模块名 “com.mysql”，映射了这个模块的目录结构。<dependencies> 元素用来指定这个模块对其他模块的依赖关系。在这种情况下，所有的 JDBC 数据源都依赖于在另一个名为 javax.api 的模块里定义的 Java JDBC API。这个模块位于 modules/system/layers/base/javax/api/main/ 目录。

           注意

           确保您在 module.xml 文件的开头没有留下一个空格，否则您会遇到 "New missing/unsatisfied dependencies" 错误。
        3. 复制 MySQL JDBC 驱动 JAR 到 EAP_HOME/modules/com/mysql/main/ 目录：

           $ cp mysql-connector-java-5.1.15.jar EAP_HOME/modules/com/mysql/main/

      • 将 IBM DB2 JDBC 驱动和 license JAR 安装为核心模块。

        这个例子只是用来演示如何部署要求 JDBC Driver JAR 之外的 JAR 的驱动。
        1. 创建目录结构 EAP_HOME/modules/com/ibm/db2/main/。
        2. 在 main/ 子目录里，创建一个包含下列用于 IBM DB2 JDBC 驱动和许可证的模块定义的 module.xml 文件：

           <?xml version="1.0" encoding="UTF-8"?>
           <module xmlns="urn:jboss:module:1.1" name="com.ibm.db2">
             <resources>
               <resource-root path="db2jcc.jar"/>
               <resource-root path="db2jcc_license_cisuz.jar"/>
             </resources>
             <dependencies>
               <module name="javax.api"/>
               <module name="javax.transaction.api"/>
             </dependencies>
           </module>
           
           

           注意

           确保您在 module.xml 文件的开头没有留下一个空格，否则您会遇到 "New missing/unsatisfied dependencies" 错误。
        3. 复制 JDBC 驱动和 license JAR 到 EAP_HOME/modules/com/ibm/db2/main/ 目录里。

           $ cp db2jcc.jar EAP_HOME/modules/com/ibm/db2/main/
           $ cp db2jcc_license_cisuz.jar EAP_HOME/modules/com/ibm/db2/main/

      这种方法的优点是：

      • 当 JDBC 驱动由多个 JAR 组成时，这是唯一的途径。
      • 用这个方法，不兼容 JDBC 4.0 的驱动可以无需修改驱动 JAR 或创建覆盖文件就进行安装。

      这种方法的缺点是：

      • 通过设置模块要更为困难。
      • 您必须手动将模块复制到运行在受管域里的每个服务器里。

2. 配置数据源。

   1. 添加数据库驱动。

      在相同的文件的 <drivers> 元素了添加 <driver> 元素。它也包含了之前的 *-ds.xml 文件里定义的一些数据源信息。
      首先确定驱动 JAR 是否兼容 JDBC 4.0。兼容 JDBC 4.0 的 JAR 包含一个指定驱动类名的 META-INF/services/java.sql.Driver。这个服务器使用这个文件来在 JAR 里查找驱动类的名称。兼容 JDBC 4.0 的 JAR 不要求 <driver-class> 元素，因为在 JAR 里它已被指定。下面是一个 JDBC 4.0 兼容的 MySQL 驱动的 driver 元素示例：

      <driver name="mysql-connector-java-5.1.15.jar" module="com.mysql"/>
      

      不兼容 JDBC 4.0 的驱动要求一个 <driver-class> 属性来确定驱动类，这是因为没有 META-INF/services/java.sql.Driver 文件来指定驱动类名。下面是一个不兼容 JDBC 4.0 的 MySQL 驱动的 driver 元素示例：

      <driver name="mysql-connector-java-5.1.15.jar" module="com.mysql">
      <driver-class>com.mysql.jdbc.Driver</driver-class></driver>
      

   2. 创建数据源。

      在 standalone.xml 文件的 <datasources> 部分创建一个 <datasource> 元素。这个文件包含之前的 *-ds.xml 文件里定义的大部分数据源信息。

      重要

      要使修改在服务器重启后仍然生效，您必须在编辑服务器配置文件前停止服务器。
      下面是 standalone.xml 文件里的一个 MySQL 数据源元素示例：

      <datasource jndi-name="java:/YourDatasourceName" pool-name="YourDatasourceName">
        <connection-url>jdbc:mysql://localhost:3306/YourApplicationURL</connection-url>
        <driver>mysql-connector-java-5.1.15.jar</driver>
        <transaction-isolation>TRANSACTION_READ_COMMITTED</transaction-isolation>
        <pool>
          <min-pool-size>100</min-pool-size>
          <max-pool-size>200</max-pool-size>
        </pool>
        <security>
          <user-name>USERID</user-name>
          <password>PASSWORD</password>
        </security>
        <statement>
          <prepared-statement-cache-size>100</prepared-statement-cache-size>
          <share-prepared-statements/>
        </statement>
      </datasource>
      
      

3. 更新程序代码里的 JNDI 引用。

   您必须在程序源代码里替换过时的 JNDI 查找名称以使用新的 JNDI 标准化数据源名称。详情请参考： 第 3.1.8.4 节 “修改应用程序以遵循新的 JNDI 命名规则”。
   您也必须让现有的访问数据源的 @Resource 注解使用新的 JNDI 名称。例如：

   @Resource(name = "java:/YourDatasourceName").
   

过程 3.10. 删除 Hibernate 捆绑

1. 从您的应用程序的库目录里将 Hibernate JAR 删除。
2. 当不再需要 <hibernate.transaction.manager_lookup_class> 元素时，在 persistence.xml 里将其删除或注释。

过程 3.11. 禁用额外的授权检查

• 您可以禁用额外的授权检查并通过下列方法之一坚持使用现有的 PicketLink 部署。

  • 设置系统属性

    您可以通过设置 org.jboss.ws.cxf.disableHandlerAuthChecks 属性为 true 来禁用服务器级别的额外授权检查。这个方法会影响应用服务器上的所有部署。
    关于设置系统属性的信息，请参考《管理和配置指南》里的 『用管理 CLI 配置系统属性』。

  • 在部署的 Web 服务描述文件里创建一个属性

    您可以通过设置 jboss-webservices.xml 文件里的 org.jboss.ws.cxf.disableHandlerAuthChecks 属性为 true 来禁用部署级别的额外授权检查。这个方法只会影响专有的部署。
    1. 在您要禁用额外授权检查的部署的 META-INF/ 目录里创建一个 jboss-webservices.xml 文件。
    2. 添加下列内容：

       <?xml version="1.1" encoding="UTF-8"?>
       <webservices xmlns="http://www.jboss.com/xml/ns/javaee"
         xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
         version="1.2" xsi:schemaLocation="http://www.jboss.com/xml/ns/javaee">
         <property>
           <name>org.jboss.ws.cxf.disableHandlerAuthChecks</name>
           <value>true</value>
         </property>
       </webservices>
       

过程 3.12. 修改 JNDI 查找

1. 了解更多的 第 3.1.8.2 节 “可移植的 EJB JNDI 名称”
2. 第 3.1.8.3 节 “复核 JNDI 命名空间规则”
3. 第 3.1.8.4 节 “修改应用程序以遵循新的 JNDI 命名规则”