Chapter 5. Application Migration Changes

5.1. Web Services Application Changes

JBossWS 5 brings new features and performance improvements to JBoss EAP 7 web services, mainly through upgrades of the Apache CXF, Apache WSS4J, and Apache Santuario components.

5.1.1. JAX-RPC Support Changes

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

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

  • The presence of a JAX-RPC mapping file, which is an XML file with the root element <java-wsdl-mapping>.
  • The presence of a webservices.xml XML descriptor file that contains a <webservice-description> element, which includes a <jaxrpc-mapping-file> child element. The following is an example of webservices.xml descriptor file that defines a JAX-RPC web service.

    <webservices xmlns="http://java.sun.com/xml/ns/j2ee"
          xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
          xsi:schemaLocation="http://java.sun.com/xml/ns/j2ee http://www.ibm.com/webservices/xsd/j2ee_web_services_1_1.xsd" version="1.1">
      <webservice-description>
        <webservice-description-name>HelloService</webservice-description-name>
        <wsdl-file>WEB-INF/wsdl/HelloService.wsdl</wsdl-file>
        <jaxrpc-mapping-file>WEB-INF/mapping.xml</jaxrpc-mapping-file>
        <port-component>
          <port-component-name>Hello</port-component-name>
          <wsdl-port>HelloPort</wsdl-port>
          <service-endpoint-interface>org.jboss.chap12.hello.Hello</service-endpoint-interface>
          <service-impl-bean>
            <servlet-link>HelloWorldServlet</servlet-link>
          </service-impl-bean>
        </port-component>
      </webservice-description>
    </webservices>
  • The presence of an ejb-jar.xml file, which contains a <service-ref> that references a JAX-RPC mapping file.

5.1.2. Apache CXF Spring Web Services Changes

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

Apache CXF Interceptors

The JBossWS descriptor provides new configuration options that allow you to declare the interceptors without modifying the client endpoint code. Instead you declare interceptors within predefined client and endpoint configurations by specifying a list of interceptor class names for the cxf.interceptors.in and cxf.interceptors.out properties.

The following is an example of a jaxws-endpoint-config.xml file that declares interceptors using these properties.

<?xml version="1.0" encoding="UTF-8"?>
<jaxws-config xmlns="urn:jboss:jbossws-jaxws-config:4.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:javaee="http://java.sun.com/xml/ns/javaee"
  xsi:schemaLocation="urn:jboss:jbossws-jaxws-config:4.0 schema/jbossws-jaxws-config_4_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>
Apache CXF Features

The JBossWS descriptor allows you to declare features within predefined client and endpoint configurations by specifying a list of feature class names for the cxf.features property.

The following is an example of a jaxws-endpoint-config.xml file that declares a feature using this property.

<?xml version="1.0" encoding="UTF-8"?>
<jaxws-config xmlns="urn:jboss:jbossws-jaxws-config:4.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:javaee="http://java.sun.com/xml/ns/javaee"
  xsi:schemaLocation="urn:jboss:jbossws-jaxws-config:4.0 schema/jbossws-jaxws-config_4_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>
Apache CXF HTTP Transport

In Apache CXF, HTTP transport configuration is achieved by specifying org.apache.cxf.transport.http.HTTPConduit options. JBossWS integration allows conduits to be modified programmatically using the Apache CXF API as follows.

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);
...

You can also control and override the Apache CXF HTTPConduit default values by setting system properties.

PropertyTypeDescription

cxf.client.allowChunking

Boolean

Specifies whether to send requests using chunking.

cxf.client.chunkingThreshold

Integer

Sets the threshold at which switching from non-chunking to chunking mode.

cxf.client.connectionTimeout

Long

Sets the number of milliseconds for the connection timeout.

cxf.client.receiveTimeout

Long

Sets the number of milliseconds for the receive timeout.

cxf.client.connection

String

Specifies whether to use the Keep-Alive or close connection type.

cxf.tls-client.disableCNCheck

Boolean

Specifies whether to disable the CN host name check.

5.1.3. WS-Security Changes

  • If your application contains a custom callback handler that accesses the org.apache.ws.security.WSPasswordCallback class, be aware that this class has moved to package org.apache.wss4j.common.ext.
  • Most of the SAML bean objects from the org.apache.ws.security.saml.ext package have been moved to the org.apache.wss4j.common.saml package.
  • Use the RSA v1.5 key transport and all related algorithms are disallowed by default.
  • The Security Token Service (STS) previously only validated onBehalfOf tokens. It now also validates ActAs tokens. As a consequence, a valid username and password must be specified in the UsernameToken that is provided for the ActAs token.
  • SAML Bearer tokens are now required to have an internal signature. The org.apache.wss4j.dom.validate.SamlAssertionValidator class now has a setRequireBearerSignature() method to enable or disable the signature verification.

5.1.4. JBoss Modules Structure Change

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.

5.1.5. Bouncy Castle Requirements and Changes

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.

JBoss EAP 7 ships with the org.bouncycastle module and JBossWS is now 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.49, 1.51, or greater.

5.1.6. Apache CXF Bus Selection Strategy

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.

  • Boot the JBoss EAP server with the system property org.jboss.ws.cxf.jaxws-client.bus.strategy value set to THREAD_BUS.
  • Explicitly set the selection strategy in the client code.

5.1.7. JAX-WS 2.2 Requirements for WebServiceRef

Containers must use JAX-WS 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. JBoss EAP 7 ships with JBossWS 5, which no longer hides this requirement. This means that user provided service classes injected by the container must implement JAX-WS 2.2 or later by updating the existing code to use the javax.xml.ws.Service constructor that includes one or more WebServiceFeature arguments.

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

5.1.8. IgnoreHttpsHost CN Check Change

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.

5.1.9. Server Side Configuration and Class Loading

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

5.1.10. Deprecation of Java Endorsed Standards Override Mechanism

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.

If your application uses the JBossWS implementation of Apache CXF, JBoss EAP 7 ensures 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.

5.1.11. Specification of Descriptor in EAR Archive

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

In JBoss EAP 7, you can now 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 both 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.

5.2. Update the Remote URL Connector and Port

In JBoss EAP 7, the default connector has changed from remote to http-remoting and the default remote connection port has changed from 4447 to 8080. The JNDI provider URL for the default configuration has changed from remote://localhost:4447 to http-remoting://localhost:8080.

If you use the JBoss EAP 7 migrate operation to update your configuration, you do not need to modify the remote connector, remote port, or JNDI provider URLs because the migration operation preserves the JBoss EAP 6 remoting connector and 4447 port configuration settings in the subsystem configuration. For more information about the migrate operation, see Management CLI Migration Operation.

If you do not use the migrate operation and instead run with the new JBoss EAP 7 default configuration, you must change the remote connector, remote port, and JNDI provider URL to use the new settings as described above.

5.3. Messaging Application Changes

5.3.1. Replace or Update JMS Deployment Descriptors

The proprietary HornetQ JMS resource deployment descriptor files identified by the naming pattern -jms.xml no longer work in JBoss EAP 7. The following is an example of a JMS 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>

If you used -jms.xml JMS deployment descriptors in your application in the previous release, you can either convert your application to use the standard Java EE deployment descriptor as specified in section EE.5.18 of the Java EE 7 specification 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.

  • Change the namespace from "urn:jboss:messaging-deployment:1.0" to "urn:jboss:messaging-activemq-deployment:1.0".
  • Change the <hornetq-server> element name to <server>.

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>

For information about server configuration changes related to messaging, see Messaging Server Configuration Changes.

5.3.2. Update External JMS Clients

JBoss EAP 7 still supports the JMS 1.1 API, so you do not need to modify your code.

The default remote connector and port has changed in JBoss EAP 7. For details about this change, see Update the Remote URL Connector and Port.

If you migrate your server configuration using the migrate operation, the old settings are preserved and you do not need to update your PROVIDER_URL. However, if you run with the new JBoss EAP 7 default configuration, you must change the PROVIDER_URL in the client code to use the new http-remoting://localhost:8080 setting. For more information, see Migrate Remote Naming Client Code.

If you plan to migrate your code to use the JMS 2.0 API, see the helloworld-jms quickstart for a working example.

5.3.3. Replace the HornetQ API

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.

5.3.4. Replace Deprecated Address Setting Attributes

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.

Note

The deprecated attributes no longer configure this functionality in JBoss EAP 7.2 and do not take effect. The replacement attributes are not supported either. They are provided only as a way to migrate on the best effort basis.

