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