JBoss EAP XP upgrade and migration guide

Red Hat JBoss Enterprise Application Platform 7.4

Guidance for upgrading and migrating from JBoss EAP XP 2.0.x to JBoss EAP XP 3.0.0

Red Hat Customer Content Services

Abstract

This document provides information about upgrading JBoss EAP XP 2.0.x to JBoss EAP XP 3.0.0 and any necessary application migration.

Making open source more inclusive

Red Hat is committed to replacing problematic language in our code, documentation, and web properties. We are beginning with these four terms: master, slave, blacklist, and whitelist. Because of the enormity of this endeavor, these changes will be implemented gradually over several upcoming releases. For more details, see our CTO Chris Wright’s message.

Providing feedback on Red Hat documentation

We appreciate your feedback on our documentation. To provide feedback, you can highlight the text in a document and add comments. Follow the steps in the procedure to learn about submitting feedback on Red Hat documentation.

Prerequisites

  • Log in to the Red Hat Customer Portal.
  • In the Red Hat Customer Portal, view the document in Multi-page HTML format.

Procedure

  1. Click Feedback to see existing reader comments.

    Note

    The feedback feature is enabled only in the Multi-page HTML format.

  2. Highlight the section of the document where you want to provide feedback.
  3. In the prompt menu that displays near the text you selected, click Add Feedback.

    A text box opens in the feedback section on the right side of the page.

  4. Enter your feedback in the text box and click Submit.

    You have created a documentation issue.

  5. To view the issue, click the issue tracker link in the feedback view.

Chapter 1. JBoss EAP XP upgrades

1.1. Upgrades and migrations

Use the steps outlined in the JBoss EAP XP upgrade and migration guide to prepare, upgrade, and migrate your JBoss EAP XP 2.0.x product to the JBoss EAP XP 3.0.0 product. JBoss EAP XP 3.0.0 is compatible with only JBoss EAP 7.4. If you operate servers on JBoss EAP 7.3 and you want to apply the JBoss EAP XP 3.0.0 patch on it, you must first upgrade your JBoss EAP 7.3 instance to JBoss EAP 7.4.

The guide references tools that you can use for the upgrading and migration process. These tools are as follows:

  • Migration Toolkit for Applications (MTA)
  • JBoss Server Migration Tool

After you successfully upgrade and migrate JBoss EAP XP 2.0.x release to JBoss EAP XP 3.0.0, you can begin to implement any applications migrations for your JBoss EAP 7.4 instance.

Additional resources

1.2. Preparation for upgrade and migration

After you upgrade the JBoss EAP Expansion Pack, you might have to update application code.

For JBoss EAP XP 3.0.0, some backward compatibility might exist for JBoss EAP XP 2.0.x applications. However, if your application uses features that were deprecated or functionality that was removed from JBoss EAP XP 2.0.x, you might need to make changes to your application code.

Please review the following new items before you begin the migration process:

  • JBoss EAP XP features added in the JBoss EAP XP 3.0.0 release.
  • MicroProfile capabilities added in the JBoss EAP XP 3.0.0.
  • Enhancements to existing MicroProfile capabilities.
  • Capabilities and features that are deprecated in the JBoss EAP XP 3.0.0.
  • Capabilities and features that have been removed from JBoss EAP XP 3.0.0.
  • Tools that you can use to migrate from one EAP XP release to another release.

After you have reviewed the listed items, analyze your environment and plan for the upgrade process and migration process. Ensure you back up any applications that you plan to migrate to JBoss EAP XP 3.0.0.

You can now upgrade your current JBoss EAP XP 2.0.x release to JBoss EAP XP 3.0.0. You can implement any applications migrations after the upgrade process

Additional resources

1.3. New JBoss EAP XP capabilities

The JBoss EAP XP 3.0.0 includes new features that enhance the use of Red Hat implementation of the MicroProfile specification for JBoss EAP applications.

Note

The MicroProfile Reactive Messaging subsystem supports Red Hat AMQ Streams. This feature implements the MicroProfile Reactive Messaging 1.0 API and Red Hat provides the feature as a technology preview for JBoss EAP XP 3.0.0.

