Chapitre 5. Changements apportés à la migration des applications

5.1. Changements apportés aux applications de services web

JBossWS 5 apporte de nouvelles fonctionnalités et améliorations des performances aux services web JBoss EAP 7, principalement à travers la mise à niveau des composants Apache CXF, Apache WSS4J, et Apache Santuario.

5.1.1. Changements de prise en charge JAX-RPC

L'API Java pour RPC basée XML (JAX-RPC) a été déconseillée pour Java EE 6 et est optionnelle sur Java EE 7. Cette API n'est plus disponible ou prise en charge sur JBoss EAP 7. Les applications qui utilisent JAX-RPC doivent être migrées pour utiliser JAX-WS, qui est le framework actuel des services web standard Java EE.

L'utilisation des services JAX-RPC peut être identifiée de l'une des manières suivantes :

  • La présence d'un fichier de mappage JAX-RPC, qui est un fichier XML avec l'élément root <java-wsdl-mapping>.
  • La présence d'un fichier descripteur XML webservices.xml qui contient un élément <webservice-description> incluant un élément enfant <jaxrpc-mapping-file>. Ci-dessous figure un exemple de fichier descripteur webservices.xml qui définit un service web JAX-RPC.

    <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>
  • La présence d'un fichier ejb-jar.xml, qui contient un <service-ref> référençant un fichier de mappage JAX-RPC.

5.1.2. Changements aux services web Apache CXF Spring

Dans les versions précédentes de JBoss EAP, vous pouviez personnaliser l'intégration JBossWS et Apache CXF en incluant un fichier de configuration jbossws-cxf.xml avec l'archive du déploiement du point de terminaison (« endpoint deployment archive »). Un exemple de cas d'utilisation consiste à configurer des threads d'intercepteurs pour les points de terminaison du serveur et du client du service web sur le bus Apache CXF. Cette intégration nécessitait que Spring soit déployé dans le serveur JBoss EAP.

L'intégration Spring n'est plus prise en charge dans JBoss EAP 7. Toute application qui contient un fichier de configuration de descripteur jbossws-cxf.xml doit être modifié pour remplacer la configuration personnalisée définie dans ce fichier. Alors qu'il est toujours possible d'accéder directement à l'API Apache CXF, veuillez prendre en compte le fait que l'application ne sera pas portable.

L'approche suggérée consiste à remplacer les configurations personnalisées Spring par les nouvelles options de configuration du descripteur JBossWS lorsque c'est possible. L'approche basée descripteur JBossWS fournit une fonctionnalité similaire sans nécessiter de modifications du code du point de terminaison du client. Dans certains cas, vous pouvez remplacer Spring par CDI (« Context Dependency Injection »).

Intercepteurs Apache CXF

Le descripteur JBossWS fournit de nouvelles options de configuration vous permettant de déclarer les intercepteurs sans modifier le code du point de terminaison du client. Au lieu de cela, vous pouvez déclarer les intercepteurs dans des configurations de clients et de points de terminaison prédéfinis en spécifiant une liste de noms de classes d'intercepteurs pour les propriétés cxf.interceptors.in et cxf.interceptors.out.

Ci-dessous figure un exemple de fichier jaxws-endpoint-config.xml qui déclare des intercepteurs en utilisant ces propriétés.

<?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>
Fonctionnalités Apache CXF

Le descripteur JBossWS vous permet de déclarer des fonctionnalités dans des configurations de clients et de points de terminaison prédéfinis en spécifiant une liste de noms de classes de fonctionnalités pour la propriété cxf.features.

Ci-dessous figure un exemple de fichier jaxws-endpoint-config.xml qui déclare une fonctionnalité en utilisant cette propriété.

<?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>
Transport HTTP Apache CXF

Dans Apache CXF, la configuration du transport HTTP est effectuée en spécifiant les options org.apache.cxf.transport.http.HTTPConduit. L'intégration JBossWS permet aux conduits d'être modifiés par moyen de programme en utilisant l'API Apache CXF comme suit.

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

Vous pouvez également contrôler et outrepasser les valeurs par défaut Apache CXF HTTPConduit en paramétrant les propriétés système.

PropriétéTypeDescription

cxf.client.allowChunking

Boolean

Spécifie s'il faut envoyer des requêtes en utilisant la segmentation.

cxf.client.chunkingThreshold

Integer

Définit la limite à laquelle basculer du mode sans segmentation au mode de segmentation.

cxf.client.connectionTimeout

Long

Définit le nombre de millisecondes avant l'expiration de la connexion.

cxf.client.receiveTimeout

Long

Définit le nombre de millisecondes avant l'expiration de la réception.

cxf.client.connection

String

Spécifie s'il faut utiliser le type de connexion Keep-Alive ou close.

cxf.tls-client.disableCNCheck

Boolean

Spécifie s'il faut désactiver la vérification de nom d'hôte CN.

5.1.3. Changements WS-Security

  • Si votre application contient un gestionnaire de rappels (« callback ») personnalisé qui accède à la classe org.apache.ws.security.WSPasswordCallback, prenez en compte que cette classe a été déplacée sur le paquet org.apache.wss4j.common.ext.
  • La plupart des objets bean SAML du paquet org.apache.ws.security.saml.ext ont été déplacés sur org.apache.wss4j.common.saml package.
  • Veuillez utiliser le transport de clé RSA v1.5 et tous les algorithmes connexes seront rejetés par défaut.
  • Auparavant, le service de jetons de sécurité (STS, ou « Security Token Service ») ne validait que les jetons onBehalfOf. Désormais, il valide également les jetons ActAs. Par conséquent, un nom d'utilisateur et un mot de passe valides doivent être spécifiés dans le UsernameToken fourni pour le jeton ActAs.
  • Les jetons Bearer SAML doivent désormais avoir une signature interne. La classe org.apache.wss4j.dom.validate.SamlAssertionValidator contient maintenant une méthode setRequireBearerSignature() pour activer ou désactiver la vérification de signatures.

5.1.4. Changements dans la structure des modules JBoss

Les JAR cxf-api et cxf-rt-core ont été fusionnés en une seule JAR cxf-core. Par conséquent, le module org.apache.cxf de JBoss EAP contient désormais la JAR cxf-core et expose davantage de classes par rapport à la version précédente.

5.1.5. Conditions préalable et changements de Bouncy Castle

Si vous souhaitez utiliser le chiffrement AES avec GCM (« Galois/Counter Mode ») pour le chiffrement symétrique en XML/WS-Security, vous aurez besoin du fournisseur de sécurité BouncyCastle.

JBoss EAP 7 est fourni avec le module org.bouncycastle et JBossWS est désormais capable de reposer sur son chargeur de classes pour obtenir et utiliser le fournisseur de sécurité BouncyCastle. Ainsi, il n'est plus nécessaire d'installer BouncyCastle statiquement dans la JVM actuelle. Pour les applications exécutées hors du conteneur, le fournisseur de sécurité peut être mis à disponibilité de JBossWS en ajoutant une bibliothèque BouncyCastle au chemin de classe.

Vous pouvez désactiver ce comportement en paramétrant la valeur de la propriété org.jboss.ws.cxf.noLocalBC sur true dans le fichier du descripteur de déploiement jaxws-endpoint-config.xml pour le serveur ou dans le fichier du descripteur jaxws-client-config.xml pour les clients.

Si vous souhaitez utiliser une version différente de celle fournie dans JBoss EAP, vous pouvez installer statiquement BouncyCastle sur la JVM. Dans ce cas, le fournisseur de sécurité installé statiquement BouncyCastle sera choisi plutôt à la place du fournisseur présent dans le classpath. Pour éviter tout problème, vous devez utiliser BouncyCastle 1.49, 1.51, ou une version supérieure.

5.1.6. Stratégie de sélection de Bus Apache CXF

La stratégie de sélection de bus par défaut pour des clients exécutés dans des conteneurs a été modifiée de THREAD_BUS à TCCL_BUS. Pour les clients exécutés hors conteneurs, la stratégie par défaut reste THREAD_BUS. Vous pouvez restaurer le comportement de la version précédente en utilisant l'une de méthodes suivantes.

  • Lancez le serveur JBoss EAP avec la valeur de la propriété système org.jboss.ws.cxf.jaxws-client.bus.strategy définie sur THREAD_BUS.
  • Définissez explicitement la stratégie de sélection dans le code client.

