Chapter 2. Prepare for Migration

2.1. Preparation Overview

In JBoss EAP 7, an effort was made to provide backward compatibility for JBoss EAP 6 applications. However, if your application uses features that were deprecated or functionality that was removed from JBoss EAP 7, you might need to make changes to your application code.

In addition, a number of things have changed in this release that might impact deployment of JBoss EAP 7 applications. It is recommended that you do some research and planning before you attempt to migrate your application.

Once you are comfortable with the feature changes, the development materials, and the tools that can assist your migration efforts, you can begin to evaluate your applications and your server configuration to determine the changes that are needed to run in JBoss EAP 7.

2.2. Review the Java EE 8 Features

Java EE 8 builds on Java EE 7, which included many improvements to make it easier to develop and run feature rich applications on private and public clouds. It incorporated new features and the latest standards such as HTML5, WebSocket, JSON, Batch, and Concurrency Utilities. Updates included JPA 2.1, JAX-RS 2.0, Servlet 3.1, Expression Language 3.0, JMS 2.0. JSF 2.2, EJB 3.2, CDI 1.2, and Bean Validation 1.1. Java EE 8 enhancements include a new portable security API, support for Java Servlet 4.0 with HTTP/2 support, JPA 2.2, JAX-RS 2.1, JSF 2.3, CDI 2.0, enhanced JSON support and a new JSON binding API, support for asynchronous CDI events, and much more.

You can find more information about Java EE 8, including tutorials, on Oracle’s website: Java EE at a Glance.

2.3. Review the Java EE 7 Features

If you are migrating from JBoss EAP 6.4, Java EE 7 includes many improvements to make it easier to develop and run feature rich applications on private and public clouds. It incorporates new features and the latest standards such as HTML5, WebSocket, JSON, Batch, and Concurrency Utilities. Updates include JPA 2.1, JAX-RS 2.0, Servlet 3.1, Expression Language 3.0, JMS 2.0. JSF 2.2, EJB 3.2, CDI 1.2, and Bean Validation 1.1.

You can find more information about Java EE 7, including tutorials, on Oracle’s web site: Java™ EE Documentation.

2.4. Review What’s New in JBoss EAP 7

JBoss EAP 7 includes some notable upgrades and improvements over previous releases. This section highlights some of the new features and enhancements that have been introduced in the JBoss EAP 7 point releases.

New Features and Enhancements Introduced JBoss EAP 7.0

Java EE 7
JBoss EAP 7 is a certified implementation of Java EE 7, meeting both the Web Profile and the full platform specifications. It also includes support for the latest iterations of CDI 1.2 and Web Sockets 1.1.
Undertow
Undertow is the new lightweight, flexible, and performant web server included in JBoss EAP 7, replacing JBoss Web. Written in Java, it is designed for maximum throughput and scalability. It supports the latest web technologies, such as the new HTTP/2 standard.
Apache ActiveMQ Artemis
Apache ActiveMQ Artemis is the new JBoss EAP 7 built-in messaging provider. Based on a code donation from HornetQ, this Apache subproject provides outstanding performance based on a proven non-blocking architecture.
IronJacamar 1.2
The latest IronJacamar provides a stable and feature rich support for JCA and DataSources.
JBossWS 5
The fifth generation of JBossWS is a major leap forward, bringing new features and performance improvements to JBoss EAP 7 web services.
RESTEasy 3
JBoss EAP 7 includes the latest generation of RESTEasy. It goes beyond the standard Java EE REST APIs (JAX-RS 2.0) by providing a number of useful extensions such as JSON Web Encryption, Jackson, JSON-P, and Jettison.
OpenJDK ORB
JBoss EAP 7 replaced the JacORB IIOP implementation with a downstream branch of the OpenJDK ORB, leading to better interoperability with the JVM ORB and the Java EE RI.
Feature Rich Clustering
Clustering support was heavily refactored in JBoss EAP 7 and includes several public APIs for access by applications.
Port Reduction
By utilizing HTTP upgrade, JBoss EAP 7 has moved nearly all of its protocols to be multiplexed over just two HTTP ports: a management port (9990), and an application port (8080).
Enhanced Logging
The management API now supports the ability to list and view the available log files on a server, or even define custom formatters other than the default pattern formatter. Deployment’s logging setup is also greatly enhanced.