Red Hat tested Red Hat AMQ Streams 2021.Q2 on JBoss EAP. However, check the Red Hat JBoss Enterprise Application Platform supported configurations page for information about the latest Red Hat AMQ Streams version that has been tested on JBoss EAP XP 3.0.0.

JBoss EAP XP 3.0.0 includes the following new features in its release:

  • Run CLI scripts after you have started your application.
  • Use the --cli-script=<path to CLI script> argument to update the server configuration of a bootable JAR file at runtime.
  • Use the MicroProfile Reactive Messaging 1.0 API to send and receive messages between microservices.
  • Use the MicroProfile Reactive Messaging 1.0 API to write and configure a user application, so the application can send, receive, and process event streams efficiently and asynchronously.
  • Enable MicroProfile Reactive Messaging functionality in your server configuration, as MicroProfile Reactive Messaging only comes pre-installed on your server.
  • View the MicroProfile Reactive Messaging with MicroProfile Reactive Messaging with Kafka quickstart to learn how you can complete the following tasks on your server:

    • Enable the MicroProfile Reactive Messaging subsystem.
    • Run and test applications by using MicroProfile Reactive Messaging to send data and receive data from Red Hat AMQ Streams.

Additional resources

  • For information about Red Hat AMQ Streams, see Overview of AMQ Streams in the Using AMQ Streams on OpenShift guide.
  • For information about Technology Preview features. see Technology Preview Features Support Scope on the Red Hat Customer Portal.
  • For information on the Red Hat AMQ Streams versions, see Red Hat AMQ on the Product Documentation page.
  • For more information about the MicroProfile Reactive Messaging with Kafka quickstart, see jboss-eap-quickstarts and select the listed MicroProfile Reactive Messaging with Kafka quickstart.

1.4. Enhancements to MicroProfile capabilities

The JBoss EAP XP 3.0.0 release includes support for the following MicroProfile 4.0 components:

  • MicroProfile Config
  • MicroProfile Fault Tolerance
  • MicroProfile Health
  • MicroProfile JWT
  • MicroProfile Metrics
  • MicroProfile OpenAPI
  • MicroProfile OpenTracing
  • MicroProfile REST Client

Additional resources

  • For more information about MicroProfile 4.0 and its specifications, see MicroProfile 4.0 on GitHub.
  • For more information about MicroProfile 4.0 specification components, see About JBoss EAP XP in the Using JBoss EAP XP 3.0.0 guide.

1.5. Deprecated and unsupported MicroProfile capabilities

Before you migrate your application to JBoss EAP XP 3.0.0 be aware that some features that were available in JBoss EAP XP 2.0.x might be deprecated or no longer supported.

Red Hat removed support for some technologies due to the high maintenance cost, low community interest, and much better alternative solutions.

Ensure that you review the Red Hat JBoss EAP XP 3.0.0 Release Notes guide and the 7.4.0 Release Notes guide for any unsupported and deprecated features.

Additional resources

  • For more information about any unsupported and deprecated features for JBoss EAP XP 3.0.0, see the Using JBoss EAP XP 3.0.0 guide.
  • For more information about any unsupported and deprecated features for JBoss EAP 7.4, see the 7.4.0 Release Notes guide.

Chapter 2. Tools for migrating from JBoss EAP XP 2.0.x servers to JBoss EAP XP 3.0.0 servers

You can choose one of the following tools to upgrade and migrate your JBoss EAP XP 2.0.x product to the JBoss EAP XP 3.0.0 product:

  • Migration Toolkit for Applications (MTA)
  • JBoss Server Migration Tool

2.1. Use the JBoss Server Migration Tool to migrate your server configurations

Use the JBoss Server Migration Tool when updating your server configuration to include the new features and settings of JBoss EAP XP 3.0.0. You can keep your existing JBoss EAP XP 2.0.x server configuration, provided that JBoss EAP XP 3.0.0 supports the configurations.

The JBoss Server Migration Tool reads your existing JBoss EAP XP 2.0.x server configuration files and adds any new required subsystems to these files. The tool also updates existing subsystem configurations with new features, and removes any obsolete subsystem configurations.

