Chapter 3. Migrate Your Application

3.1. Changes Required by Most Applications

3.1.1. Review Changes Required by Most Applications

Class loading and configuration changes in JBoss Enterprise Application Platform 6 will impact almost every application. JBoss Enterprise Application Platform 6 also uses new standard portable JNDI naming syntax. These changes will impact most applications, so it is suggested you review the following information first when you migrate your application.

3.1.2. Class Loading Changes

3.1.2.1. Update the Application Due to Class Loading Changes

Modular class loading is a significant change in JBoss Enterprise Application Platform 6and will impact almost every application. Review the following information first when you 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”

3.1.2.2. Understand Module Dependencies

Summary
A module is only able to access its own classes and the classes of any module on which it has an explicit or implicit dependency.

Procedure 3.1. Task

  1. Understand implicit dependencies

    The deployers within the server implicitly automatically add some commonly used module dependencies, like the javax.api and sun.jdk. This makes the classes visible to the deployment at runtime and relieves the developer of the task of explicitly adding the dependencies. For details on how and when these implicit dependencies are added, see Implicit Module Dependencies in the Class Loading and Modules chapter of the Development Guide for JBoss Enterprise Application Platform 6.
  2. Understand explicit dependencies

    For other classes, the modules must be specified explicitly or else the missing dependencies result in deployment or runtime errors. If a dependency is missing, you see ClassNotFoundExceptions or NoClassDefFoundErrors traces in the server log. If more than one module loads the same JAR or a module loads a class that extends a class loaded by a different module, you see ClassCastExceptions traces in the server log. To specify dependencies explicitly, modify the MANIFEST.MF or create a JBoss specific deployment descriptor file jboss-deployment-structure.xml. For more information on module dependencies, see Overview of Class Loading and Modules in the Class Loading and Module chapter of the Development Guide for JBoss Enterprise Application Platform 6.

3.1.2.3. Update Application Dependencies Due to Class Loading Changes

Summary
Class loading in JBoss Enterprise Application Platform 6 is considerably different than in previous versions of JBoss Enterprise Application Platform. Class loading is now based on the JBoss Modules project. Rather than a single, hierarchical class loader that loads all JARs into a flat class path, each library becomes a module that only links against the exact modules on which it depends. Deployments in JBoss Enterprise Application Platform 6 are also modules and do not have access to classes that are defined in JARs in the application server unless an explicit dependency on those classes is defined. Some module dependencies defined by the application server are set up for you automatically. For instance, if you are deploying a Java EE application, a dependency on the Java EE API is added to your module automatically. For a complete list of the dependencies that are automatically added see Implicit Module Dependencies in the Class Loading and Modules chapter of the Development Guide for JBoss Enterprise Application Platform 6.
Tasks
When you migrate your application to JBoss Enterprise Application Platform 6, you may need to perform one or more of the following tasks due to the modular class loading changes:

3.1.3. Configuration File Changes

3.1.3.1. Create or Modify Files That Control Class Loading in JBoss Enterprise Application Platform 6

Summary
Due to the change in JBoss Enterprise Application Platform 6 to use modular class loading, you may need to create or modify one or more files to add dependencies or to prevent automatic dependencies from loading. For more information on class loading and class loading precedence, see the Class Loading and Modules chapter of the Development Guide for JBoss Enterprise Application Platform 6.
The following files are used to control class loading in JBoss Enterprise Application Platform 6.
jboss-web.xml
If you have defined a <class-loading> element in the jboss-web.xml file, you need to remove it. The behavior that this evoked in JBoss Enterprise Application Platform 5 is now the default class loading behavior in JBoss Enterprise Application Platform 6, so it is no longer necessary. If you do not remove this element, you see a ParseError and XMLStreamException in your server log.
This is an example of a <class-loading> element in the jboss-web.xml file that is commented out.

