Migration Guide

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

      Copy to Clipboard Toggle word wrap
   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>

      Copy to Clipboard Toggle word wrap
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

          Copy to Clipboard Toggle word wrap
        • For Windows, enter the following at a command line:

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

          Copy to Clipboard Toggle word wrap
        You should see the following response:

        Connected to standalone controller at localhost:9999

        Copy to Clipboard Toggle word wrap
     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"}])

        Copy to Clipboard Toggle word wrap
        You should see the following result:

        {"outcome" => "success"}

        Copy to Clipboard Toggle word wrap
   • 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>

        Copy to Clipboard Toggle word wrap
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");

   Copy to Clipboard Toggle word wrap

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>
   

   Copy to Clipboard Toggle word wrap
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>
   

   Copy to Clipboard Toggle word wrap
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

   Copy to Clipboard Toggle word wrap
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

   Copy to Clipboard Toggle word wrap
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
     

     Copy to Clipboard Toggle word wrap
   • For Windows, enter the following at a command line:

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

     Copy to Clipboard Toggle word wrap
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)

   Copy to Clipboard Toggle word wrap
   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>
   

   Copy to Clipboard Toggle word wrap
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);
   }
   

   Copy to Clipboard Toggle word wrap
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
   

   Copy to Clipboard Toggle word wrap
   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>

   Copy to Clipboard Toggle word wrap
   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/

      Copy to Clipboard Toggle word wrap
      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

        Copy to Clipboard Toggle word wrap
      • 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>
           
           

           Copy to Clipboard Toggle word wrap
           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/

           Copy to Clipboard Toggle word wrap
      • 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>
           

           Copy to Clipboard Toggle word wrap

           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/

           Copy to Clipboard Toggle word wrap
      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"/>
      

      Copy to Clipboard Toggle word wrap

      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>
      

      Copy to Clipboard Toggle word wrap
   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>
      

      Copy to Clipboard Toggle word wrap
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").
   

   Copy to Clipboard Toggle word wrap

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>

   Copy to Clipboard Toggle word wrap
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>

   Copy to Clipboard Toggle word wrap

   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>

       Copy to Clipboard Toggle word wrap

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”

Procedure 3.14. Configure the Application

1. Copy the required Hibernate 3 JARs to your application library.
   You may be able to resolve the issue by copying the specific Hibernate 3 JARs that contain the missing classes into the application's lib/ directory or by adding them to the classpath using some other method. In some cases this may result in ClassCastExceptions or other class loading issues due to the mixed use of the Hibernate versions. If that happens, you need to use the next approach.
2. Instruct the server to use only the Hibernate 3 libraries.
   JBoss EAP 6 allows you to package Hibernate 3.5 (or greater) persistence provider jars with the application. To direct the server to use only the Hibernate 3 libraries and to exclude the Hibernate 4 libraries, you need to set the jboss.as.jpa.providerModule to hibernate3-bundled in the persistence.xml as follows:

   <?xml version="1.0" encoding="UTF-8"?>
   <persistence xmlns="http://java.sun.com/xml/ns/persistence" version="1.0">
       <persistence-unit name="plannerdatasource_pu">
           <description>Hibernate 3 Persistence Unit.</description>
           <jta-data-source>java:jboss/datasources/PlannerDS</jta-data-source>
           <properties>
               <property name="hibernate.show_sql" value="false" />
               <property name="jboss.as.jpa.providerModule" value="hibernate3-bundled" />
           </properties>
       </persistence-unit>
   </persistence>
   

   Copy to Clipboard Toggle word wrap

   The Java Persistence API (JPA) deployer will detect the presence of a persistence provider in the application and use the Hibernate 3 libraries. For more information on the JPA persistence properties, refer Section 3.2.2.3, “Persistence Unit Properties”.
3. Disable Hibernate second-level cache.
   Second-level cache for Hibernate 3 does not exhibit the same behavior with JBoss EAP 6 as it did in previous releases. If you are using Hibernate second-level cache with your application, you must disable it until you upgrade to Hibernate 4. To disable second-level cache, set the <hibernate.cache.use_second_level_cache> to false in the persistence.xml file.
4. Replace references to org.jboss.ejb3.entity.ExtendedEntityManager.
   In JBoss EAP 5, the org.jboss.ejb3.entity.ExtendedEntityManager class extended javax.persistence.EntityManager for extended persistence context management. In JBoss EAP 6, this class was replaced with the org.jboss.as.jpa.container.ExtendedEntityManager class. However, it is recommended that you update the code to use the standard Java EE 6 JPA API javax.persistence.EntityManager class instead of the proprietary class.

Procedure 3.15. Update the application to use Hibernate 4

1. The default behavior of autoincrement sequence generator has changed in JBoss EAP 6. For more information, refer Section 3.2.2.5, “Preserve the Existing Behavior of the Hibernate Identity Auto Generated Value”.
2. Determine the version of Hibernate currently used by the application and choose the correct update procedure below.
   • Section 3.2.2.6, “Migrate Your Hibernate 3.3.x Application to Hibernate 4.x”
   • Section 3.2.2.7, “Migrate Your Hibernate 3.5.x Application to Hibernate 4.x”
3. Refer Section 3.2.2.8, “Modify Persistence Properties for Migrated Seam and Hibernate Applications that Run in a Clustered Environment” if you plan to run your application in a clustered environment.

1. Hibernate text types are now mapped to JDBC LONGVARCHAR
   In versions of Hibernate prior to 3.5, text type was mapped to JDBC CLOB. A new Hibernate type, materialized_clob, was added in Hibernate 4 to map Java String properties to JDBC CLOB. If your application has properties configured as type="text" that are intended to be mapped to JDBC CLOB, you must do one of the following:
   1. If your application uses hbm mapping files, change the property to type="materialized_clob".
   2. If your application uses annotations, you should replace @Type(type = "text") with @Lob.
2. Review code to find changes in returned value types
   Numeric aggregate criteria projections now return the same value type as their HQL counterparts. As a result, the return types from the following projections in org.hibernate.criterion have changed.
   1. Due to changes in CountProjection, Projections.rowCount(), Projections.count(propertyName), and Projections.countDistinct(propertyName), the count and count distinct projections now return a Long value.
   2. Due to changes in Projections.sum(propertyName), the sum projections now return a value type that depends on the property type.

      Note

      Failure to modify your application code could result in a java.lang.ClassCastException.
      1. For properties mapped as Long, Short, Integer, or primitive integer types, a Long value is returned;
      2. For properties mapped as Float, Double, or primitive floating point types, a Double value is returned.
