Chapter 3. Migrate Your Application

1. First, look at the packaging of your application and its dependencies. For more information, see: Section 3.1.2.3, “Update Application Dependencies Due to Class Loading Changes”
2. If your application does logging, you need to specify the correct module dependencies. For more information, see: Section 3.1.4.1, “Modify Logging Dependencies”
3. Due to the modular class loading changes, you may have to change the packaging structure of your EAR or WAR. For more information, see: Section 3.1.5.1, “Modify Packaging of EARs and WARs”

Procedure 3.1. Change the ResourceBundle Properties Location

1. If you are deploying a WAR archive, you must package those properties in the WAR's WEB-INF/classes/ folder.
2. If you want those properties accessible to all components in an EAR, then you must package them at the root of a JAR and then place the JAR in EAR's lib/ folder.

Procedure 3.2. Create a Custom Module

1. Create and populate the module/ directory structure.
   1. Create a directory structure under the EAP_HOME/module directory to contain the files and JARs. For example:

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

   2. Move the properties files to the EAP_HOME/modules/myorg-conf/main/properties/ directory you created in the previous step.
   3. Create a module.xml file in the EAP_HOME/modules/myorg-conf/main/ directory containing the following XML:

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

2. Modify the ee subsystem in the server configuration file. You can use the Managemet CLI or you can manually edit the file.
   • Follow these steps to modify the server configuration file using the Management CLI.
     1. Start the server and connect to the Management CLI.
        • For Linux, enter the following at the command line:

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

        • For Windows, enter the following at a command line:

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

        You should see the following response:

        Connected to standalone controller at localhost:9999

     2. To create the myorg-conf <global-modules> element in the ee subsystem, type the following in the command line:

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

        You should see the following result:

        {"outcome" => "success"}

   • Follow these steps if you prefer to manually edit the server configuration file.
     1. Stop the server and open the server configuration file in a text editor. If you are running a standalone server, this is the EAP_HOME/standalone/configuration/standalone.xml file, or the EAP_HOME/domain/configuration/domain.xml file if you are running a managed domain.
     2. Find the ee subsystem and add the global module for myorg-conf. The following is an example of the ee subsystem element, modified to include the myorg-conf element:

        Example 3.1. myorg-conf element

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

3. Assuming you copied a file named my.properties into the correct module location, you are now able to load properties files using code similar to the following:

   Example 3.2. Load properties file

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

Procedure 3.3. Update application logging code

1. Section 3.1.4.2, “Update Application Code for Third-party Logging Frameworks”
2. Section 3.1.4.3, “Modify Code to Use the New JBoss Logging Framework”

Procedure 3.4. Configure JBoss EAP 6 to use a log4j.properties or log4j.xml file

1. Create a jboss-deployment-structure.xml with the following content:

   <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. Place the jboss-deployment-structure.xml file in either the META-INF/ directory or the WEB-INF/ directory if you are deploying a WAR, or in the META-INF/ directory if you are deploying an EAR. If your deployment includes dependent child deployments, you must also exclude the module for each subdeployment.
3. Include the log4j.properties or log4j.xml file in the lib/ directory of your EAR, or the WEB-INF/classes/ directory of your WAR deployment. If you prefer to place the file in lib/ directory of your WAR, you must specify the <resource-root> path in the jboss-deployment-structure.xml file.

   <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. Start the JBoss EAP 6 server with the following runtime argument to prevent a ClassCastException from appearing in the console when you deploy the application:

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

5. Deploy your application.

Procedure 3.5. Configure Logging Dependencies for JBoss EAP 6.3 or later

1. Start the JBoss EAP 6 server with the following runtime argument to prevent a ClassCastException from appearing in the console when you deploy the application:

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

2. Open a terminal and connect to the Management CLI.
   • For Linux, enter the following at the command line:

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

   • For Windows, enter the following at a command line:

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

3. Modify the add-logging-api-dependencies attribute in the logging subsystem.
   This attribute controls whether the container adds implicit logging API dependencies to your deployments.

   • If set to true, which is the default, all implicit logging API dependencies are added.
   • If set to false, the dependencies are not added to your deployments.
   To exclude the third-party logging framework dependencies, you must set this attribute to false using the following command:

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

   This command adds the <add-logging-api-dependencies> element to the logging subsystem of the standalone.xml configuration file.

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

4. Deploy your application.

Procedure 3.6. Modify Code and Dependencies to Use the JBoss Logging Framework

1. Change your imports and logging code.
   The following is an example of code that uses the new JBoss Logging framework.

   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. Add the logging dependency.
   The JAR containing the JBoss Logging classes is located in the module named org.jboss.logging. Your MANIFEST-MF file should look like the following.

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

   For more information on how to find the module dependency, refer Section 3.1.2.3, “Update Application Dependencies Due to Class Loading Changes” and Section 4.2.1, “Debug and Resolve Migration Issues”.

Procedure 3.7. Modify archive packaging