<jboss-web>  
<!-- 
    <class-loading java2ClassLoadingCompliance="false">
        <loader-repository>
            seam.jboss.org:loader=MyApplication
            <loader-repository-config>java2ParentDelegation=false</loader-repository-config>
        </loader-repository>
    </class-loading>
 -->
 </jboss-web>

MANIFEST.MF
Manually edited
Depending on which components or modules your application uses, you may need to add one or more dependencies to this file. You can add them as either Dependencies or Class-Path entries.
The following is an example of MANIFEST.MF edited by a developer:
Manifest-Version: 1.0
Dependencies: org.jboss.logmanager
Class-Path: OrderManagerEJB.jar

If you modify this file, make sure to include a newline character at the end of the file.
Generated using Maven
If you use Maven, you need to modify your pom.xml file to generate the dependencies for the MANIFEST.MF file. If your application uses EJB 3.0, you may have a section in the pom.xml file that looks like the following:
<plugin>
    <groupId>org.apache.maven.plugins</groupId>
    <artifactId>maven-ejb-plugin</artifactId>
    <configuration>
        <ejbVersion>3.0</ejbVersion>
    </configuration>
</plugin>
If the EJB 3.0 code uses org.apache.commons.log, you need that dependency in the MANIFEST.MF file. To generate that dependency, add the <plugin> element to the pom.xml file as follows:
<plugin>
    <groupId>org.apache.maven.plugins</groupId>
    <artifactId>maven-ejb-plugin</artifactId>
    <configuration>
        <ejbVersion>3.0</ejbVersion>
        <archive>
            <manifestFile>src/main/resources/META-INF/MANIFEST.MF</manifestFile>
        </archive>
    </configuration>
</plugin>
In the above example, the src/main/resourcres/MANIFEST.MF file only needs to contain the dependency entry:
Dependencies: org.apache.commons.logging
Maven will generate the complete MANIFEST.MF file:
Manifest-Version: 1.0
Dependencies: org.apache.commons.logging
jboss-deployment-structure.xml
This file is a JBoss specific deployment descriptor that can be used to control class loading in a fine grained manner. Like the MANIFEST.MF, this file can be used to add dependencies. It can also prevent automatic dependencies from being added, define additional modules, change an EAR deployment's isolated class loading behavior, and add additional resource roots to a module.
The following is an example of a jboss-deployment-structure.xml file that adds a dependency for JSF 1.2 module and prevents the automatic loading of the JSF 2.0 module.
<jboss-deployment-structure xmlns="urn:jboss:deployment-structure:1.0">
  <deployment>
      <dependencies>
        <module name="javax.faces.api" slot="1.2" export="true"/>
              <module name="com.sun.jsf-impl" slot="1.2" export="true"/>
      </dependencies>
  </deployment>
  <sub-deployment name="jboss-seam-booking.war">
    <exclusions>
        <module name="javax.faces.api" slot="main"/>
              <module name="com.sun.jsf-impl" slot="main"/>
      </exclusions>
      <dependencies>
        <module name="javax.faces.api" slot="1.2"/>
              <module name="com.sun.jsf-impl" slot="1.2"/>
      </dependencies>
  </sub-deployment>