3. Update the UserType signatures for the nullSafeGet() and nullSafeSet() methods.
   The signatures for the nullSafeGet() and nullSafeSet() methods in the UserType class changed in Hibernate 4. Any application code that uses these methods must be updated to use the new signatures.
   The following is an example of the method signatures in Hibernate 3.x.

   public Object nullSafeGet(ResultSet rs, String[] names, Object owner) 
       throws HibernateException, SQLException;
   
   public void nullSafeSet(PreparedStatement st, Object value, int index) 
       throws HibernateException, SQLException;

   Copy to Clipboard Toggle word wrap

   The following is an example of the new method signatures in Hibernate 4.

   public Object nullSafeGet(ResultSet rs, String[] names, SessionImplementor session, Object owner) 
       throws HibernateException, SQLException;
   
   public void nullSafeSet(PreparedStatement st, Object value, int index, SessionImplementor session) 
       throws HibernateException, SQLException;

   Copy to Clipboard Toggle word wrap

1. AnnotationConfiguration was merged into Configuration
   Although AnnotationConfiguration is now deprecated, it should not affect your migration.
   1. If you are still using an hbm.xml file, you should be aware that JBoss EAP 6 now uses the org.hibernate.cfg.EJB3NamingStrategy in AnnotationConfiguration instead of the org.hibernate.cfg.DefaultNamingStrategy that was used in previous releases. This can result in naming mismatches.
   2. If you rely on the naming strategy to default the name of an association (many-to-many and collections of elements) table, you may see this issue. To resolve it, you can tell Hibernate to use the legacy org.hibernate.cfg.DefaultNamingStrategy by calling Configuration#setNamingStrategy and passing it org.hibernate.cfg.DefaultNamingStrategy#INSTANCE.
2. Modify the namespaces to conform to the new Hibernate DTD file names as noted in the following table.
   Expand

   Table 3.5. DTD Namespace Mapping Table

   Previous DTD Namespace	New DTD Namespace
   http://hibernate.sourceforge.net/hibernate-configuration-3.0.dtd	http://www.hibernate.org/dtd/hibernate-configuration-3.0.dtd
   http://hibernate.sourceforge.net/hibernate-mapping-3.0.dtd	http://www.hibernate.org/dtd/hibernate-mapping-3.0.dtd

   Show more
3. Modify environment variables.
   1. If you are using Oracle and using the materialized_clob or materialized_blob properties, the global environment variable hibernate.jdbc.use_streams_for_binary must be set to true.
   2. If you are using PostgreSQL and using the CLOB or BLOB properties, the global environment variable hibernate.jdbc.use_streams_for_binary must be set to false.
4. Update the UserType signatures for the nullSafeGet() and nullSafeSet() methods.
   The signatures for the nullSafeGet() and nullSafeSet() methods in the UserType class changed in Hibernate 4. Any application code that uses these methods must be updated to use the new signatures. See Section 3.2.2.6, “Migrate Your Hibernate 3.3.x Application to Hibernate 4.x” for details.

Procedure 3.16. Set persistence properties to run in a clustered environment

1. Set the hibernate.session_factory_name value to a unique name. This name must be unique across all application deployments on the JBoss EAP 6 instance. For example:

   <property name="hibernate.session_factory_name" value="jboss-seam-booking.ear_session_factory"/>
   

   Copy to Clipboard Toggle word wrap
2. Set the hibernate.ejb.entitymanager_factory_name value to a unique name. This name must be unique across all application deployments on the JBoss EAP 6 instance. For example:

   <property name="hibernate.ejb.entitymanager_factory_name" value="seam-booking.ear_PersistenceUnitName"/>
   

   Copy to Clipboard Toggle word wrap

Procedure 3.17. Modify the persistence.xml file to use Infinispan

1. Configure Infinispan for a JPA application in JBoss EAP 6
   This is an example of how properties to achieve the same configuration for a JPA application using Infinispan in JBoss EAP 6 can be specified:

   <property name="hibernate.cache.use_second_level_cache" value="true"/>
   

   Copy to Clipboard Toggle word wrap

   In addition, you need to specify a shared-cache-mode with a value of ENABLE_SELECTIVE or ALL as follows:
   • ENABLE_SELECTIVE is the default and recommended value. It means entities are not cached unless you explicitly mark them as cacheable.

     <shared-cache-mode>ENABLE_SELECTIVE</shared-cache-mode>
     

     Copy to Clipboard Toggle word wrap
   • ALL means entities are always cached even if you mark them as not cacheable.

     <shared-cache-mode>ALL</shared-cache-mode>
     

     Copy to Clipboard Toggle word wrap
2. Configure Infinispan for a native Hibernate application in JBoss EAP 6
   This is an example of how the same configuration for a native Hibernate application using Infinispan with JBoss EAP 6 can be specified:

   <property name="hibernate.cache.region.factory_class"
        value="org.jboss.as.jpa.hibernate4.infinispan.InfinispanRegionFactory"/>
   <property name="hibernate.cache.infinispan.cachemanager"
        value="java:jboss/infinispan/container/hibernate"/>     
   <property name="hibernate.transaction.jta.platform"
        value="org.hibernate.service.jta.platform.internal.JBossAppServerJtaPlatform"/>
   <property name="hibernate.cache.use_second_level_cache" value="true"/>
   
   

   Copy to Clipboard Toggle word wrap

   You must also add the following dependencies to the MANIFEST.MF file:

   Manifest-Version: 1.0
   Dependencies: org.infinispan, org.hibernate
   

   Copy to Clipboard Toggle word wrap

Procedure 3.18. You may need to perform one or more of the following tasks

1. Access the default ValidatorFactory
   JBoss EAP 6 binds a default ValidatorFactory to the JNDI context under the name java:comp/ValidatorFactory.
2. Understand life cycle triggered validation
   When used in combination with Hibernate Core 4, life-cycle based validation is automatically enabled by Hibernate Core.
   1. Validation occurs on entity INSERT, UPDATE, and DELETE operations.
   2. You can configure the groups to be validated by event type using the following properties:

      • javax.persistence.validation.group.pre-persist,
      • javax.persistence.validation.group.pre-update, and
      • javax.persistence.validation.group.pre-remove.

      The values of these properties are the comma-separated, fully qualified class names of the groups to validate.
      Validation groups are a new feature of the Bean Validation specification. If you do not want to take advantage of this new feature, no changes are required when you migrate to Hibernate Validator 4.
   3. You can disable life-cycle based validation by setting the javax.persistence.validation.mode property to none. Other valid values for this property are auto (the default), callback and ddl.
3. Configure your application to use manual validation
   1. To manually control validation, you can create a Validator in either of the following ways:

      • Create a Validator instance from the ValidatorFactory using the getValidator() method.
      • Inject Validator instances in your EJB, CDI bean or any other Java EE injectable resource.
   2. You can use the ValidatorContext returned by the ValidatorFactory.usingContext() to customize your Validator instance. Using this API you can configure a custom MessageInterpolator, TraverableResolver and ConstraintValidatorFactory. These interfaces are specified in the Bean Validation specification and are new to Hibernate Validator 4.