5.1.7. Conditions préalables JAX-WS 2.2 pour WebServiceRef

Les conteneurs doivent utiliser des constructeurs de style JAX-WS 2.2, en utilisant la classe WebServiceFeature, pour créer des clients injectés dans les références du service web. Cela signifie que les classes de services fournies par l'utilisateur et injectées par le conteneur doivent implémenter JAX-WS 2.2 ou une version supérieure.

5.1.8. Changements de vérification CN IgnoreHttpsHost

Dans les versions précédentes, vous pouviez désactiver la vérification du nom d'hôte de l'URL HTTPS avec le nom commun (« Common Name », ou CN) donné dans son certificat en paramétrant la propriété système org.jboss.security.ignoreHttpsHost sur true. Ce nom de propriété système a été remplacé par cxf.tls-client.disableCNCheck.

5.1.9. Configuration côté client et chargement de classe

En conséquence de l'activation des injections dans les points de terminaison de services et les gestionnaires de clients de services, il n'est plus possible de charger automatiquement les classes de gestionnaires du module JBoss org.jboss.as.webservices.server.integration. Si votre application dépend d'une configuration prédéfinie, vous devrez définir de nouvelles dépendances de modules pour votre déploiement de manière explicite. Pour obtenir davantage d'informations, veuillez consulter Migrer les dépendances de modules explicites

5.1.10. Le mécanisme de remplacement des standards approuvés Java est déconseillé

Le Mécanisme de remplacement des standards approuvés Java a été déconseillé sur JDK 1.8_40 dans le but de le supprimer dans JDK 9. Ce mécanisme permettait aux développeurs de rendre des bibliothèques disponibles à toutes les applications déployées en plaçant les JAR dans un répertoire approuvé dans JRE.

Si votre application utilise l'implémentation JBossWS d'Apache CXF, JBoss EAP 7 s'assure que les dépendances requises soient ajoutées dans l'ordre correct et que vous ne soyez pas affecté par ce changement. Si votre application accède directement à Apache CXF, vous devrez désormais fournir les dépendances Apache CXF après avoir fourni les dépendances JBossWS, car cela fait partie de votre déploiement d'application.

5.1.11. Spécification du descripteur dans l'archive EAR

Dans les versions précédentes de JBoss EAP, vous pourriez configurer le fichier descripteur de déploiement jboss-webservices.xml pour les déploiements de service web EJB dans le répertoire META-INF/ des archives JAR ou dans le répertoire WEB-INF/ pour les déploiements de services web POJO et les points de terminaison de services web EJB regroupés en archives WAR.

Avec JBoss EAP 7, vous pouvez désormais configurer le fichier du descripteur de déploiements jboss-webservices.xml dans le répertoire META-INF/ d'une archive EAR. Si un fichier jboss-webservices.xml est trouvé dans l'archive EAR et dans l'archive JAR ou WAR, les données de configuration du fichier jboss-webservices.xml JAR ou WAR remplaceront les données correspondantes du fichier descripteur EAR.

5.2. Mettez à jour le port et le connecteur d'URL distants

Dans JBoss EAP 7, le connecteur par défaut a changé de remote à http-remoting et le port de connexion à distance par défaut est passé de 4447 à 8080. L'URL du fournisseur JNDI pour la configuration par défaut est passé de remote://localhost:4447 à http-remoting://localhost:8080.

Si vous utilisez l'opération migrate de JBoss EAP 7 pour mettre à jour votre configuration, vous n'aurez pas besoin de modifier le connecteur distant, ni le port distant ou l'URL de fournisseur JNDI parce que l'opération de migration préservera les paramètres de configuration du connecteur distant et du port4447 dans la configuration du sous-système. Pour plus d'informations sur l'opération migrate, voir la Gestion des opération de migration par lignes de commande.

Si vous n'utilisez pas l'opération de migrate, et qu'à la place, vous exécutez avec la nouvelle configuration par défaut de JBoss EAP 7, vous devez modifier le connecteur distant, le port distant et l'URL de fournisseur JNDI pour utiliser les nouveaux paramètres, comme décrit ci-dessus.

5.3. Changements dans l'application de messagerie

5.3.1. Remplacer ou mettre à jour des descripteurs de déploiement JMS

Les fichiers de descripteurs de déploiement des ressources JMS propriétaires identifiées par le schéma de dénomination -jms.xml sont déconseillés dans JBoss EAP 7. Vous verrez ci-dessous un exemple de fichier descripteur de déploiement de ressources JMS dans 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>

Si vous avez utilisé des descripteurs JMS -jms.xml dans votre application dans la version précédente, vous pouvez convertir votre application pour utiliser le descripteur de déploiement Java EE 7 standard comme indiqué dans la section EE.5.18 de la spécification Java EE 7, ou vous pouvez mettre à jour le descripteur de déploiement pour utiliser le sous-système messaging-activemq dans JBoss EAP 7.

Si vous choisissez de mettre à jour le descripteur, vous devrez effectuer les modifications suivantes.

  • Remplacez l'espace de noms « urn:jboss:messaging-deployment:1.0 » par « urn:jboss:messaging-activemq-deployment:1.0 ».
  • Remplacez le nom de l'élément <hornetq-server> par <server>.

Le fichier modifié devrait ressembler à l'exemple suivant.

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

Pour obtenir des informations sur les changements de la configuration du serveur liés à la messagerie, veuillez consulter Changements de la configuration du serveur de messagerie.

5.3.2. Mise à jour des clients JMS externes

JBoss EAP 7 continue de prendre en charge l'API JMS 1.1. Ainsi, il n'est pas nécessaire de modifier votre code.

Le connecteur distant et le port distant par défaut ont été modifiés dans JBoss EAP 7. Pour obtenir plus d'informations sur ce changement, voir Mise à jour du port et du connecteur d'URL distants.

Si vous migrez votre configuration de serveur à l'aide de l'opération migrate, les anciens paramètres seront conservés et vous n'aurez pas besoin de mettre à jour votre PROVIDER_URL. Toutefois, si vous exécutez avec la nouvelle configuration par défaut de JBoss EAP 7, vous devrez modifier le PROVIDER_URL dans le code client pour utiliser le nouveau paramètre de configuration http-remoting://localhost:8080. Pour plus d'informations, consultez Migrer la désignation de code client à distance.

Si vous planifiez de migrer votre code pour utiliser l'API JMS 2.0, veuillez voir le quickstart helloworld-jms pour un exemple.

5.3.3. Remplacement de l'API HornetQ

JBoss EAP 6 comprenait le module org.hornetq, qui vous permettait d'utiliser l'API HornetQ dans le code source de votre application.

Apache ActiveMQ Artemis remplace HornetQ dans JBoss EAP 7, donc vous devez migrer tout code qui a utilisé l'API HornetQ pour pouvoir utiliser l' API de Artemis Apache ActiveMQ. Les bibliothèques de cette API se trouvent dans le module org.apache.activemq.artemis.

ActiveMQ Artemis est une évolution d'HornetQ, donc de nombreux concepts s'appliquent toujours.

5.4. Changements dans les applicationsJAX-RS et RESTEasy

La version précédente de JBoss EAP fournissait RESTEasy 2, qui est une implémentation de JAX-RS 1.x. JBoss EAP 7 comprend maintenant 3 RESTEasy, qui est une implémentation de JAX-RS 2.0 définie par la spécification JSR 339 : JAX-RS 2.0 : The Java API for RESTful Web Services. Pour plus d'informations sur l'API de Java des Services Web RESTful, consultez la Spécification de l'API JAX-RS 2.0.

La version de Jackson comprise dans JBoss EAP a changé. L'ancienne version de JBoss EAP comprenait Jackson 1.9.9. JBoss EAP 7 inclut maintenant Jackson 2.6.3 ou version supérieure.