For a complete list of new features introduced in JBoss EAP 7.0, see New Features and Enhancements in the JBoss EAP 7.0.0 Release Notes.

New Features and Enhancements Introduced in JBoss EAP 7.1

Elytron
Elytron, based on the WildFly Elytron project, is the new security framework in JBoss EAP 7.1. It is designed to unify security across the entire application server.
Management Console
The management console has been improved to provide the ability to configure more subsystems, provide enhanced transaction subsystem and transaction resource metrics, and manage many additional configurations.
Management CLI
The management CLI provides enhanced support for response and file attachments, module configuration, and debugging support through the echo-command argument.

For the complete list of new features introduced in JBoss EAP 7.1, see New Features and Enhancements in the 7.1.0 Release Notes on the Red Hat Customer Portal.

New Features and Enhancements Introduced in JBoss EAP 7.2

Java EE 8
JBoss EAP 7.2 is a certified implementation of Java EE 8. It includes support for Java Servlet 4.0, Java Persistence 2.2, CDI 2.0, JSF 2.3, JSON-B 1.0, JSON-P 1.1, and JAX-RS 2.1, and more. See Java™ EE 8 Technologies for more information about the technologies supported in the Java Enterprise Edition (Java EE) 8 platform.
BOMs Available for Application Development
A new set of BOMs are available that provide the JBoss EAP runtime dependencies for Java EE 8. Where the Java EE 7 BOM names contained javaee7, the BOMs in this release now contain javaee8 in their names. For more information about the new BOMs, see Manage Project Dependencies in the Development Guide for JBoss EAP.

For the complete list of new features introduced in JBoss EAP 7.2, see New Features and Enhancements in the 7.2.0 Release Notes on the Red Hat Customer Portal.

New Features and Enhancements Introduced in JBoss EAP 7.3

Clustering
The mod_cluster subsystem now defines a new attribute, initial-load. The initial-load attribute helps to gradually increase the load value of a newly joined node to avoid overloading it while joining a cluster.
Eclipse MicroProfile Metrics
The Eclipse MicroProfile Metrics functionality provides monitoring data for JBoss EAP. This release enhances the SmallRye Metrics component to provide the JBoss EAP metrics in the Prometheus format.
EJB
A message-driven bean (MDB) can now belong to more than one delivery group.
Elytron
The elytron subsystem in this release now provides an implementation of the Servlet profile from the Java Authentication SPI for Containers (JASPI). Elytron now includes enhanced support for JwtValidator. Support is also included for the Java EE Security API (Security 1.0 API) as defined in JSR 375. The Jakarta equivalent for this support is defined in the Jakarta Security 1.0 specification.
Jakarta EE 8
JBoss EAP 7.3 is based on the Jakarta EE 8 platform.
Changes to BOMs for Jakarta EE 8

Some JBoss EAP BOMs in the Group ID org.jboss.bom were replaced as a result of the move to Jakarta EE 8 platform in JBoss EAP 7.3. If your applications use the BOMs that were replaced, update the project POMs to contain the Artifact IDs of the new BOMs, when migrating the applications to the JBoss EAP 7.3 release. The following BOMs were replaced:

Table 2.1. BOM Artifacts Replaced in the Group ID org.jboss.bom for Jakarta EE

Old Artifact IDNew Artifact ID

jboss-eap-javaee8

jboss-eap-jakartaee8

jboss-eap-javaee8-with-spring4

jboss-eap-jakartaee8-with-spring4

jboss-eap-javaee8-with-tools

jboss-eap-jakartaee8-with-tools

For information about configuring project dependencies, see Manage Project Dependencies in the Development Guide.