4. Modify code to use the new Bean Validation constraints
   The new Bean level validation constraints require code changes when you migrate to Hibernate Validator 4.
   1. To upgrade to Hibernate Validator 4, you must use the constraints in the following packages:

      • javax.validation.constraints
      • org.hibernate.validator.constraints
   2. All constraints that existed in Hibernate Validator 3 are still available in Hibernate Validator 4. To use them, you need to import the specified class, and in some cases, change the name or type of the constraint parameter.
5. Use custom constraints
   In Hibernate Validator 3, a custom constraint needed to implement the org.hibernate.validator.Validator interface. In Hibernate Validator 4, you need to implement the javax.validation.ConstraintValidator interface. This interface contains the same initialize() and isValid() methods as the previous interface, however, the method signature has changed. In addition, DDL alteration is no longer supported in Hibernate Validator 4.
6. The following Hibernate 3.x Validator classes are obsolete.
   1. Replace org.hibernate.validator.NotNull with javax.validation.constraints.NotNull.
   2. Replace org.hibernate.validator.ClassValidator with javax.validation.Validator..
   3. Replace org.hibernate.validator.InvalidValue with javax.validation.Validator..
   For more information, see the Hibernate Valitator Reference Guide.
7. The jboss-ejb3-ext-api-VERSION.jar file removed many of the annotation extension APIs because they are no longer needed in JBoss EAP 6. For example, the org.jboss.ejb3.annotation.IgnoreDependency class is no longer available or needed because JBoss EAP 6 handles the interdependencies automatically.

Procedure 3.19. Configure JBoss EAP to Use Axis

1. You must first disable the web services implementation that ships with JBoss EAP 6. For detailed instructions, see Section 3.2.6.3, “Disable JBossWS in JBoss EAP 6”.
2. Rebuild and deploy the application. The Axis WS API implementation should now access the Java EE 6 API classes correctly.

Procedure 3.20. Disable JBossWS for a Single Deployment

1. Create a jboss-deployment-structure.xml file for your application.
   • If your application is packaged and deployed as a WAR, create the jboss-deployment-structure.xml file in either the META-INF/ or the WEB-INF/ directory of the WAR with the following contents.

     <jboss-deployment-structure xmlns="urn:jboss:deployment-structure:1.2">
       <deployment>
         <!-- Exclude webservices subsystem so the implicit dependencies will not be added -->
          <exclude-subsystems>
             <subsystem name="webservices"/>
         </exclude-subsystems>
       </deployment>
     </jboss-deployment-structure>

     Copy to Clipboard Toggle word wrap
   • If your application is packaged and deployed in an EAR, create the jboss-deployment-structure.xml file in the META-INF/ directory of the EAR with contents similar to the following example.

     <jboss-deployment-structure xmlns="urn:jboss:deployment-structure:1.2">
       ...
       <sub-deployment name="example.war">
         <!-- Exclude webservices subsystem so the implicit dependencies will not be added -->
          <exclude-subsystems>
             <subsystem name="webservices"/>
         </exclude-subsystems>
         <dependencies>
            ...
         </dependencies>
       </sub-deployment>
     </jboss-deployment-structure>
     

     Copy to Clipboard Toggle word wrap
2. Deploy the application in the usual manner. JBossWS is now disabled for the application.

Procedure 3.21. Disable JBossWS for All Deployments to the Server

1. Stop the JBoss EAP server.
2. Open the server configuration file for editing. For a standalone server, this is the EAP_HOME/standalone/configuration/standalone.xml file. For a managed domain, this is the EAP_HOME/domain/configuration/domain.xml file.
3. Find the org.jboss.as.webservices extension and either comment it out or remove it.
4. Find the webservices subsystem profile and either comment it out or remove it.
5. The following is an example of the changes maded to a standalone.xml file.

   <?xml version='1.0' encoding='UTF-8'?>
   <server xmlns="urn:jboss:domain:1.7">
     <extensions>
          ...
       <!-- <extension module="org.jboss.as.webservices"/> -->
          ...
     </extensions>
     ...
     <profile>
       <!--
       <subsystem xmlns="urn:jboss:domain:webservices:1.2">
         <modify-wsdl-address>true</modify-wsdl-address>
         <wsdl-host>${jboss.bind.address:127.0.0.1}</wsdl-host>
         <endpoint-config name="Standard-Endpoint-Config"/>
         <endpoint-config name="Recording-Endpoint-Config">
           <pre-handler-chain name="recording-handlers" protocol-bindings="##SOAP11_HTTP ##SOAP11_HTTP_MTOM ##SOAP12_HTTP ##SOAP12_HTTP_MTOM">
   	       <handler name="RecordingHandler" class="org.jboss.ws.common.invocation.RecordingServerHandler"/>
           </pre-handler-chain>
         </endpoint-config>
       	<client-config name="Standard-Client-Config"/>
     	</subsystem>
       -->
     ...
     </profile>
     ...
   </server>

   Copy to Clipboard Toggle word wrap

Procedure 3.22. Create a JMS Bridge

