Red Hat Summit Red Hat SummitSupportConsoleDevelopersStart a trialContact

JBoss EAP XP 5.0 upgrade and migration guide

Red Hat JBoss Enterprise Application Platform 8.0

Guidance for upgrading and migrating from JBoss EAP XP 4.0.x to JBoss EAP XP 5.0

Red Hat Customer Content Services

Abstract

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

Making open source more inclusive
Copy link

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 JBoss EAP documentation
Copy link

To report an error or to improve our documentation, log in to your Red Hat Jira account and submit an issue. If you do not have a Red Hat Jira account, then you will be prompted to create an account.

Procedure

  1. Click the following link to create a ticket.
  2. Enter a brief description of the issue in the Summary.
  3. Provide a detailed description of the issue or enhancement in the Description. Include a URL to where the issue occurs in the documentation.
  4. Clicking Submit creates and routes the issue to the appropriate documentation team.

Chapter 1. JBoss EAP XP upgrades
Copy link

1.1. Upgrades and migrations
Copy link

Use the steps outlined in the JBoss EAP XP 5.0 upgrade and migration guide to prepare, upgrade, and migrate your JBoss EAP XP 3.0 or 4.0 product to the JBoss EAP XP 5.0 product. JBoss EAP XP 5.0 is compatible with only JBoss EAP 8.0. If you operate servers on JBoss EAP 7.4 and you want to install the JBoss EAP XP 5.0 on it, you must first upgrade your JBoss EAP 7.4 instance to JBoss EAP 8.0.

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 3.0 or 4.0 release to JBoss EAP XP 5.0, you can begin to implement any application migrations for your JBoss EAP 8.0 instance.

1.2. Preparation for upgrade and migration
Copy link

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

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

Review the following new items before you begin the migration process:

  • JBoss EAP XP features added in the JBoss EAP XP 5.0 release.
  • MicroProfile capabilities added in the JBoss EAP XP 5.0 release.
  • Enhancements to existing MicroProfile capabilities.
  • Capabilities and features that are deprecated in the JBoss EAP XP 5.0.
  • Capabilities and features that have been removed from JBoss EAP XP 5.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 5.0.

You can now upgrade your current JBoss EAP XP 3.0 or 4.0 release to JBoss EAP XP 5.0. You can implement any application migrations after the upgrade process.

1.3. Enhancements to MicroProfile capabilities
Copy link

The JBoss EAP XP 5.0 release includes support for the following MicroProfile 6.1 components:

  • MicroProfile Config
  • MicroProfile Fault Tolerance
  • MicroProfile Health
  • MicroProfile JWT
  • MicroProfile OpenAPI
  • MicroProfile Telemetry
  • MicroProfile REST Client

Before you migrate your application to JBoss EAP XP 5.0 be aware that some features that were available in JBoss EAP XP 4.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 5.0 release notes and the Release notes for Red Hat JBoss Enterprise Application Platform 8.0 for any unsupported and deprecated features.

You can choose one of the following tools to upgrade and migrate your JBoss EAP XP 3.0 or 4.0 product to the JBoss EAP XP 5.0 product:

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

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

The JBoss Server Migration Tool reads your existing JBoss EAP XP 3.0 or 4.0 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 for your JBoss EAP XP 5.0 configuration.

JBoss EAP XP 5.0 does not include the JBoss Server Migration Tool, so you need to download the tool from the JBoss EAP XP download page.

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 3.0 or 4.0 to JBoss EAP XP 5.0.

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 3.0 or 4.0 applications before you migrate them to JBoss EAP XP 5.0. The MTA rule set for migrating applications from JBoss EAP XP 3.0 or 4.0 to JBoss EAP XP 5.0 reports on XML descriptors, specific application code, and parameters, that you need to replace with alternative configurations when migrating to JBoss EAP XP 5.0.

Chapter 3. Application Migration
Copy link

You can migrate your applications created for an older release of JBoss EAP XP to JBoss EAP XP 5.0.

3.1. MicroProfile application migration
Copy link

MicroProfile 6.1 aligns with the Jakarta EE 10 Core Profile and introduces MicroProfile Telemetry, replacing MicroProfile OpenTracing.

MicroProfile 6.1 includes updates to all the major MicroProfile specifications.

The following specifications might include API incompatible changes for MicroProfile 6.1:

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

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

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

  • Adding the MicroProfile 6.1 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.

MicroProfile OpenTracing is not supported in JBoss EAP XP 5.0 and is replaced by OpenTelemetry tracing.

To replace MicroProfile OpenTracing with OpenTelemetry Tracing, follow these steps:

  • Replace the dependency org.eclipse.microprofile.opentracing:microprofile-opentracing-api with io.opentelemetry:opentelemetry-api and io.opentelemetry:opentelemetry-context.
  • Replace the usage of the org.eclipse.microprofile.opentracing Java package with the io.opentelemetry Java package. Such replacement might involve additional changes to classes and methods.

MicroProfile Metrics is not supported in JBoss EAP XP 5.0 and is replaced by Micrometer.

To replace MicroProfile Metrics with Micrometer, follow these steps:

  • Replace the dependency org.eclipse.microprofile.metrics:microprofile-metrics-api with io.micrometer:micrometer-core.
  • Replace the usage of the org.eclipse.microprofile.metric Java package with the io.micrometer Java package. Such replacement might involve additional changes to classes and methods.

Legal Notice
Copy link

Copyright © 2024 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.
Red Hat logoGithubredditYoutubeTwitter

Learn

Try, buy, & sell

Communities

About Red Hat Documentation

We help Red Hat users innovate and achieve their goals with our products and services with content they can trust. Explore our recent updates.

Making open source more inclusive

Red Hat is committed to replacing problematic language in our code, documentation, and web properties. For more details, see the Red Hat Blog.

About Red Hat

We deliver hardened solutions that make it easier for enterprises to work across platforms and environments, from the core datacenter to the network edge.

Theme

© 2026 Red HatBack to top