Deprecated AttributeReplacement Attribute

auto-create-jms-queues

auto-create-queues

auto-delete-jms-queues

auto-delete-queues

auto-create-jms-topics

auto-create-addresses

auto-delete-jms-topics

auto-delete-addresses

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

5.3.5. Messaging Application Changes Required for JBoss EAP 7.2

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>

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

5.4. JAX-RS and RESTEasy Application Changes

JBoss EAP 6 bundled RESTEasy 2, which was an implementation of JAX-RS 1.x.

JBoss EAP 7.0 and JBoss EAP 7.1 included RESTEasy 3.0.x, which is an implementation of JAX-RS 2.0 as defined by the JSR 339: JAX-RS 2.0: The Java API for RESTful Web Services specification. For more information about the Java API for RESTful Web Services, see the JAX-RS 2.0 API Specification.

JBoss EAP 7.2 includes RESTEasy 3.6.1, which is an implementation of JAX-RS 2.1 as defined by the JSR 370: Java(TM )API for RESTful Web Services (JAX-RS 2.1) Specification. This release also adds support for JDK 11. While providing some of the RESTEasy 4 key features, this release is based on RESTEasy 3.0, ensuring full backward compatibility. As a result, you should encounter few issues when migrating from RESTEasy 3.0.x to 3.6.1. For more information about the Java API for RESTEasy 3.6.1, see RESTEasy JAX-RS 3.6.1.Final API.

If you are migrating from JBoss EAP 6.4, be aware that the version of Jackson included in JBoss EAP has changed. JBoss EAP 6.4 included Jackson 1.9.9. JBoss EAP 7 and later now include Jackson 2.6.3 or greater.

This section describes how these changes might impact applications that use RESTEasy or JAX-RS.

5.4.1. RESTEasy Deprecated Classes

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 JAX-RS compliant interceptor facility in RESTEasy 3.x. The relevant interfaces are defined in the javax.ws.rs.ext package of the jaxrs-api module.

Note

All interceptors from the previous release of RESTEasy can run in parallel with the new JAX-RS filter and interceptor interfaces.

For more information about interceptors, see RESTEasy Interceptors in Developing Web Services Applications for JBoss EAP.

For more information about the new replacement API, see the RESTEasy JAX-RS 3.6.1.Final API.

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.

Note

For more information about the org.jboss.resteasy.client.jaxrs API classes, see the RESTEasy JAX-RS JavaDoc.

StringConverter

The org.jboss.resteasy.spi.StringConverter class is deprecated in RESTEasy 3.x. This functionality can be replaced using the JAX-RS jax.ws.rs.ext.ParamConverterProvider class.

5.4.2. Removed or Protected RESTEasy Classes

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 JAX-RS method should be cached on the server, was removed from RESTEasy 3 and must be removed from the application code.

5.4.3. Additional RESTEasy Changes

SignedInput and SignedOuput
  • SignedInput and SignedOutput for resteasy-crypto must have the Content-Type set to multipart/signed in either the Request or Response object, or by using the @Consumes or @Produces annotation.
  • SignedOutput and SignedInput can be used to return the application/pkcs7-signature MIME type format in binary form by setting that type in the @Produces or @Consumes annotations.
  • If the @Produces or @Consumes is text/plain MIME type, SignedOutput will be base64 encoded and sent as a String.
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 Developing Web Services Applications for JBoss EAP.

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 Developing Web Services Applications for JBoss EAP.

SerializableProvider

Deserializing Java objects from untrusted sources is not safe. For this reason, in 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();
    }
}
Resource Method Algorithm Switch

A bug discovered in the resource method matching algorithm used in RESTEasy 3.0.x versions prior to 3.0.25.Final caused RESTEasy to return too many resource methods when responding to requests.

There are three stages in the matching algorithm:

  1. Use the request path to choose possible resource classes.
  2. Use the request path to choose possible resource methods.
  3. Use the HTTP verb and media types, coming and going, to choose a final resource method.

According to the JAX-RS 2.0 specification, after the set of potential resource methods is sorted, only the maximal elements should be passed on to step 3. However, RESTEasy 3.0.x implementations prior to RESTEasy 3.0.25 passed all methods to step 3. RESTEasy 3.0.24, which was included in JBoss EAP 7.1.0, exhibits this incorrect behavior.

RESTEasy 3.0.25, which is included in JBoss EAP 7.1.1, provides the fix to limit the methods passed to step 3 to be compliant with the JAX-RS 2.0 specification. Because the looser behavior might be preferable, RESTEasy 3.0.25 also introduces a context-param configuration option, resteasy.loose.step2.request.matching, which defaults to false, that can be configured to enable the old behavior.

If you update your JBoss EAP server from 7.1.0 to 7.1.1 and you want to keep the old behavior and pass all potential resource methods to step 3, set the resteasy.loose.step2.request.matching option to true.

The matching algorithm was changed in the JAX-RS 2.1 specification to pass all matching resource methods to step 3. RESTEasy 3.6.1, which is included in JBoss EAP 7.2, provides a jaxrs.2.0.request.matching option to to retain the stricter behavior as defined in the JAX-RS 2.0 specification.

If you migrate your application from JBoss EAP from 7.1.0 to 7.2.x, you should not see a change in the behavior of the resource method matching algorithm. If you migrate your application from JBoss EAP from 7.1.1 to 7.2.x and want to retain the stricter behavior as defined in the JAX-RS 2.0 specification, set the jaxrs.2.0.request.matching option to true.

5.4.4. RESTEasy SPI Changes

SPI Exceptions

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

Deprecated ExceptionReplacement Exception in jaxrs-api module

org.jboss.resteasy.spi.ForbiddenException

javax.ws.rs.ForbiddenException

org.jboss.resteasy.spi.MethodNotAllowedException

javax.ws.rs.NotAllowedException

org.jboss.resteasy.spi.NotAcceptableException

javax.ws.rs.NotAcceptableException

org.jboss.resteasy.spi.NotFoundException

javax.ws.rs.NotFoundException

org.jboss.resteasy.spi.UnauthorizedException

javax.ws.rs.NotAuthorizedException

org.jboss.resteasy.spi.UnsupportedMediaTypeException

javax.ws.rs.NotSupportedException

InjectorFactory and Registry

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

5.4.5. Jackson Provider Changes

The version of Jackson included in JBoss EAP has changed. The previous version of JBoss EAP included Jackson 1.9.9. JBoss EAP 7 now includes Jackson 2.6.3 or greater. As a result, 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.

To switch your application to use the default provider that was included in the previous release of JBoss EAP, see Switching the Default Jackson Provider in Developing Web Services Applications for JBoss EAP.

5.4.6. Spring RESTEasy Integration Changes

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.

5.4.7. RESTEasy Jettison JSON Provider Changes

The RESTEasy Jettison JSON provider is deprecated in 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>

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

5.5. CDI Application Changes

JBoss EAP 7.2 includes support for CDI 2.0. As a result, applications written using CDI 1.0 or CDI 1.2 might see some changes in behavior when migrating to JBoss EAP 7.2. This section summarizes only few of the changes made in CDI 1.2 and CDI 2.0.

You can find more information about Weld and CDI 2.0 in the following references:

Bean Archives

Bean classes of enabled beans must be deployed in bean archives to ensure they are scanned by CDI to find and process the bean classes.

In CDI 1.0, an archive was defined as an explicit bean archive if it contained a beans.xml file in the META-INF/ directory for an application client, EJB, or library JAR, or if it contained a beans.xml file in the WEB-INF/ directory for a WAR.

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.

A bean archive has a bean discovery mode of all, annotated or none. A bean archive that contains a beans.xml file with no version has a default bean discovery mode of all. A bean archive that contains a beans.xml file with version 1.1 or later 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:

  • It contains a beans.xml file with a bean-discovery-mode of none.
  • It contains a CDI extension with no beans.xml file.

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

  • The archive contains a beans.xml file with a version number of 1.1 or later and a bean-discovery-mode of all.
  • The archive contains a beans.xml file with no version number.
  • The archive contains an empty beans.xml file.

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

  • The archive contains one or more bean classes with a bean defining annotation, or one or more session beans, even if it does not contain a beans.xml file.
  • The archive contains a beans.xml file with a bean-discovery-mode of annotated.

CDI 1.2 limited bean defining annotations to the following:

  • @ApplicationScoped, @SessionScoped, @ConversationScoped, and @RequestScoped annotations
  • All other normal scope types
  • @Interceptor and @Decorator annotations
  • All stereotype annotations, which are annotations annotated with @Stereotype
  • @Dependent scope annotation