You can use the JBoss Server Migration Tool to migrate standalone servers and servers in a managed domain for your JBoss EAP XP 3.0.0 configuration.

JBoss EAP XP 3.0.0 includes the JBoss Server Migration Tool, so you do not need to download a file and install the tool. Issue the jboss-server-migration script, which is located in the EAP_HOME/bin directory, to start the tool.

Additional resources

2.2. Use the Migration Toolkit for Applications to analyze applications for migration

The Migration Toolkit for Applications (MTA) includes extensible and customizable rule-based tools that simplify migration of Jakarta applications. You can use the toolkit to analyze an application’s APIs, technologies, and architectures. The toolkit provides reports for the application you plan to migrate from JBoss EAP XP 2.0.x to JBoss EAP XP 3.0.0.

You can use MTA to analyze standard JBoss EAP applications and bootable JAR applications.

The MTA reports output the following information:

  • Detailed explanations of all required migration changes.
  • Whether the change is mandatory or optional.
  • Whether the change is complex or simple.
  • Links to code that requires a migration update.
  • Hints and links to information for helping you complete the required migration changes.
  • An estimate of the level of effort for each migration issue found and the total estimated effort to migrate the application .

You can also use MTA to analyze the code and architecture of your JBoss EAP XP 2.0.x applications before you migrate them to JBoss EAP XP 3.0.0. The MTA rule set for migrating applications from JBoss EAP XP 2.0.x to JBoss EAP XP 3.0.0 reports on XML descriptors, specific application code, and parameters, that you need to replace with alternative configurations when migrating to JBoss EAP XP 3.0.0.

Additional resources

2.3. Upgrades from JBoss EAP 7.3 and earlier

JBoss EAP XP 3.0.0 is only supported on JBoss EAP 7.4.

If you operate servers on JBoss EAP 7.3 or earlier and want to use JBoss EAP XP, upgrade the servers to JBoss EAP 7.4. Complete any necessary migration before attempting to install JBoss EAP XP.

Additional resources

2.4. MicroProfile application migration

MicroProfile 4.0 is based on the Jakarta EE 8 platform. Although Jakarta EE 8 is API backward compatible with Java EE 8, Jakarta EE 8 dependencies replace Java EE 8 dependencies for all MicroProfile specifications.

MicroProfile 4.0 includes updates to all the major MicroProfile specifications.

The following specifications include API incompatible changes for MicroProfile 4.0:

  • MicroProfile Config
  • MicroProfile Fault Tolerance
  • MicroProfile Health
  • MicroProfile Metrics
  • MicroProfile OpenAPI

You must update your applications that use these specifications to the latest Jakarta EE 8 specifications.

You can update your applications to MicroProfile 4.0 by choosing one of the following methods:

  • Adding the MicroProfile 4.0 dependency to your project’s pom.xml file.
  • Using the JBoss EAP XP BOMs to import supported artifacts to the JBoss EAP XP dependency management of your project’s pom.xml file.

Additional resources

  • For more information about MicroProfile 4.0 and options for updating your applications to use MicroProfile 4.0, see MicroProfile 4.0 on GitHub.

2.5. Bootable JAR application migration

Before you migrate a JBoss EAP XP 2.0.0 bootable JAR application to JBoss EAP XP 3.0.0, you might need to update your JBoss EAP XP bootable JAR Maven plug-in configuration.

For JBoss EAP XP 3.0.0, the extraServerContentDirs configuration element replaces the extraServerContent configuration element. This element naming replacement aligns with the pre-existing extra-server-content-dirs element.

If you used the extraServerContent element in your JBoss EAP Maven plug-in configuration, you must replace this element with the extraServerContentDirs element. If you used the extra-server-content-dirs element then you do not need to make any configuration changes.

Additional resources

Chapter 3. Thorntail application Maven project migration

The Red Hat build of Thorntail is approaching its end of life. If you have a Thorntail application, you can migrate your application’s Maven project into JBoss EAP XP. Thorntail applications are packaged in two ways:

  • Packaged with the Thorntail runtime as an as Uberjar, an executable JAR,
  • Packaged in a standard WAR archive to be deployed and run in a Thorntail hollow JAR, a runtime-only executable JAR.

