Chapter 7. Understanding application migration changes

The Java API for XML-based RPC (JAX-RPC) was deprecated in Java EE 6 and was optional in Java EE 7. Starting with JBoss EAP 7, it is no longer supported. Applications that use JAX-RPC must be migrated to use Jakarta XML Web Services, which is the current Jakarta EE standard web services framework.

Use of JAX-RPC web services can be identified in any of the following ways:

In previous releases of JBoss EAP, you could customize the JBossWS and Apache CXF integration by including a jbossws-cxf.xml configuration file with the endpoint deployment archive. One use case for this was to configure interceptor chains for web service client and server endpoints on the Apache CXF bus. This integration required Spring to be deployed in the JBoss EAP server.

Spring integration is no longer supported in JBoss EAP 8. Any application that contains a jbossws-cxf.xml descriptor configuration file must be modified to replace the custom configuration defined in that file. While it is still possible to directly access the Apache CXF API, be aware that the application will not be portable.

The suggested approach is to replace Spring custom configurations with the new JBossWS descriptor configuration options where possible. The JBossWS descriptor-based approach provides similar functionality without requiring modification of the client endpoint code. In some cases, you can replace Spring with Context Dependency Injection (CDI).

<?xml version="1.0" encoding="UTF-8"?>
<jaxws-config xmlns="urn:jboss:jbossws-jaxws-config:5.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:jakartaee="https://jakarta.ee/xml/ns/jakartaee"
  xsi:schemaLocation="urn:jboss:jbossws-jaxws-config:5.0 schema/jbossws-jaxws-config_5_0.xsd">
  <endpoint-config>
    <config-name>org.jboss.test.ws.jaxws.cxf.interceptors.EndpointImpl</config-name>
    <property>
      <property-name>cxf.interceptors.in</property-name>
      <property-value>org.jboss.test.ws.jaxws.cxf.interceptors.EndpointInterceptor,org.jboss.test.ws.jaxws.cxf.interceptors.FooInterceptor</property-value>
    </property>
    <property>
      <property-name>cxf.interceptors.out</property-name>
      <property-value>org.jboss.test.ws.jaxws.cxf.interceptors.EndpointCounterInterceptor</property-value>
    </property>
  </endpoint-config>
</jaxws-config>

<?xml version="1.0" encoding="UTF-8"?>
<jaxws-config xmlns="urn:jboss:jbossws-jaxws-config:5.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:jakartaee="https://jakarta.ee/xml/ns/jakartaee"
  xsi:schemaLocation="urn:jboss:jbossws-jaxws-config:5.0 schema/jbossws-jaxws-config_5_0.xsd">
  <endpoint-config>
    <config-name>org.jboss.test.ws.jaxws.cxf.interceptors.EndpointImpl</config-name>
    <property>
      <property-name>cxf.interceptors.in</property-name>
      <property-value>org.jboss.test.ws.jaxws.cxf.interceptors.EndpointInterceptor,org.jboss.test.ws.jaxws.cxf.interceptors.FooInterceptor</property-value>
    </property>
    <property>
      <property-name>cxf.interceptors.out</property-name>
      <property-value>org.jboss.test.ws.jaxws.cxf.interceptors.EndpointCounterInterceptor</property-value>
    </property>
  </endpoint-config>
</jaxws-config>

<?xml version="1.0" encoding="UTF-8"?>
<jaxws-config xmlns="urn:jboss:jbossws-jaxws-config:5.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:jakartaee="https://jakarta.ee/xml/ns/jakartaee"
  xsi:schemaLocation="urn:jboss:jbossws-jaxws-config:5.0 schema/jbossws-jaxws-config_5_0.xsd">
  <endpoint-config>
    <config-name>Custom FI Config</config-name>
    <property>
      <property-name>cxf.features</property-name>
      <property-value>org.apache.cxf.feature.FastInfosetFeature</property-value>
    </property>
  </endpoint-config>
</jaxws-config>

<?xml version="1.0" encoding="UTF-8"?>
<jaxws-config xmlns="urn:jboss:jbossws-jaxws-config:5.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:jakartaee="https://jakarta.ee/xml/ns/jakartaee"
  xsi:schemaLocation="urn:jboss:jbossws-jaxws-config:5.0 schema/jbossws-jaxws-config_5_0.xsd">
  <endpoint-config>
    <config-name>Custom FI Config</config-name>
    <property>
      <property-name>cxf.features</property-name>
      <property-value>org.apache.cxf.feature.FastInfosetFeature</property-value>
    </property>
  </endpoint-config>
</jaxws-config>

import org.apache.cxf.frontend.ClientProxy;
import org.apache.cxf.transport.http.HTTPConduit;
import org.apache.cxf.transports.http.configuration.HTTPClientPolicy;

// Set chunking threshold before using a JAX-WS port client
...
HTTPConduit conduit = (HTTPConduit)ClientProxy.getClient(port).getConduit();
HTTPClientPolicy client = conduit.getClient();

client.setChunkingThreshold(8192);
...

import org.apache.cxf.frontend.ClientProxy;
import org.apache.cxf.transport.http.HTTPConduit;
import org.apache.cxf.transports.http.configuration.HTTPClientPolicy;

// Set chunking threshold before using a JAX-WS port client
...
HTTPConduit conduit = (HTTPConduit)ClientProxy.getClient(port).getConduit();
HTTPClientPolicy client = conduit.getClient();

client.setChunkingThreshold(8192);
...

This section describes the various WS-Security changes for your application in JBoss EAP 6.4 and JBoss EAP 7.0.

The cxf-api and cxf-rt-core JARs have been merged into one cxf-core JAR. As a consequence, the org.apache.cxf module in JBoss EAP now contains the cxf-core JAR and exposes more classes than in the previous release.

If you want to use AES encryption with Galois/Counter Mode (GCM) for symmetric encryption in XML/WS-Security, you need the BouncyCastle Security Provider.

Starting with JBoss EAP 7, it was included with the org.bouncycastle module and JBossWS was able to rely on its class loader to get and use the BouncyCastle Security Provider. Therefore it is no longer necessary to statically install BouncyCastle in the current JVM. For applications running outside of the container, the security provider can be made available to JBossWS by adding a BouncyCastle library to the class path.

