Chapter 8. Migrating from Older Releases of JBoss EAP

8.1. Migrating from JBoss EAP 5 to JBoss EAP 7

This guide focuses on the changes that are required to successfully run and deploy JBoss EAP 6 applications on JBoss EAP 7. If you plan to migrate your applications directly from JBoss EAP 5 to JBoss EAP 7, there are a number of resources available to help you plan and execute your migration. We suggest you take the following approach.

  1. See Summary of Changes Made to Each Release in this guide for a quick, high-level overview of the changes made to each release of JBoss EAP.
  2. Read through the JBoss EAP 6 Migration Guide and this guide to become familiar with the contents of each one.
  3. Use the JBoss EAP 5 Component Upgrade Reference as a quick reference to migration information about specific components and features.
  4. The rule-based Red Hat Application Migration Toolkit continues to add rules to help you migrate directly from JBoss EAP 5 to JBoss EAP 7. You can use these tools to analyze your application and to generate detailed reports about the changes needed to migrate to JBoss EAP 7. For more information, see Use Red Hat Application Migration Toolkit to Analyze Applications for Migration.
  5. The Customer Portal Knowledgebase currently contains articles and solutions to help with migration from JBoss EAP 5 to JBoss EAP 6. There are plans in place to add additional content for migration from JBoss EAP 5 to JBoss EAP 7 over time.

8.2. Summary of Changes Made to Each Release

Before you plan your migration, you should be aware of the changes that were made to JBoss EAP 6 and JBoss EAP 7.

The JBoss EAP 6 Migration Guide covers changes that were made between JBoss EAP 5 and JBoss EAP 6. The following is a condensed list of the most significant changes made in JBoss EAP 6.

  • Implemented a new architecture built on the Modular Service Container
  • Was a certified implementation of the Java Enterprise Edition 6 specification
  • Introduced domain management, new deployment configuration, and a new file directory structure and scripts
  • Standardized on new portable JNDI namespaces

See Review What’s New and Different in JBoss EAP 6 in the JBoss EAP 6 Migration Guide for a detailed list of changes made in that release.

JBoss EAP 7 is built on the same modular structure as JBoss EAP 6 and includes the same domain management, deployment configuration, file directory structure, and scripts. It also still uses the same standardized JNDI namespaces. However, JBoss EAP 7 introduces the following changes.

  • Adds support for the Java Enterprise Edition 7 specification
  • Replaces the web server with Undertow
  • Replaces the JacORB IIOP implementation with a downstream branch of the OpenJDK ORB
  • Includes Apache ActiveMQ Artemis as the new messaging provider
  • Removes the cmp, jaxr, and threads subsystems
  • Removes support for EJB entity beans

For a more complete list of changes, see Review What’s New in JBoss EAP 7

8.3. Review the Content in the Migration Guides

Review the entire contents of the Migration Guide for each release to become aware of the features that were added or deprecated, and to understand the server configuration and the application changes required to run existing applications for that release.

Because the underlying architecture was not changed between JBoss EAP 6 and JBoss EAP 7, many of the changes documented in the JBoss EAP 6 Migration Guide still apply. For example, changes documented under Changes Required by Most Applications are related to the underlying architectural changes made in JBoss EAP 6, which still apply to this release. The change to the new modular class loading system is significant and impacts the packaging and dependencies of almost every JBoss EAP 5 application. Many of the changes listed under Changes Dependent on Your Application Architecture and Components are also still valid. However, because JBoss EAP 7 replaced the web server, ORB, and messaging provider, removed the cmp, threads, and jaxr subsystems, and removed support for EJB entity beans, you must consult this guide for any changes related to those component areas. Pay particular attention to the Server Configuration Changes and Application Migration Changes detailed in this guide before you begin.

8.4. JBoss EAP 5 Component Upgrade Reference

Use the following table to find information about how to migrate a particular feature or component from JBoss EAP 5 to JBoss EAP 7.2.

JBoss EAP 5
Feature or Component
Summary of Changes and
Where to Find Migration Information

Application Packaging and Class Loading