1. Package a WAR.
   A WAR is a single module and all classes in the WAR are loaded with the same class loader. This means classes packaged in the WEB-INF/lib/ directory are treated the same as classes in the WEB-INF/classes directory.
2. Package an EAR.
   An EAR consists of multiple modules. The EAR/lib/ directory is a single module and every WAR or EJB jar subdeployment within the EAR is a separate module. Classes do not have access to classes in other modules within the EAR unless explicit dependencies have been defined. Subdeployments always have an automatic dependency on the parent module which gives them access to classes in the EAR/lib/ directory. However, subdeployments do not always have an automatic dependency to allow them to access each other. This behavior is controlled by setting the <ear-subdeployments-isolated> element in the ee subsystem configuration as follows.

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

   By default this is set to false which allows the subdeployments to see classes belonging to other subdeployments within the EAR.
   For more information on class loading, see the chapter entitled Class Loading and Modules in the Development Guide for JBoss EAP 6 on https://access.redhat.com/documentation/en-us/red_hat_jboss_enterprise_application_platform/?version=6.4.

1. If your application uses a datasource, see: Section 3.1.6.2, “Update the DataSource Configuration”.
2. If your application uses JPA and currently bundles the Hibernate JARs, see the following for your migration options: Section 3.1.6.4, “Configure the Datasource for Hibernate or JPA”.
3. If your application uses a resource adapter, see: Section 3.1.6.5, “Update the Resource Adapter Configuration”.
4. Review the following for information on how to configure changes for basic security: Section 3.1.7.1, “Configure Application Security Changes”.

Procedure 3.8. Install and Configure the JDBC Driver

1. Install the JDBC Driver.
   1. Install the JDBC Driver as a deployment.
      This is the recommended way to install the driver. When the JDBC driver is installed as a deployment, it is deployed as a regular JAR. If the JBoss EAP 6 instance is running as a standalone server, copy the JDBC 4.0 compliant JAR into the EAP_HOME/standalone/deployments/ directory. For a managed domain, you must use the Management Console or Management CLI to deploy the JAR to the server groups.
      The following is an example of a MySQL JDBC driver installed as a deployment to a standalone server:

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

      Any JDBC 4.0 compliant driver is automatically recognized and installed into the system by name and version. A JDBC 4.0 compliant JAR contains a text file named META-INF/services/java.sql.Driver which specifies the driver class name(s). If the driver is not JDBC 4.0 compliant, it can be made deployable in one of the following ways:

      • Create and add a java.sql.Driver file to the JAR under the META-INF/services/ path. This file should contain the driver class name, for example:

        com.mysql.jdbc.Driver

      • Create a java.sql.Driver file in the deployment directory. For a JBoss EAP 6 instance running as a standalone server, the file should be placed here: EAP_HOME/standalone/deployments/META-INF/services/java.sql.Driver. If the server is in a managed domain, you must use the Management Console or Management CLI to deploy the file.
      The pros of this approach are:

      • This is the easiest method because there is no need to define a module.
      • When the server is running in a managed domain, deployments that use this approach are automatically propagated to all servers in the domain. This means the administrator does not need to distribute the driver JAR manually.

      The cons of this approach are:

      • If the JDBC driver consists of more than one JAR, for example the driver JAR plus a dependent license JAR or localization JAR, you can not install the driver as a deployment. You must install the JDBC driver as a core module.
      • If the driver is not JDBC 4.0 compliant, a file must be created containing the driver class name(s) and must be imported into the JAR or overlayed in the deployments/ directory.
   2. Install the JDBC Driver as a core module.
      To install a JDBC driver as a core module, you must create a file path structure under the EAP_HOME/modules/ directory. This structure contains the JDBC driver JAR, any additional vendor license or localization JARs, and a module.xml file to define the module.
      • Install the MySQL JDBC Driver as a core module
        1. Create the directory structure EAP_HOME/modules/com/mysql/main/
        2. In the main/ subdirectory, create a module.xml file containing the following module definition for the MySQL JDBC driver:

           <?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>
           
           

           The module name, "com.mysql", matches the directory structure for this module. The <dependencies> element is used to specify this module's dependencies on other modules. In this case, as is the case with all JDBC datasources, it is dependent on the Java JDBC APIs which are defined in another module named javax.api. That module is located under the modules/system/layers/base/javax/api/main/ directory.

           Note

           Make sure you do NOT have a space at the beginning of module.xml file or you will get a "New missing/unsatisfied dependencies" error for this driver.
        3. Copy the MySQL JDBC driver JAR into the EAP_HOME/modules/com/mysql/main/ directory:

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

      • Install the IBM DB2 JDBC driver and license JAR as a core module.
        This example is provided to only demonstrate how to deploy drivers that require JARs in addition to the JDBC Driver JAR.
        1. Create the directory structure EAP_HOME/modules/com/ibm/db2/main/.
        2. In the main/ subdirectory, create a module.xml file containing the following module definition for the IBM DB2 JDBC driver and license:

           <?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>
           

           Note

           Make sure you do NOT have a space at the beginning of module.xml file or you will get a "New missing/unsatisfied dependencies" error for this driver.
        3. Copy the JDBC driver and license JAR to the EAP_HOME/modules/com/ibm/db2/main/ directory.

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

      The pros of this approach are:

      • This is the only approach that works when the JDBC driver consists of more than one JAR.
      • With this approach, drivers that are not JDBC 4.0 compliant can be installed without modifying the driver JAR or creating a file overlay.

      The cons of this approach are:

      • It is more difficult to set up a module.
      • The module must be manually copied to every server running in a managed domain.
