第 4 章 工具和提示

4.1. 协助移植的资源

4.1.1. 可协助移植的资源

下面是在移植应用程序到 JBoss EAP 6 时可能会由帮助的资源列表。
工具
这是几个自动化某些配置修改的工具。详情请参考： 第 4.1.2 节 “熟悉可以协助移植的工具”。
调试提示
关于您可能遇到的问题和错误的常见原因和解决办法，请参考： 第 4.2.1 节 “调试和解决移植问题”。
例程移植
关于已经移植到 JBoss EAP 6 里的例程，请参考： 第 4.3.1 节 “复查例程的移植”。
提交 bug 报告

4.1.2. 熟悉可以协助移植的工具

介绍

有些工具可以协助您移植应用程序。下面是这些工具以及相关的描述。

Tattletale
由于采用模块化类加载，您需要找到并修订应用程序的依赖关系。Tattletale 可以帮助您确定依赖的模块名称并为应用程序生成配置 XML 内容。
第 4.1.3 节 “使用 Tattletale 来查找应用程序的依赖关系”
IronJacamar 移植工具
在 JBoss EAP 6 里，数据源和资源适配器都不再在单独的文件里配置了。它们现在在服务器配置文件里进行配置且使用新的 schema。IronJacamar 移植工具可以帮助转换旧的配置为 JBoss EAP 6 需要的格式。
第 4.1.6 节 “使用 IronJacamar 工具来移植数据源和资源适配器配置”
提交 bug 报告

4.1.3. 使用 Tattletale 来查找应用程序的依赖关系

介绍

由于 JBoss EAP 6 里的模块化类加载的改动，当您移植应用程序时，您可能会在 JBoss 日志里看到 ClassNotFoundException 或 ClassCastException 跟踪信息。要解决这些错误，您需要找到包含这些异常指定的类的 JAR。

Tattletale 是一个优秀的第三方工具，它递归地扫描您的应用程序并提供其内容的详细报告。Tattletale 1.2.0.Beta2 或更新版本包含额外的支持以帮助新的 JBoss 模块化类加载。Tattletale 的 "JBoss AS 7" 报告可以用于自动确定和生成依赖模块的名称来包含应用程序的 jboss-deployment-structure.xml 文件。

过程 4.1. 安装并运行 Tattletale 来查找应用程序的依赖关系

  1. 第 4.1.4 节 “下载和安装 Tattletale”
  2. 第 4.1.5 节 “创建和复查 Tattletale 报告”

注意

Tattletale 是一个第三方的工具，它并不是 JBoss EAP 6 的一部分。关于如何安装和使用 Tattletale 的最新文档，请访问其网站：http://www.jboss.org/tattletale。
提交 bug 报告

4.1.4. 下载和安装 Tattletale

过程 4.2. 下载和安装 Tattletale

  1. http://sourceforge.net/projects/jboss/files/JBoss%20Tattletale 下载 Tattletale 1.2.0.Beta2 或更新版本。
  2. 解压文件到您指定的目录。
  3. 修改 TATTLETALE_HOME/jboss-tattletale.properties 文件：
    1. 添加 ee6 和 as7 到 profiles 属性。 
      profiles=java5, java6, ee6, as7
    2. 取消 scan 和 reports 属性的注释。
提交 bug 报告

4.1.5. 创建和复查 Tattletale 报告

  1. 用下列命令创建 Tattletale 报告： java -jar TATTLETALE_HOME/tattletale.jarAPPLICATION_ARCHIVEOUTPUT_DIRECTORY
    例如： java -jar tattletale-1.2.0.Beta2/tattletale.jar ~/applications/jboss-seam-booking.ear ~/output-results/
  2. 在浏览器里打开 OUTPUT_DIRECTORY/index.html 文件并点击 "Reports" 下的 JBoss AS 7"。
    1. 左侧的列列出了应用程序使用的归档。点击 ARCHIVE_NAME 链接来查看归档的细节，如位置、Manifest 信息和它包含的类。
    2. 右侧列上的 jboss-deployment-structure.xml 链接显示了如何为左侧列命名的归档指定模块依赖关系。点击这个链接来查看如何为这个归档定义部署依赖关系模块信息。
