Release Notes for Thorntail 2.7

Red Hat build of Thorntail 2.7

For use with Thorntail 2.7.3

Red Hat Customer Content Services

Abstract

This Release Note contains important information related to Thorntail 2.7.3

Preface

Date of release: 2021-02-08

Red Hat build of Thorntail 2.7 - End of Life

The Red Hat build of Thorntail 2.7 is the last supported release. The full support ends on May 31, 2021. See the product life cycle page for details. Red Hat will continue to deliver security and bug fixes for Red Hat build of Thorntail with 2.7.x releases until the product end of life.

Depending on your requirements, you can migrate Thorntail applications to one of the following runtimes:

Red Hat build of Quarkus

Quarkus is a Kubernetes-native Java framework tailored for JVM and native compilation, created using the best Java libraries and standards. It provides an effective solution for running Java applications in environments such as serverless, microservices, containers, Kubernetes, FaaS, or the cloud.

Thorntail uses many of the same libraries and standards, and targets similar environments. Therefore, migration of Thorntail applications to Quarkus is the recommended option.

See the Quarkus product page and documentation for more information.

Red Hat JBoss Enterprise Application Platform (EAP)

EAP is a certified Jakarta EE application server based on the WildFly project. Thorntail is built on EAP, so migration to EAP is another option.

Migrate your Thorntail applications to EAP if you are using technologies such as EJB, JCA, JSF, or want to use other technologies such as SOAP or application server clustering.

With the introduction of the JBoss Enterprise Application Platform expansion pack (EAP XP), EAP now supports all the Eclipse MicroProfile APIs. To implement the APIs, EAP uses the same SmallRye components that Thorntail uses.

See the EAP product page and documentation for more information.

We will create resources to help you with the migration process.

Providing feedback on Red Hat documentation

We appreciate your feedback on our documentation. To provide feedback, you can highlight the text in a document and add comments.

This section explains how to submit feedback.

Prerequisites

  • You are logged in to the Red Hat Customer Portal.
  • In the Red Hat Customer Portal, view the document in Multi-page HTML format.

Procedure

To provide your feedback, perform the following steps:

  1. Click the Feedback button in the top-right corner of the document to see existing feedback.

    Note

    The feedback feature is enabled only in the Multi-page HTML format.

  2. Highlight the section of the document where you want to provide feedback.

  3. Click the Add Feedback pop-up that appears near the highlighted text.

    A text box appears in the feedback section on the right side of the page.

  4. Enter your feedback in the text box and click Submit.

    A documentation issue is created.

  5. To view the issue, click the issue tracker link in the feedback view.

Making open source more inclusive

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.

Chapter 1. Required Infrastructure Component Versions

Red Hat does not provide support for components listed below, with the exception of components explicitly designated as supported.

Component nameVersion

Maven

3.6.0

OpenShift Maven Plugin

1.1.0

JDK[a][b]

OpenJDK 8 or OpenJDK 11[c]

Red Hat Enterprise Linux 7[d]

7.7

Red Hat Enterprise Linux 8[e]

8.1

OpenShift Container Platform (OCP)[f]

3.11, 4.6

Minishift

1.34.2 or later

CDK[g]

3.11.0

git

2.0 or later

oc command line tool

3.11 or later[h]

[a] A full JDK installation is required, as JRE does not provide tools for compiling Java applications from source.
[b] Red Hat OpenJDK is supported by Red Hat.
[c] Red Hat supports only LTS releases of JDK.
[d] For deploying applications based on CNR on stand-alone RHEL in a production environment.
[e] For deploying applications based on CNR on stand-alone RHEL in a production environment.
[f] OCP is supported by Red Hat
[g] CDK is supported by Red Hat
[h] The version of the oc CLI tool should correspond to the version of OCP that you are using.

Chapter 2. Supported Thorntail Runtime Component Configurations and Integrations

The following resources define the supported configurations and integrations of Red Hat products with Thorntail:

Chapter 3. Release components

3.1. Supported artifacts introduced in this release

The following supported artifacts are introduced in this release:

  • A new fraction io.thorntail:hibernate

3.2. Technology Preview artifacts introduced in this release