1. Configure the Bridge on the Source JBoss EAP 5.x Server
   To avoid conflicts in classes between releases, you must follow these steps to configure the JMS bridge on JBoss EAP 5.x. The names of the SAR directory and bridge are arbitrary and can be changed if you prefer.
   1. Create a subdirectory in the JBoss EAP 5 deployment directory to contain the SAR, for example: EAP5_HOME/server/PROFILE_NAME/deploy/myBridge.sar/.
   2. Create a subdirectory named META-INF in EAP5_HOME/server/PROFILE_NAME/deploy/myBridge.sar/.
   3. Create a jboss-service.xml file in the EAP5_HOME/server/PROFILE_NAME/deploy/myBridge.sar/META-INF/ directory. It should contain information similar to the following example.

      <server>
         <loader-repository>
            com.example:archive=unique-archive-name
            <loader-repository-config>java2ParentDelegation=false</loader-repository-config>
         </loader-repository> 
      
         <!-- JBoss EAP 6 JMS Provider --> 
         <mbean code="org.jboss.jms.jndi.JMSProviderLoader" name="jboss.messaging:service=JMSProviderLoader,name=EnterpriseApplicationPlatform6JMSProvider">
            <attribute name="ProviderName">EnterpriseApplicationPlatform6JMSProvider</attribute>
            <attribute name="ProviderAdapterClass">org.jboss.jms.jndi.JNDIProviderAdapter</attribute>
            <attribute name="FactoryRef">jms/RemoteConnectionFactory</attribute> 
            <attribute name="QueueFactoryRef">jms/RemoteConnectionFactory</attribute>  
            <attribute name="TopicFactoryRef">jms/RemoteConnectionFactory</attribute>      
            <attribute name="Properties">
               java.naming.factory.initial=org.jboss.naming.remote.client.InitialContextFactory
               java.naming.provider.url=remote://EnterpriseApplicationPlatform6host:4447
               java.naming.security.principal=jbossuser
               java.naming.security.credentials=jbosspass
            </attribute>
         </mbean> 
      
         <mbean code="org.jboss.jms.server.bridge.BridgeService" name="jboss.jms:service=Bridge,name=MyBridgeName" xmbean-dd="xmdesc/Bridge-xmbean.xml">      
            <depends optional-attribute-name="SourceProviderLoader">jboss.messaging:service=JMSProviderLoader,name=JMSProvider</depends>          
            <depends optional-attribute-name="TargetProviderLoader">jboss.messaging:service=JMSProviderLoader,name=EnterpriseApplicationPlatform6JMSProvider</depends>          
            <attribute name="SourceDestinationLookup">/queue/A</attribute>      
            <attribute name="TargetDestinationLookup">jms/queue/test</attribute>       
            <attribute name="QualityOfServiceMode">1</attribute>           
            <attribute name="MaxBatchSize">1</attribute>      
            <attribute name="MaxBatchTime">-1</attribute>           
            <attribute name="FailureRetryInterval">60000</attribute>      
            <attribute name="MaxRetries">-1</attribute>      
            <attribute name="AddMessageIDInHeader">false</attribute>
            <attribute name="TargetUsername">jbossuser</attribute>
            <attribute name="TargetPassword">jbosspass</attribute>
         </mbean>
      </server>
      
      

      Copy to Clipboard Toggle word wrap

      Note

      The load-repository element is present to ensure the SAR has an isolated class loader. Also note both the JNDI look-up and the bridge "target" include security credentials for user "jbossuser" with password "jbosspass". This is because JBoss EAP 6 is secured by default. The user named "jbossuser" with password "jbosspass" was created in the ApplicationRealm with the guest role using the EAP_HOME/bin/add_user.sh script.
   4. Copy the following JARs from the EAP_HOME/modules/system/layers/base/ directory into the EAP5_HOME/server/PROFILE_NAME/deploy/myBridge.sar/ directory. Replace each VERSION_NUMBER with the actual version number in your JBoss EAP 6 distribution.

      • org/hornetq/main/hornetq-core-VERSION_NUMBER.jar
      • org/hornetq/main/hornetq-jms-VERSION_NUMBER.jar
      • org/jboss/ejb-client/main/jboss-ejb-client-VERSION_NUMBER.jar
      • org/jboss/logging/main/jboss-logging-VERSION_NUMBER.jar
      • org/jboss/logmanager/main/jboss-logmanager-VERSION_NUMBER.jar
      • org/jboss/marshalling/main/jboss-marshalling-VERSION_NUMBER.jar
      • org/jboss/marshalling/river/main/jboss-marshalling-river-VERSION_NUMBER.jar
      • org/jboss/remote-naming/main/jboss-remote-naming-VERSION_NUMBER.jar
      • org/jboss/remoting3/main/jboss-remoting-VERSION_NUMBER.jar
      • org/jboss/sasl/main/jboss-sasl-VERSION_NUMBER.jar
      • org/jboss/netty/main/netty-VERSION_NUMBER.jar
      • org/jboss/remoting3/remote-jmx/main/remoting-jmx-VERSION_NUMBER.jar
      • org/jboss/xnio/main/xnio-api-VERSION_NUMBER.jar
      • org/jboss/xnio/nio/main.xnio-nio-VERSION_NUMBER.jar

      Note

      Do not simply copy the EAP_HOME/bin/client/jboss-client.jar because the javax API classes will conflict with those in JBoss EAP 5.x.
2. Configure the Bridge on the Destination JBoss EAP 6 Server
   In JBoss EAP 6.1 and later, the JMS bridge can be used to bridge messages from any JMS 1.1 compliant server. Because the source and target JMS resources are looked up using JNDI, the JNDI lookup classes of the source messaging provider, or message broker, must be bundled in a JBoss Module. The following steps use the fictitious 'MyCustomMQ' message broker as an example.
   1. Create the JBoss module for the messaging provider.
      1. Create a directory structure under EAP_HOME/modules/system/layers/base/ for the new module. The main/ subdirectory will contain the client JARs and module.xml file. The following is an example of the directory structure created for the MyCustomMQ messaging provider: EAP_HOME/modules/system/layers/base/org/mycustommq/main/
      2. In the main/ subdirectory, create a module.xml file containing the module definition for the messaging provider. The following is an example of the module.xml created for the MyCustomMQ messaging provider.

         <?xml version="1.0" encoding="UTF-8"?>
         <module xmlns="urn:jboss:module:1.1" name="org.mycustommq">
             <properties>
                 <property name="jboss.api" value="private"/>
             </properties> 
         
             <resources>
                 <!-- Insert resources required to connect to the source or target   -->
                 <resource-root path="mycustommq-1.2.3.jar" />
                 <resource-root path="mylogapi-0.0.1.jar" />
             </resources> 
         
             <dependencies>
                <!-- Add the dependencies required by JMS Bridge code                 -->
                <module name="javax.api" />
                <module name="javax.jms.api" />
                <module name="javax.transaction.api"/>
                <!-- Add a dependency on the org.hornetq module since we send         -->
                <!-- messages tothe HornetQ server embedded in the local EAP instance -->
                <module name="org.hornetq" />
             </dependencies>
         </module>
         

         Copy to Clipboard Toggle word wrap
      3. Copy the messaging provider JARs required for the JNDI lookup of the source resources to the module's main/ subdirectory. The directory structure for the MyCustomMQ module should now look like the following.

         modules/
         `-- system
             `-- layers
                 `-- base
                     `-- org
                           `-- mycustommq
                               `-- main
                                   |-- mycustommq-1.2.3.jar
                                   |-- mylogapi-0.0.1.jar
                                   |-- module.xml
         

         Copy to Clipboard Toggle word wrap
   2. Configure the JMS bridge in the messaging subsystem of the JBoss EAP 6 server.
      1. Before you begin, stop the server and back up the current server configuration files. If you are running a standalone server, this is the EAP_HOME/standalone/configuration/standalone-full-ha.xml file. If you are running a managed domain, back up both the EAP_HOME/domain/configuration/domain.xml and the EAP_HOME/domain/configuration/host.xml files.
      2. Add the jms-bridge element to the messaging subsystem in the server configuration file. The source and target elements provide the names of the JMS resources used for JNDI lookups. If user and password credentials are specified, they are passed as arguments when JMS connection is created.
         The following is an example of the jms-bridge element configured for the MyCustomMQ messaging provider:

         <subsystem xmlns="urn:jboss:domain:messaging:1.3">
            ...
            <jms-bridge name="myBridge" module="org.mycustommq">
               <source>
                  <connection-factory name="ConnectionFactory"/>
                  <destination name="sourceQ"/>
                  <user>user1</user>
                  <password>pwd1</password>
                  <context>
                     <property key="java.naming.factory.initial" value="org.mycustommq.jndi.MyCustomMQInitialContextFactory"/>
                     <property key="java.naming.provider.url"    value="tcp://127.0.0.1:9292"/>
                  </context>
               </source>
               <target>
                  <connection-factory name="java:/ConnectionFactory"/>
                  <destination name="/jms/targetQ"/>
               </target>
               <quality-of-service>DUPLICATES_OK</quality-of-service>
               <failure-retry-interval>500</failure-retry-interval>
               <max-retries>1</max-retries>
               <max-batch-size>500</max-batch-size>
               <max-batch-time>500</max-batch-time>
               <add-messageID-in-header>true</add-messageID-in-header>
            </jms-bridge>
         </subsystem>
         

         Copy to Clipboard Toggle word wrap

         In the above example, the JNDI properties are defined in the context element for the source. If the context element is omitted, as in the target example above, the JMS resources are looked up in the local instance.

