Chapter 7. Thorntail

The Thorntail runtime artifacts provided with this release of RHOAR are all based on upstream version 2.2.0.Final.

7.1. Migrating your application from WildFly Swarm to Thorntail

7.1.1. Naming and versioning changes in Thorntail 2.2.0

With this release, the name of the WildFly Swarm runtime changes to Thorntail. The product release versioning scheme also changes, as RHOAR Wildfly Swarm 7.1.0 is followed by Thorntail 2.2.0. From a technical perspective, the new versioning scheme is intended to be a continuation of the 7.x.x scheme and does not constitute a new major product version. Subsequent Thorntail product releases will follow the new versioning scheme.

The name change has the following impact:

  • The groupId of productized artifacts changes to io.thorntail from org.wildfly.swarm.
  • The artifactId for the Maven plugin changes to thorntail-maven-plugin.
  • The suffix of generated uberjars and hollow JAR files changes to -thorntail.jar.

You need to:

The name change does NOT impact:

  • class names
  • package names
  • the set of productized artifacts shipped with Thorntail.
  • configuration properties

7.1.2. Updating the build configuration of your application

Manually migrate your application project from WildFly Swarm 7.1.0 to Thorntail 2.2.0.

Prerequisites

  • A Maven-based application project using the WildFly Swarm runtime.

Procedure

  1. Update the groupId and version of the BOM referenced in the pom.xml file of your application project. 

    ...
<dependency>
   <groupId>io.thorntail</groupId>
   <artifactId>bom</artifactId>
   <version>2.2.0.Final-redhat-00021</version>
</dependency>
...

  2. Change the groupId of each fraction defined as a dependency in the pom file of your application project from org.wildfly.swarm to io.thorntail. For example: 

    ...
<dependency>
  <groupId>io.thorntail</groupId>
  <artifactId>jaxrs</artifactId>
</dependency>
...

  3. Change groupId and artifactId of the Maven plugin in the pom.xml to the values appropriate for Thorntail: 

    ...
<plugin>
  <groupId>io.thorntail</groupId>
  <artifactId>thorntail-maven-plugin</artifactId>
</plugin>
...

  4. Update the suffix of JAR file names in commands that you use to run your apps to -thorntail.jar so that it refers to Thorntail. 

    java -jar target/MY_APP_NAME-1.0.0-thorntail.jar

  5. Update the name of the Maven plugin in commands that invoke it. For example: 

    mvn thorntail:start

  6. If you use Fabric8 Maven Plugin to deploy your apps to OpenShift, ensure that you upgrade it to version 3.5.40 or later. Earlier FMP versions do not support the current release of Thorntail. 

    <project>
 <build>
  ...
   <plugins>
    ...
     <plugin>
       <groupId>io.fabric8</groupId>
       <artifactId>fabric8-maven-plugin</artifactId>
       <version>3.5.40</version>
     </plugin>
     ...
   </plugins>
   ...
 </build>
</project>

    Note that the set of features that FMP supports for deploying Thorntail applications is not impacted by the rename. You must, however, update the names of these features if you refer to them directly in your project.

    Table 7.1. Fabric8 Maven Plugin name changes

    FMP conceptName in WildFly SwarmName in Thorntail

    Docker image generator

    wildfly-swarm

    thorntail-v2

    Health Check enricher name

    f8-wildfly-swarm-health-check

    f8-thorntail-v2-health-check

    Reference to health check enricher in pom.xml

    <wildfly-swarm-health-check>

    <thorntail-v2-health-check>

  7. If you use a parser to parse the log output of your application, ensure that you update the prefixes of log messages to match the prefixes used by Thorntail:

    Table 7.2. Log message prefix changes

    WildFly SwarmThorntail

    WFSWARMnnnnn

    THORNnnnnn

    WFSxxxnnnnn

    TTxxxnnnnn

7.1.3. Migrating your application project to Thorntail automatically using the Thorntail Maven Plugin.

Migrate your application project from WildFly Swarm 7.1.0 to Thorntail 2.2.0 automatically using the Thorntail Maven Plugin.

Prerequisites

  • A Maven-based application project using the WildFly Swarm runtime.

