Chapter 1. JBoss EAP XP for the latest MicroProfile capabilities

1.1. About JBoss EAP XP

The Eclipse 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 Eclipse MicroProfile 3.3 components:

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

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 latest JBoss EAP XP 2.0.x patch is compatible with the latest JBoss EAP 7.3 patch.

Additional Resources

1.3. JBoss EAP XP manager for managing JBoss EAP XP patch streams

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 3.3 implementations and the bug fixes for these MicroProfile 3.3 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 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 2.0 commands

JBoss EAP XP manager 2.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 2.0 performs validation to prevent patch and patch stream mismatch. The following example illustrates incorrect combinations:

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

    java.lang.IllegalStateException: The JBoss EAP XP patch stream in the patch 'jboss-eap-xp-1.0' does not match the currently enabled JBoss EAP XP patch stream [jboss-eap-xp-2.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 2.0 patch on a server that is not set up for JBoss EAP XP 2.0 patch stream causes the following error: 

    java.lang.IllegalStateException: You are attempting to install a patch for the 'jboss-eap-xp-2.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 2.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 2.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 2.0.0 on JBoss EAP 7.3.x

Install JBoss EAP XP 2.0.0 on the JBoss EAP 7.3.x base server.

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

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

    • The jboss-eap-xp-2.0.0-manager.jar file (JBoss EAP XP manager 2.0)
    • JBoss EAP 7.3.4 GA patch
    • JBoss EAP XP 2.0.0 patch

Procedure

  1. If you have not applied the JBoss EAP 7.3.4 GA patch patch to your JBoss EAP server, apply the JBoss EAP 7.3.4 GA patch using the JBoss EAP XP manager 2.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-7.3.4-patch.zip

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

  2. Set up JBoss EAP XP manager 2.0.0 to manage the EAP XP 2.0 patch stream 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 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 setup --jboss-home=/PATH/TO/EAP --xp-patch /PATH/TO/PATCH/jboss-eap-xp-2.0.0-patch.zip

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

  3. Optional: If you did not use the the --xp-patch argument with the setup command, apply the JBoss EAP XP 2.0.0 patch using the JBoss EAP XP manager 2.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-2.0.0-patch.zip

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

Additional Resources

1.6. 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.

Note

JBoss EAP XP 2.0.0 is certified with JBoss EAP 7.3.4 and 7.3.z versions.

Prerequisites

  • The base JBoss EAP server is updated to patch 7.3.4 or a later patch.
  • You have downloaded the JBoss EAP XP 2.0.0 patch from the Product download page.

Procedure

  1. Verify that your server is on the correct patch and has JBoss EAP XP 1.0.x installed: 

    $ java -jar jboss-eap-xp-manager.jar status --jboss-home=__<path_to_eap>__
...
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.4'
- 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]

    This output indicates that your server is ready for upgrade to JBoss EAP XP 2.0.0.

    If you see other output, refer to the troubleshooting recommendations.

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

    $ 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.

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

Additional resources

1.7. Uninstalling JBoss EAP XP

Uninstalling JBoss EAP XP removes all the files related to enabling the JBoss EAP XP 2.0.0 patch stream and the Eclipse MicroProfile 3.3 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 2.0.0 by issuing the following command: 

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

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

1.8. 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