Cette section décrit comment ces changements peuvent avoir un impact sur les applications qui utilisent RESTEasy ou JAX-RS.

5.4.1. Classes dépréciées de RESTEasy

Classes de corps de texte ou d'intercepteurs

JSR 311 : JAX-RS: l'API Java™ des Services Web RESTful ne comprenait pas de framework d'intercepteur, donc RESTEasy 2 en a fourni un. JSR 339 : JAX-RS 2.0 : l'API Java des Services Web RESTful a introduit un framework d'intercepteur et de filtre officiels, donc le framework de l'intercepteur inclus dans RESTEasy 2 est maintenant obsolète et est remplacé par l'intercepteur conforme JAX-RS 2.0 dans RESTEasy 3.x.. Les interfaces pertinentes sont définies dans le paquet javax.ws.rs.ext du module jaxrs-api.

Note

Tous les intercepteurs de l'ancienne version de RESTasy peuvent exécuter en parrallèle avec le nouveau filtre JAX-RS 2.0 et les interfaces de l'intercepteur.

Pour obtenir plus d'informations sur les intercepteurs, voir Intercepteurs RESTEasy dans Développer des applications de services Web dans JBoss EAP.

Pour obtenir plus d'informations sur la nouvelle API de remplacement, voir RESTEasy JAX-RS 3.0.13.Final API ou version supérieure.

API Client

Le framework du client RESTEasy de resteasy-jaxrs a été remplacé par le module resteasy-client conforme à JAX-RS 2.0. De ce fait, certaines classes et méthodes de l'API du clientRESTEasy sont dépréciées.

Note

Pour obtenir davantage d'informations sur les classes d'API org.jboss.resteasy.client.jaxrs, veuillez consulter le RESTEasy JAX-RS JavaDoc.

StringConverter

La classe org.jboss.resteasy.spi.StringConverter est obsolète dans RESTEasy 3.x. Cette fonctionnalité peut être remplacée par la classe JAX-RS 2.0 jax.ws.rs.ext.ParamConverterProvider.

5.4.2. Classes de RESTEasy supprimées ou protégées

Méthodes d'ajout de ResteasyProviderFactory

La plupart des méthodes org.jboss.resteasy.spi.ResteasyProviderFactory add() ont été supprimées ou sont maintenant protégées dans RESTEasy 3.0. Ainsi, les méthodes addBuiltInMessageBodyReader() et addBuiltInMessageBodyWriter() ont été supprimées et les méthodes addMessageBodyReader() et addMessageBodyWriter() sont maintenant protégées.

Vous devriez utiliser les méthodes registerProvider() et registerProviderInstance().

Classes supplémentaires supprimées de RESTEasy 3

L'annotation @org.jboss.resteasy.annotations.cache.ServerCached, qui spécifiait que la réponse à la méthode JAX-RS devait être mise en cache sur le serveur, a été supprimée de RESTEasy 3 et doit être supprimée du code d'application.

5.4.3. Autres changements dans RESTEasy

SignedInput et SignedOuput
  • SignedInput et SignedOutput de resteasy-crypto doivent avoir le Content-Type défini sur multipart/signed dans l'objet Request ou Response, ou en utilisant les annotations @Consumes ou @Produces.
  • SignedOutput et SignedInput peuvent être utilisés pour transformer le format MIME de la application/pkcs7-signature en forme binaire, en définissant ce type dans les annotations @Produces ou @Consumes.
  • Si @Produces ou @Consumes sont de type MIME text/plain, SignedOutput sera encodé en base64 et envoyé en tant que chaîne.
Filtres de sécurité

Les filtres de sécurité @RolesAllowed, @PermitAll, et @DenyAll retournent maintenant l'erreur "403 Forbidden" à la place de "401 Unauthorized".

Filtres côté client

Les nouveaux filtres JAX-RS 2.0 côté client ne seront pas reliés et exécuteront quand vous utilisez l'API de client RESTEasy d'une ancienne version.

Support HTTP asynchrone

Parce que la spécification JAX-RS 2.0 ajoute la prise en charge HTTP asynchrone par l'annotation @Suspended et l'interface AsynResponse, l'API RESTEasy propriétaire d'HTTP asynchrone a été dépréciée et risque d'être supprimée dès RESTEasy 3.1. Le Tomcat asynchrone et les modules de JBoss Web asynchrones ont également été supprimés de l'installation du serveur. Si vous n'utilisez pas le conteneur de Servlet 3.0 ou ultérieur, le traitement HTTP asynchrone côté serveur HTTP sera simulé et exécuté en simultané dans le même thread de demande.

Cache côté serveur

La configuration du cache côté serveur a changé. Veuillez consulter RESTEasy Documentation pour plus d'informations.

5.4.4. Changements apportés à RESTEasy

Exceptions SPI

Toutes les exceptions d'échecs SPI ont été dépréciées et ne sont plus utilisées en interne. Elles ont été remplacées par l'exception JAX-RS 2.0 correspondante.

Exception dépréciéeException de remplacement dans le module jaxrs-api

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 et Registre

Les SPI InjectorFactory et Registry ont changé. Cela ne devrait pas être un problème si vous utilisez le RESTEasy documenté et pris en charge.

5.4.5. Changements dans le fournisseur Jackson

La version de Jackson comprise dans JBoss EAP a changé. L'ancienne version de JBoss EAP comprenait Jackson 1.9.9. JBoss EAP 7 inclut maintenant Jackson 2.6.3 ou version supérieure. De ce fait, le fournisseur Jackson est passé de resteasy-jackson-provider à resteasy-jackson2-provider.

La mise à niveau à resteasy-jackson2-provider requiert certains changements de paquets. Par exemple, le package d'annotations Jackson est passé de org.codehaus.jackson.annotate à com.fasterxml.jackson.annotation.

Pour que votre application puisse utiliser le fournisseur par défaut qui était inclus dans la dernière version de JBoss EAP, voir Activer le fournisseur Jackson par défaut dans Développer des applications de services web de JBoss EAP.

5.4.6. Changements à l'intégration de Spring RESTEasy

Le framework de Spring 4.0 introduisait un support pour Java 8. Si vous avez l'intention d'utiliser l'intégration RESTEasy 3.x avec Spring, veillez à spécifier 4.2.x comme version Spring minimum dans votre déploiement car c'est l'ancienne version la plus stable supportée par JBoss EAP 7.

5.4.7. Changements au fournisseur Jettison RESTEasy

Le fournisseur Jettison RESTEasy est déprécié dans JBoss EAP 7 et n'est plus ajouté aux déploiements par défaut. Nous vous encourageons à passer au fournisseur Jackson RESTEasy recommandé. Si vous préférez continuer à utiliser le fournisseur Jettison, vous devez lui définir une dépendance explicite dans le fichier jboss-deployment-descriptor.xml comme illustré dans l'exemple suivant.

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

Pour plus d'informations sur la façon de définir les dépendances explicites, voir Ajouter une dépendance de module explicite à un déploiement dans le Guide de développement de JBoss EAP.

5.5. Changements à l'application CDI 1.2

JBoss EAP 7 inclut un support à CDI 1.2. De ce fait, les applications écrites avec CDI 1.0 risquent de voir des changements de comportement quand elles sont migrées dans JBoss EAP 7. Cette section résume quelques uns de ces changements uniquement.

Vous allez trouver des informations sur Weld et CDI 1.2 dans les références suivantes :

Archives Bean

Les classes de bean des beans activés doivent être déployées dans les archives de bean pour s'assurer qu'elles soient scannées par CDI afin de trouver et traiter les classes de bean.

Dans CDI 1.0, une archive était définie comme archive de beanexplicite si elle contenait un fichier beans.xml dans le répertoire META-INF/ pour une application cliente, un EJB, ou un JAR de bibliothèque, ou si elle contenait un fichier beans.xml dans le répertoire WEB-INF/ pour un WAR.

CDI 1.1 introduit des archives bean implicites, qui sont des archives qui contiennent une ou plusieurs classes de bean avec une annotation de définition de bean, ou une ou plusieurs session beans. Les archives bean implicites sont scannées par CDI et, au cours de la découverte du type, seules les classes ayant des annotations de définition de bean sont découvertes. Pour plus d'informations, consultez Type et Découverte de bean dans Injection de dépendances et contextes dans la plate-forme Java EE.