Procedure

  1. Modify your local settings.xml file to point to the Red Hat General Availability Maven Repository to enable Maven to download the latest Thorntail Maven Plugin version. By default, the local repository settings file is located at ~/.m2/settings.xml. 

    <settings>
  <profiles>
    ...
    <profile>
      <id>redhat-maven-repository</id>
      <repositories>
        <repository>
          <id>redhat-ga</id>
          <name>Red Hat General Availability Maven Repository</name>
          <url>https://maven.repository.redhat.com/ga/</url>
        </repository>
      </repositories>
      <pluginRepositories>
        <pluginRepository>
          <id>redhat-ga</id>
          <name>Red Hat General Availability Maven Repository</name>
          <url>https://maven.repository.redhat.com/ga/</url>
        </pluginRepository>
      </pluginRepositories>
    </profile>
    ...
  </profiles>
  <activeProfiles>
    ...
    <activeProfile>redhat-maven-repository</activeProfile>
    ...
  </activeProfiles>
</settings>

  2. Execute the Maven command for the upgrade goal. 

    mvn io.thorntail:thorntail-maven-plugin:2.2.0.Final-redhat-00021:migrate-from-wildfly-swarm

    To preview the migration actions without making changes, append the -DdryRun=true parameter to the automated upgrade command.

    It is recommended that you review the changes to your application project configuration once the automated migration is complete.

  3. If you use Fabric8 Maven Plugin to deploy your apps to OpenShift, ensure that you upgrade it to version 3.5.40 or later. Earlier FMP versions do not support the current release of Thorntail. 

    <project>
 <build>
  ...
   <plugins>
    ...
     <plugin>
       <groupId>io.fabric8</groupId>
       <artifactId>fabric8-maven-plugin</artifactId>
       <version>3.5.40</version>
     </plugin>
     ...
   </plugins>
   ...
 </build>
</project>

    Note that the set of features that FMP supports for deploying Thorntail applications is not impacted by the rename. The automated migration goal does not update any direct references to FMP features that you may have in your project. You must update the names of these features manually.

    Table 7.3. Fabric8 Maven Plugin name changes

    FMP conceptName in WildFly SwarmName in Thorntail

    Docker image generator

    wildfly-swarm

    thorntail-v2

    Health Check enricher name

    f8-wildfly-swarm-health-check

    f8-thorntail-v2-health-check

    Reference to health check enricher in pom.xml

    <wildfly-swarm-health-check>

    <thorntail-v2-health-check>

7.2. Breaking changes to OpenTracing components in Thorntail 2.2.0

In previous releases, the jaeger fraction automatically introduced the opentracing fraction as a dependency to your project. In the Thorntail 2.2.0 release, the jaeger and opentracing fractions are decoupled to allow the jaeger fraction to be reused by any other tracing fraction. The change is required to improve the way Thorntail supports both the old opentracing and the new microprofile-opentracing fractions. In this release, the jaeger fraction only provides tracer configuration.

You must manually specify one of the 2 OpenTracing fractions provided by Thorntail 2.2.0 as a dependency in the pom.xml file of your project:

  • opentracing
  • microprofile-opentracing

To retain the behavior of the tracing functionality in your application, in instances where you previously only specified the jaeger fraction, you must also explicitly specify a dependency on the opentracing fraction.

7.3. Breaking changes to JAX-RS components.

In RHOAR Thorntail 2.2.0, subclasses of the JAX-RS Application class are no longer generated by default. To enable Thorntail to generate the subclass of the JAX-RS Application class, you must:

  • not have a custom Application subclass in your project,
  • have the swarm.deployment.WAR_FILE_NAME.jaxrs.application-path key set in project-defaults.yml.

7.4. New Thorntail features and feature upgrades

This release of RHOAR Thorntail introduces the following new features and feature upgrades:

MicroProfile 1.3
This release of RHOAR Thorntail implements the MicroProfile version 1.3 specification.
Enterprise Application Platform 7.1.4.GA
EAP dependencies used by RHOAR Thorntail have been updated and aligned with the 7.1.4.GA release of Red Hat JBoss Enterprise Application Platform.
Red Hat SSO 7.2.4.GA
This RHOAR Thorntail release uses components provided by Red Hat Single Sign-On release version 7.2.4.GA.