For more information about bean archives, see Bean Archives in JSR 365: Contexts and Dependency Injection for Java 2.0.

Clarification of Conversation Resolution

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 Java EE in JSR 365: Contexts and Dependency Injection for Java 2.0.

Observer Resolution

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 in JSR 365: Contexts and Dependency Injection for Java 2.0.

5.6. HTTP Session ID Change

The string returned by the request.getSession().getId() call to get the unique identifier assigned to an HTTP session has changed between JBoss EAP 6.4 and JBoss EAP 7.

JBoss EAP 6.4 returned both the session ID and the instance ID in the session-id.instance-id format.

JBoss EAP 7 returns only the session ID.

This change can create issues with routeless cookies for some upgrades from JBoss EAP 6 to JBoss EAP 7. If your application recreates JSESSIONID cookies based upon the return value from this method call, you might need to update the application code to provide the desired behavior.

5.7. Migrate Explicit Module Dependencies

The introduction of the modular class loading system and JBoss Modules in the previous release of JBoss EAP allowed for fine-grained control of the classes available to applications. This feature allowed you to configure explicit module dependencies using the application’s MANIFEST.MF file or the jboss-deployment-structure.xml deployment descriptor file.

If you defined explicit module dependencies in your application, you should be aware of the following changes in JBoss EAP 7.

Review Dependencies for Availability

The modules that are included in JBoss EAP have changed. When you migrate your application to JBoss EAP 7, review your MANIFEST.MF and jboss-deployment-structure.xml file entries to make sure they do not refer to any modules that were removed from this release of the product.

Dependencies That Require Annotation Scanning

In the previous release of JBoss EAP, if your dependency contained annotations that needed to be processed during annotation scanning, such as when declaring EJB Interceptors, you were required to generate and include a Jandex index in a new JAR file and then set a flag in the MANIFEST.MF or jboss-deployment-structure.xml deployment descriptor file.

JBoss EAP 7 now provides automatic runtime generation of annotation indexes for static modules, so you no longer need to generate them manually. However, you still need to add the annotations flag to the application’s MANIFEST.MF file or the jboss-deployment-structure.xml deployment descriptor file as demonstrated below.

Example: Annotation Flag in the MANIFEST.MF File

Dependencies: com.company.my-ejb annotations, com.company.other

Example: Annotation Flag in the jboss-deployment-structure.xml File

<jboss-deployment-structure>
  <deployment>
    <dependencies>
      <module name="com.company.my-ejb" annotations="true"/>
      <module name="com.company.other"/>
    </dependencies>
  </deployment>
</jboss-deployment-structure>

5.8. Hibernate and JPA Migration Changes

5.8.1. Hibernate ORM 3.0

The integration classes that made it easier to use Hibernate ORM 3 in JBoss EAP 6.4 were removed from JBoss EAP 7. If your application still uses Hibernate ORM 3 libraries, it is strongly recommended that you migrate your application to use Hibernate ORM 5 as Hibernate ORM 3 will no longer work in JBoss EAP without a lot of effort. If you can not migrate to Hibernate ORM 5, you must define a custom JBoss Module for the Hibernate ORM 3 JARs and exclude the Hibernate ORM 5 classes from your application.

5.8.2. Hibernate ORM 4.0 - 4.3

If your application needs second-level cache enabled, be aware that Infinispan 8.x was integrated with Hibernate ORM 5.0. Support for using Infinispan as a Hibernate 2nd-level cache provider was then moved to the Infinispan project in Hibernate ORM 5.3, and as a result, the hibernate-infinispan module was dropped from that release.

Applications written with Hibernate ORM 4.x can still use Hibernate ORM 4.x. You must define a custom JBoss module for the Hibernate ORM 4.x JARs and exclude the Hibernate ORM 5 classes from your application. However, it is strongly recommended that you rewrite your application code to use Hibernate ORM 5. For information about migrating to Hibernate ORM 5, see Migrating to Hibernate ORM 5.

5.8.3. Migrating to Hibernate ORM 5

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
  • Built-in org.hibernate.type.descriptor.sql.SqlTypeDescriptor implementations no longer auto-register themselves with org.hibernate.type.descriptor.sql.SqlTypeDescriptorRegistry. Applications using custom SqlTypeDescriptor implementations that extend the built-in implementations and rely on that behavior must be updated to call SqlTypeDescriptorRegistry.addDescriptor() themselves.
  • For IDs defined as generated UUIDs, some databases require you to explicitly set the @Column(length=16) in order to generate BINARY(16) so that comparisons work properly.
  • For EnumType mappings defined in the hbm.xml, where you want javax.persistence.EnumType.STRING name-mapping, this configuration must be explicitly stated by using either the useNamed(true) setting or by specifying a VARCHAR value of 12.
Transaction Management
Other Hibernate ORM 5 Changes
  • The cfg.xml files are again fully parsed and integrated with events, security, and other functions.
  • The properties loaded from the cfg.xml using the EntityManagerFactory did not previously prefix names with hibernate. This has now been made consistent.
  • The configuration is no longer serializable.
  • The org.hibernate.dialect.Dialect.getQuerySequencesString() method now retrieves catalog, schema, and increment values.
  • The AuditConfiguration modifier was removed from org.hibernate.envers.boot.internal.EnversService.
  • The AuditStrategy method parameters were changed to remove the obsolete AuditConfiguration and use the new EnversService.
  • Various classes and interfaces in the org.hibernate.hql.spi package and subpackages have been moved to the new org.hibernate.hql.spi.id package. This includes the MultiTableBulkIdStrategy class and the AbstractTableBasedBulkIdHandler, TableBasedDeleteHandlerImpl, and TableBasedUpdateHandlerImpl interfaces and their subclasses.
  • There was a complete redesign of property access contracts.
  • Valid hibernate.cache.default_cache_concurrency_strategy setting values are now defined using the org.hibernate.cache.spi.access.AccessType.getExternalName() method rather than the org.hibernate.cache.spi.access.AccessType enum constants. This is more consistent with other Hibernate settings.

5.8.4. Migrating from Hibernate ORM 5.0 to Hibernate ORM 5.1

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 many performance improvements and bug fixes, which are detailed in Hibernate ORM 5.1 Features in the JBoss EAP 7.1.0 Release Notes. 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 mainly focused in the following areas:

  • Unifying the handling of hbm2ddl.auto and Hibernate’s JPA schema-generation support.
  • Removing JDBC concerns from the SPI to facilitate true replacement for Hibernate OGM, a persistence engine that provides Java Persistence (JPA) support for NoSQL data stores.

The schema management tooling changes should only be a migration concern for applications that directly use any of the following classes:

  • org.hibernate.tool.hbm2ddl.SchemaExport
  • org.hibernate.tool.hbm2ddl.SchemaUpdate
  • org.hibernate.tool.hbm2ddl.SchemaValidator
  • org.hibernate.tool.schema.spi.SchemaManagementTool, or any of its delegates
Schema Management Tooling Changes in JBoss EAP 7.1

Hibernate ORM 5.1.10 which is included in JBoss EAP 7.1, introduced a new strategy for retrieving database tables that improves 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, which executes 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.

5.8.5. Migrating from Hibernate ORM 5.1 to Hibernate ORM 5.3

JBoss EAP 7.2 includes Hibernate ORM 5.3. This section highlights some the changes needed when migrating from Hibernate ORM 5.1 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.

  • The hibernate-java8 module was merged into hibernate-core, and the Java 8 date/time datatypes are now natively supported.
  • The hibernate-entitymanager module was merged into hibernate-core. HibernateEntityManager and HibernateEntityManagerFactory are deprecated.
  • The Session, StatelessSession, and SessionFactory class hierarchies were refactored to remove deprecated classes and to better align with the JPA Metamodel API.
  • The SPIs in the org.hibernate.persister and org.hibernate.tuple packages have changed. Any custom classes using those SPIs will need to be reviewed and updated.
  • LimitHandler changes introduced a new hibernate.legacy_limit_handler setting, which is set to false by default, that is designed to allow you to enable the legacy Hibernate 4.3 limit handler behavior. This impacts a limited list of dialects.
  • A new strategy for retrieving database tables was introduced that improves SchemaMigrator and SchemaValidator performance.
  • This release changes how CLOB values for String, character[], and Character[] attributes that are annotated with @Lob are processed when using PostgreSQL81Dialect and its subclasses.
  • The scope of @TableGenerator and @SequenceGenerator names has changed from global to local.

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