Une archive bean possède un mode de découverte de bean coorespondant à all, annoted ou none. Une archive bean qui contient un fichier beans.xml sans version dispose d'un mode de découverte de bean par défaut de all. Une archive de bean qui contient un fichier beans.xml avec la version 1.1 ou version ultérieure doit spécifier l'attribut bean-discovery-mode. La valeur par défaut de l'attribut est annoted.

Une archive n'est pas une archive bean dans les cas suivants :

  • Elle contient un fichier beans.xml avec un mode bean-discovery-mode de none.
  • Elle contient une extension de CDI sans fichier beans.xml.

Une archive est une archive bean explicite dans les cas suivants :

  • L'archive contient un fichier beans.xml avec un numéro de version 1.1 ou ultérieur et un bean-discovery-mode correspondant à all.
  • L'archive contient un fichier beans.xml sans numéro de version.
  • L'archive contient un fichier beans.xml vide.

L'archive est une archive bean implicite dans les cas suivants :

  • L'archive contient une ou plusieurs classes de beans avec une annotation de définition de bean, une ou plusieurs sessions de bean, même si elle ne contient-elle pas de fichier beans.xml.
  • L'archive contient un fichier beans.xml avec un bean-discovery-mode correspondant à annotated.

CDI 1.2 limitait les annotations de définition de bean aux suivantes :

  • Annotations @ApplicationScoped, @SessionScoped, @ConversationScoped, et @RequestScoped
  • Tous les autres types de scopes habituels
  • Annotations @Interceptor et @Decorator
  • Toutes les annotations de stéréotype, qui sont des annotations annotées par @Stereotype
  • Annotations de scope @Dependent

Pour plus d'informations sur les archives de bean, voir les Archives Bean dans Injection de dépendance et contextes dans la plateforme Java EE.

Clarification et Résolution de conversations

Le cycle de vie de contexte de conversation a été changé pour éviter tout conflit avec la spécification du Servlet comme décrit dans Problème de spécification CDI-411. Le scope de conversation est actif durant toutes les requêtes du servlet et ne devrait pas empêcher les autres servlets ou filtres de servlets de fixer le corps de la requête ou le codage de caractères.

Résolution par observation

La résolution de l'événement a été en partie réécrite dans CDI 1.2. Dans CDI 1.0, un événement est remis à une méthode d'observation si la méthode d'observation possède tous les qualificateurs d'événement. Dans CDI 1.2, un événement est remis à une méthode d'observation si la méthode d'observation n'a aucun qualificateur d'événement ou a un sous-ensemble de qualificateurs événement.

5.6. Migrer les dépendances de module explicites

L'introduction du système de chargement de classe modulaire et des Modules JBoss dans la version précédente de JBoss EAP permet un contrôle très précis des classes disponibles aux applications. Cette fonctionnalité vous permet de configurer des dépendances de module explicites en utilisant le fichier MANIFEST.MF de l'application ou le fichier descripteur de déploiement jboss-deployment-structure.xml.

Si vous avez définit des dépendances de module explicites dans votre application, veuillez prendre en compte les changements suivants apportés à JBoss EAP 7.

Examiner les dépendances pour la disponibilité

Les modules inclus dans JBoss EAP ont changé. Lorsque vous migrez votre application vers JBoss EAP 7, veuillez examiner les entrées des fichiers MANIFEST.MF et jboss-deployment-structure.xml afin de vous assurer qu'elles ne font pas référence à des modules supprimés dans cette version du produit.

Dépendances requérant un scan d'annotations

Dans la version précédente de JBoss EAP, si votre dépendance contenait des annotations nécessitant d'être traitées pendant le scan des annotations, comme lors de la déclaration d'intercepteurs EJB, il est requis de générer et d'inclure un index Jandex dans un nouveau fichier JAR et de paramétrer un indicateur dans le fichier descripteur de déploiement MANIFEST.MF ou jboss-deployment-structure.xml.

JBoss EAP 7 permet désormais de générer un runtime automatique des index d'annotations pour les modules statiques, il n'est ainsi plus nécessaire de les générer manuellement. Cependant, vous devrez toujours ajouter l'indicateur annotations au fichier de l'application MANIFEST.MF ou au fichier descripteur de déploiement jboss-deployment-structure.xml comme indiqué ci-dessous.

Exemple d'indicateur d'annotation dans le fichier MANIFEST.MF

Dépendances : com.company.my-ejb annotations, com.company.other

Exemple d'indicateur d'annotation dans le fichier jboss-deployment-structure.xml

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

5.7. Changements de migration Hibernate et JPA

Hibernate ORM 5.0

Si votre application contient un fichier persistence.xml ou si le code utilise les annotations @PersistenceContext ou @PersistenceUnit, JBoss EAP 7 les détectera pendant le déploiement et assumera que l'application utilise JPA. Les bibliothèques Hibernate ORM 5.O sont implicitement ajoutées (ainsi que quelques autres dépendances) au chemin de classe de votre application et ces bibliothèques sont utilisées par défaut.

Hibernate ORM 4.0 - 4.3

Si votre application nécessite que le cache du second niveau soit activé, vous devriez effectuer une migration vers Hibernate ORM 5.0, qui est intégré dans Infinispan 8.0.

Les applications écrites avec Hibernate ORM 4.x peuvent toujours utiliser Hibernate 4.x. Vous devez définir un module JBoss personnalisé pour les JAR Hibernate 4.x et exclure les classes Hibernate 5 de votre application. Cependant, il est fortement recommandé que vous ré-écriviez votre code d'application afin d'utiliser Hibernate 5.

Pour obtenir des informations sur les changements implémentés entre Hibernate 4 et Hibernate 5, veuillez consulter le Guide de migration Hibernate ORM 5.0.

Hibernate ORM 3.0

Les classes d'intégration qui ont facilité l'utilisation d'Hibernate 3 dans la version précédente ont été supprimées de JBoss EAP 7. Si votre application utilise toujours des bibliothues Hibernate 3, il est fortement recommandé de migrer votre application pour utiliser Hibernate 5 car Hibernate 3 ne fonctionnera plus dans JBoss EAP sans fournir de gros efforts. Si vous ne pouvez pas effectuer la migration vers Hibernate 5, vous devrez définir un module JBoss personnalisé pour les JAR Hibernate 3 et exclure les classes Hibernate 5 de votre application.

5.8. Changements apportés à Hibernate Search

La version d'Hibernate Search comprise dans JBoss EAP 7 a changé. L'ancienne version de JBoss EAP comprenait Hibernate Search 4.6.x. JBoss EAP 7 inclut maintenant Hibernate Search 5.5.x.

Hibernate Search 5.5 repose sur Apache Lucene 5.3.1. Si vous utilisez des APIs Lucene natif, assurez-vous de vous aligner avec cette version. L' Hibernate Search 5.5 API encapsule et masque la complexité des nombreux changements des API Lucene qui ont eu lieu entre les versions 3 et 5. Cependant, certaines classes sont désormais déconseillées, renommées ou reconditionnées. Cette section décrit comment ces changements peuvent avoir une incidence sur votre code d'application.

Changements apportés au mappage dans Hibernate Search

Indexation des champs d'id dans les relations intégrées

Quand on utilise une annotation @IndexedEmbedded pour qu'elle puisse inclure des champs en provenance d'une entité liée, l'identifiant de l'entité liée n'est plus inclus. Vous pouvez activer l'inclusion de l'id en utilisant l'attribut includeEmbeddedObjectId de l'annotation @IndexedEmbedded.

@IndexedEmbedded(includeEmbeddedObjectId=true)
Modifications apportées au format d'indexes de dates ou de nombres