7.5. Resolved Thorntail Issues

7.5.1. Notable non-security issue fixes

7.5.1.1. MicroProfile JWT: cannot use different roles for different methods with the same @Path but different @Produces and/or @Consumes annnotations.

Description

The implementation of MicroProfile JWT used in RHOAR WildFly Swarm 7.1.0 was previously unable to honor the @RolesAllowed annotations properly. This lead to a situation where separation of access roles to different methods did not work for methods that shared a common @Path, but had different @Produces and/or @Consumes annotations. This issue has been fixed in the RHOAR Thorntail 2.2.0 release.

7.5.1.2. MicroProfile JWT: cannot use different roles for different methods with parameterized @Paths that share a common prefix

Description

Our implementation of MicroProfile JWT used in WildFly Swarm 7.1.0 was unable to honor the @RolesAllowed annotations properly. This lead to a situation where separation of access roles to different endpoints did not work for methods with parameterized @Paths that shared a common prefix. This issue has been fixed in the RHOAR Thorntail 2.2.0 release.

7.5.1.3. Maven build fails on downloading the org.wildfly.swarm:config-api-runtime artifact

Description

When building your application, Maven failed to download the org.wildfly.swarm:config-api-runtime artifact, causing the build to fail. This issue occured when you managed the dependency versions in the pom.xml file of your application manually, that is, without importing the BOM. This issue has been fixed in the RHOAR Thorntail 2.2.0 release.

7.5.2. Security issues fixes

7.5.2.1. CVE-2018-7489

Affected component
jackson-databind
Issue Summary
Incomplete fix for CVE-2017-7525 permits unsafe serialization via c3p0 libraries
Red Hat CVE database entry
CVE-2018-7489
Bugzilla Bug ID
1462702

7.5.2.2. CVE-2018-1047

Affected component
undertow
Issue Summary
Path traversal in ServletResourceManager class
Red Hat CVE database entry
CVE-2018-1047
Bugzilla Bug ID
1528361

7.6. Known Thorntail Issues

7.6.1. Thorntail Arquillian adapter ignores mvn -s settings.xml

Issue Key:

THORN-1546

NOTE: You do not have to log into JIRA to view this issue.

7.6.2. MicroProfile Fault Tolerance: CDI contexts not available in @Timeout methods

Description

If your application contains a @Timeout method that uses a contextual service , such as the @RequestScoped MyService shown in the example below, the contexts are not activated for that service. 

@Inject
private MyService service;

@Timeout
public String doSomething() throws InterruptedException {
    return "Hello " + service.call();
}

The method is not @Asynchronous and should, therefore, be executed on the caller thread, which would make the CDI (Context and Dependency Injection) contexts available. However, the following debug message indicates that the contexts are not available: 

2018-04-03 21:16:35,976 ERROR [io.undertow.request] (default task-1) UT005023: Exception handling request to /: org.jboss.weld.context.ContextNotActiveException: WELD-001303: No active contexts for scope type javax.enterprise.context.RequestScoped

Cause

This issue is caused by @Timeout methods always being invoked on a separate thread, even if they are not @Asynchronous.

Workaround

At the time of this release, there is no workaround available for this issue.

7.6.3. MicroProfile Metrics: Application metric behavior does not conform to metrics specification

Description

When you build and package your application and then run the resulting -thorntail.jar uberjar, the application metric is not registered immediately upon deployment. The application metric is registered only after the monitored method is called.

For example, your Thorntail application contains a simple application metric, such as: 

@ApplicationScoped
public class HelloService {
    @Counted(monotonic = true, name = "hello", absolute = true, displayName = "HELLO", description = "Number of hello invocations")
    public String hello() {
        return "Hello from counted method";
    }
}
Note

You can test whether application metrics are registered by issuing an OPTIONS HTTP request to the /metrics REST endpoint. For example, localhost:8080/metrics, when running your application locally.

Cause

The implementation does not conform to the current version of the MicroProfile Metrics specification. The specification will likely change in the future to allow this behavior.

Workaround

At the time of this release, there is no workaround available for this issue.

7.6.4. Harmless error message in application log: Missing org.glassfish:javax.el-api:3.0.1.b08-redhat-1

Description