When migrated to JBoss EAP XP, a Thorntail application can be packaged as a bootable JAR and trim down the JBoss EAP XP runtime to include the MicroProfile platform and other technologies that the application depends on.

When migrating an application to JBoss EAP XP, you must remove any Thorntail fraction dependency, and add the artifacts of any required MicroProfile and Jakarta EE 8 specifications to the Maven Project dependencies.

Note

You can use the JBoss CLI tool or JBoss EAP web console at runtime to make changes to the server configuration. However, unlike the configuration changes made during packaging, any changes made to the configuration at runtime are not persisted and are lost when you restart the bootable JAR.

3.1. Migrating a Thorntail application Maven project into JBoss EAP XP

If you have a Thorntail application that relies on technologies such as Jakarta Enterprise Beans, Jakarta Server Faces, Jakarta Connector API, SOAP web services, or CORBA, you can migrate your application’s Maven project into JBoss EAP XP.

Galleon layers are used to configure the capabilities of the JBoss EAP XP runtime packaged in a bootable JAR. When you migrate a Thorntail application that uses Jakarta EE 8 specifications, you must add the relevant Galleon layers to the bootable JAR Maven plug-in configuration.

When using Galleon layers, JBoss EAP XP generates a server configuration and packages it inside the bootable JAR. If no Galleon layers are used, a configuration identical to the default standalone-microprofile.xml is packaged in the bootable JAR.

If you are building a bootable JAR for cloud by using the <cloud> configuration element, an OpenShift configuration similar to the default standalone-microprofile-ha.xml is applied to your bootable JAR.

The bootable JAR Maven plug-in executes JBoss CLI scripts while packaging the bootable JAR .