</jboss-deployment-structure>
For additional information about this file, see: Section 3.1.3.2, “jboss-deployment-structure.xml”.
application.xml
In previous versions of JBoss Enterprise Application Platform, you controlled the order of deployments within an EAR using the jboss-app.xml file. This is no longer the case. The Java EE6 spec provides the <initialize-in-order> element in the application.xml which allows control of the order in which the Java EE modules within an EAR are deployed.
In most cases you do not need to specify deployment order. If your application uses dependency injections and resource-refs to refer to components in external modules, in most cases the <initialize-in-order> element is not required because the application server is able to implicitly determine the correct and optimal way of ordering the components.
Let's assume you have an application that contains a myBeans.jar and a myApp.war within a myApp.ear. A servlet in the myApp.war@EJB injects a bean from myBeans.jar. In this case, the application server has the appropriate knowledge to make sure that the EJB component is available before the servlet is started and you do not have to use the <initialize-in-order> element.
However, if that servlet uses legacy JNDI lookup style remote references like the following to access the bean, you may need to specify module order.
init() {
  Context ctx = new InitialContext();
  ctx.lookup("TheBeanInMyBeansModule");
}
In this case, the server is not able to determine that the EJB component is in the myBeans.jar and you need to enforce that the components in the myBeans.jar are initialized and started before the components in myApp.war. To do this, you set the <initialize-in-order> element to true and specify the order of the myBeans.jar and myApp.war modules in the application.xml file.
The following is an example that uses the <initialize-in-order> element to control deployment order. The myBeans.jar is deployed before the myApp.war file.
<application xmlns="http://java.sun.com/xml/ns/javaee" 
             xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" version="6"
             xsi:schemaLocation="http://java.sun.com/xml/ns/javaee 
             http://java.sun.com/xml/ns/javaee/application_6.xsd">
    <application-name>myApp</application-name>
    <initialize-in-order>true</initialize-in-order>
    <module>
        <ejb>myBeans.jar</ejb>
    </module>
    <module>
        <web>
            <web-uri>myApp.war</web-uri>
            <context-root>myApp</context-root>
        </web>
    </module>
</application>
The schema for the application.xml file can be found here at http://java.sun.com/xml/ns/javaee/application_6.xsd.

Note

You should be aware that setting the <initialize-in-order> element to true slows down deployment. It is preferable to define proper dependencies using dependency injections or resource-refs since it allows the container more flexibility in optimizing deployments.
jboss-ejb3.xml
The jboss-ejb3.xml deployment descriptor replaces the jboss.xml deployment descriptor to override and add to the features provided by the Java Enterprise Edition (EE) defined ejb3-jar.xml deployment descriptor. The new file is incompatible with jboss.xml, and the jboss.xml is now ignored in deployments.
login-config.xml
The login-config.xml file is no longer used for security configuration. Security is now configured in the <security-domain> element in the server configuration file. For a standalone server, this is the standalone/configuration/standalone.xml file. If you are running your server in a managed domain, this is the domain/configuration/domain.xml file.

3.1.3.2. jboss-deployment-structure.xml

jboss-deployment-structure.xml is a new optional deployment descriptor for JBoss Enterprise Application Platform 6. This deployment descriptor provides control over class loading in the deployment.
The XML schema for this deployment descriptor is in EAP_HOME/docs/schema/jboss-deployment-structure-1_2.xsd

3.1.3.3. Package Resources for the New Modular Class Loading System

Summary
In previous versions of JBoss Enterprise Application Platform, all resources inside the WEB-INF/ directory were added to the WAR classpath. In JBoss Enterprise Application Platform 6, web application artifacts are only loaded from the WEB-INF/classes and WEB-INF/lib directories. Failure to package application artifacts in the specifed locations can result in ClassNotFoundException, NoClassDefError, or other runtime errors.
To resolve these class loading errors, you must modify the structure of your application archive or define a custom module.

Modify the Resource Packaging
To make the resources available only to the application, you must bundle the properties files, JARs, or other artifacts with the WAR by moving them to the WEB-INF/classes/ or WEB-INF/lib/ directory. This approach is described in more detail here: Section 3.1.3.4, “Change ResourceBundle Properties Location”
Create a Custom Module
If you want make custom resources available to all applications running on the JBoss Enterprise Application Platform server, you must create a custom module. This approach is described in more detail here: Section 3.1.3.5, “Create a Custom Module”

3.1.3.4. Change ResourceBundle Properties Location

Summary
In previous versions of JBoss Enterprise Application Platform, the EAP_HOME/server/SERVER_NAME/conf/ directory was in the classpath and available to the application. To make properties available to the classpath of the application in JBoss Enterprise Application Platform 6, you must package them within your application.

Procedure 3.2. 

  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.

3.1.3.5. Create a Custom Module