提交 bug 报告

4.1.6. 使用 IronJacamar 工具来移植数据源和资源适配器配置

介绍

在以前的应用服务器版本里，数据源和资源适配器都是使用后缀为 *-ds.xml 的文件来配置和部署的。IronJacamar 1.1 版本包含了一个移植工具，它可以用来将这些文件转换为 JBoss EAP 6 所要求的格式。这个工具解析了之前版本的源配置文件，然后创建 XML 配置并写入新格式的输出文件。这个 XML 文件可以在 JBoss EAP 6 服务器配置文件里的正确的子系统下复制和粘贴。这个工具尽量将旧的属性和元素转换为新的格式，然而，您还是有必要对生成的文件进行额外的修改。

过程 4.3. 安装和运行 IronJacamar 移植工具

  1. 第 4.1.7 节 “下载和安装 IronJacamar 移植工具”
  2. 第 4.1.8 节 “使用 IronJacamar 移植工具来转换数据源配置文件”
  3. 第 4.1.9 节 “使用 IronJacamar 移植工具来转换资源适配器配置文件”

注意

IronJacamar 移植工具是一个第三方的工具，它不会以 JBoss EAP 6 的一部分而被支持。关于 IronJacamar 的更多信息，请访问 http://www.ironjacamar.org/。关于如何安装和使用这个工具的最新文档，请访问：http://www.ironjacamar.org/documentation.html。
提交 bug 报告

4.1.7. 下载和安装 IronJacamar 移植工具

注意

移植工具只能用于 IronJacamar 1.1 或更高版本且要求 Java 7 或更高版本。
  1. 在这里下载最新年的 IronJacamar：http://www.ironjacamar.org/download.html
  2. 解压下载的文件到您指定的目录。
  3. 在 IronJacamar 里找到转换脚本。
    • Linux 脚本在这里：IRONJACAMAR_HOME/doc/as/converter.sh
    • Windows 批处理文件在这里：IRONJACAMAR_HOME/doc/as/converter.bat
提交 bug 报告

4.1.8. 使用 IronJacamar 移植工具来转换数据源配置文件

注意

IronJacamar 转换器脚本要求 Java 7 或更高版本。

过程 4.4. 转换数据源配置文件

  1. 打开命令行并进入 IRONJACAMAR_HOME/doc/as/ 目录。
  2. 请输入以下命令来运行转换脚本：
    • 对于 Linux：./converter.sh -ds SOURCE_FILE TARGET_FILE
    • 对于 Microsoft Windows：./converter.bat -ds SOURCE_FILE TARGET_FILE
    SOURCE_FILE 是以前版本的 -ds.xml 文件。TARGET_FILE 包含新的配置。
    例如，要转换位于当前目录里的 jboss-seam-booking-ds.xml 数据源配置文件，您可以输入：
    • 对于 Linux：./converter.sh -ds jboss-seam-booking-ds.xmlnew-datasource-config.xml
    • 对于 Microsoft Windows：./converter.bat -ds jboss-seam-booking-ds.xmlnew-datasource-config.xml
    请注意数据源转换的参数是 -ds。
  3. 从目标文件复制 <datasource> 元素并粘贴到 <subsystem xmlns="urn:jboss:domain:datasources:1.1"><datasources> 元素下的服务器配置文件。

    重要

    要使修改在服务器重启后仍然生效，您必须在编辑服务器配置文件前停止服务器。
    • 如果服务器运行在受管域里，请将 XML 复制到 EAP_HOME/domain/configuration/domain.xml 文件里。
    • 如果运行的是独立服务器，请将 XML 复制到 EAP_HOME/standalone/configuration/standalone.xml 文件里。
  4. 修改新配置文件里生成的 XML。
    下面是 JBoss EAP 5.x 里附带的 Seam 2.2 Booking 例程里的 jboss-seam-booking-ds.xml 数据源配置文件： 
    <?xml version="1.0" encoding="UTF-8"?>