Java EE 8 and EE 7 Backwards Compatibility
JBoss EAP 7.3 maintains backwards compatibility with Java EE 8. Java EE 8 remains backwards compatible with Java EE 7 as well. All previous JBoss EAP 7 applications should deploy on JBoss EAP 7.3.
JBoss EAP Operator
JBoss EAPnow offers EAP operator, a JBoss EAP-specific controller, to automate common deployment-related tasks. The EAP operator ensures safe transaction recovery in your application cluster and uses StatefulSet for the appropriate handling of EJB remoting and transaction recovery processing.
Management Console
External JMS server resources can now be configured from the management console.
Messaging
The journal-file-open-timeout attribute now configures the timeout value for opening message journal files.

In addition to existing support for static HTTP load balancers, load balancers using mod_cluster are now supported.

OpenShift Enhancements
OpenShift now utilizes the JBoss EAP management CLI for S2I builds. OpenShift now allows customization of image footprints using Galleon layers. EJB remoting and transaction recovery processing also underwent improvements within OpenShift.
Security
The server-ssl-sni-context in this release provides server-side SNI matching. It supplies matching rules to correlate host names to SSL contexts, along with a default in case none of the provided host names are matched.

For the complete list of new features introduced in JBoss EAP 7.3, see New Features and Enhancements in the 7.3.0 Release Notes on the Red Hat Customer Portal.

2.5. Review The List of Deprecated and Unsupported Features

Before you migrate your application to JBoss EAP 7.3, be aware that some features that were available in previous releases of JBoss EAP might be deprecated or no longer supported. Support for some technologies was removed due to the high maintenance cost, low community interest, and much better alternative solutions.

The following is a short summary of some of the deprecated and unsupported features.

EJB Entity Beans
EJB entity beans are no longer supported. If your application uses EJB entity beans, you should migrate the code to use JPA, which offers a much more performant and flexible API.
JAX-RPC
Because JAX-WS offers a much more accurate and complete solution, code written for JAX-RPC should be migrated to use JAX-WS.
JSR-88
Java EE Application Deployment API specification (JSR-88), which defined a contract to enable tools from multiple providers to configure and deploy applications on any Java EE platform product, was not widely adopted. You must use another JBoss EAP supported option for application deployment, such as the management console, the management CLI, deployment scanner, or Maven.
Generic JMS Resource Adapter
The ability to configure a generic JMS resource adapter to connect to a JMS provider is no longer supported.
IO Subsystem
IO buffer pools are deprecated, but they are still set as the default in the current release. If you want, you can set Undertow byte buffer pools as the default.
Cache Stores
The remote cache store has been deprecated in favor of using the hotrod cache store.
Platforms and Features
A number of platforms and databases that were available in previous releases are deprecated in JBoss EAP 7.3.

For a complete list of deprecated and unsupported features in JBoss EAP 7.0, see Unsupported and Deprecated Functionality in the JBoss EAP 7.0.0 Release Notes on the Red Hat Customer Portal.

For the complete list of deprecated and unsupported features in JBoss EAP 7.1, see Unsupported and Deprecated Functionality in the JBoss EAP 7.1.0 Release Notes on the Red Hat Customer Portal.

For the complete list of deprecated and unsupported features in JBoss EAP 7.2, see Unsupported and Deprecated Functionality in the JBoss EAP 7.2.0 Release Notes on the Red Hat Customer Portal.

For the complete list of deprecated and unsupported features in JBoss EAP 7.3, see Unsupported and Deprecated Functionality in the JBoss EAP 7.3.0 Release Notes on the Red Hat Customer Portal.

2.6. Review the JBoss EAP Getting Started Material

Be sure to review the JBoss EAP Getting Started Guide. It contains the following important information:

  • How to download and install JBoss EAP 7
  • How to download and install Red Hat CodeReady Studio
  • How to configure Maven for your development environment, manage project dependencies, and configure your projects to use the JBoss EAP Bill of Material (BOM) artifacts
  • How to download and run the quickstart example applications that ship with the product