The following procedure describes how to create a custom module in order to make properties files and other resources available to all applications running on the JBoss Enterprise Application Platform server.

Procedure 3.3. 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 JBoss CLI or you can manually edit the file.
    • Follow these steps to modify the server configuration file using the JBoss 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
          $ Connected to standalone controller at localhost:9999
          
        • For Windows, enter the following at a command line:
          C:\>EAP_HOME\bin\jboss-cli.bat --connect
          C:\> 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:
        <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:
    Thread.currentThread().getContextClassLoader().getResource("my.properties");
    

3.1.4. Logging Changes

3.1.4.1. Modify Logging Dependencies

Summary
JBoss LogManager supports front ends for all logging frameworks, so you can keep your current logging code or move to the new JBoss logging infrastructure. Regardless of your decision, because of the modular class loading changes, you probably need to modify your application to add the required dependencies.

3.1.4.2. Update Application Code for Third-party Logging Frameworks

Summary
In JBoss Enterprise Application Platform 6, logging dependencies for common third-party frameworks like Apache Commons Logging, Apache log4j, SLF4J, and Java Logging are added by default. However, if you are using log4j and you do not want to use the logging subsystem to configure your handlers (appenders), you need to exclude the JBoss Enterprise Application Platform log4j module.

Procedure 3.5. Configure JBoss Enterprise Application Platform 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.
  3. Include the log4j.properties or log4j.xml file in the lib/ directory in your deployment.
  4. Start the JBoss Enterprise Application Platform 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.

Note

If you choose to use a log4j configuration file, you will no longer be able to change the log4j logging configuration at runtime.

3.1.4.3. Modify Code to Use the New JBoss Logging Framework

Summary
To use the new framework, change your imports and code as follows:

Procedure 3.6. Task

  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 this:
    Manifest-Version: 1.0
    Dependencies: org.jboss.logging
    

3.1.5. Application Packaging Changes

3.1.5.1. Modify Packaging of EARs and WARs

Summary
When you migrate your application, you may have to change the packaging structure of your EAR or WAR due to the change to modular class loading. Module dependencies are loaded in this specific order:
  1. System dependencies
  2. User dependencies
  3. Local resources
  4. Inter-deployment dependencies

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 Class Loading and Modules chapter of the Development Guide for JBoss Enterprise Application Platform 6.

3.1.6. Datasource and Resource Adapter Configuration Changes

3.1.6.1. Update the Application Due to Configuration Changes

In JBoss Enterprise Application Platform 5, services and subsystems were configured in many different files. In JBoss Enterprise Application 6, configuration is now done mainly in one file. If your application uses any of the following resources or services, configuration changes may be needed.
  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”.

3.1.6.2. Update the DataSource Configuration

Summary
In previous versions of the JBoss Enterprise Application Platform, the JCA datasource configuration was defined in a file with a suffix of *-ds.xml. This file was then deployed in the server's deploy/ directory or packaged with the application. The JDBC driver was copied to the server/lib/ directory or packaged in the application's WEB-INF/lib/ directory. While this method of configuring a datasource is still supported for development, it is not recommended for production because it is not supported by the JBoss administrative and management tools.
In JBoss Enterprise Application Platform 6, the datasource is configured in the server configuration file. If the JBoss Enterprise Application Platform instance is running in a managed domain, the datasource is configured in the domain/configuration/domain.xml file. If the JBoss Enterprise Application Platform instance is running as a standalone server, the datasource is configured in the standalone/configuration/standalone.xml file. Datasources configured this way can be managed and controlled using the JBoss management interfaces, including the Web Management Console and command line interface (CLI). These tools make it easy to manage deployments and configure multiple servers running in a managed domain.
The following section describes how to modify your datasource configuration so that it can be managed and supported by the available management tools.
Migrate to a Manageable Datasource Configuration for JBoss Enterprise Application Platform 6
A JDBC 4.0 compliant driver can be installed as a deployment or as a core module. A driver that is JDBC 4.0 compliant contains a META-INF/services/java.sql.Driver file that specifies the driver class name. A driver that is not JDBC 4.0 compliant requires additional steps. For details on how to make a driver JDBC 4.0 compliant and how update your current datasource configuration to one that is manageable by the Web Management Console and CLI, see Section 3.1.6.3, “Install and Configure the JDBC Driver”.
If your application uses Hibernate or JPA, it may require additional changes. See Section 3.1.6.4, “Configure the Datasource for Hibernate or JPA” for more information.
Use the IronJacamar Migration Tool to Convert Configuration Data
You can Section 4.1.6, “Use the IronJacamar Tool to Migrate Datasource and Resource Adapter Configurations”. This tool converts the *-ds.xml style configuration files into the format expected by JBoss Enterprise Application Platform 6.