You can disable this behavior by setting the org.jboss.ws.cxf.noLocalBC property value to true in the jaxws-endpoint-config.xml deployment descriptor file for the server or the jaxws-client-config.xml descriptor file for clients.

If you want to use a different version than the one that ships with JBoss EAP, you can still statically install BouncyCastle to the JVM. In that case, the statically installed BouncyCastle Security Provider is chosen over the provider present in the class path. To avoid any issues, you must use BouncyCastle 1.72 or greater.

The default bus selection strategy for clients running in-container has changed from THREAD_BUS to TCCL_BUS. For clients running out-of container, the default strategy is still THREAD_BUS. You can restore the behavior to that of the previous release by using either of the following methods.

Containers must use Jakarta XML Web Services 2.2 style constructors, which include the WebServiceFeature class as an argument in the constructor, to build clients that are injected into web service references. JBoss EAP 6.4, which ships with JBossWS 4, hides that requirement. Starting with JBoss EAP 7 that included JBossWS 5, this requirement is not hidden. This states that user provided service classes injected by the container must implement Jakarta XML Web Services 2.2 or later by updating the existing code to use the jakarta.xml.ws.Service constructor that includes one or more WebServiceFeature arguments.

protected Service(URL wsdlDocumentLocation,
       QName serviceName,
       WebServiceFeature... features)

protected Service(URL wsdlDocumentLocation,
       QName serviceName,
       WebServiceFeature... features)

In previous releases, you could disable the HTTPS URL hostname check against a service’s Common Name (CN) given in its certificate by setting the system property org.jboss.security.ignoreHttpsHost to true. This system property name has been replaced with cxf.tls-client.disableCNCheck.

As a consequence of enabling injections into service endpoint and service client handlers, it is no longer possible to automatically load handler classes from the org.jboss.as.webservices.server.integration JBoss module. If your application depends on a given predefined configuration, you might need to explicitly define new module dependencies for your deployment. For more information, see Migrate explicit module dependencies.

The Java-endorsed standards override mechanism was deprecated in JDK 1.8_40 with intent to remove it in JDK 9. This mechanism allowed developers to make libraries available to all deployed applications by placing JARs into an endorsed directory within the JRE.

Starting with the JBoss EAP 7 release, if your application used the JBossWS implementation of Apache CXF, it ensured that the required dependencies are added in the correct order and you should not be impacted by this change. If your application accesses Apache CXF directly, you must now provide the Apache CXF dependencies after the JBossWS dependencies as part of your application deployment.

In previous releases of JBoss EAP, you could configure the jboss-webservices.xml deployment descriptor file for Jakarta Enterprise Beans web service deployments in the META-INF/ directory of JAR archives or in the WEB-INF/ directory for POJO web service deployments and Jakarta Enterprise Beans web service endpoints bundled in WAR archives.

Starting with JBoss EAP 7, you can configure the jboss-webservices.xml deployment descriptor file in the META-INF/ directory of an EAR archive. If a jboss-webservices.xml file is found in the EAR archive and the JAR or WAR archive, the configuration data in the jboss-webservices.xml file for the JAR or WAR overrides the corresponding data in the EAR descriptor file.

Starting with JBoss EAP 7, the proprietary HornetQ messaging resource deployment descriptor files identified by the naming pattern -jms.xml does not work. The following is an example of a Java Message Service resource deployment descriptor file in JBoss EAP 6:

<?xml version="1.0" encoding="UTF-8"?>
<messaging-deployment xmlns="urn:jboss:messaging-deployment:1.0">
  <hornetq-server>
    <jms-destinations>
      <jms-queue name="testQueue">
        <entry name="queue/test"/>
        <entry name="java:jboss/exported/jms/queue/test"/>
      </jms-queue>
      <jms-topic name="testTopic">
        <entry name="topic/test"/>
        <entry name="java:jboss/exported/jms/topic/test"/>
      </jms-topic>
    </jms-destinations>
  </hornetq-server>
</messaging-deployment>

<?xml version="1.0" encoding="UTF-8"?>
<messaging-deployment xmlns="urn:jboss:messaging-deployment:1.0">
  <hornetq-server>
    <jms-destinations>
      <jms-queue name="testQueue">
        <entry name="queue/test"/>
        <entry name="java:jboss/exported/jms/queue/test"/>
      </jms-queue>
      <jms-topic name="testTopic">
        <entry name="topic/test"/>
        <entry name="java:jboss/exported/jms/topic/test"/>
      </jms-topic>
    </jms-destinations>
  </hornetq-server>
</messaging-deployment>

If you used -jms.xml Java Message Service deployment descriptors in your application in the previous release, you can either convert your application to use the standard deployment descriptor as specified in the Resource Definition and Configuration section of the Jakarta EE platform, or you can update the deployment descriptor to use the messaging-activemq-deployment schema instead. If you choose to update the descriptor, you need to make the following modifications:

The modified file should look like the following example.

<?xml version="1.0" encoding="UTF-8"?>
<messaging-deployment xmlns="urn:jboss:messaging-activemq-deployment:1.0">
  <server>
    <jms-destinations>
      <jms-queue name="testQueue">
        <entry name="queue/test"/>
        <entry name="java:jboss/exported/jms/queue/test"/>
      </jms-queue>
      <jms-topic name="testTopic">
        <entry name="topic/test"/>
        <entry name="java:jboss/exported/jms/topic/test"/>
      </jms-topic>
    </jms-destinations>
  </server>
</messaging-deployment>

<?xml version="1.0" encoding="UTF-8"?>
<messaging-deployment xmlns="urn:jboss:messaging-activemq-deployment:1.0">
  <server>
    <jms-destinations>
      <jms-queue name="testQueue">
        <entry name="queue/test"/>
        <entry name="java:jboss/exported/jms/queue/test"/>
      </jms-queue>
      <jms-topic name="testTopic">
        <entry name="topic/test"/>
        <entry name="java:jboss/exported/jms/topic/test"/>
      </jms-topic>
    </jms-destinations>
  </server>
</messaging-deployment>