Les nombres et des dates sont maintenant indexés sous forme de champs numériques par défaut. Les propriétés de type int, long, float, double et leurs classes wrapper correspondantes ne sont plus indexées sous forme de chaînes. Au lieu de cela, elles sont désormais indexées en utilisant le codage numérique approprié de Lucene. Les champs d'identification (id) sont une exception à cette règle. Même quand ils sont représentés par un type numérique, ils sont toujours indexés comme un mot clé de chaîne par défaut. L'utilisation de @NumericField est désormais obsolète, sauf si vous voulez spécifier une précision personnalisée pour le codage numérique. Vous pouvez garder l'ancien format d'index basés sur une chaîne, en spécifiant explicitement un pont de champ de codage de chaîne. Dans le cas des entiers, c'est org.hibernate.search.bridge.builtin.IntegerBridge. Vérifier le paquet org.hibernate.search.bridge.builtin pour les autres ponts de champs accessibles publiquement.

Les champs Date et Calendrier ne sont plus indexés sous forme de chaînes. Au lieu de cela, les instances sont codées comme valeurs longues représentant le nombre de millisecondes depuis le 1er janvier 1970, 00:00:00 GMT. Vous pouvez changer le format d'indexation en utilisant le nouvel enum EncodingType. Par exemple :

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

Le changement de codage des dates et des nombres est important, et peut avoir un grand impact sur le comportement de l'application. Si vous avez une requête qui cible un champ qui avait été codé précédemment en chaîne, mais qui est maintenant codé numériquement, vous devez mettre la requête à jour. Les champs numériques doivent être recherchés par une requête NumericRangeQuery. Vous devez également vous assurer que tous les champs ciblés par facettage sont en codifiés par chaîne. Si vous utilisez la requête de DSL Search, la requête correcte devra être créée automatiquement pour vous.

Divers changements apportés à Hibernate Search

  • Les options de tri sont améliorées et les champ de codage spécifiés de façon erronée dans les options de tri résultent maintenant en exceptions de runtime. Lucene offre également un système de triage plus performant si les champs utilisés pour le triage sont connus dès le départ. Hibernate Search 5.5 fournit la nouvelle annotation @SortableField et son compagnon multi-valeurs @SortableFields. Consultez le Guide de Migration d'Hibernate Search 5.4 à 5.5 pour plus d'informations.
  • L'API SortField de Lucene exige le changement de code d'application suivant :

    Dans les anciennes versions de JBoss EAP, vous définissiez le type de champ de triage dans la demande comme suit :

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

    Voici un exemple sur la façon de le définir dans JBoss EAP 7.

    fulltextQuery.setSort(new Sort(new SortField("title", SortField.Type.STRING)));
  • Comme SearchFactory ne doit être utilisé que par l'intégration ORM, elle a été déplacée du module de hibernate-search-engine dans le module hibernate-search-orm. D'autres intégrateurs doivent dépendre exclusivement du SearchIntegrator, qui remplace l'ancien SearchFactoryIntegrator.
  • L'enum SpatialMode.GRID a été renommé SpatialMode.HASH.
  • FullTextIndexEventListener est maintenant une classe finale. Si vous étendez cette classe actuellement, vous devez trouver une autres solution pour obtenir la même fonctionnalité.
  • Le module hibernate-search-analyzers a été supprimé. L'approche conseillée est de rediriger l'utilisation de l'artefact de Lucène qui convient, par exemple org.apache.lucene:lucene-analyzers-common.
  • L'API du contrôleur JMS a changé. La dépendance de backend de JMS sur l'ORM d'Hibernate a été supprimée afin qu'elle puisse être utilisée dans d'autres environnements non-ORM. Une des conséquence est que les implémenteurs de org.hibernate.search.backend.impl.jms.AbstractJMSHibernateSearchController doivent s'adapter à la nouvelle signature. Cette classe est une classe interne et il est recommandé de l'utiliser comme exemple au lieu de l'étendre.
  • Le SPI org.hibernate.search.spi.ServiceProvider a été remanié. Si vous intégriez avec l'ancien contrat de service, reportez-vous à la Hibernate Search 5.5 Javadoc du ServiceManager, Service, Startable et Stoppable pour plus de détails sur le nouveau contrat.
  • Si vous avez conservé les indexes générés par Lucene 3.x et que vous ne les avez pas reconstruit dans Hibernate Search 5.0 ou version ultérieure, vous obtiendrez une IndexFormatTooOldException. Il est conseillé de reconstruire les indexes avec l'indexeur en masse. Si vous n'êtes pas capable de le faire, essayez d'utiliser l'IndexUpgrader de Lucene. Vous devez soigneusement mettre à jour les mappages d'Hibernate Search au cas où le comportement par défaut aurait changé. Pour plus d'informations, consultez le Guide de Migration d'Apache Lucene.
  • Apache Lucene est passé de 3.6 à 5.3 dans JBoss EAP 7. Si votre code importe directement des code de Lucene, voir le Guide de Migration d'Apache Lucene pour plus de détails des changements. On trouvera également des informations supplémentaires dans le Journal des changements dans Lucene.
  • Lorsque vous utilisez @Field(indexNullAs=) pour encoder une valeur de marqueur null dans l'index, le type de marqueur doit être compatible avec toutes les autres valeurs qui sont indexées dans ce même champ. Par exemple, il était possible d'encoder une valeur null pour les champs numériques à l'aide d'une chaîne « null ». Ce n'est plus autorisé. Au lieu de cela, vous devez choisir un nombre pour représenter la valeur null, comme -1.
  • Des améliorations de taille ont été apportées au moteur de facettage. La plupart des modifications n'affecte pas l'API. La seule exception notable est que vous devez maintenant annoter tous les champs que vous voulez utiliser pour le facettage avec l'annotation @Facet ou @Facets.

Classes d'Hibernate Search renommées ou re-paquetées

Voici un liste de classes d'Hibernate Search qui ont été renommées ou repaquetées.

Ancien paquet et classeNouveau paquet et classe

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 - Classes renommées ou re-paquetées

Les analyseurs de demandes ont été déplacés dans un nouveau module, résultant en changement de packaging de org.apache.lucene.queryParser.QueryParser à org.apache.lucene.queryparser.classic.QueryParser.

Bon nombre des analyseurs Lucene ont été refactorisés, entraînant des modifications de packaging. Consultez la Documentation d'Apache Lucene pour trouver les paquets de remplacement.

Certaines classes d'utilitaire Apache Solr, par exemple TokenizerFactory ou TokenFilterFactory, ont été déplacés vers Apache Lucene. Si votre application utilise ces utilitaires ou des analyseurs personnalisés, vous devez trouver le nouveau nom du package dans Apache Lucene.

Voir Apache Lucene Migration Guide pour plus d'informations.

Les API d'Hibernate Search dépréciés

Pour obtenir une liste complète des interfaces d'Hibernate Search obsolètes, des classes, des enums, des types d'annotations, des méthodes, des constructeurs, et des constantes d'enum, voir Hibernate Search Deprecated API.

Interfaces d'Hibernate Search dépréciées
InterfaceDescription

org.hibernate.search.store.IndexShardingStrategy

Dépréciée dans Hibernate Search 4.4. Pourrait être supprimée dans Search 5. Utiliser ShardIdentifierProvider à la place.

org.hibernate.search.store.Workspace

Cette interface sera supprimée et ne sera plus considérée publique API [HSEARCH-1915].

Classes d'Hibernate Search dépréciées
ClasseDescription

org.hibernate.search.filter.FilterKey

Les clés de filtrage personnalisées sont dépréciées et devront être supprimées dans Hibernate Search 6. À partir d'Hibernate Search 5.1, les clés pour cacher les filtres de Lucene sont calculées automatiquement sur la base des paramètres de filres donnés.

org.hibernate.search.filter.StandardFilterKey

Les clés de filtrage personnalisées sont dépréciées et devront être supprimées dans Hibernate Search 6. À partir d'Hibernate Search 5.1, les clés pour cacher les filtres de Lucene sont calculées automatiquement sur la base des paramètres de filres donnés.

Enums dépréciés d'Hibernate Search
EnumDescription

org.hibernate.search.annotations.FieldCacheType

Supprimer l'annotation CacheFromIndex si elle est dépréciée. Voir Annotations d'Hibernate dépréciées.