In JBoss EAP 6, the previous hierarchical class loading structure was replaced with a modular architecture based on JBoss Modules. Application packaging also changed due to the new modular class loading structure. This architecture is still used in JBoss EAP 7. For information about the new modular architecture, see the following chapter in the JBoss EAP 7.2 Development Guide.

For information about how to update and repackage applications for the new modular architecture, see the following section in the JBoss EAP 6 Migration Guide.

Application Configuration Files

Due to the changes in JBoss EAP 6 to use modular class loading, you might need to create or modify one or more application configuration files to add dependencies or to prevent automatic dependencies from loading. This has not changed in JBoss EAP 7. For details, see the following section in the JBoss EAP 6 Migration Guide.

Caching and Infinispan

JBoss Cache was replaced by Infinispan for internal use by the server only in JBoss EAP 6. See the following sections in the JBoss EAP 6 Migration Guide for information about how to replace JBoss Cache in application code.

Infinispan caching strategy and configuration changes for JBoss EAP 7 are documented in the following section of this guide.

Data Sources and Resource Adapters

JBoss EAP 6 consolidated configuration of data sources and resource adapters into mainly one file and this is still true in JBoss EAP 7. See the following section in the JBoss EAP 6 Migration Guide for more information.

Directory Structure, Scripts, and Deployment Configuration

In JBoss EAP 6, the directory structure, scripts, and deployment configuration changed. These changes are still valid in JBoss EAP 7. See the following section of the JBoss EAP 6 Migration Guide for more information.

EJB

The Java EE 7 specification made EJB 2.x and earlier features optional, so it is strongly recommended that you rewrite your application code to use the EJB 3.x specification and JPA. For information about deprecated features and changes required to run EJB 2.x, see the following section in the JBoss EAP 6 Migration Guide.

In JBoss EAP 6, stateful EJB cache and stateless session bean pool size is configured in the ejb3 subsystem of the server configuration file. The jboss-ejb3.xml deployment descriptor replaces the jboss.xml deployment descriptor file. For more information about these changes, see the following section in the JBoss EAP 6 Migration Guide.

The default remote connector and port has changed in JBoss EAP 7. For more information about this and server configuration changes, see the following sections in this guide.

EJB entity beans are not supported in JBoss EAP 7. For information about how to migrate entity beans to JPA, see the following section in this guide.

Hibernate and JPA

In JBoss EAP 6, Hibernate was updated from version 3 to version 4. This version of JBoss EAP also implemented the JPA 2.0 specification and changes were made to JPA persistence properties. For information about how to modify your application for these changes, see the following section in the JBoss EAP 6 Migration Guide.

JBoss EAP 7.2 implements JPA 2.2 and includes Hibernate 5.3. It also includes Hibernate Search version 5.10. Other changes include removal of support for EJB entity beans and additional updates to JPA persistence properties. For information about how these changes impact your applications, see the following sections in this guide.

Note

Use of a different version of Hibernate than the one shipped with JBoss EAP is unsupported. The version shipped with JBoss EAP is the only version of Hibernate that is tested, and is the only version for which patches will be provided for defects.

JAX-RS and RESTEasy

JBoss EAP 6 bundled RESTEasy 2, which automatically configured RESTEasy and required changes in application configuration. See the following section in the JBoss EAP 6 Migration Guide for information.

JBoss EAP 7 includes RESTEasy 3 and many classes have been deprecated. The version of Jackson changed from version 1.9.9 to version 2.6.3 or greater. For details about these changes, see the following section in this guide.

JBoss AOP

JBoss AOP (Aspect Oriented Programming) was removed in JBoss EAP 6. For information about how to refactor applications that use JBoss AOP, see the following section in the JBoss EAP 6 Migration Guide.

JGroups and Clustering

The way you enable clustering and specify bind addresses changed in JBoss EAP 6. See the following section in the JBoss EAP 6 Migration Guide for more information.

In JBoss EAP 7, JGroups now defaults to using a private network interface instead of a public network interface and also introduces <channel> elements to the jgroups subsystem. JBoss EAP 7 also includes the Undertow mod_cluster implementation, introduces a new API for building singleton services, and other new clustering features. These changes are documented in the following sections of this guide.

JNDI

