Red Hat JBoss EAP XP 2.0.0 Migration Guide

Red Hat JBoss Enterprise Application Platform 7.3

Guidance for upgrading and migrating from JBoss EAP XP 1.0 to JBoss EAP XP 2.0.0

Red Hat Customer Content Services

Abstract

This document provides general information about using Eclipse MicroProfile in JBoss EAP XP 2.0.0.

Chapter 1. JBoss EAP XP migration guide

1.1. Upgrades and migrations

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

NOTE
No application migration requirement has been identified for this release.

Before starting the upgrade and migration process, prepare for the process:

  • Review new JBoss EAP XP capabilities and features added in the new JBoss EAP XP release.
  • Review enhancements to existing MicroProfile capabilities.

After you complete your preparations, you can upgrade your JBoss EAP XP. After you have upgraded succesfully, you can implement any necessary application migrations.

1.1.1. Upgrades from JBoss EAP 7.2 and earlier

JBoss EAP XP is only supported on JBoss EAP 7.3.

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

Additional resources

1.2. Preparation for upgrade and migration

When you plan and prepare you increase the likelihood of a successful upgrade and migration.

1.2.1. New JBoss EAP XP capabilities

  • Starting in JBoss EAP XP 2.0.0, you can create a bootable JAR. A bootable JAR contains the server, a packaged application, and the runtime required to launch the server.

1.2.2. Enhancements to MicroProfile capabilities

The JBoss EAP XP 2.0.0 release includes additional server health probes.

  • server status: Indicates whether the server is running.
  • boot-errors: Indicates whether boot errors were detected.
  • deployment status: Indicates the status of deployments.

1.3. Upgrading JBoss EAP XP 1.0.x to 2.0.0

Upgrade JBoss EAP XP 1.0.x to 2.0.0 using the upgrade command that is provided in JBoss EAP XP manager.

Use JBoss EAP XP 2.0.0 to manage JBoss EAP XP 2.0.0 patch streams.

Note

JBoss EAP XP 2.0.0 is certified with JBoss EAP 7.3.4.

Prerequisites

  • The base JBoss EAP server is updated to 7.3.4 or later version.

Procedure

  1. Verify that your server is in the correct state for upgrade:

    $ java -jar jboss-eap-xp-manager.jar status --jboss-home=/PATH/TO/EAP-XP
    ...
    You are currently on JBoss EAP XP 1.
    You are using an old version of JBoss EAP XP. The current version is 2, please upgrade.
    Enabled patch streams and their cumulative patch ids:
    - Patch stream: 'JBoss EAP'; Cumulative patch id: 'jboss-eap-7.3.1.CP'
    - Patch stream: 'jboss-eap-xp-1.0'; Cumulative patch id: 'jboss-eap-xp-1.0.0.CP'
    Available commands in this state are: [remove, upgrade]

    If you see output similar to the above, you can upgrade your JBoss EAP XP server.

    If the output indicates that the server is in an inconsistent state, follow the Troubleshooting steps.

  2. Use the upgrade command to upgrade JBoss EAP XP 1.0.x to 2.0.0.

    $ java -jar jboss-eap-xp-manager.jar upgrade --jboss-home=/PATH/TO/EAP
    Note

    You can apply the JBoss EAP XP 2.0.0 patch at the same time. Include the path to the JBoss EAP XP 2.0.0 patch using the --xp-patch argument.

    Example:

    $ java -jar jboss-eap-xp-manager.jar upgrade --jboss-home=/PATH/TO/EAP --xp-patch /PATH/TO/PATCH/jboss-eap-xp-2.0.0-patch.zip
  3. Accept the support policy prompt by entering yes.

    The server is now ready to manage the JBoss EAP XP 2.0 patch stream.

  4. Optional: If you did not use the the --xp-patch argument with the upgrade command, use the JBoss EAP XP manager 2.0.0 patch-apply command to apply the JBoss EAP XP 2.0.0 patch patch:

    $ java -jar jboss-eap-xp-manager.jar patch-apply --jboss-home=/PATH/TO/EAP --patch=/PATH/TO/PATCH/jboss-eap-xp-2.0.0-patch.zip

    Use the JBoss EAP XP manager 2.0.0 patch-apply command to apply the latest JBoss EAP XP 2.0.x patches when they are available.

Your server is ready to manage the JBoss EAP XP 2.0 patch stream and is patched with the JBoss EAP XP 2.0.0 patch.

Troubleshooting steps

  1. Remove the JBoss EAP XP patch stream using the remove command of JBoss EAP XP manager 2.0.0:

    $ java -jar jboss-eap-xp-manager.jar remove --jboss-home=/PATH/TO/EAP
  2. Re-install JBoss EAP XP 2.0.0.

Chapter 2. 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 Eclipse 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.

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

If you have a Thorntail application that relies on technologies such as EJB, 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 such as the one in the following example:

    <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:

    <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 Eclipse MicroProfile platform.

  3. Replace 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:2.0.0.GA-redhat-00002</feature-pack-location>
          <layers>
             <layer>microprofile-platform</layer>
          </layers>
       </configuration>
       <executions>
          <execution>
             <goals>
                <goal>package</goal>
             </goals>
          </execution>
       </executions>
    </plugin>
    Note
    • The example shown in the procedure specify the following property:

    ${bootable.jar.maven.plugin.version} for the Maven plug-in version.

    You must set this property in your project. For example:

    <properties>
        <bootable.jar.maven.plugin.version>2.0.2.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. For example:

      <dependencies>
        <dependency>
          <groupId>io.thorntail</groupId>
          <artifactId>jaxrs</artifactId>
        </dependency>
      </dependencies>
    2. Configure Maven dependencies. The following example XML snippet adds dependencies to the artifacts of the Jakarta EE 8 Jakarta RESTful Web Services and Eclipse 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. For example, if your application requires Jakarta RESTful Web Services, then configure the following Galleon layers in the bootable JAR Maven plug-in:

      <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 © 2021 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.