Annotations d'Hibernate Search dépréciées
AnnotationDescription

org.hibernate.search.annotations.CacheFromIndex

Supprimer l'annotation. Aucun autre remplacement n'est nécessaire.

org.hibernate.search.annotations.Key

Les clés de cache de filtre personnalisé constituent une fonctionnalité obsolète et sont programmés pour être supprimées dans Hibernate Search 6. À partir de Hibernate Search 5.1, les clés du cache filtre sont déterminées automatiquement sur la base des paramètres de filtre, donc il n'est plus nécessaire de fournir un objet de clé.

Méthodes dépréciées d'Hibernate Search
MéthodeDescription

org.hibernate.search.FullTextSharedSessionBuilder.autoClose()

Aucun remplacement

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

Aucun remplacement

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

Cela sera supprimé sans remplacement.

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

Cela sera supprimé sans remplacement.

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

Invoquer field().numericField() à la place.

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

Cela sera supprimé sans remplacement.

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

Cette méthode sera remplacée.

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

Utiliser FuzzyContext.withEditDistanceUpTo(int).

Constructeurs d'Hibernate dépréciés
ConstruteursDescription

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

Utiliser NumericFieldMapping.NumericFieldMapping(String, PropertyDescriptor, EntityDescriptor, SearchMapping) à la place.

Changements ayant un impact sur les intégrateurs avancés

Cette section décrit les modifications qui ne font pas partie de l'API publique. Elles ne devraient pas influer le développeur moyen car ces artefacts devraient uniquement être accessibles par les intégrateurs qui étendent le framework d'Hibernate Search.

5.9. Migrer des Beans d'entité CMP vers JPA

Le support aux beans d'entité EJB est facultatif dans Java EE 7 et les beans d'entité ne sont pas supportés dans JBoss EAP 7. Cela signifie que la persistance gérée par conteneur (CMP) (container-managed persistence) et que les beans entity (BMP) (bean-managed persistence ) doivent être réécrits pour utiliser des entités Java Persistence API (JPA) lors de la migration vers JBoss EAP 7.

Dans les versions précédentes de JBoss EAP, des beans d'entité étaient créés dans le code source de l'application en étendant la classe javax.ejb.EntityBean et en implémentant les méthodes requises. Ils étaient ensuite configurés dans le fichier ejb-jar.xml. Un bean d'entité CMP était spécifié en utilisant un élément <entity> qui contenait un élément enfant <persistence-type> avec une valeur de Conteneur. Un entity bean BPM a été spécifié avec un élément <entity> contenant un élément enfant <persistence-type> ayant une valeur de Bean.

Dans JBoss EAP 7, vous devez remplacer tout bean d'entité CMP et BMP dans votre code par des entités JPA (« Java Persistence API »). Les entités JPA sont créées en utilisant les classes javax.persistence.* et sont définies dans le fichier persistence.xml.

Ci-dessous figure un exemple de classe d'entité JPA.

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;
    }

Ci-dessous figure un exemple de fichier persistence.xml.

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

Pour obtenir des exemples d'entités JPA, voir les quickstarts bmt, cmt, et hibernate5 fournis dans JBoss EAP 7.

5.10. Changements dans les propriétés de persistence JPA

Une nouvelles propriété de persistance, jboss.as.jpa.deferdetach, a été ajoutée pour permettre la compatibilité avec le comportement de persistance présent dans les anciennes versions de JBoss EAP.

La propriété jboss.as.jpa.deferdetach contrôle si le contexte de persistance de transaction-scoped utilisé dans un thread de transaction non-JTA détache des entités chargées après chaque appel de l'EntityManager ou si il attend que le contexte de persistance soit fermé, par exemple, lors de l'invocation de bean de session se termine. La valeur de la propriété est par défaut sur false, ce qui signifie que des entités sont détachées ou effacées après chaque appel de l'EntityManager. C'est le comportement par défaut approprié ainsi défini dans la spécification JPA. Si la valeur de la propriété est définie sur true, les entités ne sont pas détachées tant que le contexte de persistance est fermé.

Dans JBoss EAP 5, la persistance se comportait comme si la propriété jboss.as.jpa.deferdetach était définie à la valeur true. Pour obtenir ce même comportement lors de la migration de votre application de JBoss EAP 5 à JBoss EAP 7, vous devez définir la valeur de la propriété jboss.as.jpa.deferdetach sur true dans votre persistence.xml comme illustré dans l'exemple suivant.

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

Dans JBoss EAP 6, la persistance se comportait comme si la propriété jboss.as.jpa.deferdetach était définie à la valeur false. C'est le même comportement que dans JBoss EAP 7, donc aucun changement n'est nécessaire quand vous migrez votre application.

5.11. Migrez le code du client EJB

Le connecteur distant et le port distant par défaut ont été modifiés dans JBoss EAP 7. Pour obtenir plus d'informations sur ce changement, voir Mise à jour du port et du connecteur d'URL distants.

Si vous avez utilisé l'opération migrate pour migrer la configuration de votre serveur, les anciens paramètres sont conservés et vous n'avez pas besoin d'ajouter les modifications détaillées ci-dessous. Toutefois, si vous exécutez avec la nouvelle configuration par défaut de JBoss EAP 7, vous devez ajouter les modifications suivantes.

5.11.1. Mettez à jour le port de connexion distante par défaut

Modifier la valeur de port de la connexion distante 4447 à 8080 dans le fichier jboss-ejb-client.properties.

Ci-dessous figurent des exemples de fichier jboss-ejb-client.properties dans la version précédente et la version actuelle.

Exemple : Fichier JBoss EAP 6 jboss-ejb-client.properties

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

Exemple : Fichier JBoss EAP 7 jboss-ejb-client.properties

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.11.2. Mettez à jour le connecteur par défaut

Dans la nouvelle configuration de JBoss EAP 7, le connecteur par défaut est passé de remote à http-remoting. Ce changement a un impact sur les clients qui utilisent les bibliothèques d'une version de JBoss EAP et pour se connecter au serveur dans une version différente.

  • Si une application cliente utilise la bibliothèque EJB à partir de JBoss EAP 6 et souhaite se connecter au serveur JBoss EAP 7, le serveur doit être configuré pour exposer un connecteur distant « remote » sur un autre port que le port 8080. Le client doit ensuite se connecter en utilisant le connecteur nouvellement configuré.
  • Une application cliente qui utilise la bibliothèque cliente EJB de JBoss EAP 7 et souhaite se connecter au serveur JBoss EAP 6 doit veiller à ce que l'instance du serveur n'utilise pas le connecteur http-remoting, mais le connecteur remote. Ceci est effectué en définissant une nouvelle propriété de connexion côté client.

    remote.connection.default.protocol=remote

5.11.3. Migrez le code du client de nommage distant

Si vous exécutez dans la nouvelle configuration de JBoss EAP 7 par défaut, vous devez modifier votre code client pour utiliser le nouveau connecteur et port distant par défaut.

Voici un exemple sur la façon dont les propriétés d'affectation de noms ont été spécifiées dans le code client de JBoss EAP 6.

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

Voici un exemple sur la façon de spécifier les propriétés d'affectation de noms dans le code client de JBoss EAP 7.

java.naming.factory.initial=org.jboss.naming.remote.client.InitialContextFactory
java.naming.provider.url=http-remoting://localhost:8080

5.12. Migrer les configurations des plans de déploiement

La spécification du déploiement d'applications Java EE (JSR-88) visait à définir un contrat type pour activer les outils provenant de plusieurs fournisseurs pour configurer et déployer des applications sur n'importe quel produit de plateforme Java EE. Le contrat exigeait que les fournisseurs de produits Java EE implémentant les interfaces DeploymentManager et autres interfaces de javax.enterprise.deploy.spi puissent être accédées par les fournisseurs de l'outil. Dans le cas de JBoss EAP 6, un plan de déploiement est identifié par un descripteur XML nommé deployment-plan.xml qui est livré dans une archive ZIP ou JAR.