Hibernate ORM 5.3 Features

Hibernate ORM 5.3 adds support for the JPA 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.

  • Changes to positional query parameter handling has resulted in the following changes:

    • Removal of support for JDBC-style parameter declarations in HQL/JPQL queries.
    • JPA positional parameters behave more like named parameters.
    • JDBC-style parameter declarations in native queries use one-based instead of zero-based parameter binding to be consistent with JPA. You can revert back to zero-based binding by setting the hibernate.query.sql.jdbc_style_params_base property to true.
  • To comply with the JPA specification, the sequence value stored by the @TableGenerator stored value is that last generated value. Previously, Hibernate stored the next sequence value. You can use the hibernate.id.generator.stored_last_used property to enable the legacy Hibernate behavior. Existing applications that use @TableGenerator and migrate to Hibernate 5.3 must set the hibernate.id.generator.stored_last_used configuration property to false.
  • The getType() method in the org.hibernate.query.QueryParameter class was renamed to getHibernateType().
  • Hibernate’s second-level cache SPI was redesigned to better meet the requirements of the various caching providers. Details can be found in HHH-11356.
  • Changes for HHH-11356 also required changes in consumers, which impacts the Hibernate Statistics system.
  • Some methods were temporarily added to the org.hibernate.Query class to make it easier to migrate native applications from Hibernate ORM 5.1 to 5.3 and maintain the Hibernate 5.1 pagination behavior. These methods are deprecated, and to be portable with future versions of Hibernate, applications should be updated to use the JPA methods.
  • Support for using Infinispan as a Hibernate 2nd-level cache provider has been moved to the Infinispan project. As a result, the hibernate-infinispan module has been dropped.
  • The API of the org.hibernate.tool.enhance.EnhancementTask Ant task was changed. The addFileset() method was dropped in favor of the setBase() and the setDir() methods. Details can be found in HHH-11795.
  • A bug introduced in Hibernate 4.3 caused many-to-one associations in embeddable collection elements and composite IDs to be eagerly fetched, even when explicitly mapped as lazy. In Hibernate 5.3.2, this bug was fixed. As a result, these associations are fetched as specified by their mappings. Details can be found in HHH-12687.
  • JPA and native implementations of Hibernate event listeners were unified in this release. As a result, the JpaIntegrator class is obsolete. Classes that extend org.hibernate.jpa.event.spi.JpaIntegrator must be modified to have to change these classes to implement the org.hibernate.integrator.spi.Integrator interface. Details can be found in HHH-11264.
  • The SPIs in the org.hibernate.persister package have changed. Any custom classes using those SPIs will need to be reviewed and updated.

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

5.8.5.1. 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 JPA 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 JPA specification. This setting is ignored for a SessionFactory built using JPA bootstrapping.

5.8.5.2. Compatibility Transformer

JBoss EAP 7.2 incudes 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.2. This is a temporary solution and you should replace these method calls with the recommended JPA method calls.

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

  • You can enable the transformer globally for all applications by setting the Hibernate51CompatibilityTransformer system property to true.
  • You can use the jboss-deployment-structure.xml file to enable the transformer at the application level.

    <jboss-deployment-structure>
      <deployment>
        <transformers>
          <transformer class="org.jboss.as.hibernate.Hibernate51CompatibilityTransformer"/>
        </transformers>
      </deployment>
      <sub-deployment name="main.war">
        <transformers>
          <transformer class="org.jboss.as.hibernate.Hibernate51CompatibilityTransformer"/>
        </transformers>
      </sub-deployment>
    </jboss-deployment-structure>

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

5.9. Hibernate Search Changes

The version of Hibernate Search that ships with JBoss EAP 7 has changed. The previous release of JBoss EAP shipped with Hibernate Search 4.6.x. JBoss EAP 7 ships with Hibernate Search 5.5.x.

Hibernate Search 5.5 is built upon Apache Lucene 5.3.1. If you use any native Lucene APIs, be sure to align with this version. The Hibernate Search 5.5 API wraps and hides the complexity of many of the Lucene API changes made between version 3 and version 5; however, some classes are now deprecated, renamed, or repackaged. This section describes how these changes might impact your application code.

Hibernate Search Mapping Changes

Indexing of id Fields of Embedded Relations

When using an @IndexedEmbedded annotation to include fields from a related entity, the id of the related entity is no longer included. You can enable the inclusion of the id by using the includeEmbeddedObjectId attribute of the @IndexedEmbedded annotation.

Example: @IndexedEmbedded Annotation

@IndexedEmbedded(includeEmbeddedObjectId=true)

Number and Date Index Formatting Changes

Numbers and dates are now indexed as numeric fields by default. Properties of type int, long, float, double, and their corresponding wrapper classes are no longer indexed as strings. Instead, they are now indexed using Lucene’s appropriate numeric encoding. The id fields are an exception to this rule. Even when they are represented by a numeric type, they are still indexed as a string keyword by default. The use of @NumericField is now obsolete unless you want to specify a custom precision for the numeric encoding. You can keep the old string-based index format by explicitly specifying a string encoding field bridge. In the case of integers, this is the org.hibernate.search.bridge.builtin.IntegerBridge. Check the org.hibernate.search.bridge.builtin package for other publicly available field bridges.

Date and Calendar are no longer indexed as strings. Instead, instances are encoded as long values representing the number of milliseconds since January 1, 1970, 00:00:00 GMT. You can switch the indexing format by using the new EncodingType enum. For example:

Example: @DateBridge and @CalendarBridge Annotation

@DateBridge(encoding=EncodingType.STRING)
@CalendarBridge(encoding=EncodingType.STRING)

The encoding change for numbers and dates is important and can have a big impact on application behavior. If you have a query that targets a field that was previously string-encoded, but is now encoded numerically, you must update the query. Numeric fields must be searched with a NumericRangeQuery. You must also make sure that all fields targeted by faceting are string encoded. If you use the Search query DSL, the correct query should be created automatically for you.

Miscellaneous Hibernate Search Changes

  • Sorting options have improved and field encoding specified incorrectly for sorting options now results in runtime exceptions. Lucene also offers more performant sorting if the fields used in the sort are known up front. Hibernate Search 5.5 provides the new @SortableField annotation and its multi-valued companion @SortableFields. See the Migration Guide from Hibernate Search 5.4 to 5.5 for more information.
  • The Lucene SortField API requires the following application code change.

    In the previous release of JBoss EAP, you set the type of the sort field in the query as follows.

    fulltextQuery.setSort(new Sort(new SortField("title", SortField.STRING)));

    The following is an example of how you set it in JBoss EAP 7.

    fulltextQuery.setSort(new Sort(new SortField("title", SortField.Type.STRING)));
  • Since SearchFactory should only be used by ORM integration, it was moved from the hibernate-search-engine module to the hibernate-search-orm module. Other integrators should depend exclusively on SearchIntegrator, which replaces the deprecated SearchFactoryIntegrator.
  • The enum value SpatialMode.GRID was renamed to SpatialMode.HASH.
  • FullTextIndexEventListener is now a final class. If you currently extend this class, you must find an alternate solution to achieve the same functionality.
  • The hibernate-search-analyzers module was removed. The recommended approach is to directly use the appropriate Lucene artifact, for example org.apache.lucene:lucene-analyzers-common.
  • The JMS controller API has changed. The JMS back-end dependency on Hibernate ORM was removed so that it could be used in other non-ORM environments. A consequence is that implementors of org.hibernate.search.backend.impl.jms.AbstractJMSHibernateSearchController must adjust to the new signature. This class is an internal class and it is recommended to use it as an example instead of extending it.
  • The org.hibernate.search.spi.ServiceProvider SPI was refactored. If you were integrating with the old service contract, refer to the Hibernate Search 5.5 Javadoc of ServiceManager, Service, Startable and Stoppable for details about the new contract.
  • If you have kept indexes generated by Lucene 3.x and have not rebuilt them with Hibernate Search 5.0 or later, you will get an IndexFormatTooOldException. It is recommended that you rebuild the indexes with the mass indexer. If you are not able to do that, try to use Lucene’s IndexUpgrader. You must carefully update the Hibernate Search mappings in case the default behavior has changed. For more information, see the Apache Lucene Migration Guide.
  • Apache Lucene was upgraded from 3.6 to 5.3 in JBoss EAP 7. If your code imports Lucene code directly, see the Apache Lucene Migration Guide for details of the changes. Additional information can also be found in the Lucene Change Log.
  • When using @Field(indexNullAs=) to encode a null marker value in the index, the type of the marker must be compatible with all other values that are indexed in that same field. For example, it was previously possible to encode a null value for numeric fields using a string "null". This is no longer allowed. Instead, you must choose a number to represent the null value, such as -1.
  • Significant improvements were made to the faceting engine. Most of the changes do not affect the API. The one notable exception is that you must now annotate any fields you intend to use for faceting with the @Facet or @Facets annotation.

