SupportConsoleDevelopersStart a trialContact

Chapter 1. JBoss EAP XP for the latest MicroProfile capabilities

1.1. About JBoss EAP XP

The MicroProfile Expansion Pack (JBoss EAP XP) is available as a patch stream, which is provided using JBoss EAP XP manager.

Note

JBoss EAP XP is subject to a separate support and life cycle policy. For more details, see the JBoss Enterprise Application Platform expansion pack Support and Life Cycle Policies page.

The JBoss EAP XP patch provides the following MicroProfile 4.1 components:

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

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

Red Hat tested Red Hat AMQ Streams 2021.Q4 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 4.0.0.

Technology Preview features are not supported with Red Hat production service level agreements (SLAs) and might not be functionally complete. Red Hat does not recommend using them in production. These features provide early access to upcoming product features, enabling customers to test functionality and provide feedback during the development process. For more information about the support scope of Red Hat Technology Preview features, see Technology Preview Features Support Scope.

1.2. JBoss EAP XP installation

When you install JBoss EAP XP, make sure that the JBoss EAP XP patch is compatible with your version of JBoss EAP. The JBoss EAP XP 4.0.x patch is compatible with the JBoss EAP 7.4 release.

Note

You can install JBoss EAP XP either through the XP manager and EAP archive or using the JBoss EAP XP OpenShift Container images. You cannot install JBoss EAP XP on top of EAP RPMs.

Additional Resources

1.3. JBoss EAP XP manager

JBoss EAP XP manager is an executable jar file that you can download from the Product Downloads page. Use JBoss EAP XP manager to apply the JBoss EAP XP patches from the JBoss EAP XP patch stream. The patches contain the MicroProfile 4.1 implementations and the bug fixes for these MicroProfile 4.1 implementations.

Note

You can not manage the JBoss EAP XP patches using the management console.

If you run JBoss EAP XP manager without any arguments, or with the help command, you get a list of all the available commands with a description of what they do.

Run the manager with the help command to get more information about the arguments available.

Note

Most of the JBoss EAP XP manager commands take a --jboss-home argument to point to the JBoss EAP XP server to manage the JBoss EAP XP patch stream. Specify the path to the server in the JBOSS_HOME environment variable if you want to omit this. --jboss-home takes precedence over the environment variable.

1.4. JBoss EAP XP manager 4.0 commands

JBoss EAP XP manager 4.0 provides different commands for managing JBoss EAP XP patch streams.

The following commands are provided:

patch-apply

Use this command to apply patches to your JBoss EAP installation.

The patch-apply command is similar to the patch apply management CLI command. The patch-apply command accepts only those arguments that are required for applying patches using the tool. It uses the default values for other patch apply management CLI command arguments.

You can use the patch-apply command to apply patches to any patch stream that is enabled on the server. You can also use the command to apply both the base server patches as well as the XP patches.

Example of using the patch-apply command:

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

When you apply an XP patch, JBoss EAP XP manager 4.0 performs validation to prevent patch and patch stream mismatch. The following example illustrates incorrect combinations:

  • Trying to install JBoss EAP XP 3.0 patch on a server with XP 4.0 patch stream set up causes the following error: 

    java.lang.IllegalStateException: The JBoss EAP XP patch stream in the patch 'jboss-eap-xp-3.0' does not match the currently enabled JBoss EAP XP patch stream [jboss-eap-xp-4.0]
	at org.jboss.eap.util.xp.patch.stream.manager.ManagerPatchApplyAction.doExecute(ManagerPatchApplyAction.java:33)
	at org.jboss.eap.util.xp.patch.stream.manager.ManagerAction.execute(ManagerAction.java:40)
	at org.jboss.eap.util.xp.patch.stream.manager.ManagerMain.main(ManagerMain.java:50)

  • Trying to install JBoss EAP XP 4.0.0 patch on a server that is not set up for JBoss EAP XP 4.0.0 patch stream causes the following error: 

    java.lang.IllegalStateException: You are attempting to install a patch for the 'jboss-eap-xp-4.0' JBoss EAP XP Patch Stream. However this patch stream is not yet set up in the JBoss EAP server. Run the 'setup' command to enable the patch stream.
	at org.jboss.eap.util.xp.patch.stream.manager.ManagerPatchApplyAction.doExecute(ManagerPatchApplyAction.java:29)
	at org.jboss.eap.util.xp.patch.stream.manager.ManagerAction.execute(ManagerAction.java:40)
	at org.jboss.eap.util.xp.patch.stream.manager.ManagerMain.main(ManagerMain.java:50)

    In both the cases, no changes are made to the server.

remove

Use this command to remove the JBoss EAP XP patch stream setup from the JBoss EAP server.

Example of using the remove command

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

setup

Use this command to set up a clean JBoss EAP server for the JBoss EAP XP patch stream.

When you use the setup command, JBoss EAP XP manager performs the following actions:

  • Enables the JBoss EAP XP 4.0.0 patch stream.
  • Applies patches specified using --base-patch and --xp-patch attributes.

  • Copies the standalone-microprofile.xml and standalone-microprofile-ha.xml configuration files into the server configuration directory.

    If older configuration files are already installed, the new files are saved as timestamped copies in the target configuration directory, such as standalone-microprofile-yyyyMMdd-HHmmss.xml.

    You can set the target directory using the --jboss-config-directory argument.