Cette spécification n'a été que faiblement adoptée car la plupart des produits de serveur d'application fournissent leurs propre solution de déploiement « riche en fonctionnalités ». Pour cette raison, la prise en charge de JSR-88 a été abandonnée sur Java EE 7, et par conséquent par JBoss EAP 7 aussi.

Si vous avez utilisé la JSR-88 pour déployer votre application, vous devez maintenant utiliser une autre méthode pour déployer l'application. La commande CLI de JBoss EAP deploy fournit un moyen standard de déployer des archives dans des serveurs autonomes ou dans des groupes de serveurs dans un domaine géré. Pour plus d'informations sur la gestion par interface en ligne de commandes (CLI), consultez le Guide de gestion en ligne de commandes.

5.13. Migrer des valves d'applications personnalisées

Vous devez migrer manuellement les valves personnalisés ou des valves qui sont définies dans le fichier XML jboss-Web.xml. Cela inclut les valves créées en étendant la classe org.apache.catalina.valves.ValveBase et configurées dans l'élément <valve> du fichier descripteur jboss-Web.xml.

Important

Les valves personnalisées et celles qui sont définies dans le fichier jboss-web.xml ne sont pas automatiquement réécrites ou remplacées par le handler d'Undertow correspondant intégré. Pour obtnenir des informations sur le mappage de valves dans les handlers d'Undertow, voir Migrate JBoss Web Valves.

Les valves d'authentification doivent être remplacées manuellement en utilisant les mécanismes d'authentification intégrés d'Undertow.

Migrer des valves configurées dans les déploiements

Dans JBoss EAP 6, vous pouvez définir des valves personnalisées au niveau de l'application en les configurant dans le fichier descripteur d'application web jboss-Web.xml. Dans JBoss EAP 7, il est possible de le faire avec les handlers d'Undertow également.

Voici un exemple de valve configurée dans le fichier jboss-web.xml de 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>

Pour obtenir plus d'informations sur la façon de créer et de configurer des handlers personnalisés dans JBoss EAP, voir Créer des handlers personnalisés du Guide de développement.

Migrer des valves d'authentificateur personnalisées

Pour obtenir plus d'informations sur la façon de migrer des valves d'authentificateur, voir Changements dans les applications de sécurité

5.14. Changements dans les applications de sécurité

Le remplacement de JBoss Web par Undertow nécessite des modifications de configuration de la sécurité dans JBoss EAP 7.

5.14.1. Migrer des valves d'authentificateur

Les valves d'authentification doivent être remplacées manuellement en utilisant des mécanismes d'authentification intégrés d'Undertow. Voir les sections suivantes pour obtenir des informations sur la façon de migrer les valves d'authentificateur.

5.14.3. Autres changements dans les applications de sécurité

Pour obtenir des informations sur les différences de configuration SSO avec Kerberos, voir Différences de configuration avec les anciennes versions de JBoss EAP dans Comment installer SSO avec Kerberos dans JBoss EAP.

5.15. Changements de la journalisation dans JBoss

Si votre application utilise JBoss Logging, sachez que les annotations dans le paquet org.jboss.logging sont désormais dépréciées dans JBoss EAP 7. Elles ont été mises dans le paquet org.jboss.logging.annotations, donc vous devez mettre à jour votre code source pour importer le nouveau package.

Les annotations sont également passées à un numéro d'identification distinct (ID) pour Maven groupId:artifactId:version (GAV), donc vous devrez ajouter une nouvelle dépendance de projet à org.jboss.logging:jboss-logging-annotations dans votre fichier pom.xml du projet.

Note

Seules les annotations de journalisation ont été déplacées. Le org.jboss.logging.BasicLogger et le org.jboss.logging.Logger existent toujours dans le paquet org.jboss.logging.

Le tableau suivant dresse la liste des classes d'annotations dépréciées et de leurs remplacements.

Tableau 5.1. Remplacement d'annotations de journalisation dépréciées

Classe dépréciéeClasse de remplacement

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.16. Changements au code JavaServer Faces (JSF)

Support JSF 1.2 abandonné

JBoss EAP 6 vous permet de continuer à utiliser JSF 1.2 avec vos déploiemens d'applications en créant un fichier jboss-deployment-structure.xml.

JBoss EAP 7 inclut JSF 2.2 et ne supporte plus l'API JSF 1.2. Si votre application utilise JSF 1.2, vous devrez la réécrire pour utiliser JSF 2.2.

Problème de compatibilité entre JSF 2.1 et JSF 2.2

Les API JSF 2.1 et JSF 2.2 ne sont pas entièrement compatibles. La valeur de la constante FACELET_CONTEXT_KEY est passée de com.sun.faces.facelets.FACELET_CONTEXT à javax.faces.FACELET_CONTEXT entre les versions. Cette valeur est inlined par le compilateur et le code compilé pour une version ne fonctionnera pas avec l'autre.

Les applications qui contiennent du code similaire à l'exemple suivant et sont compilées avec l'API de JSF 2.1, mais qui sont exécutées dans JBoss EAP 7 en utilisant l'API JSF 2.2, engendrent une exception NullPointerException. Pour résoudre ce problème, vous devez recompiler l'application avec l'API JSF 2.2.

Object obj = FacesContext.getCurrentInstance().getAttributes().get(FaceletContext.FACELET_CONTEXT_KEY);

Voir JAVASERVERFACES_SPEC_PUBLIC-1257 pour plus d'informations.

5.17. Changements au niveau du chargement des classes de modules

Dans JBoss EAP 7, le comportement de chargement de classes a changé dans les cas où plusieurs modules contiennent les mêmes classes ou paquets.

Assumons qu'il y ait deux modules, MODULE_A et MODULE_B, dépendant l'un de l'autre et qui contiennent des paquets en commun. Dans JBoss EAP 6, les classes ou les paquets qui étaient chargés à partir des dépendances prévalaient sur ceux spécifiés dans ressource-root du fichier module.xml. Cela signifie que MODULE_A voyait les paquets pour MODULE_B et que MODULE_B voyait les paquets pour MODULE_A. Ce comportement a été source de confusion et pouvait entraîner des conflits. Il a changé dans JBoss EAP 7. Maintenant les classes ou les paquets spécifiés par ressource-root du fichier module.xml prévalent sur ceux qui sont spécifiés par la dépendance. Cela signifie que MODULE_A voit les paquets de MODULE_A et que MODULE_B voit les paquets de MODULE_B. Cela empêche les conflits et offre un comportement plus approprié.

Si vous avez défini des modules personnalisés avec des bibliothèques de ressources-root ou des paquets qui contiennent des classes dupliquées dans leurs dépendances de module, vous pouvez voir les exceptions ClassCastException, LinkageError, des erreurs de chargement de classes, ou autres changements dans le comportement de chargement lorsque vous migrez vers JBoss EAP 7. Pour résoudre ces problèmes, vous devez configurer votre fichier module.xml pour veiller à ce qu'une seule version de classe soit utilisée. Ceci peut être accompli en utilisant l'une des approches suivantes.

  • Vous pouvez éviter de spécifier un resource-root qui multiplie les classes dans la dépendance de module.
  • Vous pouvez utiliser les sous-éléments include et exclude des éléments imports et exports pour contrôler le chargement de classes dans le fichier module.xml. Ce qui suit est un élément d'exportation qui exclut les classes dans le paquet spécifié.

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

Si vous préférez conserver votre comportement existant, vous devez filtrer les paquets de dépendance par la ressource-root dépendante dans le fichier module.xml à l'aide de l'élément filter. Cela vous permet de conserver le comportement existant sans le bouclage singulier qui vous voyez dans JBoss EAP 6. Voici un exemple d'une ressource-root qui filtre les classes dans un package spécifié.

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

Pour obtenir davantage d'informations sur les chargements de classes et les modules, voir Chargements de classes et modules dans le Guide de développement.

5.18. Changements Clustering d'applications

5.18.1. Aperçu sur les fonctionnalités du nouveau clustering