<datasources>
  <local-tx-datasource>
    <jndi-name>bookingDatasource</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>
    下面是运行转换器脚本生成的配置文件。生成的文件包含 <driver-class> 元素。首选的方式是定义 JBoss EAP 6 里的驱动类使用 <driver> 元素。下面是注释 <driver-class>元素并添加对应的 <driver> 元素的 JBoss EAP 6 配置文件里的 XML 内容： 
    <subsystem xmlns="urn:jboss:domain:datasources:1.1">
  <datasources>
    <datasource enabled="true" jndi-name="java:jboss/datasources/bookingDatasource" jta="true"
            pool-name="bookingDatasource" use-ccm="true" use-java-context="true">
      <connection-url>jdbc:hsqldb:.</connection-url>
      <!-- Comment out the following driver-class element 
           since it is not the preferred way to define this.
           <driver-class>org.hsqldb.jdbcDriver</driver-class>     -->
      <!-- Specify the driver, which is defined later in the datasource  -->
      <driver>h2<driver>
      <transaction-isolation>TRANSACTION_NONE</transaction-isolation>
      <pool>
        <prefill>false</prefill>
        <use-strict-min>false</use-strict-min>
        <flush-strategy>FailingConnectionOnly</flush-strategy>
      </pool>
      <security>
        <user-name>sa</user-name>
        <password/>
      </security>
      <validation>
        <validate-on-match>false</validate-on-match>
        <background-validation>false</background-validation>
        <use-fast-fail>false</use-fast-fail>
      </validation>
      <timeout/>
      <statement>
        <track-statements>false</track-statements>
      </statement>
    </datasource>
    <drivers>
      <!-- The following driver element was not in the 
     XML target file. It was created manually. -->
      <driver name="h2" module="com.h2database.h2">
        <xa-datasource-class>org.h2.jdbcx.JdbcDataSource</xa-datasource-class>
        </driver>
      </drivers>
  </datasources>
</subsystem>
提交 bug 报告

4.1.9. 使用 IronJacamar 移植工具来转换资源适配器配置文件

注意

IronJacamar 转换器脚本要求 Java 7 或更高版本。
  1. 打开命令行并进入 IRONJACAMAR_HOME/docs/as/ 目录。
  2. 请输入以下命令来运行转换脚本：
    • 对于 Linux：./converter.sh -ra SOURCE_FILE TARGET_FILE
    • 对于 Microsoft Windows：./converter.bat -ra SOURCE_FILE TARGET_FILE
    SOURCE_FILE 是以前版本的资源适配器 -ds.xml 文件。TARGET_FILE 包含新的配置。
    例如，要转换位于当前目录里的 mttestadapter-ds.xml 资源适配器配置文件，您可以输入：
    • 对于 Linux: ./converter.sh -ra mttestadapter-ds.xmlnew-adapter-config.xml
    • 对于 Microsoft Windows：./converter.bat -ra mttestadapter-ds.xmlnew-adapter-config.xml
    请注意资源适配器转换的参数是 -ra。
  3. 从目标文件将整个 <resource-adapters> 元素复制并粘贴到 <subsystem xmlns="urn:jboss:domain:resource-adapters:1.1"> 元素下的服务器配置文件里。

    重要

    要使修改在服务器重启后仍然生效，您必须在编辑服务器配置文件前停止服务器。
    • 如果服务器运行在受管域里，请将 XML 复制到 EAP_HOME/domain/configuration/domain.xml 文件里。
    • 如果运行的是独立服务器，请将 XML 复制到 EAP_HOME/standalone/configuration/standalone.xml 文件里。
  4. 修改新配置文件里生成的 XML。
    下面是 JBoss EAP 5.x TestSuite 里的 mttestadapter-ds.xml 资源适配器配置文件的一个例子： 
    <?xml version="1.0" encoding="UTF-8"?>
  <!-- ==================================================================== -->
  <!-- ConnectionManager setup for jboss test adapter                       -->
  <!-- Build jmx-api (build/build.sh all) and view for config documentation -->
  <!-- ==================================================================== -->
