Release Notes for Thorntail 2.7
For use with Thorntail 2.7.3
Abstract
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:
Click the Feedback button in the top-right corner of the document to see existing feedback.
NoteThe feedback feature is enabled only in the Multi-page HTML format.
- Highlight the section of the document where you want to provide feedback.
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.
Enter your feedback in the text box and click Submit.
A documentation issue is created.
- 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 name | Version |
---|---|
Maven | 3.6.0 |
OpenShift Maven Plugin | 1.1.0 |
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:
- For a list of technologies that are supported for integration with Thorntail in production environments see the Supported Thorntail 2.7.3 configurations and integrations.
- For a list of Thorntail runtime artifacts and their versions see the Thorntail 2.7.3 component details page.
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.
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 methodsHealthCheckResponse.up
andHealthCheckResponse.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. TheREST.request
metric tracks the count and duration of requests for a REST endpoint. -
New methods are available in the
MetadataBuilder
,MetricID
, andMetricType
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 theClientHeadersFactory
interface is not supported in Thorntail. This is an optional feature of the MicroProfile RestClient specification.
-
Classes that implement the
Config 1.4
-
Some caching and classloading issues are fixed in the
ConfigProviderResolver
class. -
The
Converter
interface extendsSerializable
interface. -
New built-in
Converter
types are available.
-
Some caching and classloading issues are fixed in the
Fault Tolerance 2.1
-
New annotation attributes
CircuitBreaker.skipOn
,Fallback.applyOn
, andFallback.skipOn
are available. Specified the behavior for
@Retry
when theretryOn
andabortOn
exception sets overlap. Similar behavior is specified for:-
@CircuitBreaker
whenfailOn
andskipOn
overlap -
@Fallback
whenapplyOn
andskipOn
overlap
-
-
New annotation attributes
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
totrue
-
AB_JOLOKIA_OFF
totrue
-
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>
Chapter 7. Advisories related to this release
The following advisories have been issued to document enhancements, bugfixes, and CVE fixes included in this release.