2. Configure the datasource.
   1. Add the database driver.
      Add the <driver> element to the <drivers> element of the same file. Again, this contains some of the same datasource information that was previously defined in the *-ds.xml file.
      First determine if the driver JAR is JDBC 4.0 compliant. A JAR that is JDBC 4.0 compliant contains a META-INF/services/java.sql.Driver file that specifies the driver class name. The server uses this file to find the name of the driver class(es) in the JAR. A driver that is JDBC 4.0 compliant does not require a <driver-class> element since it is already specified in the JAR. This is an example of the driver element for a JDBC 4.0 compliant MySQL driver:

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

      A driver that is not JDBC 4.0 compliant requires a <driver-class> attribute to identify the driver class since there is no META-INF/services/java.sql.Driver file that specifies the driver class name. This is an example of the driver element for driver that is not JDBC 4.0 compliant:

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

   2. Create the datasource.
      Create a <datasource> element in the <datasources> section of the standalone.xml file. This file contains much of the same datasource information that was previously defined in the *-ds.xml file.

      Important

      You must stop the server before editing the server configuration file for your change to be persisted on server restart.
      The following is an example of a MySQL datasource element in the standalone.xml file:

      <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. Update JNDI references in the application code.
   You must replace outdated JNDI lookup names in the application source code to use the new JNDI standardized datasource names you have defined. For more information, see: Section 3.1.8.4, “Modify the Application to Follow the New JNDI Namespace Rules”.
   You must also replace any existing @Resource annotations that access the datasource to use the new JNDI name. For example:

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

Procedure 3.9. Remove the Hibernate bundle

1. Remove the Hibernate JARs from your application library folders.
2. Remove or comment out the <hibernate.transaction.manager_lookup_class> element in your persistence.xml file as this element is not needed.

Procedure 3.10. Enable the Cached Connection Manager

1. Enable CCM in the datasources subsystem of the server configuration file by setting <use-ccm="true". This is the default value and does not need to be set explicitly.

   <subsystem xmlns="urn:jboss:domain:datasources:1.2">
     <datasources>
       <datasource ... enabled="true" use-ccm="true">
         ...
       </datasource>
     </datasources>
   </subsystem>

2. Verify that the <cached-connection-manager> exists in the jca subsystem of the server configuration file. Set the debug attribute to true.

   <subsystem xmlns="urn:jboss:domain:jca:1.1">
     ...
     <cached-connection-manager debug="true" error="true"/>
     ...
   </subsystem>

   Setting debug="true" causes the following to happen.

   • An INFO message is logged with the following message: "Closing a connection for you. Please close them yourself"
   • A stacktrace is generated for the code that opened the leaked connection.
   • The leaked connection is closed.

   The additional property error="true" can be used to raise a RuntimeException and generate an ERROR message in the log.
3. Activating debug will have some impact on performance and log file size, so it is only recommended for use during testing. After verifying that no leaks remain and before deploying applications to production, restore the configuration by removing the debug="true" setting or using <cached-connection-manager debug="false"/>.

Procedure 3.11. Debug Leaks Not Reported by Cached Connection Manager

1. Be sure the datasource subsystem of the server configuration file is not configured with use-ccm="false"
2. Be sure the datasource subsystem of the server configuration file is not configured with jta="false"
3. Be sure the minimum logging level is set to INFO for org.jboss.jca.

Procedure 3.12. Disable Additional Authorization Checks

• You can disable the additional authorization checks and keep using the existing PicketLink deployments by using one of the following methods.
  • Set a system-wide property.
    You can disable additional authorization checks at the server level by setting the org.jboss.ws.cxf.disableHandlerAuthChecks system property value to true. This method affects any deployment made to the application server.
    For information on how to set a system property, see the topic entitled Configure System Properties Using the Management CLI in the Administration and Configuration Guide for JBoss EAP.
  • Create a property in the deployment's web services descriptor file.
    You can disable additional authorization checks at the deployment level by setting the org.jboss.ws.cxf.disableHandlerAuthChecks property value to true in the jboss-webservices.xml file. This method impacts only the specific deployment.
    1. Create a jboss-webservices.xml file in the META-INF/ directory of the deployment in which you want to disable additional authorization checks.
    2. Add the following content.

       <?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>

Procedure 3.13. Modify JNDI lookups

1. Learn more about Section 3.1.8.2, “Portable EJB JNDI Names”
2. Section 3.1.8.3, “Review the JNDI Namespace Rules”
3. Section 3.1.8.4, “Modify the Application to Follow the New JNDI Namespace Rules”