Hibernate Search Renamed and Repackaged Classes

The following is a list of Hibernate Search classes that were repackaged or renamed.

Previous Package and ClassNew Package and Class

org.hibernate.search.Environment

org.hibernate.search.cfg.Environment

org.hibernate.search.FullTextFilter

org.hibernate.search.filter.FullTextFilter

org.hibernate.search.ProjectionConstants

org.hibernate.search.engine.ProjectionConstants

org.hibernate.search.SearchException

org.hibernate.search.exception.SearchException

org.hibernate.search.Version

org.hibernate.search.engine.Version

Lucene - Renamed and Repackaged Classes

Query parsers were moved to a new module, resulting in a packaging change from org.apache.lucene.queryParser.QueryParser to org.apache.lucene.queryparser.classic.QueryParser.

Many of the Lucene analyzers were refactored, resulting in packaging changes. See the Apache Lucene Documentation to find the replacement packages.

Some Apache Solr utility classes, for example TokenizerFactory or TokenFilterFactory, were moved into Apache Lucene. If your application uses those utilities or custom analyzers, you must find the new package name in Apache Lucene.

See the Apache Lucene Migration Guide for more information.

Hibernate Search Deprecated APIs

For the complete list of Hibernate Search deprecated interfaces, classes, enums, annotation types, methods, constructors, and enum constants, see the Hibernate Search Deprecated API document.

Hibernate Search Deprecated Interfaces
InterfaceDescription

org.hibernate.search.store.IndexShardingStrategy

Deprecated as of Hibernate Search 4.4. Might be removed in Search 5. Use ShardIdentifierProvider instead.

org.hibernate.search.store.Workspace

This interface will be moved and should be considered non-public API. For more information, see HSEARCH-1915.

Hibernate Search Deprecated Classes
ClassDescription

org.hibernate.search.filter.FilterKey

Custom filter keys are deprecated and are scheduled for removal in Hibernate Search 6. As of Hibernate Search 5.1, keys for caching Lucene filters are calculated automatically based on the given filter parameters.

org.hibernate.search.filter.StandardFilterKey

Custom filter keys are deprecated and are scheduled for removal in Hibernate Search 6. As of Hibernate Search 5.1, keys for caching Lucene filters are calculated automatically based on the given filter parameters.

Hibernate Search Deprecated Enums
EnumDescription

org.hibernate.search.annotations.FieldCacheType

Remove the CacheFromIndex annotation as it is deprecated. See Hibernate Search Deprecated Annotations.

Hibernate Search Deprecated Annotations
AnnotationDescription

org.hibernate.search.annotations.CacheFromIndex

Remove the annotation. No alternative replacement is necessary.

org.hibernate.search.annotations.Key

Custom filter cache keys are a deprecated feature and are scheduled to be removed in Hibernate Search 6. As of Hibernate Search 5.1, the filter cache keys are determined automatically based on the filter parameters so it is no longer required to provide a key object.

Hibernate Search Deprecated Methods
MethodDescription

org.hibernate.search.FullTextSharedSessionBuilder.autoClose()

No replacement

org.hibernate.search.FullTextSharedSessionBuilder.autoClose(boolean)

No replacement

org.hibernate.search.cfg.IndexedMapping.cacheFromIndex(FieldCacheType…​)

This will be removed with no replacement.

org.hibernate.search.cfg.EntityDescriptor.getCacheInMemory()

This will be removed with no replacement.

org.hibernate.search.cfg.ContainedInMapping.numericField()

Invoke field().numericField() instead.

org.hibernate.search.cfg.EntityDescriptor.setCacheInMemory(Map<String, Object>)

This will be removed with no replacement.

org.hibernate.search.MassIndexer.threadsForSubsequentFetching(int)

This method will be removed.

org.hibernate.search.query.dsl.FuzzyContext.withThreshold(float)

Use FuzzyContext.withEditDistanceUpTo(int).

Hibernate Search Deprecated Constructors
ConstructorDescription

org.hibernate.search.cfg.NumericFieldMapping(PropertyDescriptor, EntityDescriptor, SearchMapping)

Use NumericFieldMapping.NumericFieldMapping(String, PropertyDescriptor, EntityDescriptor, SearchMapping) instead.

Changes Impacting Advanced Integrators

This section describes changes that are not part of the public API. They should not impact the average developer as these artifacts should only be accessed by integrators who extend the Hibernate Search framework.

5.10. Migrate Entity Beans to JPA

Support for EJB Entity Beans is optional in Java EE 7 and they are not supported in JBoss EAP 7. This means container-managed persistence (CMP) and bean-managed persistence (BMP) entity beans must be rewritten to use Java Persistence API (JPA) entities when you migrate to JBoss EAP 7.

In previous releases of JBoss EAP, entity beans were created in application source code by extending the javax.ejb.EntityBean class and implementing the required methods. They were then configured in the ejb-jar.xml file. A CMP entity bean was specified using an <entity> element that contained a <persistence-type> child element with a value of Container. A BMP entity bean was specified using an <entity> element that contained a <persistence-type> child element with a value of Bean.

In JBoss EAP 7, you must replace any CMP and BMP entity beans in your code with Java Persistence API (JPA) entities. JPA entities are created using the javax.persistence.* classes and are defined in the persistence.xml file.

The following is an example of a JPA entity class.

import javax.persistence.Column;
import javax.persistence.Entity;
import javax.persistence.GeneratedValue;
import javax.persistence.Id;
import javax.persistence.Table;

@Entity
// User is a keyword in some SQL dialects!
@Table(name = "MyUsers")
public class MyUser {
    @Id
    @GeneratedValue
    private Long id;

    @Column(unique = true)
    private String username;
    private String firstName;
    private String lastName;

    public Long getId() {
        return id;
    }
    public String getUsername() {
        return username;
    }
    public void setUsername(String username) {
        this.username = username;
    }
    public String getFirstName() {
        return firstName;
    }
    public void setFirstName(String firstName) {
        this.firstName = firstName;
    }
    public String getLastName() {
        return lastName;
    }
    public void setLastName(String lastName) {
        this.lastName = lastName;
    }

The following is an example of a persistence.xml file.

<persistence version="2.1"
      xmlns="http://xmlns.jcp.org/xml/ns/persistence" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
      xsi:schemaLocation="
        http://xmlns.jcp.org/xml/ns/persistence
        http://xmlns.jcp.org/xml/ns/persistence/persistence_2_1.xsd">
  <persistence-unit name="my-unique-persistence-unit-name">
    <properties>
      // properties...
    </properties>
  </persistence-unit>
</persistence>

For working examples of JPA entities, see the bmt, cmt, and hibernate5 quickstarts that ship with JBoss EAP 7.

5.11. JPA Persistence Property Changes

JPA Persistence Property Changes Introduced in JBoss EAP 7.0

A new persistence property, jboss.as.jpa.deferdetach, was added to provide compatibility with the persistence behavior in previous releases of JBoss EAP.

The jboss.as.jpa.deferdetach property controls whether the transaction-scoped persistence context used in a non-JTA transaction thread detaches loaded entities after each EntityManager invocation or whether it waits until the persistence context is closed, for example, when the session bean invocation ends. The property value defaults to false, meaning entities are detached or cleared after each EntityManager invocation. This is the correct default behavior as defined in the JPA specification. If the property value is set to true, the entities are not detached until the persistence context is closed.

In JBoss EAP 5, persistence behaved as if the jboss.as.jpa.deferdetach property was set to true. To get this same behavior when migrating your application from JBoss EAP 5 to JBoss EAP 7, you must set the jboss.as.jpa.deferdetach property value to true in your persistence.xml as shown in the following example.

<?xml version="1.0" encoding="UTF-8"?>
<persistence xmlns="http://java.sun.com/xml/ns/persistence" version="1.0">
    <persistence-unit name="EAP5_COMPAT_PU">
    <jta-data-source>java:jboss/datasources/ExampleDS</jta-data-source>
    <properties>
         <property name="jboss.as.jpa.deferdetach" value="true" />
    </properties>
  </persistence-unit>
</persistence>

In JBoss EAP 6, persistence behaved as if the jboss.as.jpa.deferdetach property was set to false. This is the same behavior as seen in JBoss EAP 7, so no changes are necessary when you migrate your application.

JPA Persistence Property Changes Introduced in JBoss EAP 7.1

In JBoss EAP 7.0, unsynchronized persistence context error checking was not as strict as it should have been in the following areas.