Procedure 3.23. Change Your Provider to HornetQ

1. Transfer configurations.
   Transfer the existing JBoss Messaging configurations to the JBoss EAP 6 configuration. The following configurations can be found in deployment descriptors located on the JBoss Messaging server:
   • Connection Factories Service Configuration
     This configuration describes the JMS connection factories deployed with the JBoss Messaging server. JBoss Messaging configures connection factories in a file named connection-factories-service.xml which is located in the deployment directory of the application server.
   • Destination Configuration
     This configuration describes JMS queues and topics deployed with JBoss Messaging server. By default, JBoss Messaging configures destinations in a file named destinations-service.xml which is located in the deployment directory of the application server.
   • Message Bridge Service Configuration
     This configuration includes bridge services deployed with JBoss Messaging server. No bridges are deployed by default so the name of the deployment file varies depending on your JBoss Messaging installation.
2. Modify your application code.
   If the application code uses standard JMS, no code changes are required. However, you must modify the application to use the new standardized JNDI namespaces as described in the section Section 3.1.8.2, “Portable EJB JNDI Names”. If the application uses features specific to JBoss Messaging, you must modify the code to use the equivalent features available in HornetQ.
   The following is an example of a JMS client that creates the InitialContext and looks up a queue in JBoss EAP 6.

   Hashtable<String, String> env = new Hashtable<String, String>();
   String providerUrl = "remote:" + host + ":" + port;
   env.put(Context.URL_PKG_PREFIXES, "org.jboss.ejb.client.naming");
   env.put("java.naming.factory.initial", "org.jboss.naming.remote.client.InitialContextFactory");
   env.put("java.naming.provider.url", providerUrl);
   env.put(Context.SECURITY_PRINCIPAL, user);
   env.put(Context.SECURITY_CREDENTIALS, pass);
   InitialContext context = new InitialContext(env);
   Queue myTestQueue = (Queue) context.lookup("jms/queue/myTestQueue");
   

   Copy to Clipboard Toggle word wrap
   If the application will be connecting to a cluster, you must carefully review the HornetQ documentation on clustering semantics. Clustering is outside the scope of the JMS specification and HornetQ and JBoss Messaging have taken substantially different approaches in their respective implementations of clustering functionality.
   For more information on how to configure messaging with HornetQ, see: Section 3.2.9.5, “Configure Messaging with HornetQ”
3. Migrate existing messages.
   Move any messages in the JBoss Messaging database to the HornetQ journal using a JMS bridge. Instructions for configuring the JMS bridge can be found here: Section 3.2.9.2, “Configure a JMS Bridge to Migrate Existing JMS Messages to JBoss EAP 6”.

1. Start JBoss EAP 6 with clustering enabled

   To enable clustering in JBoss EAP 5.x, you needed to start your server instances using the all profile or some derivation of it, like this:

   $ EAP5_HOME/bin/run.sh -c all

   Copy to Clipboard Toggle word wrap
   In JBoss EAP 6, the method for enabling clustering depends on whether the servers are standalone or running in a managed domain.

   1. Enable clustering for servers running in a managed domain

      To enable clustering for servers started using the domain controller, update your domain.xml and designate a server group to use the ha profile and ha-sockets socket binding group. For example:

      <server-groups>
        <server-group name="main-server-group" profile="ha">
          <jvm name="default">
            <heap size="64m" max-size="512m"/>
          </jvm>
          <socket-binding-group ref="ha-sockets"/>
        </server-group>
      </server-group>

      Copy to Clipboard Toggle word wrap

   2. Enable clustering for standalone servers

      To enable clustering for standalone servers, start the server using the appropriate configuration file as follows:

      $ EAP_HOME/bin/standalone.sh --server-config=standalone-ha.xml -Djboss.node.name=UNIQUE_NODE_NAME

      Copy to Clipboard Toggle word wrap

2. Specify the bind address

   In JBoss EAP 5.x, you would typically indicate the bind address used for clustering using the -b command line argument like this:

   $ EAP5_HOME/bin/run.sh -c all -b 192.168.0.2

   Copy to Clipboard Toggle word wrap
   JBoss EAP 6 binds sockets to the IP addresses and interfaces contained in the <interfaces> elements in standalone.xml, domain.xml and host.xml files. The standard configurations that ship with JBoss EAP include two interface configurations:

   <interfaces>
       <interface name="management">
           <inet-address value="${jboss.bind.address.management:127.0.0.1}"/>
       </interface>
       <interface name="public">
          <inet-address value="${jboss.bind.address:127.0.0.1}"/>
       </interface>
   </interfaces>

   Copy to Clipboard Toggle word wrap

   These interface configurations use the values of the system properties jboss.bind.address.management and jboss.bind.address. If these system properties are not set, the default 127.0.0.1 is used for each value.
   You can also specify the bind address as a command line argument when you start the server or you can explicitly define it within the JBoss EAP 6 server configuration file.
   • Specify the bind argument on the command line when you start the JBoss EAP standalone server.
     The following is an example of how to specify the bind address on the command line for a standalone server:

     EAP_HOME/bin/standalone.sh -Djboss.bind.address=127.0.0.1

     Copy to Clipboard Toggle word wrap

     Note

     You can also use the -b argument, which is a shortcut for -Djboss.bind.address=127.0.0.1:

     EAP_HOME/bin/standalone.sh -b=127.0.0.1

     Copy to Clipboard Toggle word wrap

     The JBoss EAP 5 syntax format is also still supported:

     EAP_HOME/bin/standalone.sh -b 127.0.0.1

     Copy to Clipboard Toggle word wrap

     Note that the -b argument only changes the public interface. It does not affect the management interface.
   • Specify the bind address in the server configuration file.
     For servers running in a managed domain, specify the bind addresses in the domain/configuration/host.xml file. For standalone servers, specify the bind addresses in the standalone-ha.xml file.
     In the following example, the public interface is specified as the default interface for all sockets within the ha-sockets socket binding group.

     <interfaces>
       <interface name="management">
         <inet-address value="192.168.0.2"/>
       </interface>
       <interface name="public">
         <inet-address value="192.168.0.2"/>
       </interface>
     </interfaces>

     Copy to Clipboard Toggle word wrap

     <socket-binding-groups>
       <socket-binding-group name="ha-sockets" default-interface="public">
         <!-- ... -->
       </socket-binding-group>
     </socket-binding-groups>

     Copy to Clipboard Toggle word wrap

     Note

     If you specify the bind address as a hard-coded value rather than a system property in the configuration file, you can not override it with a command line argument.