Procedure

  1. Remove any Thorntail BOM import.

    Example of removing the io.thorntail Thorntail BOM import from the pom.xml file.

    <dependencyManagement>
      <dependencies>
        <dependency>
          <groupId>io.thorntail</groupId>
          <artifactId>bom</artifactId>
          <version>${version.thorntail}</version>
          <type>pom</type>
          <scope>import</scope>
        </dependency>
      </dependencies>
    </dependencyManagement>

  2. Use the JBoss EAP XP BOMs to import supported artifacts to JBoss EAP XP dependency management.

    Example of using the jboss-eap-jakartaee8-with-tools BOM to import supported artifacts to a project.

    <dependencyManagement>
            <dependencies>
                <!-- importing the jakartaee8-with-tools BOM adds specs and other useful artifacts as managed dependencies -->
                <dependency>
                    <groupId>org.jboss.bom</groupId>
                    <artifactId>jboss-eap-jakartaee8-with-tools</artifactId>
                    <version>${version.server.bom}</version>
                    <type>pom</type>
                    <scope>import</scope>
                </dependency>
                <!-- importing the microprofile BOM adds MicroProfile specs -->
                <dependency>
                    <groupId>org.jboss.bom</groupId>
                    <artifactId>jboss-eap-xp-microprofile</artifactId>
                    <version>${version.microprofile.bom}</version>
                    <type>pom</type>
                    <scope>import</scope>
                </dependency>
            </dependencies>
        </dependencyManagement>

    Note

    Import the jakartaee8-with-tools BOM only if your application depends on Jakarta EE 8 specifications that are not included in the MicroProfile platform.

  3. Replace the Thorntail Maven plug-in with the JBoss EAP XP bootable JAR Maven plug-in.

    Example showing the replacement of the Thorntail Maven plug-in with the JBoss EAP XP bootable JAR Maven plug-in.

    <plugin>
       <groupId>org.wildfly.plugins</groupId>
       <artifactId>wildfly-jar-maven-plugin</artifactId>
       <version>${bootable.jar.maven.plugin.version}</version>
       <configuration>
          <feature-pack-location>${org.jboss.eap:wildfly-galleon-pack:${jboss.xp.galleon.feature.pack.version}</feature-pack-location>
          <layers>
             <layer>microprofile-platform</layer>
          </layers>
       </configuration>
       <executions>
          <execution>
             <goals>
                <goal>package</goal>
             </goals>
          </execution>
       </executions>
    </plugin>

    Note

    The previous example specifies the following property for the Maven plug-in version:

    ${bootable.jar.maven.plugin.version}

    You must set your Maven plug-in version in place of this property in your project. For example:

    <properties>
        <bootable.jar.maven.plugin.version>4.0.3.Final-redhat-00001</bootable.jar.maven.plugin.version>
    </properties>
    • The bootable JAR plug-in builds an UberJAR by default, which means it packages the JBoss EAP XP runtime with the application deployed. To build a hollow JAR, add <hollow-jar>true</hollow-jar> to the configuration of the plug-in.
  4. Make the following changes to the Thorntail fractions in the Maven project.

    1. Remove the Thorntail fraction dependencies.

      Example showing the removal of the io.thorntail Thorntail fractions from a Maven project.

      <dependencies>
        <dependency>
          <groupId>io.thorntail</groupId>
          <artifactId>jaxrs</artifactId>
        </dependency>
      </dependencies>

    2. Configure Maven dependencies.

      Example of using an XML snippet to add dependencies to the artifacts of the Jakarta EE 8 JAX-RS and MicroProfile Config APIs.

      <dependencies>
          <!-- Import the MicroProfile Config API, we use provided scope as the API is included in the server -->
          <dependency>
            <groupId>org.eclipse.microprofile.config</groupId>
            <artifactId>microprofile-config-api</artifactId>
            <scope>provided</scope>
          </dependency>
          <!-- Import the Jakarta REST API, we use provided scope as the API is included in the server -->
          <dependency>
            <groupId>org.jboss.spec.javax.ws.rs</groupId>
            <artifactId>jboss-jaxrs-api_2.1_spec</artifactId>
            <scope>provided</scope>
          </dependency>
        </dependencies>

    3. Remove Thorntail YAML files, system properties and environment properties.
    4. Configure Galleon layers.

      Example of configuring Galleon layers in the bootable JAR Maven plug-in for an application that requires JAX-RS.

      <plugin>
        <groupId>org.wildfly.plugins</groupId>               <artifactId>wildfly-jar-maven-plugin</artifactId>                  <configuration>
         ...
            <layers>
              <layer>jaxrs-server</layer>
              <layer>microprofile-platform</layer>
            </layers>
        </configuration>
         ...
      </plugin>

Additional resources

Legal Notice

Copyright © 2022 Red Hat, Inc.
The text of and illustrations in this document are licensed by Red Hat under a Creative Commons Attribution–Share Alike 3.0 Unported license ("CC-BY-SA"). An explanation of CC-BY-SA is available at http://creativecommons.org/licenses/by-sa/3.0/. In accordance with CC-BY-SA, if you distribute this document or an adaptation of it, you must provide the URL for the original version.
Red Hat, as the licensor of this document, waives the right to enforce, and agrees not to assert, Section 4d of CC-BY-SA to the fullest extent permitted by applicable law.
Red Hat, Red Hat Enterprise Linux, the Shadowman logo, the Red Hat logo, JBoss, OpenShift, Fedora, the Infinity logo, and RHCE are trademarks of Red Hat, Inc., registered in the United States and other countries.
Linux® is the registered trademark of Linus Torvalds in the United States and other countries.
Java® is a registered trademark of Oracle and/or its affiliates.
XFS® is a trademark of Silicon Graphics International Corp. or its subsidiaries in the United States and/or other countries.
MySQL® is a registered trademark of MySQL AB in the United States, the European Union and other countries.
Node.js® is an official trademark of Joyent. Red Hat is not formally related to or endorsed by the official Joyent Node.js open source or commercial project.
The OpenStack® Word Mark and OpenStack logo are either registered trademarks/service marks or trademarks/service marks of the OpenStack Foundation, in the United States and other countries and are used with the OpenStack Foundation's permission. We are not affiliated with, endorsed or sponsored by the OpenStack Foundation, or the OpenStack community.
All other trademarks are the property of their respective owners.