  • A synchronized container-managed persistence context was allowed to use an unsynchronized extended persistence context that was associated with a JTA transaction. Instead, it should have thrown an IllegalStateException to prevent the unsynchronized persistence context from being used.
  • An unsynchronized persistence context specified in a deployment descriptor was treated as synchronized.

In addition, PersistenceProperty hints in the @PersistenceContext were mistakenly ignored in JBoss EAP 7.0.

These issues were addressed and fixed in JBoss EAP 7.1 and later. Because these updates can result in an unwanted change in application behavior, two new persistence unit properties were introduced in JBoss EAP 7.1 to provide backward compatibility and preserve the previous behavior.

PropertyDescription

wildfly.jpa.skipmixedsynctypechecking

This property disables the error checking. It should only be used as a temporary measure for backward compatibility in situations where applications worked in JBoss EAP 7.0 and fail in JBoss EAP 7.1 and later. Because this property might be deprecated in a future release, it is recommended that you correct your application code as soon as you are able to do so.

wildfly.jpa.allowjoinedunsync

This property is an alternative to wildfly.jpa.skipmixedsynctypechecking. It allows the application to treat unsynchronized persistence contexts that are associated with a JTA transaction as if they are synchronized persistence contexts.

5.12. Migrate EJB Client Code

5.12.1. EJB Client Changes in JBoss EAP 7

The default remote connector and port has changed in JBoss EAP 7. For details about this change, see Update the Remote URL Connector and Port.

If you used the migrate operation to migrate your server configuration, the old settings are preserved and you do not need to make the changes detailed below. However, if you run with the new JBoss EAP 7 default configuration, you must make the following changes.

5.12.1.1. Update the Default Remote Connection Port

Change the remote connection port value from 4447 to 8080 in the jboss-ejb-client.properties file.

The following are examples of a jboss-ejb-client.properties file in the previous and the current release.

Example: JBoss EAP 6 jboss-ejb-client.properties File

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

Example: JBoss EAP 7 jboss-ejb-client.properties File

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

5.12.1.2. Update the Default Connector

If you are running with the new JBoss EAP 7 configuration, the default connector has changed from remote to http-remoting. This change impacts clients that use libraries from one release of JBoss EAP and to connect to server in a different release.

  • If a client application uses the EJB client library from JBoss EAP 6 and wants to connect to JBoss EAP 7 server, the server must be configured to expose a remote connector on a port other than 8080. The client must then connect using that newly configured connector.
  • A client application that uses the EJB client library from JBoss EAP 7 and wants to connect to JBoss EAP 6 server must be aware that the server instance does not use the http-remoting connector and instead uses a remote connector. This is achieved by defining a new client-side connection property.

    Example: remote Connection Property

    remote.connection.default.protocol=remote

5.12.2. Migrate Remote Naming Client Code

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

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

5.12.3. Additional EJB Client Changes Introduced in JBoss EAP 7.1

While JBoss EAP 7.0 shipped with JBoss EJB Client 2.1.4, JBoss EAP 7.1 and later ship with JBoss EJB Client 4.0.x, which includes a number of changes to the API.

  • The org.ejb.client.EJBClientInvocationContext class has added the following new methods.

    MethodTypeDescription

    isBlockingCaller()

    boolean

    Determine whether this invocation is currently blocking the calling thread.

    isClientAsync()

    boolean

    Determine whether the method is marked client-asynchronous, meaning that invocation should be asynchronous regardless of whether the server-side method is asynchronous.

    isIdempotent()

    boolean

    Determine whether the method is marked idempotent, meaning that the method may be invoked more than one time with no additional effect.

    setBlockingCaller(boolean)

    void

    Establish whether this invocation is currently blocking the calling thread.

    setLocator(EJBLocator<T>)

    <T> void

    Set the locator for the invocation target.

  • The org.ejb.client.EJBLocator class has added the following new methods.

    MethodTypeDescription

    asStateful()

    StatefulEJBLocator<T>

    Return this locator as a stateful locator, if it is one.

    asStateless()

    StatelessEJBLocator<T>

    Return this locator as a stateless locator, if it is one.

    isEntity()

    boolean

    Determine if this is an entity locator.

    isHome()

    boolean

    Determine if this is a home locator.

    isStateful()

    boolean

    Determine if this is a stateful locator.

    isStateless()

    boolean

    Determine if this is a stateless locator.

    withNewAffinity(Affinity)

    abstract EJBLocator<T>

    Create a copy of this locator, but with the new given affinity.

  • A new org.ejb.client.EJBClientPermission class, which is a subclass of java.security.Permission, has been introduced for controlling access to privileged EJB operations.

    • It provides the following constructors.

      • EJBClientPermission(String name)
      • EJBClientPermission(String name, String actions)
    • It provides the following methods.

      MethodTypeDescription

      equals(EJBClientPermission obj)

      boolean

      Checks two EJBClientPermission objects for equality.

      equals(Object obj)

      boolean

      Checks two Permission objects for equality.

      equals(Permission obj)

      boolean

      Checks two Permission objects for equality.

      getActions()

      String

      Returns the actions as a string.

      hashcode()

      int

      Returns the hash code value for this Permission object.

      implies(EJBClientPermission permission)

      boolean

      Checks if the specified permission’s actions are implied by this EJBClientPermission object’s actions.

      implies(Permission permission)

      boolean

      Checks if the specified permission’s actions are implied by this Permission object’s actions.

  • A new org.ejb.client.EJBMethodLocator class has been introduced for locating a specific EJB method.

    • It provides the following constructor.

      • EJBMethodLocator(String methodName, String…​ parameterTypeNames)
    • It provides the following methods.

      MethodTypeDescription

      equals(EJBMethodLocator other)

      boolean

      Determine whether this object is equal to another.

      equals(Object other)

      boolean

      Determine whether this object is equal to another.

      forMethod(Method method)

      static EJBMethodLocator

      Get a method locator for the given reflection method.

      getMethodName()

      String

      Get the method name.

      getParameterCount()

      int

      Get the parameter count.

      getParameterTypeName(int index)

      String

      Get the name of the parameter at the given index.

      hashCode()

      int

      Get the hash code.

  • A new org.jboss.ejb.client.EJBReceiverInvocationContext.ResultProducer.Failed class has been introduced for failure cases.

    • It provides the following constructor.

      • Failed(Exception cause)
    • It provides the following methods.

      MethodTypeDescription

      discardResult()

      void

      Discard the result, indicating that it will not be used.

      getResult()

      Object

      Get the result.

  • A new org.jboss.ejb.client.EJBReceiverInvocationContext.ResultProducer.Immediate class has been introduced for immediate results.

    • It provides the following constructor.

      • Failed(Exception cause)
    • It provides the following methods.

      MethodTypeDescription

      discardResult()

      void

      Discard the result, indicating that it will not be used.

      getResult()

      Object

      Get the result.

  • A new org.jboss.ejb.client.URIAffinity class, which is a subclass of org.jboss.ejb.client.Affinity has been introduced for URI affinity specification.

    • It is created using Affinity.forUri(URI).
    • It provides the following methods.

      MethodTypeDescription

      equals(Affinity other)

      boolean

      Indicates whether another object is equal to this one.

      equals(Object other)

      boolean

      Indicates whether another object is equal to this one.

      equals(URIAffinity other)

      boolean

      Indicates whether another object is equal to this one.

      getURI()

      URI

      Get the associated URI.

      hashCode()

      int

      Get the hash code.

      toString()

      String

      Returns a string representation of the object.

  • The org.jboss.ejb.client.EJBMetaDataImpl class has deprecated the following methods.