If your application, or any of its dependencies, depends on the Java Expression Language, it will display the following warning message during startup. 

Failed downloading org/glassfish/javax.el-api/3.0.1.b08-redhat-1/javax.el-api-3.0.1.b08-redhat-1.pom from https://repository.jboss.org/nexus/content/groups/public/. Reason:
org.eclipse.aether.transfer.ArtifactNotFoundException: Could not find artifact org.glassfish:javax.el-api:pom:3.0.1.b08-redhat-1 in jboss-public-repository-group (https://repository.jboss.org/nexus/content/groups/public/)
Failed downloading org/glassfish/javax.el-api/3.0.1.b08-redhat-1/javax.el-api-3.0.1.b08-redhat-1.pom from http://repo.gradle.org/gradle/libs-releases-local/. Reason:
org.eclipse.aether.transfer.ArtifactNotFoundException: Could not find artifact org.glassfish:javax.el-api:pom:3.0.1.b08-redhat-1 in gradle (http://repo.gradle.org/gradle/libs-releases-local)
Failed downloading org/glassfish/javax.el-api/3.0.1.b08-redhat-1/javax.el-api-3.0.1.b08-redhat-1.pom from https://repo.maven.apache.org/maven2/. Reason:
org.eclipse.aether.transfer.ArtifactNotFoundException: Could not find artifact org.glassfish:javax.el-api:pom:3.0.1.b08-redhat-1 in central (https://repo.maven.apache.org/maven2)
Failed downloading org/glassfish/javax.el-api/3.0.1.b08-redhat-1/javax.el-api-3.0.1.b08-redhat-1.pom from http://repo1.maven.org/maven2/. Reason:
org.eclipse.aether.transfer.ArtifactNotFoundException: Could not find artifact org.glassfish:javax.el-api:pom:3.0.1.b08-redhat-1 in central (http://repo1.maven.org/maven2)

The message is harmless and does not impact the functionality of the application.

Cause

The likely cause of this issue is related to the way dependency resolution works in Thorntail. During the dependency resolution phase, Thorntail ignores dependency exclusions, and thus pulls in javax.el-api, despite javax.el-api being excluded in the EAP BOM. Since it is interpreted as a valid dependency, it is indicated as missing due to being absent from the repository, which causes the error messages displayed in the build log.

Workaround

At the time of this release, there is no workaround available for this issue.

7.7. Supported Maven Artifacts Provided with Thorntail

Group IDArtifact IDVersion

io.thorntail

bean-validation

2.2.0.Final-redhat-00021

io.thorntail

bom-certified

2.2.0.Final-redhat-00021

io.thorntail

bom

2.2.0.Final-redhat-00021

io.thorntail

cdi-config

2.2.0.Final-redhat-00021

io.thorntail

cdi

2.2.0.Final-redhat-00021

io.thorntail

connector

2.2.0.Final-redhat-00021

io.thorntail

container

2.2.0.Final-redhat-00021

io.thorntail

datasources

2.2.0.Final-redhat-00021

io.thorntail

ee

2.2.0.Final-redhat-00021

io.thorntail

ejb

2.2.0.Final-redhat-00021

io.thorntail

elytron

2.2.0.Final-redhat-00021

io.thorntail

hibernate-validator

2.2.0.Final-redhat-00021

io.thorntail

io

2.2.0.Final-redhat-00021

io.thorntail

jaeger

2.2.0.Final-redhat-00021

io.thorntail

jaxrs-cdi

2.2.0.Final-redhat-00021

io.thorntail

jaxrs-jaxb

2.2.0.Final-redhat-00021

io.thorntail

jaxrs-jsonp

2.2.0.Final-redhat-00021

io.thorntail

jaxrs-multipart

2.2.0.Final-redhat-00021

io.thorntail

jaxrs-validator

2.2.0.Final-redhat-00021

io.thorntail

jaxrs

2.2.0.Final-redhat-00021

io.thorntail

jca

2.2.0.Final-redhat-00021

io.thorntail

jmx

2.2.0.Final-redhat-00021

io.thorntail

jpa

2.2.0.Final-redhat-00021

io.thorntail

jsf

2.2.0.Final-redhat-00021

io.thorntail

jsonp

2.2.0.Final-redhat-00021

io.thorntail

keycloak

2.2.0.Final-redhat-00021

io.thorntail

logging

2.2.0.Final-redhat-00021

io.thorntail

management

2.2.0.Final-redhat-00021

io.thorntail

microprofile-config

2.2.0.Final-redhat-00021

io.thorntail

microprofile-fault-tolerance

2.2.0.Final-redhat-00021

io.thorntail

microprofile-health

2.2.0.Final-redhat-00021

io.thorntail

microprofile-jwt

2.2.0.Final-redhat-00021

io.thorntail

microprofile-metrics

2.2.0.Final-redhat-00021

io.thorntail

microprofile-openapi

2.2.0.Final-redhat-00021

io.thorntail

microprofile-opentracing

2.2.0.Final-redhat-00021

io.thorntail

microprofile-restclient

2.2.0.Final-redhat-00021

io.thorntail

microprofile

2.2.0.Final-redhat-00021

io.thorntail

msc

2.2.0.Final-redhat-00021

io.thorntail

naming

2.2.0.Final-redhat-00021

io.thorntail

opentracing

2.2.0.Final-redhat-00021

io.thorntail

remoting

2.2.0.Final-redhat-00021

io.thorntail

request-controller

2.2.0.Final-redhat-00021

io.thorntail

resource-adapters

2.2.0.Final-redhat-00021

io.thorntail

security

2.2.0.Final-redhat-00021

io.thorntail

spi

2.2.0.Final-redhat-00021

io.thorntail

topology-openshift

2.2.0.Final-redhat-00021

io.thorntail

topology-webapp

2.2.0.Final-redhat-00021

io.thorntail

topology

2.2.0.Final-redhat-00021

io.thorntail

transactions

2.2.0.Final-redhat-00021

io.thorntail

undertow

2.2.0.Final-redhat-00021

io.thorntail

web

2.2.0.Final-redhat-00021

7.8. Tested Maven Artifacts Provided with Thorntail

Maven artifacts designated as Tested that are provided with a RHOAR Thorntail release are not supported.

Group IDArtifact IDVersion

io.thorntail

ribbon

2.2.0.Final

io.thorntail

ribbon-secured

2.2.0.Final

io.thorntail

ribbon-secured-client

2.2.0.Final

io.thorntail

arquillian

2.2.0.Final

7.9. Technology Preview Maven Artifacts Provided with Thorntail

Red Hat provides limited support for Thorntail artifacts designated as Technology Preview:

Group IDArtifact IDVersion

io.jaegertracing

jaeger-core

0.30.6.redhat-00001

io.jaegertracing

jaeger-thrift

0.30.6.redhat-00001

io.opentracing

opentracing-api

0.31.0.redhat-00008

io.opentracing

opentracing-noop

0.31.0.redhat-00008

io.opentracing

opentracing-util

0.31.0.redhat-00008

io.opentracing

parent

0.31.0.redhat-00008

io.opentracing.contrib

opentracing-concurrent

0.1.0.redhat-00002

io.opentracing.contrib

opentracing-tracerresolver

0.1.4.redhat-7

io.opentracing.contrib

opentracing-tracerresolver-parent

0.1.4.redhat-7

io.opentracing.contrib

opentracing-web-servlet-filter

0.1.0.redhat-00027

io.opentracing.contrib

opentracing-web-servlet-filter-parent

0.1.0.redhat-00027

io.opentracing.contrib

opentracing-jaxrs2

0.1.6.redhat-00001

io.opentracing.contrib

opentracing-jaxrs-parent

0.1.6.redhat-00001

io.opentracing.contrib

opentracing-jaxrs2

0.1.6.redhat-00001

org.keycloak

keycloak-authz-client

3.4.12.Final-redhat-2

7.10. Deprecated Thorntail Maven Artifacts

Group IDArtifact IDVersion

io.thorntail

monitor[a]

2.2.0.Final-redhat-00021

io.thorntail

hystrix

2.2.0.Final-redhat-00021

io.thorntail

archaius

2.2.0.Final-redhat-00021

[a] The monitor fraction has been removed from the BOM. It is still shipped with this release of Thorntail, but it will not be automatically imported when you specify the BOM as a dependency in your application project.