JBoss EAP 6 included the org.hornetq module, which allowed you to use the HornetQ API in your application source code.

Apache ActiveMQ Artemis replaces HornetQ in JBoss EAP 7, so you must migrate any code that used the HornetQ API to use the Apache ActiveMQ Artemis API. The libraries for this API are included in the org.apache.activemq.artemis module.

ActiveMQ Artemis is an evolution of HornetQ, so many of the concepts still apply.

The ability to auto-create and auto-delete topics and queues using the auto-create-jms-queues, auto-delete-jms-queues, auto-create-jms-topics, and auto-delete-jms-topics attributes was only partially implemented and not fully configurable in JBoss EAP 7. These attributes, which are deprecated, were provided as a technology preview feature only and were not supported.

You must replace any usage of these deprecated attributes with the following replacement attributes.

In JBoss EAP 6, the default address setting attributes were set to false. Starting with JBoss EAP 7, the replacement attributes are set to true by default.

If you prefer to preserve the JBoss EAP 6 behavior, you must set the replacement attributes to false.

For more information about these replacement attributes, see Address Setting Attributes in the JBoss EAP 7.4 Configuring Messaging Guide.

Starting with JBoss EAP 7.2, if a client application directly depends on Artemis client JARs, for example, artemis-jms-client, artemis-commons, artemis-core-client, or artemis-selector, then you must add the following dependency in your pom.xml file for wildfly-client-properties.

<dependency>
  <groupId>org.jboss.eap</groupId>
  <artifactId>wildfly-client-properties</artifactId>
</dependency>

<dependency>
  <groupId>org.jboss.eap</groupId>
  <artifactId>wildfly-client-properties</artifactId>
</dependency>

This is to avoid a JMSRuntimeException when calling message.getJMSReplyTo() from an older JBoss EAP 7 client as described in JBEAP-15889.

Interceptor and MessageBody Classes

JSR 311: JAX-RS: The Java™ API for RESTful Web Services did not include an interceptor framework, so RESTEasy 2 provided one. JSR 339: JAX-RS 2.0: The Java API for RESTful Web Services introduced an official interceptor and filter framework, so the interceptor framework included in RESTEasy 2 is now deprecated, and was replaced by the Jakarta REST compliant interceptor facility in RESTEasy 3.x. The relevant interfaces are defined in the jakarta.ws.rs.ext package of the jakarta.ws.rs.api module.

The following providers have been removed in JBoss EAP 8.0:

The following has been removed in JBoss EAP 8.0 as they now have Jakarta RESTful Web Services replacements.

Client API

The RESTEasy client framework in resteasy-jaxrs was replaced by the JAX-RS 2.0 compliant resteasy-client module in JBoss EAP 7.0. As a result, some RESTEasy client API classes and methods are deprecated.

StringConverter

The org.jboss.resteasy.spi.StringConverter class is deprecated in RESTEasy 3.x and JBoss EAP 8.0. This functionality can be replaced using the Jakarta REST jakarta.ws.rs.ext.ParamConverterProvider class.

ResteasyProviderFactory Add methods

Most of the org.jboss.resteasy.spi.ResteasyProviderFactory add() methods have been removed or made protected in RESTEasy 3.0. For example, the addBuiltInMessageBodyReader() and addBuiltInMessageBodyWriter() methods have been removed and the addMessageBodyReader() and addMessageBodyWriter() methods have been made protected.

You should now use the registerProvider() and registerProviderInstance() methods.

Additional Classes Removed From RESTEasy 3

The @org.jboss.resteasy.annotations.cache.ServerCached annotation, which specified the response to the Jakarta REST method should be cached on the server, was removed from RESTEasy 3 and must be removed from the application code.

This section provides information about some additional changes in RESTEasy for JBoss EAP.

SignedInput and SignedOuput

Security Filters

The security filters for @RolesAllowed, @PermitAll, and @DenyAll now return "403 Forbidden" instead of "401 Unauthorized".

Client-side Filters

The client-side filters that were introduced in JAX-RS 2.0 will not be bound and run when you are using the RESTEasy client API from a release prior to RESTEasy 3.0.

Asynchronous HTTP Support

Because the JAX-RS 2.0 specification added asynchronous HTTP support using the @Suspended annotation and the AsynResponse interface, the RESTEasy proprietary API for asynchronous HTTP was deprecated and might be removed in a future RESTEasy release. The asynchronous Tomcat and asynchronous JBoss Web modules have also been removed from the server installation. If you are not using the Servlet 3.0 container or higher, asynchronous HTTP server-side processing will be simulated and run synchronously in same request thread.

Server-side Cache

Server-side cache setup has changed. Please see the RESTEasy Documentation for more information.

YAML Provider Setting Changes

In previous releases of JBoss EAP, the RESTEasy YAML provider setting was enabled by default. This has changed in JBoss EAP 7. The YAML provider is now disabled by default. Its use is not supported due to a security issue in the SnakeYAML library used by RESTEasy for unmarshalling and it must be explicitly enabled in the application. For information about how to enable the YAML provider in your application and add the Maven dependencies, see YAML Provider in JBoss EAP 7.4 Developing Web Services Applications.

Default Charset UTF-8 in Content-Type Header