    • toAbstractEJBMetaData()
    • EJBMetaDataImpl(AbstractEJBMetaData<?,?>)

5.12.4. EJB Client Changes Needed for JBoss EAP 7.2

The upgrade of the org.apache.santuario.xmlsec module from 2.0.8 to 2.1.1 in JBoss EAP 7.2 has caused a regression with remoting in PicketLinkSTS. The issue manifests itself as the following runtime exception.

java.lang.IllegalArgumentException: ELY05131: Invalid ASCII control "0xA"

This is caused by a change in the formatting in the generated SignatureValue in the assertion. In the previous release, the generated value looked similar to the following example.

<dsig:SignatureValue xmlns:dsig="http://www.w3.org/2000/09/xmldsig#">cUNpFJIZlLYrBDZtQSTDrq2K6PbnAHyg2qbx/D5FuB4XMjdQ5oxQjkMejLyelnA7s4GFusoLhahlqlTOT8UrOyxrR4yYAmJ/e5s+f4gys926+tbiraT/3/wG8wM/Lvcjvk5Ap69zODuRYpypsWfA4jrI7TTBXVPGy8g4KUdnFviUiTuFTc2Ghgxp53AmUuLis/THyP28jE7+28//q8bi/bQrFwHC6tWX67+NK1duFCOcQ6IPIKeVrePZz55Ivgl+WWdkF6uYCz5IdMzurhzmeQ3K8DAMIxz/MG67VWJIOnuGNWF7nmdye5zd9AFcRsr1XadvZJCbGNfuc89AL5inCg==</dsig:SignatureValue>

In JBoss EAP 7.2, the generated string value now contains instances of invalid hidden ASCII 0xD carriage return and 0xA line feed control characters.

<dsig:SignatureValue xmlns:dsig="http://www.w3.org/2000/09/xmldsig#">cUNpFJIZlLYrBDZtQSTDrq2K6PbnAHyg2qbx/D5FuB4XMjdQ5oxQjkMejLyelnA7s4GFusoLhahl&#13;
qlTOT8UrOyxrR4yYAmJ/e5s+f4gys926+tbiraT/3/wG8wM/Lvcjvk5Ap69zODuRYpypsWfA4jrI&#13;
7TTBXVPGy8g4KUdnFviUiTuFTc2Ghgxp53AmUuLis/THyP28jE7+28//q8bi/bQrFwHC6tWX67+N&#13;
K1duFCOcQ6IPIKeVrePZz55Ivgl+WWdkF6uYCz5IdMzurhzmeQ3K8DAMIxz/MG67VWJIOnuGNWF7&#13;
nmdye5zd9AFcRsr1XadvZJCbGNfuc89AL5inCg==</dsig:SignatureValue>

If you experience the above runtime exception, you must update your client code to remove occurrences of the hidden ASCII characters from the the returned assertion string.

For example, assume your current code looks similar to the following example.

WSTrustClient client = new WSTrustClient("PicketLinkSTS", "PicketLinkSTSPort",
                "http://localhost:8080/picketlink-sts/PicketLinkSTS", new WSTrustClient.SecurityInfo(username, password));
Element assertion = client.issueToken(SAMLUtil.SAML2_TOKEN_TYPE);

// Return the assertion as a string
String assertionString = DocumentUtil.getNodeAsString(assertion);
...
properties.put("remote.connection.main.password", assertionString);

You must add a line of code to remove the occurrences of the invalid hidden ASCII 0xD carriage return and 0xA line feed characters as shown below.

WSTrustClient client = new WSTrustClient("PicketLinkSTS", "PicketLinkSTSPort",
                "http://localhost:8080/picketlink-sts/PicketLinkSTS", new WSTrustClient.SecurityInfo(username, password));
Element assertion = client.issueToken(SAMLUtil.SAML2_TOKEN_TYPE);

// Return the assertion as a string, stripping the invalid hidden ASCII characters
String assertionString = DocumentUtil.getNodeAsString(assertion).replace(String.valueOf((char) 0xA), "").replace(String.valueOf((char) 0xD), "");
...
properties.put("remote.connection.main.password", assertionString);

5.13. Migrate Clients to Use the WildFly Configuration File

Prior to release 7.1, JBoss EAP client libraries, such as EJB and naming, used different configuration strategies. JBoss EAP 7.1 introduced the wildfly-config.xml file with the purpose of unifying all client configurations into one single configuration file, in a similar manner to the way the server configuration is handled.

For example, prior to JBoss EAP 7.1, you might create a new InitialContext for a Java EJB client using a jboss-ejb-client.properties file, or by programmatically setting the properties using a Properties class.

Example: jboss-ejb-client.properties Properties File

remote.connectionprovider.create.options.org.xnio.Options.SSL_ENABLED=false
remote.connections=one
remote.connection.one.port=8080
remote.connection.one.host=127.0.0.1
remote.connection.one.username=quickuser
remote.connection.one.password=quick-123

In JBoss EAP 7.1 and later, you create a wildfly-config.xml file in the META-INF/ directory of the client archive. This is the equivalent configuration using a wildfly-config.xml file.

Example: Equivalent Configuration Using the wildfly-config.xml File

<configuration>
    <authentication-client xmlns="urn:elytron:client:1.2">
        <authentication-rules>
            <rule use-configuration="ejb"/>
        </authentication-rules>
        <authentication-configurations>
            <configuration name="ejb">
                <set-user-name name="quickuser"/>
                <credentials>
                    <clear-password password="quick-123"/>
                </credentials>
            </configuration>
        </authentication-configurations>
    </authentication-client>
    <jboss-ejb-client xmlns="urn:jboss:wildfly-client-ejb:3.0">
        <connections>
            <connection uri="remote+http://127.0.0.1:8080" />
        </connections>
    </jboss-ejb-client>
</configuration>

For information about how to configure client authentication for the Elytron Client using the wildfly-config.xml file, see Configure Client Authentication with Elytron Client in How to Configure Identity Management for JBoss EAP.

For more information about the types of client configurations that can be done using the wildfly-config.xml file, see Client Configuration Using the wildfly-config.xml File in the JBoss EAP Development Guide.

5.14. Migrate Deployment Plan Configurations

The Java EE Application Deployment specification (JSR-88) was intended to define a standard contract to enable tools from multiple providers to configure and deploy applications on any Java EE platform product. The contract required Java EE Product Providers to implement the DeploymentManager and other javax.enterprise.deploy.spi interfaces to be accessed by the Tool Providers. In case of JBoss EAP 6, a deployment plan is identified by an XML descriptor named deployment-plan.xml that is bundled in a ZIP or JAR archive.

This specification saw very little adoption because most application server products provide their own more "feature rich" deployment solutions. For this reason, JSR-88 support was dropped from Java EE 7 and, in turn, from JBoss EAP 7.

If you used JSR-88 to deploy your application, you must now use another method to deploy the application. The JBoss EAP management CLI deploy command provides a standard way to deploy archives to standalone servers or to server groups in a managed domain. For more information about the management CLI, see the Management CLI Guide.

5.15. Migrate Custom Application Valves

You must manually migrate custom valves or any valves that are defined in the jboss-web.xml XML file. This includes valves created by extending the org.apache.catalina.valves.ValveBase class and configured in the <valve> element of the jboss-web.xml descriptor file.

Important

Custom valves and valves that are defined in the jboss-web.xml file must be rewritten or replaced by the corresponding Undertow built-in handler. For information about mapping valves to Undertow handlers, see Migrate JBoss Web Valves.

Authentication valves must be replaced manually using Undertow built-in authentication mechanisms.

Migrate Valves Configured in Deployments

In JBoss EAP 6, you could define custom valves at the application level by configuring them in the jboss-web.xml web application descriptor file. In JBoss EAP 7, it is possible to do this with Undertow handlers as well.

The following is an example of a valve configured in the jboss-web.xml file in JBoss EAP 6.

<jboss-web>
    <valve>
        <class-name>org.jboss.examples.MyValve</class-name>
​        <param>
    ​        <param-name>myParam</param-name>
​            <param-value>foobar</param-value>
    ​    </param>
    </valve>
</jboss-web>

For more information about how to create and configure custom handlers in JBoss EAP, see Creating Custom Handlers in the JBoss EAP Development Guide.

Migrate Custom Authenticator Valves

For information about how to migrate authenticator valves, see Migrate Authenticator Valves in this guide.

5.16. Security Application Changes

The replacement of JBoss Web with Undertow requires changes to security configuration in JBoss EAP 7.

5.16.1. Migrate Authenticator Valves

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 Development Guide for JBoss EAP.

5.16.3. Other Security Application Changes

For information about the differences in SSO configuration with Kerberos, see Differences from Configuring Previous Versions JBoss EAP in How to Set Up SSO with Kerberos for JBoss EAP.

5.17. JBoss Logging Changes

If your application uses JBoss Logging, be aware that the annotations in the org.jboss.logging package are now deprecated in JBoss EAP 7. They have been moved to the org.jboss.logging.annotations package, so you must update your source code to import the new package.

The annotations have also moved to a separate Maven groupId:artifactId:version (GAV) ID so you need to add a new project dependency for org.jboss.logging:jboss-logging-annotations in your project pom.xml file.

Note

Only the logging annotations have moved. The org.jboss.logging.BasicLogger and org.jboss.logging.Logger still exist in the org.jboss.logging package.

The following table lists the deprecated annotation classes and corresponding replacements.

Table 5.1. Deprecated Logging Annotation Replacements

Deprecated ClassReplacement Class

org.jboss.logging.Cause

org.jboss.logging.annotations.Cause

org.jboss.logging.Field

org.jboss.logging.annotations.Field

org.jboss.logging.FormatWith

org.jboss.logging.annotations.FormatWith

org.jboss.logging.LoggingClass

org.jboss.logging.annotations.LoggingClass

org.jboss.logging.LogMessage

org.jboss.logging.annotations.LogMessage

org.jboss.logging.Message

org.jboss.logging.annotations.Message

org.jboss.logging.MessageBundle

org.jboss.logging.annotations.MessageBundle

org.jboss.logging.MessageLogger

org.jboss.logging.annotations.MessageLogger

org.jboss.logging.Param

org.jboss.logging.annotations.Param

org.jboss.logging.Property

org.jboss.logging.annotations.Property

5.18. JavaServer Faces (JSF) Code Changes

Dropped Support for JSF 1.2

JBoss EAP 6.4 allowed you to continue to use JSF 1.2 with your application deployment by creating a jboss-deployment-structure.xml file.

JBoss EAP 7.2 includes JSF 2.3 and no longer supports the JSF 1.2 API. If your application uses JSF 1.2, you must rewrite it to use JSF 2.3.

5.19. Module Class Loading Changes

In JBoss EAP 7, the class loading behavior has changed in cases where multiple modules contain the same classes or packages.

Assume there are two modules, MODULE_A and MODULE_B, that depend upon each other and contain some of the same packages. In JBoss EAP 6, the classes or packages that were loaded from the dependencies took precedence over those specified in the resource-root of the module.xml file. This meant MODULE_A saw the packages for MODULE_B and MODULE_B saw the packages for MODULE_A. This behavior was confusing and could cause conflicts. This behavior has changed in JBoss EAP 7. Now the classes or packages specified by the resource-root in the module.xml file take precedence over those specified by the dependency. This means MODULE_A sees the packages for MODULE_A and MODULE_B sees the packages for MODULE_B. This prevents conflicts and provides a more appropriate behavior.

If you have defined custom modules that include resource-root libraries or packages that contain classes that are duplicated in their module dependencies, you might see ClassCastException, LinkageError, class loading errors, or other changes in behavior when you migrate to JBoss EAP 7. To resolve these issues, you must configure your module.xml file to ensure only one version of a class is used. This can be accomplished by using either of the following approaches.