<connection-factories>
  <tx-connection-factory>
    <jndi-name>JBossTestCF</jndi-name>
    <xa-transaction/>
    <rar-name>jbosstestadapter.rar</rar-name>
    <connection-definition>javax.resource.cci.ConnectionFactory</connection-definition>
    <config-property name="IntegerProperty" type="java.lang.Integer">2</config-property>
    <config-property name="BooleanProperty" type="java.lang.Boolean">false</config-property>
    <config-property name="DoubleProperty" type="java.lang.Double">5.5</config-property>
    <config-property name="UrlProperty" type="java.net.URL">http://www.jboss.org</config-property>
    <config-property name="sleepInStart" type="long">200</config-property>
    <config-property name="sleepInStop" type="long">200</config-property>
  </tx-connection-factory>
  <tx-connection-factory>
    <jndi-name>JBossTestCF2</jndi-name>
    <xa-transaction/>
    <rar-name>jbosstestadapter.rar</rar-name>
    <connection-definition>javax.resource.cci.ConnectionFactory</connection-definition>
    <config-property name="IntegerProperty" type="java.lang.Integer">2</config-property>
    <config-property name="BooleanProperty" type="java.lang.Boolean">false</config-property>
    <config-property name="DoubleProperty" type="java.lang.Double">5.5</config-property>
    <config-property name="UrlProperty" type="java.net.URL">http://www.jboss.org</config-property>
    <config-property name="sleepInStart" type="long">200</config-property>
    <config-property name="sleepInStop" type="long">200</config-property>
  </tx-connection-factory>
  <tx-connection-factory>
    <jndi-name>JBossTestCFByTx</jndi-name>
    <xa-transaction/>
    <track-connection-by-tx>true</track-connection-by-tx>
    <rar-name>jbosstestadapter.rar</rar-name>
    <connection-definition>javax.resource.cci.ConnectionFactory</connection-definition>
    <config-property name="IntegerProperty" type="java.lang.Integer">2</config-property>
    <config-property name="BooleanProperty" type="java.lang.Boolean">false</config-property>
    <config-property name="DoubleProperty" type="java.lang.Double">5.5</config-property>
    <config-property name="UrlProperty" type="java.net.URL">http://www.jboss.org</config-property>
    <config-property name="sleepInStart" type="long">200</config-property>
    <config-property name="sleepInStop" type="long">200</config-property>
  </tx-connection-factory>