Example of using the setup command

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

status

Use this command to find the current status of your JBoss EAP XP server. The status command returns the following information:

  • The status of the JBoss EAP XP stream.
  • Any support policy changes due to being in the current state.
  • The major version of JBoss EAP XP.
  • Enabled patch streams and their cumulative patch IDs.
  • The available JBoss EAP XP manager commands to change the state.

Example of using the status command

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

upgrade

Use this command to upgrade an old JBoss EAP XP patch stream to the latest patch stream in the JBoss EAP server.

When you use the upgrade command, JBoss EAP XP manager performs the following actions:

  • Creates a backup of the files enabling the old patch stream in the server.
  • Enables the JBoss EAP XP 4.0 patch stream.
  • Applies patches specified using --base-patch and --xp-patch attributes.
  • Copies the standalone-microprofile.xml and standalone-microprofile-ha.xml configuration files into the server configuration directory. If older configuration files are already installed, the new files are saved as timestamped copies in the target configuration directory, such as standalone-microprofile-yyyyMMdd-HHmmss.xml.

  • If something goes wrong, JBoss EAP XP manager attempts to restore the previous patch stream from the backup it created.

    You can set the target directory using the --jboss-config-directory argument

Example of using the upgrade command:

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

1.5. Installing JBoss EAP XP 4.0.0 on JBoss EAP 7.4.x

Install JBoss EAP XP 4.0.0 on the JBoss EAP 7.4 base server.

Use JBoss EAP XP manager 4.0.0 to manage JBoss EAP XP 4.0.0 patch streams.

Note

JBoss EAP XP 4.0.0 is certified with JBoss EAP 7.4.x.

Prerequisites

  • You have downloaded the following files from the Product Downloads page:

    • The jboss-eap-xp-4.0.0-manager.jar file (JBoss EAP XP manager 4.0)
    • JBoss EAP 7.4 server archive file
    • JBoss EAP XP 4.0.0 patch

Procedure

  1. Extract the downloaded JBoss EAP 7.4 server archive file to the path of your JBoss EAP installation.

  2. Set up JBoss EAP XP manager 4.0.0 to manage the JBoss EAP XP 4.0 patch stream by using the following command: 

    $ java -jar jboss-eap-xp-manager.jar setup --jboss-home=<path_to_eap>
    Note

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

    Example: 

    $ java -jar jboss-eap-xp-manager.jar setup --jboss-home=<path_to_eap> --xp-patch=<path_to_patch>jboss-eap-xp-4.0.0-patch.zip

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

  3. Optional: If you have not applied the JBoss EAP XP 4.0.0 patch to your JBoss EAP server by using the --xp-patch argument, apply the JBoss EAP XP 4.0.0 patch by using the JBoss EAP XP manager 4.0.0 patch-apply command: 

    $ java -jar jboss-eap-xp-manager.jar patch-apply --jboss-home=<path_to_eap> --patch=<path_to_patch>jboss-eap-xp-4.0.0-patch.zip

    The patch-apply command is similar to the patch apply management CLI command. You can also use the patch apply management CLI command to apply the patch.

The JBoss EAP server is now ready to manage the JBoss EAP XP 4.0.0 patch stream as you patched the JBoss EAP server with the JBoss EAP XP 4.0.0 patch.

Additional Resources

1.6. Uninstalling JBoss EAP XP

Uninstalling JBoss EAP XP removes all the files related to enabling the JBoss EAP XP 4.0.0 patch stream and the MicroProfile 4.1 functionality. The uninstallation process does not affect anything in the base server patch stream or functionality.

Note

The uninstallation process does not remove any configuration files, including the ones you added to the JBoss EAP XP patches when you enabled the JBoss EAP XP patch stream.

Procedure

  • Uninstall JBoss EAP XP 4.0.0 by issuing the following command: 

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

To install MicroProfile 4.1 functionality again, run the setup command again to enable the patch stream, and then apply JBoss EAP XP patches to add the MicroProfile 4.1 modules.

1.7. Viewing the status of JBoss EAP XP

You can view the following information with the status command:

  • The status of the JBoss EAP XP stream.
  • Any support policy changes due to being in the current state.
  • The major version of JBoss EAP XP.
  • Enabled patch streams and their cumulative patch ids.
  • The available JBoss EAP XP manager commands to change the state.

JBoss EAP XP can be in one of the following states:

Not set up
JBoss EAP is clean and does not have JBoss EAP XP set up.
Set up
JBoss EAP has JBoss EAP XP set up. The version of the XP patch stream is not displays as the user can use CLI to determine it.
Inconsistent
The files relating to the JBoss EAP XP are in an inconsistent state. This is an error condition and should not happen normally. If you encounter this error, remove the JBoss EAP XP manager as described in the Uninstalling JBoss EAP XP topic and install JBoss EAP XP again using the setup command.

Procedure

  • View the status of JBoss EAP XP by issuing the following command: 

    $ java -jar jboss-eap-xp-manager.jar status --jboss-home=<path_to_eap>

Additional Resources

1.8. Rolling back JBoss EAP XP and JBoss EAP 7.4.x base patches

You can roll back a previously applied JBoss EAP XP patch or JBoss EAP 7.4.x base patch using the management CLI.

Additional resources

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.

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.

© 2024 Red Hat, Inc.