  • You can avoid specifying a resource-root that duplicates classes in the module dependency.
  • You can use the include and exclude sub-elements of the imports and exports elements to control class loading in the module.xml file. The following is an export element that excludes classes is in the specified package.

    <exports>
      <exclude path="com/mycompany/duplicateclassespath/"/>
    </exports>

If you prefer to preserve your existing behavior, you must filter the dependency packages from the dependent resource-root in the module.xml file using the filter element. This allows you to retain the existing behavior without the odd looping that you would see under JBoss EAP 6. The following is an example of a root-resource that filters classes in a specified package.

<resource-root path="mycompany.jar">
  <filter>
    <exclude path="com/mycompany/duplicateclassespath"/>
  </filter>
</resource-root>

For more information about modules and class loading, see Class Loading and Modules in the JBoss EAP Development Guide.

5.20. Application Clustering Changes

5.20.1. Overview of New Clustering Features

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

  • JBoss EAP 7 introduces a new public API for building singleton services that significantly simplifies the process. For information on singleton services, see HA Singleton Service in the JBoss EAP Development Guide
  • A singleton deployment can be configured to deploy and start on only a single node in the cluster at a time. For more information, see HA Singleton Deployments in the JBoss EAP Development Guide.
  • You can now define clustered singleton MDBs. For more information, see Clustered Singleton MDBs in Developing EJB Applications for JBoss EAP.
  • JBoss EAP 7 includes the Undertow mod_cluster implementation. This offers a pure Java load balancing solution that does not require an httpd web server. For more information, see Configuring JBoss EAP as a Front-end Load Balancer in the JBoss EAP Configuration Guide.

The remainder of this section describes how clustering changes might impact the migration of your applications to JBoss EAP 7.

5.20.2. Web Session Clustering Changes

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>

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

Configuration ElementDescription of Change

<max-active-sessions/>

Previously, the session creation would fail if it caused the number of active sessions to exceed the value specified by <max-active-sessions/>.

In the new implementation, <max-active-sessions/> is used to enable session passivation. If session creation will cause the number of active sessions to exceed the <max-active-sessions/>, then the oldest session known to the session manager will passivate to make room for the new session.

<passivation-config/>

This configuration element and its sub-elements are no longer used in JBoss EAP 7.

<use-session-passivation/>

Previously, passivation was enabled using this attribute.

In the new implementation, passivation is enabled by specifying a non-negative value for <max-active-sessions/>.

<passivation-min-idle-time/>

Previously, sessions needed to be active for a minimum amount of time before becoming a candidate for passivation. This could cause session creation to fail, even when passivation was enabled.

The new implementation does not support this logic and thus avoids this Denial of Service (DoS) vulnerability.

<passivation-max-idle-time/>

Previously, a session would be passivated after it was idle for a specific amount of time.

The new implementation only supports lazy passivation. It does not support eager passivation. Sessions are only passivated when necessary to comply with <max-active-sessions/>.

<replication-config/>

The new implementation deprecates a number of sub-elements.

<replication-trigger/>

Previously, this element was used to determine when session replication was triggered. The new implementation replaces this configuration option with a single, robust strategy. For more information, see Immutable Session Attributes in the JBoss EAP Development Guide.

<use-jk/>

Previously, the instance-id of the node handling a given request was appended to the jsessionid, for use by load balancers such as mod_jk, mod_proxy_balancer, mod_cluster, depending on the value specified for <use-jk/>.

In the new implementation, the instance-id, if defined, is always appended to the jsessionid.

<max-unreplicated-interval/>

Previously, this configuration option was intended as an optimization to prevent the replication of a session’s timestamp if no session attribute was changed. While this sounds nice, in practice it does not prevent any RPCs, since session access requires cache transaction RPCs regardless of whether any session attributes changed.

In the new implementation, the timestamp of a session is replicated on every request. This prevents stale session metadata following a failover.

<snapshot-mode/>

Previously, one could configure <snapshot-mode/> as INSTANT or INTERVAL. Infinispan’s asynchronous replication makes this configuration option obsolete.

<snapshot-interval/>

This was only relevant for <snapshot-mode>INTERVAL</snapshot-mode>. Since <snapshot-mode/> is obsolete, this option is now obsolete as well.

<session-notification-policy/>

Previously, the value specified by this attribute defined a policy for triggering session events.

In the new implementation, this behavior is specification-driven and not configurable.

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.

5.20.3. Stateful Session EJB Clustering Changes

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

  • You could add the org.jboss.ejb3.annotation.Clustered annotation in the session bean.

    @Stateful
    @Clustered
    public class MyBean implements MySessionInt {
    
       public void myMethod() {
          //
       }
    }
  • You could add the <clustered> element to the jboss-ejb3.xml file.

    <c:clustering>
      <ejb-name>DDBasedClusteredSFSB</ejb-name>
      <c:clustered>true</c:clustered>
    </c:clustering>

JBoss EAP 7 no longer requires you 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.

  • You can disable the default behavior for a single stateful session bean by using @Stateful(passivationCapable=false), which is new to the EJB 3.2 specification.
  • You can disable this behavior globally in the configuration of the ejb3 subsystem in the server configuration.
Note

If the @Clustered annotation is not removed from the application, it is simply ignored and does not affect the deployment of the application.

5.20.4. Clustering Services Changes

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.

  • The new org.wildfly.clustering.group.Group interface provides access to the current cluster status and allows listening for cluster membership changes.
  • The new org.wildfly.clustering.dispatcher.CommandDispatcher interface allows running code in the cluster, on all or a selected subset of nodes.

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 Development Guide.

5.20.5. Migrate Clustering HA Singleton

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

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