JBoss EAP 6 implemented a new standardized global JNDI namespace and a series of related namespaces that map to the various scopes of a Java EE application. See the following section of the JBoss EAP 6 Migration Guide for information about application changes needed to use the new JNDI namespace rules.

JSF

JBoss EAP 6.4 included both JSF 1.2 and JSF 2.1 and allowed you to configure your application to use the older version. This is no longer possible in JBoss EAP 7.2, which now includes JSF 2.3. See the following section in this guide for more information.

Logging

JBoss EAP 6 introduced a new JBoss Logging framework that is still used in JBoss EAP 7. Applications that use third-party logging frameworks might be impacted by the modular class loading changes. Review the following section in the JBoss EAP 6 Migration Guide for information about these changes.

In JBoss EAP 7, annotations in the org.jboss.logging package are now deprecated, which impacts source code and Maven GAVs (groupId:artifactId:version). The prefixes for all log messages were also changed. For more information about these changes, see the following sections in this guide.

Messaging and JMS

In JBoss EAP 6, HornetQ replaced JBoss Messaging as the default JMS implementation. Then in JBoss EAP 7, ActiveMQ Artemis replaced HornetQ as the built-in messaging provider.

The best approach to migrating your messaging configuration is to start with the JBoss EAP 7 default server configuration and use the following guide to apply your current messaging configuration changes.

If you want to understand the changes required to move from JBoss Messaging to HornetQ, review the following section of the JBoss EAP 6 Migration Guide.

Then review the following information about how to migrate the HornetQ configuration and related messaging data in this guide.

ORB

In JBoss EAP 6, JacORB configuration was moved from the EAP_HOME/server/production/conf/jacorb.properties file to the server configuration file. JBoss EAP 7 then replaced the JacORB IIOP implementation with a downstream branch of the OpenJDK ORB.

The best approach to migrating your ORB configuration is to start with the JBoss EAP 7 default server configuration and use the following section in the JBoss EAP 7.2 Configuration Guide to apply the your current ORB configuration changes.

Remote Invocation

A new EJB client API was introduced in JBoss EAP 6 for remote invocations; however, if you preferred not to rewrite your application code to use the new API, you could modify your existing code to use the ejb:BEAN_REFERENCE for remote access to EJBs. See the following section in the JBoss EAP 6 Migration Guide for more information.

In JBoss EAP 7, the default connector and default remote connection port changed. For more information, see the following sections in this guide.

Seam 2.x

While official support for Seam 2.2 applications was dropped in JBoss EAP 6, it was still possible to configure dependencies for JSF 1.2 and Hibernate 3 to allow Seam 2.2 applications to run on that release. JBoss EAP 7.2, which now includes JSF 2.3 and Hibernate 5.3.1, does not support Seam 2.2 or Seam 2.3 due to end of life of Red Hat JBoss Web Framework Kit. It is recommended that you rewrite your Seam components using Weld CDI beans.

Security

Security updates in JBoss EAP 6 included changes to security domain names and changes to how to configure security for basic authentication. The LDAP security realm configuration was moved to the server configuration file. See the following sections in the JBoss EAP 6 Migration Guide for more information.

Updates that impact security in JBoss EAP 7 include server configuration changes and application changes. Information can be found in the following sections of this guide.

Spring Applications

Spring 4.2.x is the earliest stable Spring version supported by JBoss EAP 7. For information about Apache CXF Spring web services and Spring RESTEasy integration changes, see the following sections in this guide.

Transactions

JBoss EAP 6 consolidated transaction configuration and moved it to the server configuration file. Other updates included changes to JTA node identifier settings and how to enable JTS. For details, see the following section in the JBoss EAP 6 Migration Guide.

Some Transaction Manager configuration attributes that were available in the transactions subsystem in JBoss EAP 6 have changed in JBoss EAP 7. For more information, see the following section in this guide.

Valves

Undertow replaced JBoss Web in JBoss EAP 7 and valves are no longer supported. See the following sections in this guide.

Web Services

JBoss EAP 6 included JBossWS 4. For information about the changes required by that version update, see the following section in the JBoss EAP 6 Migration Guide.

JBoss EAP 7 introduced JBossWS 5. See the following section in this guide for required updates.