3. Configure jvmRoute to support mod_jk and mod_proxy

   In JBoss EAP 5, the web server jvmRoute was configured using a property in the server.xml file. In JBoss EAP 6, the jvmRoute attribute is configured in the web subsystem of the server configuration file using the instance-id attribute as follows:

   <subsystem xmlns="urn:jboss:domain:web:1.1" default-virtual-server="default-host" native="false" instance-id="{JVM_ROUTE_SERVER}">
   

   Copy to Clipboard Toggle word wrap

   The {JVM_ROUTE_SERVER} above should be replaced by the jvmRoute server ID.
   The instance-id can also be set using the Management Console.

4. Specify the multicast address and port

   In JBoss EAP 5.x, you could specify the multicast address and port used for intra-cluster communication using the command line arguments -u and -m, respectively, like this:

   $ EAP5_HOME/bin/run.sh -c all -u 228.11.11.11 -m 45688

   Copy to Clipboard Toggle word wrap
   In JBoss EAP 6, the multicast address and port used for intra-cluster communication are defined by the socket-binding referenced by the relevant JGroups protocol stack as follows:

   <subsystem xmlns="urn:jboss:domain:jgroups:1.0" default-stack="udp">
       <stack name="udp">
           <transport type="UDP" socket-binding="jgroups-udp"/>
           <!-- ... -->
       </stack>
   </subsystem>

   Copy to Clipboard Toggle word wrap

   <socket-binding-groups>
       <socket-binding-group name="ha-sockets" default-interface="public">
           <!-- ... -->
           <socket-binding name="jgroups-udp" port="55200" multicast-address="228.11.11.11" multicast-port="45688"/>
           <!-- ... -->
       </socket-binding-group>
   </socket-binding-groups>
   

   Copy to Clipboard Toggle word wrap

   If you prefer to specify the multicast address and port in the command line, you can define the multicast address and ports as system properties and then use those properties on the command line when you start the server. In the following example, jboss.mcast.addr is the variable name for the multicast address and jboss.mcast.port is the variable name for the port.

   <socket-binding name="jgroups-udp" port="55200"
    multicast-address="${jboss.mcast.addr:230.0.0.4}" multicast-port="${jboss.mcast.port:45688}"/>
   

   Copy to Clipboard Toggle word wrap

   You can then start your server using the following command line arguments:

   $ EAP_HOME/bin/domain.sh -Djboss.mcast.addr=228.11.11.11 -Djboss.mcast.port=45688

   Copy to Clipboard Toggle word wrap

5. Use an alternate protocol stack

   In JBoss EAP 5.x, you could manipulate the default protocol stack used for all clustering services using the jboss.default.jgroups.stack system property.

   $ EAP5_HOME/bin/run.sh -c all -Djboss.default.jgroups.stack=tcp

   Copy to Clipboard Toggle word wrap
   In JBoss EAP 6, the default protocol stack is defined by the JGroups subsystem within domain.xml or standalone-ha.xml:

   <subsystem xmlns="urn:jboss:domain:jgroups:1.0" default-stack="udp">
       <stack name="udp">
           <!-- ... -->
       </stack>
   </subsystem>

   Copy to Clipboard Toggle word wrap

6. Replace Buddy Replication

   JBoss EAP 5.x used JBoss Cache Buddy Replication to suppress replication of data to all instances in a cluster.
   In JBoss EAP 6, Buddy Replication has been replaced by Infinispan's distributed cache, also known as DIST mode. Distribution is a powerful clustering mode which allows Infinispan to scale linearly as more servers are added to the cluster. The following is an example of how to configure the server to use the DIST caching mode.
   1. Open a command line and start the server with either the HA or Full Profile, for example:

      EAP_HOME/bin/standalone.sh -c standalone-ha.xml

      Copy to Clipboard Toggle word wrap
   2. Open another command line and connect to the Management CLI.
      • For Linux, enter the following at the command line:

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

        Copy to Clipboard Toggle word wrap
      • For Windows, enter the following at a command line:

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

        Copy to Clipboard Toggle word wrap
      You should see the following response:

      Connected to standalone controller at localhost:9999

      Copy to Clipboard Toggle word wrap
   3. Issue the following commands to configure the cache tell the server to reload the new configuration:

      /subsystem=infinispan/cache-container=web/:write-attribute(name=default-cache,value=dist)
      /subsystem=infinispan/cache-container=web/distributed-cache=dist/:write-attribute(name=owners,value=3)
      reload
      

      Copy to Clipboard Toggle word wrap
      You should see the following response after each command:

      "outcome" => "success"
      

      Copy to Clipboard Toggle word wrap
      These commands modify the dist <distributed-cache> element in the web <cache-container> configuration in the infinispan subsystem of the standalone-ha.xml file as follows:

      <cache-container name="web" aliases="standard-session-cache" default-cache="dist" module="org.jboss.as.clustering.web.infinispan">
          <transport lock-timeout="60000"/>
          <replicated-cache name="repl" mode="ASYNC" batching="true">
              <file-store/>
          </replicated-cache>
          <replicated-cache name="sso" mode="SYNC" batching="true"/>
          <distributed-cache name="dist" owners="3" l1-lifespan="0" mode="ASYNC" batching="true">
              <file-store/>
          </distributed-cache>
      </cache-container>
      

      Copy to Clipboard Toggle word wrap

      For more information, see the chapter entitled Clustering in Web Applications in the Development Guide for JBoss EAP 6 located on the Customer Portal at https://access.redhat.com/documentation/en-us/red_hat_jboss_enterprise_application_platform/?version=6.4.

Procedure 3.24. Implement an HA Singleton Service