La liste suivante décrit certaines des nouvelles fonctionnalités de clustering avec lesquelles il faut être familiarisé avant la migration de votre application de JBoss EAP 6 à JBoss EAP 7.

  • JBoss EAP 7 présente une nouvelle API publique pour construire des services singleton qui simplifient le processus considérablement. Pour plus d'informations, voir Implémenter un Singleton HA dans Développer des Applications EJB dans JBoss EAP.
  • Un déploiement singleton peut être configuré pour déployer et démarrer sur un seul noeud à la fois dans le cluster. Pour plus d'informations, voir Déploiements Singleton HA du Guide de développement de JBoss EAP.
  • Vous pouvez maintenant définir des MDB singleton clusterisés. Pour plus d'informations, voir MDB Singleton clusterisés dans Développer des applications EJB dans JBoss EAP.
  • JBoss EAP 7 inclut l'implémentation mod_cluster d'Untertow. Il s'agit d'une solution d'équilibrage des charge pure Java, qui ne requiert aucun serveur web httpd. Pour plus d'informations, voir Configurer JBoss EAP en tant que Front-end Load Balancer dans le Guide de configuration.

Le reste de cette section décrit comment les changements niveau clustering peuvent impacter sur la migration de vos applications vers JBoss EAP 7.

5.18.2. Changements apportés au Web Session Clustering

JBoss EAP 7 introduit une nouvelle implémentation sur Web Session Clustering. Il remplace l'implémentation antérieure, qui a été étroitement couplée au code source du sous-système JBoss Web existant.

La nouvelle implémentation de Web Session Clustering impacte sur la façon dont l'application est configurée dans le fichier de descripteur XML de l'application web propiétaire jboss-web.xml. Ce qui suit représente les seuls éléments de configuration de clustering qui subsistent dans ce fichier.

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

Le tableau suivant décrit la procédure pour obtenir un comportement similaire pour les éléments du fichier jboss-web.xml qui sont désormais obsolètes.

Élément de configurationDescription du changement

<max-active-sessions/>

Auparavant, la création d'une session échouait si elle amenait le nombre de sessions actives à dépasser la valeur spécifiée dans <max-active-sessions/>.

Dans la nouvelle implémentation, <max-active-sessions/> est utilisé pour activer la passivation de la session. Si la création de session amène le nombre de sessions actives à dépasser la valeur de <max-active-sessions/>, alors, la session la plus ancienne connue du gestionnaire de session sera passivée pour faire place à la nouvelle session.

<passivation-config/>

L'élément de configuration et ses sous-éléments ne sont plus utilisés dans JBoss EAP 7.

<use-session-passivation/>

Auparavant, la passivation était activée en utilisant cet attribut.

Dans la nouvelle implémentation, la passivation est activée en spécifiant une valeur non-négative pour <max-active-sessions/>.

<passivation-min-idle-time/>

Auparavant, les séances devaient être actives pendant un minimum de temps avant de devenir candidat à la passivation. Cela pouvait entraîner l'échec de créations de sessions, même lorsque la passivation était activée.

Cette nouvelle implémentation ne prend pas en charge cette logique et évite ainsi ce DoS.

<passivation-max-idle-time/>

Auparavant, une session était passivée après avoir été inactive pendant un certain temps.

La nouvelle implémentation ne prend en charge que la passivation lazy, ni ne supporte la passivation eager. Les scéances sont passivées uniquement lorsque cela est nécessaire pour se conformer à <max-active-sessions/>.

<replication-config/>

Un certain nombre de sous-éléments sont dépréciés dans la nouvelle implémentation.

<replication-trigger/>

Auparavant, cet élément était utilisé pour déterminer quand la réplication de session était déclenchée. La nouvelle implémentation remplace cette option de configuration par une stratégie unique et robuste. Pour plus d'informations, consultez Attributs immuables de session dans le Guide de développement de JBoss EAP.

<use-jk/>

Auparavant, l'instance-id du nœud gèrant une demande donnée était annexée à jsessionid, pour les équilibreurs de charge comme mod_jk, mod_proxy_balancer, mod_cluster, selon la valeur spécifiée pour < use-jk/>.

Dans la nouvelle implementation, l'instance-id, si définie, est toujours annexée à jsessionid.

<max-unreplicated-interval/>

Auparavant, cette option de configuration a été conçue comme une optimisation pour empêcher la réplication de l'horodatage de la session si aucun attribut de session n'avait été modifié. Bien que cela semble une bonne chose, dans la pratique, cela n'empêche pas les RPC, car l'accès aux session nécessite les RPC de transaction cache indépendamment de savoir si tous les attributs de session ont changé.

Dans la nouvelle implémentation, l'horodatage d'une session est répliqué pour chaque requête. Cela empêche l'accumulation de métadonnées de sessions périmées après un basculement.

<snapshot-mode/>

Avant, on pouvait configurer <snapshot-mode/> en tant qu'INSTANT ou INTERVAL. Le file d'attente de réplication d'Infinispan rend cette option de configuration obsolète.

<snapshot-interval/>

Cela était utile uniquement pour <snapshot-mode>INTERVAL</snapshot-mode>. Comme le <snapshot-mode/> est obsolète, cette option est obsolète également.

<session-notification-policy/>

Auparavant, la valeur spécifiée par cet attribut définissait une politique de déclenchement d'événements de sessions.

Dans la nouvelle implémentation, ce comportement est basé sur la spécification et n'est pas configurable.

5.18.3. Changements apportés au Stateful Session EJB Clustering (SFSB)

Dans JBoss EAP 6, vous deviez activer le comportement SFSB de l'une des manières suivantes.

  • Vous pouviez ajouter l'annotation org.jboss.ejb3.annotation.Clustered au session bean.

    @Stateful
    @Clustered
    public class MyBean implements MySessionInt {
    
       public void myMethod() {
          //
       }
    }
  • Vous pouviez ajouter l'élément <clustered> au fichier jboss-ejb3.xml.

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

Dans JBoss EAP 7, il n'est plus nécessaire d'activer le comportement de clustering. Par défaut, si le serveur est démarré à l'aide d'un profil HA, l'état des SFSB sera répliqué automatiquement.

Vous pouvez désactiver ce comportement par défaut d'une des manières suivantes.

  • Vous pouvez désactiver le comportement par défaut d'un single stateful session bean avec @Stateful(passivationCapable=false), ce qui est nouveau dans la spécification EJB 3.2.
  • Vous pouvez désactiver ce comportement globalement dans la configuration du sous-système ejb3 de la configuration du serveur.
Note

Si l'annotation @Clustered n'est pas supprimée de l'application, elle sera ignorée tout simplement et cela n'affectera pas le déploiement de l'application.

5.18.4. Changements aux Services de clustering

Dans JBoss EAP 6, les API des services de clustering étaient des modules privés et n'étaient pas pris en charge.

JBoss EAP 7 présente une API de services de clustering publique utilisée par les applications. Les nouveaux services sont conçus pour être légers, injectables facilement, et ne pas nécessiter de dépendances externes.

  • La nouvelle interface org.wildfly.clustering.group.Group donne accès au nouveau statut de cluster actuel et permet d'écouter les changements d'affiliation du cluster.
  • La nouvelle interface org.wildfly.clustering.dispatcher.CommandDispatcher autorise le code existant dans le cluster, sur tous ou quelques sous-éléments des noeuds.

Ces services remplacent des API similaires qui étaient disponibles dans les versions précédentes, comme HAPartition dans JBoss EAP 5, GroupCommunicationService, GroupMembershipNotifier, et GroupRpcDispatcher dans JBoss EAP 6.

Pour obtenir davantage d'informations, voir l'API Public pour le Clustering de Services dans le Guide de développement de JBoss EAP.

5.18.5. Migrer le Clustering HA Singleton

Sur JBoss EAP 6, il n'existait pas d'API publique disponible au service global au cluster HA singleton. Si vous utilisiez des classes privées org.jboss.as.clustering.singleton.*, vous devez changer votre code pour utiliser les nouveaux paquets publics org.wildfly.clustering.singleton.* lorsque vous migrez votre application vers JBoss EAP 7.

Pour obtenir davantage d'informations sur la façon d'implémenter un singleton HA, voir Implémenter un Singleton HA dans Développer des Applications EJB de JBoss EAP.