3.1.6.3. Install and Configure the JDBC Driver

Summary
The JDBC driver can be installed into the container in one of the following two ways:

  • As a deployment
  • As a core module
The pros and cons of each approach are noted below.
In JBoss Enterprise Application Platform 6, the datasource is configured in the server configuration file. If the JBoss Enterprise Application Platform instance is running in a managed domain, the datasource is configured in the domain/configuration/domain.xml file. If the JBoss Enterprise Application Platform instance is running as a standalone server, the datasource is configured in the standalone/configuration/standalone.xml file. Schema reference information, which is the same for both modes, can be found in the doc/ directory of the JBoss Enterprise Application Platform 6 install. For purposes of this discussion, assume the server is running as standalone server and the datasource is configured in the standalone.xml file.

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 Enterprise Application Platform instance is running as a standalone server, copy the JDBC 4.0 compliant JAR into the EAP_HOME/standalone/deployments/ directory. If the server is running in a managed domain, copy the JAR into the EAP_HOME/domain/deployments/ directory.
      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 Enterprise Application Platform 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, the file should be placed here: EAP_HOME/domain/deployments/META-INF/services/java.sql.Driver.
      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 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:
          
          <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/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:
          
          <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.1.6.4. Configure the Datasource for Hibernate or JPA

If your application uses JPA and currently bundles the Hibernate JARs, you may want to use the Hibernate that is included with JBoss Enterprise Application Platform 6. To use this version of Hibernate, you must remove the old Hibernate bundle from your application.

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.

3.1.6.5. Update the Resource Adapter Configuration

Summary
In previous versions of the application server, the resource adapter configuration was defined in a file with a suffix of *-ds.xml. In JBoss Enterprise Application Platform 6, a resource adapter is configured in the server configuration file. If you are running in a managed domain, the configuration file is the EAP_HOME/domain/configuration/domain.xml file. If you are running as a standalone server, configure the resource adapter in the EAP_HOME/standalone/configuration/standalone.xml file. Schema reference information, which is the same for both modes, can be found here: Resource adapter descriptors.

Important

You must stop the server before editing the server configuration file for your change to be persisted on server restart.
Define the resource adapter
The resource adapter descriptor information is defined under the following subsystem element in the server configuration file:
<subsystem xmlns="urn:jboss:domain:resource-adapters:1.0"/>
You will use some of the same information that was previously defined in the resource adapter *-ds.xml file.
The following is an example of a resource adapter element in the server configuration file:
<resource-adapters>
  <resource-adapter>
    <archive>multiple-full.rar</archive>
    <config-property name="Name">ResourceAdapterValue</config-property>
    <transaction-support>NoTransaction</transaction-support>
    <connection-definitions>
      <connection-definition
      class-name="org.jboss.jca.test.deployers.spec.rars.multiple.MultipleManagedConnectionFactory1"
      enabled="true" jndi-name="java:/eis/MultipleConnectionFactory1"
      pool-name="MultipleConnectionFactory1">
    <config-property name="Name">MultipleConnectionFactory1Value</config-property>
      </connection-definition>
      <connection-definition
      class-name="org.jboss.jca.test.deployers.spec.rars.multiple.MultipleManagedConnectionFactory2"
      enabled="true" jndi-name="java:/eis/MultipleConnectionFactory2"
      pool-name="MultipleConnectionFactory2">
    <config-property name="Name">MultipleConnectionFactory2Value</config-property>
      </connection-definition>
    </connection-definitions>
    <admin-objects>
      <admin-object
      class-name="org.jboss.jca.test.deployers.spec.rars.multiple.MultipleAdminObject1Impl"
      jndi-name="java:/eis/MultipleAdminObject1">
    <config-property name="Name">MultipleAdminObject1Value</config-property>
      </admin-object>
      <admin-object class-name="org.jboss.jca.test.deployers.spec.rars.multiple.MultipleAdminObject2Impl"
      jndi-name="java:/eis/MultipleAdminObject2">
    <config-property name="Name">MultipleAdminObject2Value</config-property>
      </admin-object>
      </admin-objects>
  </resource-adapter>