1. Write the HA singleton service application.
   The following is a simple example of a Service that is wrapped with the SingletonService decorator to be deployed as a singleton service. A complete example can be found in the cluster-ha-singleton quickstart that ships with Red Hat JBoss Enterprise Application Platform 6. This quickstart contains all the instructions to build and deploy the application.
   1. Create a service.
      The following listing is an example of a service:

      package org.jboss.as.quickstarts.cluster.hasingleton.service.ejb;
      
      import java.util.Date;
      import java.util.concurrent.atomic.AtomicBoolean;
      
      import javax.naming.InitialContext;
      import javax.naming.NamingException;
      
      import org.jboss.logging.Logger;
      import org.jboss.msc.service.Service;
      import org.jboss.msc.service.ServiceName;
      import org.jboss.msc.service.StartContext;
      import org.jboss.msc.service.StartException;
      import org.jboss.msc.service.StopContext;
      
      
      /**
       * @author <a href="mailto:wfink@redhat.com">Wolf-Dieter Fink</a>
       */
      public class HATimerService implements Service<String> {
          private static final Logger LOGGER = Logger.getLogger(HATimerService.class);
          public static final ServiceName SINGLETON_SERVICE_NAME = ServiceName.JBOSS.append("quickstart", "ha", "singleton", "timer");
      
          /**
           * A flag whether the service is started.
           */
          private final AtomicBoolean started = new AtomicBoolean(false);
      
          /**
           * @return the name of the server node
           */
          public String getValue() throws IllegalStateException, IllegalArgumentException {
              LOGGER.infof("%s is %s at %s", HATimerService.class.getSimpleName(), (started.get() ? "started" : "not started"), System.getProperty("jboss.node.name"));
              return "";
          }
      
          public void start(StartContext arg0) throws StartException {
              if (!started.compareAndSet(false, true)) {
                  throw new StartException("The service is still started!");
              }
              LOGGER.info("Start HASingleton timer service '" + this.getClass().getName() + "'");
      
              final String node = System.getProperty("jboss.node.name");
              try {
                  InitialContext ic = new InitialContext();
                  ((Scheduler) ic.lookup("global/jboss-cluster-ha-singleton-service/SchedulerBean!org.jboss.as.quickstarts.cluster.hasingleton.service.ejb.Scheduler")).initialize("HASingleton timer @" + node + " " + new Date());
              } catch (NamingException e) {
                  throw new StartException("Could not initialize timer", e);
              }
          }
      
          public void stop(StopContext arg0) {
              if (!started.compareAndSet(true, false)) {
                  LOGGER.warn("The service '" + this.getClass().getName() + "' is not active!");
              } else {
                  LOGGER.info("Stop HASingleton timer service '" + this.getClass().getName() + "'");
                  try {
                      InitialContext ic = new InitialContext();
                      ((Scheduler) ic.lookup("global/jboss-cluster-ha-singleton-service/SchedulerBean!org.jboss.as.quickstarts.cluster.hasingleton.service.ejb.Scheduler")).stop();
                  } catch (NamingException e) {
                      LOGGER.error("Could not stop timer", e);
                  }
              }
          }
      }
      

      Copy to Clipboard Toggle word wrap
   2. Create an activator that installs the Service as a clustered singleton.
      The following listing is an example of a Service activator that installs the HATimerService as a clustered singleton service:

      package org.jboss.as.quickstarts.cluster.hasingleton.service.ejb;
      
      import org.jboss.as.clustering.singleton.SingletonService;
      import org.jboss.logging.Logger;
      import org.jboss.msc.service.DelegatingServiceContainer;
      import org.jboss.msc.service.ServiceActivator;
      import org.jboss.msc.service.ServiceActivatorContext;
      import org.jboss.msc.service.ServiceController;
      
      
      /**
       * Service activator that installs the HATimerService as a clustered singleton service
       * during deployment.
       *
       * @author Paul Ferraro
       */
      public class HATimerServiceActivator implements ServiceActivator {
          private final Logger log = Logger.getLogger(this.getClass());
      
          @Override
          public void activate(ServiceActivatorContext context) {
              log.info("HATimerService will be installed!");
      
              HATimerService service = new HATimerService();
              SingletonService<String> singleton = new SingletonService<String>(service, HATimerService.SINGLETON_SERVICE_NAME);
              /*
               * To pass a chain of election policies to the singleton, for example, 
               * to tell JGroups to prefer running the singleton on a node with a
               * particular name, uncomment the following line:
               */
              // singleton.setElectionPolicy(new PreferredSingletonElectionPolicy(new SimpleSingletonElectionPolicy(), new NamePreference("node1/singleton")));
      
              singleton.build(new DelegatingServiceContainer(context.getServiceTarget(), context.getServiceRegistry()))
                      .setInitialMode(ServiceController.Mode.ACTIVE)
                      .install()
              ;
          }
      }
      

      Copy to Clipboard Toggle word wrap

      Note

      The above code example uses a class, org.jboss.as.clustering.singleton.SingletonService, that is part of the JBoss EAP private API. A public API will become available in the JBoss EAP 7 release and the private class will be deprecated, but these classes will be maintained and available for the duration of the JBoss EAP 6.x release cycle.
   3. Create a ServiceActivator File
      Create a file named org.jboss.msc.service.ServiceActivator in the application's resources/META-INF/services/ directory. Add a line containing the fully qualified name of the ServiceActivator class created in the previous step.

      org.jboss.as.quickstarts.cluster.hasingleton.service.ejb.HATimerServiceActivator 

      Copy to Clipboard Toggle word wrap
   4. Create a Singleton bean that implements a timer to be used as a cluster-wide singleton timer.
      This Singleton bean must not have a remote interface and you must not reference its local interface from another EJB in any application. This prevents a lookup by a client or other component and ensures the SingletonService has total control of the Singleton.
      1. Create the Scheduler interface

         package org.jboss.as.quickstarts.cluster.hasingleton.service.ejb;
         
         /**
          * @author <a href="mailto:wfink@redhat.com">Wolf-Dieter Fink</a>
          */
         public interface Scheduler {
         
             void initialize(String info);
         
             void stop();
         
         }
         

         Copy to Clipboard Toggle word wrap
      2. Create the Singleton bean that implements the cluster-wide singleton timer.

         package org.jboss.as.quickstarts.cluster.hasingleton.service.ejb;
         
         import javax.annotation.Resource;
         import javax.ejb.ScheduleExpression;
         import javax.ejb.Singleton;
         import javax.ejb.Timeout;
         import javax.ejb.Timer;
         import javax.ejb.TimerConfig;
         import javax.ejb.TimerService;
         
         import org.jboss.logging.Logger;
         
         
         /**
          * A simple example to demonstrate a implementation of a cluster-wide singleton timer.
          *
          * @author <a href="mailto:wfink@redhat.com">Wolf-Dieter Fink</a>
          */
         @Singleton
         public class SchedulerBean implements Scheduler {
             private static Logger LOGGER = Logger.getLogger(SchedulerBean.class);
             @Resource
             private TimerService timerService;
         
             @Timeout
             public void scheduler(Timer timer) {
                 LOGGER.info("HASingletonTimer: Info=" + timer.getInfo());
             }
         
             @Override
             public void initialize(String info) {
                 ScheduleExpression sexpr = new ScheduleExpression();
                 // set schedule to every 10 seconds for demonstration
                 sexpr.hour("*").minute("*").second("0/10");
                 // persistent must be false because the timer is started by the HASingleton service
                 timerService.createCalendarTimer(sexpr, new TimerConfig(info, false));
             }
         
             @Override
             public void stop() {
                 LOGGER.info("Stop all existing HASingleton timers");
                 for (Timer timer : timerService.getTimers()) {
                     LOGGER.trace("Stop HASingleton timer: " + timer.getInfo());
                     timer.cancel();
                 }
             }
         }
         

         Copy to Clipboard Toggle word wrap