2.7. Migration Analysis and Planning

Each application and server configuration is unique, and you must thoroughly understand the components and architecture of the existing application and server platform before you attempt the migration. Your migration plan should include a detailed road map for testing and rollout to production that takes into account the following information.

Identify the People Responsible for the Migration
Identify the stakeholders, project managers, developers, administrators, and others who are responsible for the migration.
Review the Application Server Platform Configuration and Hardware

Examine the existing application server and platform configuration to determine how they are impacted by feature changes in JBoss EAP 7. The review should include the following items.

  • Operating systems and versions
  • Database used by the applications
  • Web servers
  • Security architecture
  • Number and type of processors
  • Amount of memory
  • Amount of physical disk storage
  • Migration of database or messaging data
  • Other components that might be impacted by the migration
Review the Current Production Environment

You should plan to recreate the production environment as closely as possible for testing and staging the migration process.

  • Take into account any clustering configurations. See Upgrading a Cluster in the JBoss EAP Patching and Upgrading Guide for more information about how to migrate clusters.
  • If you are currently running a large managed domain, consider a gradual migration approach.
  • Determine whether you need to migrate any database or messaging data.
Examine and Understand the Existing Application

Thoroughly examine the existing JBoss EAP 6 application. Be totally familiar with its architecture, functions, features and components, including:

  • The JVM version
  • Integration with other Red Hat application server middleware components
  • Integration with proprietary third-party software
  • Use of deprecated features that will require replacement
  • Application configuration including deployment descriptors, JNDI, persistence, JDBC configuration and pooling, JMS topics and queues, and logging

Identify any code or configuration incompatibilities that will require modification during the migration to JBoss EAP 7.

Create a Detailed Test Plan
  • The plan should include regression testing and acceptance criteria requirements.
  • It should also include performance testing.
  • Set up a staging environment as close to the production environment as possible to test the migration before the rollout to production.
  • Be sure to create a backup and backout plan!
Review the Resources Available for the Migration Process
  • Assess the skills of the development team and plan for training or additional consulting help.
  • Be aware that additional hardware and other resources will be required for staging and testing during the migration process until the effort is completed.
  • Determine whether any formal training is needed. If so, add it to the schedule.
Execute the Plan
Gather the necessary resources and implement the migration plan.
Important

Before making any modifications to your application, be sure to create a backup copy.

2.8. Back Up Important Data and Review Server State

Before you migrate your application, you need to be aware of the following potential issues.

  • The migration might remove temporary folders. Any deployments stored in the data/content/ directory must be backed up prior to the migration and restored after it completes. Otherwise, the server will fail to start due to the missing content.
  • Prior to the migration, handle any open transactions and delete the data/tx-object-store/ transaction directory.
  • The persistent timer data in data/timer-service-data must be checked to determine whether it will still be applicable after the upgrade. Before the upgrade, review the deployment-* files in that directory to determine which timers are still in use.

Be sure to also back up the current server configuration and applications before you begin.

2.9. Migrating an RPM Installation

Important

It is not supported to have more than one RPM-installed instance of JBoss EAP on a single Red Hat Enterprise Linux Server. As a result, we recommend that you migrate your JBoss EAP installation to a new machine when migrating to JBoss EAP 7.

When migrating a JBoss EAP RPM installation from JBoss EAP 6 to JBoss EAP 7, ensure that JBoss EAP 7 is installed on a machine that does not have an existing JBoss EAP RPM installation.

To install JBoss EAP 7 using RPMs, see the JBoss EAP Installation Guide.

The migration advice in this guide also applies to migrating RPM installations of JBoss EAP, but you might need to alter some steps (such as how to start JBoss EAP) to suit an RPM installation compared to a ZIP or installer installation.

2.10. Migrate JBoss EAP Running as a Service

If you run JBoss EAP 6 as a service, be sure to review Configuring JBoss EAP to Run as a Service in the JBoss EAP Installation Guide for updated configuration instructions for JBoss EAP 7.