</resource-adapters>

3.1.7. Security Changes

3.1.7.1. Configure Application Security Changes

Configure security for basic authentication
The UsersRolesLoginModule has always looked for properties files in the classpath. In previous versions of JBoss Enterprise Application Platform, properties files placed in the EAP_HOME/server/SERVER_NAME/conf/ directory were on classpath and could be easily found by the UsersRolesLoginModule. In JBoss Enterprise Application Platform 6, the directory structure has changed. Properties files must be packaged within the application to make them available in the classpath.

Important

You must stop the server before editing the server configuration file for your change to be persisted on server restart.
To configure security for basic authentication, add a new security domain under security-domains to the standalone/configuration/standalone.xml or the domain/configuration/domain.xml server configuration file:
<security-domain name="example">
    <authentication>
        <login-module code="UsersRoles" flag="required">
            <module-option name="usersProperties" 
                    value="${jboss.server.config.dir}/example-users.properties"/>
            <module-option name="rolesProperties" 
                    value="${jboss.server.config.dir}/example-roles.properties"/>
        </login-module>
    </authentication>
</security-domain>
If the JBoss Enterpise Application Platform 6 instance is running as a standalone server, ${jboss.server.config.dir} refers to the EAP_HOME/standalone/configuration/ directory. If the instance is running in a managed domain, ${jboss.server.config.dir} refers to the EAP_HOME/domain/configuration/ directory.
Modify security domain names
In JBoss Enterprise Application Platform 6, security domains no longer use the prefix java:/jaas/ in their names.
  • For Web applications, you must remove this prefix from the security domain configurations in the jboss-web.xml.
  • For Enterprise applications, you must remove this prefix from the security domain configurations in the jboss-ejb3.xml file. This file has replaced the jboss.xml in JBoss Enterprise Application Platform 6.

3.1.8. JNDI Changes

3.1.8.1. Update Application JNDI Namespace Names

Summary
EJB 3.1 introduced a standardized global JNDI namespace and a series of related namespaces that map to the various scopes of a Java EE application. The three JNDI namespaces used for portable JNDI lookups are java:global, java:module, and java:app. Applications that use JNDI lookups must be changed to follow the new standardized JNDI namespace convention.
Example JNDI Mappings
Examples of JNDI namespaces in previous releases and how they are specified in JBoss Enterprise Application Platform 6 can be found here: Section 3.1.8.5, “Examples of JNDI Namespaces in Previous Releases and How They are Specified in JBoss Enterprise Application Platform 6”

3.1.8.2. Portable JNDI Naming Syntax

Summary
There are four logical namespaces, each with its own scope. Three of the namespaces are used for portable JNDI lookups. The following table details when and how to use each namespace.

Table 3.1. Portable JNDI Namespaces