No technology preview artifacts have been introduced in this release.

3.3. Artifacts removed in this release

No artifacts have been removed in this release.

3.4. Artifacts deprecated in this release

No artifacts have been declared deprecated in this release.

Chapter 4. Features

4.1. New features and feature upgrades

4.1.1. Support for Thorntail Runtime on IBM Z and IBM Power Systems

The Red Hat build of Thorntail for s390xand ppc64le platform is supported only in OpenShift environments provisioned on IBM Z and IBM Power Systems infrastructure. Running an Thorntail application on a stand-alone installation of RHEL on IBM Zand IBM Power Systems is not supported.

Eclipse OpenJ9 Java images for IBM Z and IBM Power Systems and new images for products supported on IBM Z and IBM Power Systems are available in the Red Hat Ecosystem Catalog.

4.1.2. Deploying example applications on OpenShift provisioned on IBM Z and IBM Power Systems infrastructure

To deploy the example applications on OpenShift environments provisioned on IBM Z and IBM Power Systems infrastructure, specify the relevant IBM Z and IBM Power Systems image name in the pom.xml file and commands.

Some of the example applications also require other products, such as Red Hat Data Grid to demonstrate the workflows. In this case, you must also change the image names of these products to their relevant IBM Z and IBM Power Systems image names in the YAML file of the example applications.

4.1.3. Deploy Thorntail applications using OpenShift Maven plugin

Use the OpenShift Maven plugin to deploy your Thorntail applications on OpenShift. The Fabric8 Maven plugin is no longer supported. For more information, see the section migrating from Fabric8 Maven Plugin to Eclipse JKube.

4.1.4. Thorntail metering labels for OpenShift

You can add metering labels to your Thorntail pods and check Red Hat subscription details with the OpenShift Metering Operator.

Note

Do not add metering labels to any pods that an operator or a template deploys and manages.

Thorntail should use the following metering labels:

  • com.redhat.component-name: Thorntail
  • com.redhat.component-type: application
  • com.redhat.component-version: 2.7.3
  • com.redhat.product-name: "Red_Hat_Runtimes"
  • com.redhat.product-version: 2021-Q1

See Metering documentation for more information.

For more information on labels, see Understanding how to update labels on nodes.

4.1.5. New hibernate fraction

A new fraction hibernate is available. This fraction provides the same functionality as jpa fraction. Additionally the hibernate fraction provides dependencies on the correct versions of Hibernate artifacts. If you use Hibernate APIs in your applications, you can use this fraction to manage the Hibernate versions instead of managing them manually.

4.1.6. Introduced an option to only repackage application WAR inside the uberjar

The filterWebInfLib configuration option introduces a new value uberjar-only. When this value is specified, only the WAR file inside the uberjar is repackaged. The standalone WAR file is not modified.

You can use the uberjar-only option when you want to create both, an uberjar for self-contained deployment, and a standalone WAR for deployment to an application server.

4.1.7. Feature upgrades

This release of Thorntail introduces the following feature upgrades:

4.1.7.1. Eclipse MicroProfile 3.3 support

This release implements Eclipse MicroProfile 3.3 by including the latest SmallRye artifacts. The following specifications have been upgraded to the versions listed below:

  • Health Check 2.2

    • HealthCheckResponse is no longer an abstract class. It also introduces two new convenience methods HealthCheckResponse.up and HealthCheckResponse.down.

  • Metrics 2.3

    • This release introduces a new type of metric called simple timer. The timer tracks the count and duration of invocations.
    • This release introduces a new annotation, @SimplyTimed. Use the annotation to create simple timers.
    • Some new metrics, such as, REST.request, are available in the base scope. The REST.request metric tracks the count and duration of requests for a REST endpoint.
    • New methods are available in the MetadataBuilder, MetricID, and MetricType interfaces.
    • All metric registries in Thorntail are thread safe. This is now a requirement of the MicroProfile Metrics specification.

  • Rest Client 1.4

    • Classes that implement the ClientHeadersFactory interface can now be CDI beans and use CDI injection.
    • JAX-RS injection (@Context) for classes that implement the ClientHeadersFactory interface is not supported in Thorntail. This is an optional feature of the MicroProfile RestClient specification.

  • Config 1.4

    • Some caching and classloading issues are fixed in the ConfigProviderResolver class.
    • The Converter interface extends Serializable interface.
    • New built-in Converter types are available.

  • Fault Tolerance 2.1

    • New annotation attributes CircuitBreaker.skipOn, Fallback.applyOn, and Fallback.skipOn are available.

    • Specified the behavior for @Retry when the retryOn and abortOn exception sets overlap. Similar behavior is specified for:

      • @CircuitBreaker when failOn and skipOn overlap
      • @Fallback when applyOn and skipOn overlap