As of JBoss EAP 7.1, the resteasy.add.charset parameter is set to true by default. You can set the resteasy.add.charset parameter to false if you do not want RESTEasy to add charset=UTF-8 to the returned content-type header when the resource method returns a text/* or application/xml* media type without an explicit charset.

For more information about text media types and character sets, see Text Media Types and Character Sets in JBoss EAP 7.4 Developing Web Services Applications.

SerializableProvider

Deserializing Java objects from untrusted sources is not safe. For this reason, starting with JBoss EAP 7, the org.jboss.resteasy.plugins.providers.SerializableProvider class is disabled by default, and it is not recommended to use this provider.

Matching Requests to Resource Methods

In RESTEasy 3, improvements and corrections were made to the implementation of matching rules, as defined in the JAX-RS specification. In particular, a change was made to how an ambiguous URI on a sub-resource method and a sub-resource locator is handled.

In RESTEasy 2, it was possible for a sub-resource locator to execute successfully even when there was another sub-resource with the same URI. This behavior was incorrect according to the specification.

In RESTEasy 3, when there is an ambiguous URI for a sub-resource and a sub-resource locator, calling the sub-resource will be successful; however, calling the sub-resource locator will result in an HTTP status 405 Method Not Allowed error.

The following example contains an ambiguous @Path annotation on a sub-resource method and a sub-resource locator. Notice that the URI to both endpoints, anotherResource and anotherResourceLocator, is the same. The difference between the two endpoints is that the anotherResource method is associated with the REST verb, POST. The anotherResourceLocator method is not associated with any REST verb. According to the specification, the endpoint with the REST verb, in this case the anotherResource method, will always be selected.

@Path("myResource")
public class ExampleSubResources {
    @POST
    @Path("items")
    @Produces("text/plain")
    public Response anotherResource(String text) {
        return Response.ok("ok").build();
    }

    @Path("items")
    @Produces("text/plain")
    public SubResource anotherResourceLocator() {
        return new SubResource();
    }
}

@Path("myResource")
public class ExampleSubResources {
    @POST
    @Path("items")
    @Produces("text/plain")
    public Response anotherResource(String text) {
        return Response.ok("ok").build();
    }

    @Path("items")
    @Produces("text/plain")
    public SubResource anotherResourceLocator() {
        return new SubResource();
    }
}

The RESTEasy SPI provider has been removed in JBoss EAP 8.

SPI Exceptions

All SPI failure exceptions were deprecated and are no longer used internally. They have been replaced with the corresponding Jakarta REST exception.

InjectorFactory and Registry

The InjectorFactory and Registry SPIs have changed. This should not be an issue if you use RESTEasy as documented and supported.

The version of Jackson included in JBoss EAP 6.4 has changed. Starting with JBoss EAP 7, the Jackson provider has changed from resteasy-jackson-provider to resteasy-jackson2-provider.

The upgrade to the resteasy-jackson2-provider requires some package changes. For example, the Jackson annotation package has changed from org.codehaus.jackson.annotate to com.fasterxml.jackson.annotation.

JBoss EAP 8.0 provides support for RESTEasy 6.2. If you plan to use the Spring 6.0 framework with JBoss EAP 8.0, you must use Java 17.

The Spring 4.0 framework introduced support for Java 8. If you plan to use the RESTEasy 3.x integration with Spring, be sure to specify 4.2.x as the minimum Spring version in your deployment as this is the earliest stable version supported by JBoss EAP 7.

The RESTEasy Jettison JSON provider is deprecated since JBoss EAP 7 and is no longer added to deployments by default. You are encouraged to switch to the recommended RESTEasy Jackson provider. If you prefer to continue to use the Jettison provider, you must define an explicit dependency for it in the jboss-deployment-descriptor.xml file as demonstrated in the following example.

<?xml version="1.0" encoding="UTF-8"?>
<jboss-deployment-structure>
  <deployment>
    <exclusions>
      <module name="org.jboss.resteasy.resteasy-jackson2-provider"/>
      <module name="org.jboss.resteasy.resteasy-jackson-provider"/>
    </exclusions>
    <dependencies>
      <module name="org.jboss.resteasy.resteasy-jettison-provider" services="import"/>
    </dependencies>
  </deployment>
</jboss-deployment-structure>

<?xml version="1.0" encoding="UTF-8"?>
<jboss-deployment-structure>
  <deployment>
    <exclusions>
      <module name="org.jboss.resteasy.resteasy-jackson2-provider"/>
      <module name="org.jboss.resteasy.resteasy-jackson-provider"/>
    </exclusions>
    <dependencies>
      <module name="org.jboss.resteasy.resteasy-jettison-provider" services="import"/>
    </dependencies>
  </deployment>
</jboss-deployment-structure>

For more information about how to define explicit dependencies, see Add an Explicit Module Dependency to a Deployment in the JBoss EAP 7.4 Development Guide.

MicroProfile is the name of a specification that developers can use to configure applications and microservices to run in multiple environments without having to modify or repackage those apps. Previously, MicroProfile was available for JBoss EAP 7.3 as a technology preview, but it has since been removed. MicroProfile is now available only on JBoss EAP XP.

Bean classes of enabled beans must be deployed in bean archives to ensure they are discovered by CDI and processed as beans.

CDI 1.1 introduced implicit bean archives, which are archives that contain one or more bean classes with a bean defining annotation, or one or more session beans. Implicit bean archives are scanned by CDI and, during type discovery, only classes with bean defining annotations are discovered. For more information, see Type and Bean Discovery in JSR 365: Contexts and Dependency Injection for Java^™ 2.0. The Jakarta equivalents for bean defining annotations are defined in the Jakarta Context Dependency Injection 2.0 specification.

In CDI 4.0:

For more information about CDI 4.0, see Jakarta Contexts and Dependency Injection 4.0.

A bean archive has a bean discovery mode of all, annotated or none. A bean archive which contains non-empty beans.xml must specify the bean-discovery-mode attribute. The default value for the attribute is annotated.

An archive is not a bean archive in the following cases:

An archive is an explicit bean archive in the following case:

An archive is an implicit bean archive in the following cases:

CDI 1.2 limited bean defining annotations to the following:

The conversation context lifecycle was changed in CDI 1.2 to prevent conflicts with the Servlet specification as described in CDI Specification Issue CDI-411. The conversation scope is active during all servlet requests and should not prevent other servlets or servlet filters from setting the request body or character encoding. For more information, see Conversation context lifecycle in Jakarta EE.

Event resolution was partly rewritten in CDI 1.2. In CDI 1.0, an event is delivered to an observer method if the observer method has all the event qualifiers. In CDI 1.2, an event is delivered to an observer method if the observer method has no event qualifiers or has a subset of the event qualifiers. For more information, see Observer resolution.

This section highlights the changes required when migrating from Hibernate ORM version 5.3 to 5.4. For more information about the changes implemented between Hibernate ORM 5.3 and Hibernate ORM 5.4, see the Hibernate ORM 5.4 Migration Guide.

Known Changes

The following describes some of the changes when migrating from Hibernate ORM version 5.3 to 5.4.

This section highlights the changes required when migrating from Hibernate ORM version 5.4 to 5.5. For more information about the changes implemented between Hibernate ORM 5.4 and Hibernate ORM 5.5, see the Hibernate ORM 5.5 Migration Guide.

Known Changes

The Hibernate ORM 5.5 version is similar to Hibernate ORM 5.4 as it includes all bugfixes applied to the 5.4 maintenance releases and introduces support for Jakarta Persistence API.

This section highlights the changes required when migrating from Hibernate ORM version 5.5 to 5.6. For more information about the changes implemented between Hibernate ORM 5.5 and Hibernate ORM 5.6, see the Hibernate ORM 5.6 Migration Guide.

Deprecated features

The Hibernate 5.6 version is very similar to the previous Hibernate 5.5 version, with the exception of removal of some of the deprecated features from previous Hibernate releases.

This section highlights the changes required when migrating from Hibernate ORM version 5.6 to 6.0. For more information about the changes implemented between Hibernate ORM 5.6 and Hibernate ORM 6.0, see the Hibernate ORM 6.0 Migration Guide.

The Hibernate 6.0 release includes the following changes:

For more information about these features, see Hibernate ORM 6.0 Migration Guide.

The Hibernate 6.0 release contains also contains lot of feature removals from previous Hibernate releases, which are listed as follows:

For more information about features removed in Hibernate 6.0, see Hibernate ORM 6.0 Migration Guide.

This section highlights the changes required when migrating from Hibernate ORM version 6.0 to 6.1. For more information about the changes implemented between Hibernate ORM 6.0 and Hibernate ORM 6.1, see the Hibernate ORM 6.1 Migration Guide.

The Hibernate 6.1 release contains the following changes:

For more detailed information about features included in the Hibernate 6.1, see the Hibernate ORM 6.1 Migration Guide.

This section highlights the changes required when migrating from Hibernate ORM version 6.1 to 6.2. For more information about the changes implemented between Hibernate ORM 6.1 and Hibernate ORM 6.2, see the Hibernate ORM 6.2 Migration Guide.

The Hibernate 6.2 release contains the following enhancements, which are listed as follows:

DDL type changes:

JBoss EAP 7.0 included Hibernate ORM 5.0. This section highlights the changes you need to make when migrating from Hibernate ORM version 4.3 to version 5. For more information about the changes implemented between Hibernate ORM 4 and Hibernate ORM 5, see the Hibernate ORM 5.0 Migration Guide.

Removed and deprecated classes

The following deprecated classes were removed from Hibernate ORM 5:

Other changes to classes and packages

Type handling

Transaction management

Other Hibernate ORM 5 changes

JBoss EAP 7.1 included Hibernate ORM 5.1. This section highlights the differences and the changes needed when migrating from Hibernate ORM version 5.0 to version 5.1.

Hibernate ORM 5.1 features

This release of Hibernate includes performance improvements and bug fixes. For more information, see Hibernate ORM 5.1 Features in the JBoss EAP Release notes for 7.1.0. For additional information about the changes implemented between Hibernate ORM 5.0 and Hibernate ORM 5.1, see the Hibernate ORM 5.1 Migration Guide.

Schema management tooling changes

Schema management tooling changes in JBoss EAP 7

Schema management tooling changes in Hibernate ORM 5.1 are focused on the following areas:

The schema management tooling changes are only a migration concern for applications that directly use the following classes:

Schema management tooling changes in JBoss EAP 7.1

Hibernate ORM 5.1.10, included in JBoss EAP 7.1, introduced a strategy for retrieving database tables that improve SchemaMigrator and SchemaValidator performance. This strategy executes a single java.sql.DatabaseMetaData#getTables(String, String, String, String[]) call to determine if each javax.persistence.Entity has a mapped database table. This is the default strategy, and it uses the hibernate.hbm2ddl.jdbc_metadata_extraction_strategy=grouped property setting. This strategy might require hibernate.default_schema and/or hibernate.default_catalog to be provided.

To use the old strategy of executing a java.sql.DatabaseMetaData#getTables(String, String, String, String[]) call for each javax.persistence.Entity, use the hibernate.hbm2ddl.jdbc_metadata_extraction_strategy=individually property setting.

JBoss EAP 7.4 includes Hibernate ORM 5.3. This section highlights some of the changes needed when migrating from Hibernate ORM 5.1 to Hibernate ORM 5.2 and then to Hibernate ORM 5.3.

Hibernate ORM 5.2 features

Hibernate ORM 5.2 is built using the Java 8 JDK and requires the Java 8 JRE at runtime. The following is a list of some of the changes made in this release:

For the complete list of changes implemented in Hibernate 5.2, see Hibernate ORM 5.2 Migration Guide.

Hibernate ORM 5.3 features

Hibernate ORM 5.3 adds support for the Jakarta Persistence 2.2 specification. This release contains changes to comply with this specification along with other improvements. The following is a list of some of these changes:

For the complete list of these and other changes implemented in Hibernate 5.3, see the Hibernate ORM 5.3 Migration Guide.

Exception handling changes between Hibernate 5.1 and Hibernate 5.3

In Hibernate 5.2 and 5.3, exception handling for a SessionFactory that is built using Hibernate’s native bootstrapping, wraps or converts HibernateException according to the Jakarta Persistence specification. The only exception to this behavior is when the operation is Hibernate-specific, for example Session.save() or Session.saveOrUpdate().

In Hibernate 5.3.3, the hibernate.native_exception_handling_51_compliance property was added. This property indicates whether exception handling for a SessionFactory built using Hibernate’s native bootstrapping should behave the same as native exception handling in Hibernate ORM 5.1. When set to true, HibernateException is not wrapped or converted according to the Jakarta Persistence specification. This setting is ignored for a SessionFactory built using Jakarta Persistence bootstrapping.

Compatibility transformer

JBoss EAP 7.4 includes a compatibility transformer that addresses Hibernate ORM 5.3 API methods that are no longer compatible with Hibernate ORM 5.1. The transformer is a temporary measure to allow applications built using Hibernate ORM 5.1 to exhibit the same behavior with Hibernate 5.3 in JBoss EAP 7.4. This is a temporary solution and you should replace these method calls with the recommended Jakarta Persistence method calls.

You can enable the transformer in one of the following ways:

The following table lists the Hibernate 5.1 methods that are transformed and the Hibernate 5.3 method it is converted to:

Hibernate Search 5 APIs have been removed and are replaced with Hibernate Search 6 APIs in JBoss EAP 8.0.

To view a list of the removed features, see Hibernate Search 5 APIs Deprecated in JBoss EAP 7.4 and removed in EAP 8.0.

The latest version of Hibernate Search 6 included in JBoss EAP 8.0 is 6.2. If you are migrating from Hibernate Search 5, you should take into account the migration to version 6.0, 6.1, and 6.2.

See the following migrations guides for more information:

JBoss EAP 8.0 also provides support for using an Elasticsearch backend in Hibernate Search 6 to index data into remote Elasticsearch or OpenSearch clusters.

To see a list of possible Hibernate Search architectures and backends, see Table 2. Comparison of architectures in the Hibernate Search 6.2 reference documentation.

For more information about configuring Hibernate Search 6, see Using Hibernate Search in the WildFly Developer guide.

Starting with JBoss EAP 7, the default remote connector and port have been changed. For details about this change, see Update the Remote URL connector and port.

If you used the JBoss Server Migration Tool to migrate your server configuration, the old settings are preserved and you do not need to make the changes detailed here. However, if you use the new JBoss EAP 8.0 default configuration, you must make the following changes.

remote.connectionprovider.create.options.org.xnio.Options.SSL_ENABLED=false
remote.connections=default
remote.connection.default.host=localhost
remote.connection.default.port=4447
remote.connection.default.connect.options.org.xnio.Options.SASL_POLICY_NOANONYMOUS=false

remote.connectionprovider.create.options.org.xnio.Options.SSL_ENABLED=false
remote.connections=default
remote.connection.default.host=localhost
remote.connection.default.port=4447
remote.connection.default.connect.options.org.xnio.Options.SASL_POLICY_NOANONYMOUS=false

remote.connectionprovider.create.options.org.xnio.Options.SSL_ENABLED=false
remote.connections=default
remote.connection.default.host=localhost
remote.connection.default.port=8080
remote.connection.default.connect.options.org.xnio.Options.SASL_POLICY_NOANONYMOUS=false

remote.connectionprovider.create.options.org.xnio.Options.SSL_ENABLED=false
remote.connections=default
remote.connection.default.host=localhost
remote.connection.default.port=8080
remote.connection.default.connect.options.org.xnio.Options.SASL_POLICY_NOANONYMOUS=false

If you are running with the new default JBoss EAP 7 configuration, you must modify your client code to use the new default remote port and connector.

The following is an example of how remote naming properties were specified in the client code in JBoss EAP 6.

java.naming.factory.initial=org.jboss.naming.remote.client.InitialContextFactory
java.naming.provider.url=remote://localhost:4447

java.naming.factory.initial=org.jboss.naming.remote.client.InitialContextFactory
java.naming.provider.url=remote://localhost:4447

The following is an example of how to specify the remote naming properties in the client code in JBoss EAP 7.

java.naming.factory.initial=org.wildfly.naming.client.WildFlyInitialContextFactory
java.naming.provider.url=http-remoting://localhost:8080

java.naming.factory.initial=org.wildfly.naming.client.WildFlyInitialContextFactory
java.naming.provider.url=http-remoting://localhost:8080

JBoss EAP 7.0 is included with JBoss Enterprise Java Beans client 2.1.4, JBoss EAP 7.1 and later was included with JBoss Enterprise Java Beans client 4.0.x, which includes a number of changes to the API.

If you created a custom authenticator valve that extended AuthenticatorBase in JBoss EAP 6.4, you must manually replace it with a custom HTTP authentication implementation in JBoss EAP 7. The HTTP authentication mechanism is created in the elytron subsystem and then registered with the undertow subsystem. For information about how to implement a custom HTTP authentication mechanism, see Developing a Custom HTTP Mechanism in the JBoss EAP 7.4 Development Guide.

PicketLink has been removed from JBoss EAP 8.0.

PicketLink SP

Use Keycloak SAML adapter instead of the PicketLink service provider.

To migrate from PicketLink by configuring the Keycloak SAML adapter, perform the following tasks:

PicketLink IDP

PicketLink IDP is not available since JBoss EAP 8.0 and you can configure Red Hat build of Keycloak instead. For more information, see Configuring Red Hat build of Keycloak.

PicketLink STS

In previous releases, you could configure PicketLink STS as an alternative to the Apache CXF Security Token Service implementation. PicketLink STS configuration involved a legacy security domain. Any references to legacy security domains and PicketLink in the STS application needs to be removed, so you must configure Apache CXF STS instead.

For more information on how to configure Apache CXF STS, see Security Token Service (STS) in the JBoss EAP 7.4 Developing Web Services Applications.

Vaults has been removed from JBoss EAP 8.0. If your applications use legacy vault expressions, you must migrate and use Elytron encrypted expressions.

Check for instances of ${VAULT:: in your deployment files, which could be in annotations or deployment descriptors, and replace them with the corresponding encrypted expressions.

The Keycloak OIDC client adapter is not supported in JBoss EAP 8.0 and is replaced by the native Elytron OIDC client, providing similar functionality and configuration.

To migrate from the Keycloak OIDC client adapter to the native Elytron OIDC client, follow these steps:

In JBoss EAP 8.0, the legacy security subsystem has been removed. To continue using your custom login modules with the elytron subsystem, use the new Java Authentication and Authorization Service (JAAS) security realm and jaas-realm.

There are a few noticeable differences between JBoss EAP 7.2 or higher and earlier versions:

The following list describes some of the new clustering features to be aware of when migrating your application from JBoss EAP 6 to JBoss EAP 8.0.

JBoss EAP 7 introduces a new web session clustering implementation. It replaces the previous implementation, which was tightly coupled to the legacy JBoss Web subsystem source code.

The new web session clustering implementation impacts how the application is configured in the jboss-web.xml JBoss EAP proprietary web application XML descriptor file. The following are the only clustering configuration elements that remain in this file.

<jboss-web>
  ...
  <max-active-sessions>...</max-active-sessions>
  ...
  <replication-config>
    <replication-granularity>...</replication-granularity>
    <cache-name>...</cache-name>
  </replication-config>
  ...
</jboss-web>

<jboss-web>
  ...
  <max-active-sessions>...</max-active-sessions>
  ...
  <replication-config>
    <replication-granularity>...</replication-granularity>
    <cache-name>...</cache-name>
  </replication-config>
  ...
</jboss-web>

The distributable-web subsystem deprecates the <replication-config> element of jboss-web.xml. It enhances the usage of <replication-config> by generating an ad hoc distributable web session profile.

You can override the default distributable session management behavior by referencing a session management profile by name or by providing a deployment-specific session management configuration. For more information, see Overriding the default distributable session management behavior.

The following table describes how to achieve similar behavior for elements in the jboss-web.xml file that are now obsolete.

This new implementation also supports write-through cache stores as well as passivation-only cache stores. Typically, a write-through cache store is used in conjunction with an invalidation cache. The web session clustering implementation in JBoss EAP 6 did not operate correctly when used with an invalidation cache.

You can override the default distributable session management behavior in one of the following ways:

Referencing an existing session management profile

/WEB-INF/distributable-web.xml

<?xml version="1.0" encoding="UTF-8"?>
<distributable-web xmlns="urn:jboss:distributable-web:1.0">
    <session-management name="foo"/>
</distributable-web>

<?xml version="1.0" encoding="UTF-8"?>
<distributable-web xmlns="urn:jboss:distributable-web:1.0">
    <session-management name="foo"/>
</distributable-web>

/META-INF/jboss-all.xml

<?xml version="1.0" encoding="UTF-8"?>
<jboss xmlns="urn:jboss:1.0">
    <distributable-web xmlns="urn:jboss:distributable-web:1.0">
        <session-management name="foo"/>
    </distributable-web>
</jboss>

<?xml version="1.0" encoding="UTF-8"?>
<jboss xmlns="urn:jboss:1.0">
    <distributable-web xmlns="urn:jboss:distributable-web:1.0">
        <session-management name="foo"/>
    </distributable-web>
</jboss>

Using a Deployment-specific Session Management Profile

If only a single web application uses the custom session management configuration, you can define the configuration within the deployment descriptor itself. Ad hoc configuration looks identical to the configuration used by the distributable-web subsystem.

/WEB-INF/distributable-web.xml

<?xml version="1.0" encoding="UTF-8"?>
<distributable-web xmlns="urn:jboss:distributable-web:1.0">
    <infinispan-session-management cache-container="foo" cache="bar" granularity="SESSION">
        <primary-owner-affinity/>
    </infinispan-session-management>
</distributable-web>

<?xml version="1.0" encoding="UTF-8"?>
<distributable-web xmlns="urn:jboss:distributable-web:1.0">
    <infinispan-session-management cache-container="foo" cache="bar" granularity="SESSION">
        <primary-owner-affinity/>
    </infinispan-session-management>
</distributable-web>

/META-INF/jboss-all.xml

<?xml version="1.0" encoding="UTF-8"?>
<jboss xmlns="urn:jboss:1.0">
    <distributable-web xmlns="urn:jboss:distributable-web:1.0">
        <infinispan-session-management cache-container="foo" cache="bar" granularity="ATTRIBUTE">
            <local-affinity/>
        </infinispan-session-management>
    </distributable-web>
</jboss>

<?xml version="1.0" encoding="UTF-8"?>
<jboss xmlns="urn:jboss:1.0">
    <distributable-web xmlns="urn:jboss:distributable-web:1.0">
        <infinispan-session-management cache-container="foo" cache="bar" granularity="ATTRIBUTE">
            <local-affinity/>
        </infinispan-session-management>
    </distributable-web>
</jboss>

In JBoss EAP 6, you were required to enabled the clustering behavior for stateful session beans (SFSBs) in one of the following ways:

Starting with JBoss EAP 7, you no longer need to enable the clustering behavior. By default, if the server is started using an HA profile, the state of SFSBs will be replicated automatically. You can disable this default behavior in one of the following ways:

In JBoss EAP 6, the APIs for clustering services were in private modules and were not supported.

JBoss EAP 7 introduces a public clustering services API for use by applications. The new services are designed to be lightweight, easily injectable, and require no external dependencies.

These services replace similar APIs that were available in previous releases, namely HAPartition from JBoss EAP 5 and GroupCommunicationService, GroupMembershipNotifier, and GroupRpcDispatcher in JBoss EAP 6.

For more information, see Public API for Clustering Services in the JBoss EAP 7.4 Development Guide.

In JBoss EAP 6, there was no public API available for the cluster-wide HA singleton service. If you used the private org.jboss.as.clustering.singleton.* classes, you must change your code to use the new public org.wildfly.clustering.singleton.* packages when you migrate your application to JBoss EAP 8.

For more information about HA singleton services, see HA Singleton Service in the JBoss EAP 7.4 Development Guide. For information about HA singleton deployments, see HA Singleton Deployments in the JBoss EAP 7.4 Development Guide.

IBM MQ is the Messaging Oriented Middleware (MOM) product offering from IBM that allows applications on distributed systems to communicate with each other. This is accomplished through the use of messages and message queues. IBM MQ is responsible for delivering messages to the message queues and for transferring data to other queue managers using message channels. For more information about IBM MQ, see IBM MQ on the IBM products website.

Summary

IBM MQ can be configured as an external Java Message Service provider for JBoss EAP 8.0. This section covers the steps to deploy and configure the IBM MQ resource adapter in JBoss EAP. This deployment and configuration can be accomplished by using the management CLI tool or the web-based management console. See JBoss EAP supported configurations for the most current information about the supported configurations of IBM MQ.

JBoss EAP  8.0 is a Jakarta EE 10 implementation, so the packages used for all EE APIs have changed from javax to jakarta, which requires a Jakarta EE 10 compliant resource adapter. If you were using the IBM MQ Resource adapter in JBoss EAP  7.x or earlier, you must use wmq.jakarta.jmsra.rar, the IBM MQ Resource Adapter that uses this jakarta namespace.

@ActivationConfigProperty(propertyName = "destination", propertyValue = "QUEUE")

@ActivationConfigProperty(propertyName = "destination", propertyValue = "QUEUE")

@JMSConnectionFactoryDefinition(
    name = "java:/jms/WMQConnectionFactory",
    interfaceName = "javax.jms.ConnectionFactory",
    resourceAdapter = "wmq.jmsra",
    properties = {
        "channel=<channel>",
        "hostName=<hostname_wmq_broker>",
        "transportType=<transport_type>",
        "queueManager=<queue_manager>"
    }
)

@JMSConnectionFactoryDefinition(
    name = "java:/jms/WMQConnectionFactory",
    interfaceName = "javax.jms.ConnectionFactory",
    resourceAdapter = "wmq.jmsra",
    properties = {
        "channel=<channel>",
        "hostName=<hostname_wmq_broker>",
        "transportType=<transport_type>",
        "queueManager=<queue_manager>"
    }
)

@Inject
@JMSConnectionFactory("jms/CF")
@JMSPasswordCredential(userName="myusername", password="mypassword")
@JMSSessionMode(JMSContext.DUPS_OK_ACKNOWLEDGE)
transient JMSContext context3;

@Inject
@JMSConnectionFactory("jms/CF")
@JMSPasswordCredential(userName="myusername", password="mypassword")
@JMSSessionMode(JMSContext.DUPS_OK_ACKNOWLEDGE)
transient JMSContext context3;

WARN  [org.jboss.jca.core.connectionmanager.pool.strategy.PoolByCri] (EJB default - 7) IJ000604: Throwable while attempting to get a new connection: null: com.ibm.mq.connector.DetailedResourceException: MQJCA1011: Failed to allocate a JMS connection., error code: MQJCA1011 An internal error caused an attempt to allocate a connection to fail. See the linked exception for details of the failure.

WARN  [org.jboss.jca.core.connectionmanager.pool.strategy.PoolByCri] (EJB default - 7) IJ000604: Throwable while attempting to get a new connection: null: com.ibm.mq.connector.DetailedResourceException: MQJCA1011: Failed to allocate a JMS connection., error code: MQJCA1011 An internal error caused an attempt to allocate a connection to fail. See the linked exception for details of the failure.

QueueConnection qc = queueConnectionFactory.createQueueConnection("invalidUserName", "invalidPassword");

QueueConnection qc = queueConnectionFactory.createQueueConnection("invalidUserName", "invalidPassword");

SVR-ERROR: Expected JMSException, received com.ibm.mq.connector.outbound.MQQueueProxy cannot be cast to com.ibm.mq.jms.MQDestination

SVR-ERROR: Expected JMSException, received com.ibm.mq.connector.outbound.MQQueueProxy cannot be cast to com.ibm.mq.jms.MQDestination

ERROR [io.undertow.request] (default task-1) UT005023: Exception handling request to /jmsServlet-1.0-SNAPSHOT/: com.ibm.msg.client.jms.DetailedJMSRuntimeException: MQJCA0002: An exception occurred in the IBM MQ layer. See the linked exception for details.
A call to IBM MQ classes for Java(tm) caused an exception to be thrown.

ERROR [io.undertow.request] (default task-1) UT005023: Exception handling request to /jmsServlet-1.0-SNAPSHOT/: com.ibm.msg.client.jms.DetailedJMSRuntimeException: MQJCA0002: An exception occurred in the IBM MQ layer. See the linked exception for details.
A call to IBM MQ classes for Java(tm) caused an exception to be thrown.

SVR-ERROR: com.ibm.msg.client.jms.DetailedJMSException: JMSWMQ2007: Failed to send a message to destination 'MDB_NAME TOPIC_NAME'

SVR-ERROR: com.ibm.msg.client.jms.DetailedJMSException: JMSWMQ2007: Failed to send a message to destination 'MDB_NAME TOPIC_NAME'

com.ibm.mq.MQException: JMSCMQ0001: IBM MQ call failed with compcode '2' ('MQCC_FAILED') reason '2072' ('MQRC_SYNCPOINT_NOT_AVAILABLE')

com.ibm.mq.MQException: JMSCMQ0001: IBM MQ call failed with compcode '2' ('MQCC_FAILED') reason '2072' ('MQRC_SYNCPOINT_NOT_AVAILABLE')

Starting with JBoss EAP 8, support for Apache Log4j version 1 APIs has been stopped. Any application that is not packaging log4j.jar and log4j configuration must be updated.

Impact:

Log messages will no longer be routed based on the logging subsystem. If an application is not packaging log4j.jar and any of the following statements are true, then migration changes are required:

Migration:

OR

Additional Details:

<jboss-deployment-structure xmlns="urn:jboss:deployment-structure:1.2">
  <deployment>
    <exclude-subsystems>
      <subsystem name="logging"/>
    </exclude-subsystems>
  </deployment>
</jboss-deployment-structure>

<jboss-deployment-structure xmlns="urn:jboss:deployment-structure:1.2">
  <deployment>
    <exclude-subsystems>
      <subsystem name="logging"/>
    </exclude-subsystems>
  </deployment>
</jboss-deployment-structure>

<jboss-deployment-structure xmlns="urn:jboss:deployment-structure:1.2">
  <sub-deployment name="example.war">
    <exclude-subsystems>
      <subsystem name="logging"/>
    </exclude-subsystems>
  </sub-deployment>
</jboss-deployment-structure>

<jboss-deployment-structure xmlns="urn:jboss:deployment-structure:1.2">
  <sub-deployment name="example.war">
    <exclude-subsystems>
      <subsystem name="logging"/>
    </exclude-subsystems>
  </sub-deployment>
</jboss-deployment-structure>

<subsystem xmlns="urn:jboss:domain:logging:8.0">
    <add-logging-api-dependencies value="false"/>
  ...
</subsystem>

<subsystem xmlns="urn:jboss:domain:logging:8.0">
    <add-logging-api-dependencies value="false"/>
  ...
</subsystem>

For more information, see Apache Log4j version 1 is no longer provided in JBoss EAP 8.0.