</connection-factories>
    下面是运行转换器脚本生成的配置文件。用正确的受管连接工厂的类名替换生成的 XML 里的 class-name 属性值 "FIXME_MCF_CLASS_NAME"，在这个例子是 "org.jboss.test.jca.adapter.TestManagedConnectionFactory"。下面是已修改了 <class-name> 元素值的 JBoss EAP 6 配置文件的 XML 内容： 
    <subsystem xmlns="urn:jboss:domain:resource-adapters:1.1">
  <resource-adapters>
    <resource-adapter>
      <archive>jbosstestadapter.rar</archive>
      <transaction-support>XATransaction</transaction-support>
      <connection-definitions>
  <!-- Replace the "FIXME_MCF_CLASS_NAME" class-name value with the correct class name
  <connection-definition class-name="FIXME_MCF_CLASS_NAME" enabled="true"
    jndi-name="java:jboss/JBossTestCF" pool-name="JBossTestCF" 
    use-ccm="true" use-java-context="true"> -->
  <connection-definition 
    class-name="org.jboss.test.jca.adapter.TestManagedConnectionFactory" 
    enabled="true"
    jndi-name="java:jboss/JBossTestCF" pool-name="JBossTestCF" 
    use-ccm="true" use-java-context="true">
    <config-property name="IntegerProperty">2</config-property>
    <config-property name="sleepInStart">200</config-property>
    <config-property name="sleepInStop">200</config-property>
    <config-property name="BooleanProperty">false</config-property>
    <config-property name="UrlProperty">http://www.jboss.org</config-property>
    <config-property name="DoubleProperty">5.5</config-property>
    <pool>
      <prefill>false</prefill>
      <use-strict-min>false</use-strict-min>
      <flush-strategy>FailingConnectionOnly</flush-strategy>
    </pool>
    <security>
      <application/>
    </security>
    <timeout/>
    <validation>
      <background-validation>false</background-validation>
      <use-fast-fail>false</use-fast-fail>
    </validation>
  </connection-definition>
      </connection-definitions>
    </resource-adapter>
    <resource-adapter>
      <archive>jbosstestadapter.rar</archive>
      <transaction-support>XATransaction</transaction-support>
      <connection-definitions>
  <!-- Replace the "FIXME_MCF_CLASS_NAME" class-name value with the correct class name
   <connection-definition class-name="FIXME_MCF_CLASS_NAME" enabled="true"
    jndi-name="java:jboss/JBossTestCF2" pool-name="JBossTestCF2" 
    use-ccm="true" use-java-context="true"> -->
  <connection-definition 
    class-name="org.jboss.test.jca.adapter.TestManagedConnectionFactory" 
    enabled="true"
    jndi-name="java:jboss/JBossTestCF2" pool-name="JBossTestCF2" 
    use-ccm="true" use-java-context="true">
    <config-property name="IntegerProperty">2</config-property>
    <config-property name="sleepInStart">200</config-property>
    <config-property name="sleepInStop">200</config-property>
    <config-property name="BooleanProperty">false</config-property>
    <config-property name="UrlProperty">http://www.jboss.org</config-property>
    <config-property name="DoubleProperty">5.5</config-property>
    <pool>
      <prefill>false</prefill>
      <use-strict-min>false</use-strict-min>
      <flush-strategy>FailingConnectionOnly</flush-strategy>
    </pool>
    <security>
      <application/>
    </security>
    <timeout/>
    <validation>
      <background-validation>false</background-validation>
      <use-fast-fail>false</use-fast-fail>
    </validation>
  </connection-definition>
      </connection-definitions>
    </resource-adapter>
    <resource-adapter>
      <archive>jbosstestadapter.rar</archive>
      <transaction-support>XATransaction</transaction-support>
      <connection-definitions>
  <!-- Replace the "FIXME_MCF_CLASS_NAME" class-name value with the correct class name
  <connection-definition class-name="FIXME_MCF_CLASS_NAME" enabled="true"
     jndi-name="java:jboss/JBossTestCFByTx" pool-name="JBossTestCFByTx" 
     use-ccm="true" use-java-context="true"> -->
  <connection-definition 
    class-name="org.jboss.test.jca.adapter.TestManagedConnectionFactory" 
    enabled="true"
    jndi-name="java:jboss/JBossTestCFByTx" pool-name="JBossTestCFByTx" 
    use-ccm="true" use-java-context="true">
    <config-property name="IntegerProperty">2</config-property>
    <config-property name="sleepInStart">200</config-property>
    <config-property name="sleepInStop">200</config-property>
    <config-property name="BooleanProperty">false</config-property>
    <config-property name="UrlProperty">http://www.jboss.org</config-property>
    <config-property name="DoubleProperty">5.5</config-property>
    <pool>
      <prefill>false</prefill>
      <use-strict-min>false</use-strict-min>
      <flush-strategy>FailingConnectionOnly</flush-strategy>
    </pool>
    <security>
      <application/>
    </security>
    <timeout/>
    <validation>
      <background-validation>false</background-validation>
      <use-fast-fail>false</use-fast-fail>
    </validation>
  </connection-definition>
      </connection-definitions>
    </resource-adapter>
  </resource-adapters>
</subsystem>
提交 bug 报告