2. Start each JBoss EAP 6 instance with clustering enabled.
   To enable clustering for standalone servers, you must start each server with the HA profile, using a unique node name and port offset for each instance.
   • For Linux, use the following command syntax to start the servers:

     EAP_HOME/bin/standalone.sh --server-config=standalone-ha.xml -Djboss.node.name=UNIQUE_NODE_NAME -Djboss.socket.binding.port-offset=PORT_OFFSET

     Copy to Clipboard Toggle word wrap

     Example 3.6. Start multiple standalone servers on Linux

     $ EAP_HOME/bin/standalone.sh --server-config=standalone-ha.xml -Djboss.node.name=node1
     $ EAP_HOME/bin/standalone.sh --server-config=standalone-ha.xml -Djboss.node.name=node2 -Djboss.socket.binding.port-offset=100

     Copy to Clipboard Toggle word wrap
   • For Microsoft Windows, use the following command syntax to start the servers:

     EAP_HOME\bin\standalone.bat --server-config=standalone-ha.xml -Djboss.node.name=UNIQUE_NODE_NAME -Djboss.socket.binding.port-offset=PORT_OFFSET

     Copy to Clipboard Toggle word wrap

     Example 3.7. Start multiple standalone servers on Microsoft Windows

     C:> EAP_HOME\bin\standalone.bat --server-config=standalone-ha.xml -Djboss.node.name=node1
     C:> EAP_HOME\bin\standalone.bat --server-config=standalone-ha.xml -Djboss.node.name=node2 -Djboss.socket.binding.port-offset=100

     Copy to Clipboard Toggle word wrap

   Note

   If you prefer not to use command line arguments, you can configure the standalone-ha.xml file for each server instance to bind on a separate interface.
3. Deploy the application to the servers
   The following Maven command deploys the application to a standalone server running on the default ports.

   mvn clean install jboss-as:deploy

   Copy to Clipboard Toggle word wrap
   To deploy to additional servers, pass the server name. if it is on a different host, pass the host name and port number on the command line:

   mvn clean package jboss-as:deploy -Djboss-as.hostname=localhost -Djboss-as.port=10099

   Copy to Clipboard Toggle word wrap
   See the cluster-ha-singleton quickstart that ships with JBoss EAP 6 for Maven configuration and deployment details.

Procedure 3.25. Add Maven Project Configuration for Remote Invocation of Session Beans

1. Add the required project dependencies
   The pom.xml for the project must be updated to include the necessary dependencies.
2. Add the jboss-ejb-client.properties file
   The JBoss EJB client API expects to find a file in the root of the project named jboss-ejb-client.properties that contains the connection information for the JNDI service. Add this file to the src/main/resources/ directory of your project with the following content.

   # In the following line, set SSL_ENABLED to true for SSL
   remote.connectionprovider.create.options.org.xnio.Options.SSL_ENABLED=false
   remote.connections=default
   # Uncomment the following line to set SSL_STARTTLS to true for SSL
   # remote.connection.default.connect.options.org.xnio.Options.SSL_STARTTLS=true
   remote.connection.default.host=localhost
   remote.connection.default.port = 4447
   remote.connection.default.connect.options.org.xnio.Options.SASL_POLICY_NOANONYMOUS=false
   # Add any of the following SASL options if required
   # remote.connection.default.connect.options.org.xnio.Options.SASL_POLICY_NOANONYMOUS=false
   # remote.connection.default.connect.options.org.xnio.Options.SASL_POLICY_NOPLAINTEXT=false
   # remote.connection.default.connect.options.org.xnio.Options.SASL_DISALLOWED_MECHANISMS=JBOSS-LOCAL-USER
   

   Copy to Clipboard Toggle word wrap
   Change the host name and port to match your server. 4447 is the default port number. For a secure connection, set the SSL_ENABLED line to true and uncomment the SSL_STARTTLS line. The Remoting interface in the container supports secured and unsecured connections using the same port.
3. Add dependencies for the remote business interfaces
   Add the Maven dependencies to the pom.xml for the remote business interfaces of the session beans.

   <dependency>
      <groupId>org.jboss.as.quickstarts</groupId>
      <artifactId>jboss-ejb-remote-server-side</artifactId>
      <type>ejb-client</type>
      <version>${project.version}</version>
   </dependency>

   Copy to Clipboard Toggle word wrap

Procedure 3.26. Obtain a Bean Proxy using JNDI and Invoke Methods of the Bean

1. Handle checked exceptions
   Two of the methods used in the following code (InitialContext() and lookup()) have a checked exception of type javax.naming.NamingException. These method calls must either be enclosed in a try/catch block that catches NamingException or in a method that is declared to throw NamingException. The ejb-remote quickstart uses the second technique.
2. Create a JNDI Context
   A JNDI Context object provides the mechanism for requesting resources from the server. Create a JNDI context using the following code:

   final Hashtable jndiProperties = new Hashtable();
   jndiProperties.put(Context.URL_PKG_PREFIXES, "org.jboss.ejb.client.naming");
   final Context context = new InitialContext(jndiProperties);

   Copy to Clipboard Toggle word wrap
   The connection properties for the JNDI service are read from the jboss-ejb-client.properties file.
3. Use the JNDI Context's lookup() method to obtain a bean proxy
   Invoke the lookup() method of the bean proxy and pass it the JNDI name of the session bean you require. This will return an object that must be cast to the type of the remote business interface that contains the methods you want to invoke.

   final RemoteCalculator statelessRemoteCalculator = (RemoteCalculator) context.lookup(
       "ejb:/jboss-ejb-remote-server-side//CalculatorBean!" + 
       RemoteCalculator.class.getName());
   

   Copy to Clipboard Toggle word wrap
   Session bean JNDI names are defined using a special syntax. For more information, see Section 3.2.12.3, “EJB JNDI Naming Reference” .
4. Invoke methods
   Now that you have a proxy bean object you can invoke any of the methods contained in the remote business interface.

   int a = 204;
   int b = 340;
   System.out.println("Adding " + a + " and " + b + " via the remote stateless calculator deployed on the server");
   int sum = statelessRemoteCalculator.add(a, b);
   System.out.println("Remote calculator returned sum = " + sum);

   Copy to Clipboard Toggle word wrap
   The proxy bean passes the method invocation request to the session bean on the server, where it is executed. The result is returned to the proxy bean which then returns it to the caller. The communication between the proxy bean and the remote session bean is transparent to the caller.