4.1.8. Updated components

This section lists the components that are updated in Thorntail releases.

4.1.8.1. Thorntail 2.7.3

The components updated in Thorntail 2.7.3 release are:

Red Hat JBoss EAP 7.3.5 GA
The EAP dependencies in Thorntail have been updated to Red Hat JBoss Enterprise Application Platform 7.3.5 GA release.
Red Hat SSO 7.4.5 GA
The single sign-on components in Thorntail have been updated to Red Hat Single Sign-On 7.4.5 GA release.

4.1.8.2. Thorntail 2.7.2

The components updated in Thorntail 2.7.2 release are:

Red Hat JBoss EAP 7.3.4 GA
The EAP dependencies in Thorntail have been updated to Red Hat JBoss Enterprise Application Platform 7.3.4 GA release.
Red Hat SSO 7.4.4 GA
The single sign-on components in Thorntail have been updated to Red Hat Single Sign-On 7.4.4 GA release.

4.1.8.3. Thorntail 2.7.1

The components updated in Thorntail 2.7.1 release are:

Red Hat JBoss EAP 7.3.2 GA
The EAP dependencies in Thorntail have been updated to Red Hat JBoss Enterprise Application Platform 7.3.2 GA release.
Red Hat SSO 7.4.2 GA
The single sign-on components in Thorntail have been updated to Red Hat Single Sign-On 7.4.2 GA release.

4.1.8.4. Thorntail 2.7.0

The components updated in Thorntail 2.7.0 release are:

Red Hat JBoss EAP 7.3.1 GA
The EAP dependencies in Thorntail have been updated to Red Hat JBoss Enterprise Application Platform 7.3.1 GA release.
Red Hat SSO 7.4.1 GA
The single sign-on components in Thorntail have been updated to Red Hat Single Sign-On 7.4.1 GA release.
SmallRye Config 1.6.2
This release of Thorntail contains SmallRye Config 1.6.2.
SmallRye Fault Tolerance 4.3.0
This release of Thorntail contains SmallRye Fault Tolerance 4.3.0.
Jakarta EE 8 specification artifacts
This release of Thorntail uses Jakarta EE 8 specification artifacts instead of Java EE 8 specification artifacts. Since these specification artifacts are fully compatible, no changes are required in the Thorntail applications.

4.2. Changed and deprecated features

4.2.1. Red Hat Maven repository added to default Maven repositories

The Red Hat Maven repository has been included in the set of default Maven repositories that Thorntail uses to download artifacts.

If you use a Maven repository proxy, such as Nexus, add https://maven.repository.redhat.com/ga/ to the list of proxy repositories.

4.2.2. Thorntail configuration property can be set to null using environment variables or system properties

When you set an environment variable or system property to <<null>>, the corresponding Thorntail configuration property is set to null.

In releases prior to Thorntail 2.7.0, you could not set the configuration property to null using environment variables or system properties. The configuration property would always be set to the string value of the environment variable or system property, which could be an empty string, or the "null" string, or any other string.

4.2.3. Change in MicroProfile Config behavior when empty values are used

There is a change in how SmallRye Config treats empty values.

If you specify an empty string as a value for a MicroProfile Config configuration property, it is now treated as a missing value.

In previous releases, an empty string was treated as an empty value, which led to inconsistent behavior. For example, an empty string interpreted as an array would become an empty array, but a string "," interpreted as an array would become an array of 2 empty strings.

4.3. Technology preview

No technology preview features have been introduced in this release.

Chapter 5. Fixed issues