JNDI Namespace Description
java:global
Names in this namespace are shared by all applications deployed in an application server instance. Use names in this namespace to find remote EJBs.
The following is an example of a java:global namespace: java:global/jboss-seam-booking/jboss-seam-booking.jar/HotelBookingAction
java:module
Names in this namespace are shared by all components in a module, for example, all enterprise beans in a single EJB module or all components in a web module.
The following is an example of a java:module namespace: java:module/HotelBookingAction!org.jboss.seam.example.booking.HotelBooking
java:app
Names in this namespace are shared by all components in all modules in a single application. For example, a WAR and an EJB jar file in the same EAR file would have access to resources in the java:app namespace.
The following is an example of a java:app namespace: java:app/jboss-seam-booking.jar/HotelBookingAction

You can find more information about JNDI naming contexts in section EE.5.2.2, "Application Component Environment Namespaces" in the "JSR 316: JavaTM Platform, Enterprise Edition (Java EE) Specification, v6". You can download the specification from here: http://jcp.org/en/jsr/detail?id=316

3.1.8.3. Review the JNDI Namespace Rules

Summary
JBoss Enterprise Application Platform 6 has improved upon JNDI namespace names, not only to provide predictable and consistent rules for every name bound in the application server, but also to prevent future compatibility issues. This means you might run into issues with the current namespaces in your application if they don't follow the new rules.
Namespaces should follow these rules:
  1. Unqualified relative names like DefaultDS or jdbc/DefaultDS should be qualified relative to java:comp/env, java:module/env, or java:jboss/env, depending on the context.
  2. Unqualified absolute names like /jdbc/DefaultDS should be qualified relative to a java:jboss/root name.
  3. Qualified absolute names like java:/jdbc/DefaultDS should be qualified the same way as Unqualified absolute names above.
  4. The special java:jboss namespace is shared across the entire AS server instance.
  5. Any relative name with a java: prefix must be in one of the five namespaces: comp, module, app, global, or the proprietary jboss. Any name starting with java:xxx where xxx does not match any of the above five would result in an invalid name error.

3.1.8.4. Modify the Application to Follow the New JNDI Namespace Rules

  • Here is an example of a JNDI lookup in JBoss Enterprise Application Platform 5.1. This code is usually found in an initialization method.
    private ProductManager productManager;
    try {
        context = new InitialContext();
        productManager = (ProductManager) context.lookup("OrderManagerApp/ProductManagerBean/local");
    } catch(Exception lookupError) {
        throw new ServletException("Unable to find the ProductManager bean", lookupError);
    }
    
    Note the lookup name is OrderManagerApp/ProductManagerBean/local.
  • The following is an example of how the same lookup would be coded in JBoss Enterprise Application Platform 6.
    @EJB(lookup=“java:app/OrderManagerEJB/ProductManagerBean!services.ejb.ProductManager")
    private ProductManager productManager;
    
    The lookup values are now defined as member variables and use the new portable java:app JNDI namespace name java:app/OrderManagerEJB/ProductManagerBean!services.ejb.ProductManager.

3.1.8.5. Examples of JNDI Namespaces in Previous Releases and How They are Specified in JBoss Enterprise Application Platform 6

Table 3.2. 

Namespace in JBoss Enterprise Application Platform 5.x Namespace in JBoss Enterprise Application Platform 6 Additional Comments
OrderManagerApp/ProductManagerBean/local java:module/ProductManagerBean!services.ejb.ProductManager EE6 standard binding, only accessible within the same module
OrderManagerApp/ProductManagerBean/local java:app/OrderManagerEJB/ProductManagerBean!services.ejb.ProductManager EE6 standard binding, only accessible within the same application
OrderManagerApp/ProductManagerBean/local java:global/OrderManagerApp/OrderManagerEJB/ProductManagerBean!services.ejb.ProductManager EE6 standard binding, globally accessible
java:comp/UserTransaction java:comp/UserTransaction This is accessible for non EE threads, e.g. Threads your application directly creates
java:comp/UserTransaction java:jboss/UserTransaction Globally accessible, use this if java:comp/UserTransaction is not available
java:/TransactionManager java:jboss/TransactionManager
java:/TransactionSynchronizationRegistry java:jboss/TransactionSynchronizationRegistry