This Thorntail release contains the following bug fixes.

5.1. Thorntail applications work with WildFly OpenSSL

In prior releases, when WildFly OpenSSL was enabled, Thorntail applications would fail to boot.

This issue has been fixed in Thorntail 2.7.2. You can enable WildFly OpenSSL to use native OpenSSL libraries for TLS, instead of the Java implementation in the JDK. This improves the TLS performance.

5.2. Thorntail applications work with PostgreSQL JDBC driver version 42.2.15 or later

Description

In prior releases, when the PostgreSQL JDBC driver version 42.2.15 or later was used in a Thorntail application, the application would throw an exception and fail to boot.

This issue has been fixed in Thorntail 2.7.2. You can now use PostgreSQL JDBC driver version 42.2.15 or later with Thorntail applications.

5.3. Eclipse MicroProfile Fault Tolerance: Contexts and Dependency Injection (CDI) available in @Timeout methods

Description

In prior releases, Thorntail used SmallRye Fault Tolerance version 2.x, which was based on Hystrix. This implementation always executed @Timeout methods on a dedicated thread pool, even if they were not @Asynchronous. Due to this, the CDI contexts were not available in the @Timeout methods.

The Thorntail 2.7.0 release uses SmallRye Fault Tolerance 4.x, which is no longer based on Hystrix. It executes @Timeout methods that are not @Asynchronous on the original thread, so CDI contexts are available.

Example

@Inject
private MyService service;

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

In the example, MyService class is defined as @RequestScoped. The doSomething method uses a contextual instance of MyService. This example did not work in previous releases, because doSomething was invoked on an extra thread. In Thorntail 2.7.0, it works as expected.

5.4. Fixed security issues

For a list of resolved security issues, see Advisories related to this release.

Chapter 6. Known issues

6.1. Thorntail applications fail to boot due to logging issues

Description

Thorntail is based on WildFly. In Wildfly, the value of the java.util.logging.manager property should always be set to org.jboss.logmanager.LogManager (JBoss LogManager). The JBoss Modules initialize the log manager while booting. However, in some cases, java.util.logging is called before the log manager is set. In such cases, the Thorntail application fails to boot and returns the following error: 

ERROR: WFLYCTL0013: Operation ("parallel-extension-add") failed - address: ([])
java.lang.RuntimeException: WFLYCTL0079: Failed initializing module org.jboss.as.logging
        ...
Caused by: java.util.concurrent.ExecutionException: java.lang.IllegalStateException: WFLYLOG0078: The logging subsystem requires the log manager to be org.jboss.logmanager.LogManager.
The subsystem has not be initialized and cannot be used.
To use JBoss Log Manager you must add the system property "java.util.logging.manager" and set it to "org.jboss.logmanager.LogManager"

Cause

The Thorntail application fails to boot if java.util.logging is initialized too early. Some of the reasons for java.util.logging being initialized too early are:

  • The application uses Java agents, such as the Jolokia agent
  • The JDK itself uses logging

Workaround

To use Thorntail on OpenShift, it is recommended to switch off Java agents that are available in the Red Hat Java S2I images.

You can switch off the agents using one of the following ways:

  • To switch off Jolokia agent, you should set the following environment variables:

    • AB_OFF to true
    • AB_JOLOKIA_OFF to true

The following example shows an OpenShift deployment configuration where the environment variables are set. 

apiVersion: apps.openshift.io/v1
kind: DeploymentConfig
metadata:
  ...
spec:
  ...
  template:
    metadata:
      ...
    spec:
      containers:
      - image: ...
        env:
        - name: AB_JOLOKIA_OFF
          value: "true"
        - name: AB_OFF
          value: "true"
        ...
  • You can also use OpenShift Maven plugin to generate the YAML files. You can set environment variables in the OpenShift Maven plugin configuration as shown in the following code. 
<plugin>
  <groupId>org.eclipse.jkube</groupId>
  <artifactId>openshift-maven-plugin</artifactId>
  <version>${version.openshift-maven-plugin}</version>
  <executions>
    <execution>
      <goals>
        <goal>resource</goal>
        <goal>build</goal>
      </goals>
    </execution>
  </executions>
  <configuration>
    <resources>
      <env>
        <AB_OFF>true</AB_OFF>
        <AB_JOLOKIA_OFF>true</AB_JOLOKIA_OFF>
      </env>
    </resources>
  </configuration>
</plugin>
  • You can explicitly configure JBoss LogManager as the java.util.logging.manager. The following example shows you the configuration: 
java -Xbootclasspath/p:/home/test/.m2/repository/org/jboss/logmanager/jboss-logmanager/2.1.14.Final-redhat-00001/jboss-logmanager-2.1.14.Final-redhat-00001.jar:/home/test/.m2/repository/org/wildfly/common/wildfly-common/1.5.1.Final-redhat-00001/wildfly-common-1.5.1.Final-redhat-00001.jar -Djboss.modules.system.pkgs=org.jboss.logmanager,org.wildfly.common -Djava.util.logging.manager=org.jboss.logmanager.LogManager -jar myapp-thorntail.jar

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

This issue is caused by the dependency resolution mechanism in Thorntail. During the dependency resolution phase, Thorntail ignores dependency exclusions, and thus tries to pull the javax.el-api artifacts. However, javax.el-api is not available in the repository, because it is not required and has been excluded. This results in error messages that are displayed in the build log.

Workaround

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

6.3. Connection between a RHEL 8-based database application and a RHEL 7-based MySQL 5.7 database fails due to TLS protocol version mismatch

Description

Attempting to open a TLS-secured connection using OpenSSL between an application container built on a RHEL 8-based OpenJDK builder image and a database container built on a RHEL 7-based MySQL 5.7 container image results in a connection failure due to a javax.net.ssl.SSLHandshakeException at runtime: For more detail, view the issue in JIRA. 

...
Caused by: javax.net.ssl.SSLHandshakeException: No appropriate protocol (protocol is disabled or cipher suites are inappropriate)
...

Cause

The issue occurs due to a difference in the latest supported TLS protocol version between RHEL 7 and RHEL 8. The TLS implementation on RHEL 7 supports TLS protocol versions 1.0 (deprecated), 1.1, and 1.2. The TLS implementation on RHEL 8 also supports TLS protocol version 1.3, which is also the default TLS version used in RHEL 8-based builder images. This discrepancy may cause a TLS protocol version mismatch between application components while negotiating a TLS handshake, which in turn causes the connection between the application and database containers to fail.

Workaround

To prevent the issue described above, manually specify a TLS protocol version that is supported on both operating system versions in your database connection string. For example: 

jdbc:mysql://testdb-mysql:3306/testdb?enabledTLSProtocols=TLSv1.2

6.4. Thorntail Arquillian Adapter ignores mvn -s settings.xml

Description

When attempting to pass additional repositories referenced in the setting.xml file to the Thorntail Arquillian adapter when executing integration tests and unit tests, the settings.xml file is not recognized and the additional repositories are not configured. This issue results in build failure due to missing artifacts, which, in turn, causes the tests to fail.

Workaround

To avoid this issue, manually edit the <configuration> sections under the Maven Surefire and/or Maven Failsafe plugin entries in the pom.xml file of your Maven project, manually specifying the <org.apache.maven.user-settings>${session.request.userSettingsFile.path}</org.apache.maven.user-settings> property to be exported when testing your application. See example for details:

pom.xml

<project>
  ...
  <build>
    <plugins>
      ...
      <plugin>
        <groupId>org.apache.maven.plugins</groupId>
        <artifactId>maven-failsafe-plugin</artifactId>
        <configuration>
          <org.apache.maven.user-settings>${session.request.userSettingsFile.path}</org.apache.maven.user-settings>
        </configuration>
      </plugin>
      <plugin>
        <groupId>org.apache.maven.plugins</groupId>
        <artifactId>maven-surefire-plugin</artifactId>
        <configuration>
          <systemPropertyVariables>
            <org.apache.maven.user-settings>${session.request.userSettingsFile.path}</org.apache.maven.user-settings>
          </systemPropertyVariables>
        </configuration>
      </plugin>
      ...
    </plugins>
  </build>
  ...
</project>

Legal Notice

Copyright © 2021 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.