1. Veuillez tout d'abord vous pencher sur le packaging de votre application et de ses dépendances. Pour plus d'informations, voir Section 3.1.2.3, « Mise à jour des dépendances d'applications en raison des changements de chargement de classes »
2. Si votre application a une journalisation, vous devez spécifier les dépendances du module qui conviennent. Voir Section 3.1.4.1, « Modifier les Dépendances de Logging »
3. En raison des changements dans le chargement de classe modulaire, vous devrez sans doute modifier la structure de votre EAR ou WAR. Voir Section 3.1.5.1, « Modifier l'empaquetage des EAR et des WAR » pour plus d'informations.

Procédure 3.1. Les Dépendances de modules

1. Comment fonctionnent les dépendances implicites ?

   Les déployeurs qui se trouvent dans le serveur ajoutent implicitement et automatiquement certaines dépendances de module communément utilisées, comme javax.api ou sun.jdk. Cela rend les classes visibles au déploiement au moment de l'exécution et soulage le développeur de la tâche d'ajouter explicitement les dépendances. Quand et comment ces dépendances implicites sont ajoutées est expliqué dans la section Implicit Module Dependencies (Dépendances de modules implicites) du chapitre Class Loading and Modules (Chargement de classes et Modules) du Development Guide (Guide de développement) de JBoss EAP 6 https://access.redhat.com/site/documentation/JBoss_Enterprise_Application_Platform/.

2. Comment fonctionnent les dépendances explicites ?

   Pour les autres classes, les modules doivent être spécifiés explicitement sinon les dépendances manquantes entraînent des erreurs de déploiement ou de runtime. Si une dépendance est manquante, vous verrez des traces du style ClassNotFoundExceptions ou NoClassDefFoundErrors dans le journal du serveur. Si plus d'un module charge le même JAR ou si un module charge une classe qui étend une classe chargée dans un module différent, vous verrez des traces ClassCastExceptions dans le journal du serveur. Pour spécifier des dépendances explicitement, modifier MANIFEST.MF ou bien, créer un fichier de descripteur de déploiement spécifique à JBoss jboss-deployment-structure.xml. Pour plus d'informations sur les dépendances de modules, voir Overview of Class Loading and Modules (Aperçu Général des Classes de chargement et Modules) au chapitre Class Loading and Module (Guide de démarrage pour le développement d'applications) du Development Guide (Guide de développement) de JBoss EAP 6 https://access.redhat.com/site/documentation/JBoss_Enterprise_Application_Platform/.

Procédure 3.2. Changer la location des propriétés de ResourceBundle

1. Si vous déployez une archive WAR, vous devez empaqueter ces propriétés dans le dossier WEB-INF/classes/ du WAR.
2. Si vous voulez que ces propriétés soient accessibles à toutes les composantes d'un EAR, alors vous devrez les empaqueter dans un JAR, en tant que root, puis mettre le JAR dans le dossier lib / du EAR.

Procédure 3.3. Créer un module personnalisé

1. Créer et compléter la structure de répertoire module/.
   1. Créer une structure de répertoire sous le répertoire EAP_HOME/module qui contiendra les fichiers et les JAR.

      $ cd EAP_HOME/modules/ 
      $ mkdir -p myorg-conf/main/properties

   2. Déplacer les fichiers de propriétés dans le répertoire EAP_HOME/modules/myorg-conf/main/properties/ que vous avez créé à l'étape précédente.
   3. Créer un fichier module.xml dans le répertoire EAP_HOME/modules/myorg-conf/main/ qui devra contenir l'XML suivant:

      <module xmlns="urn:jboss:module:1.1" name="myorg-conf">
          <resources>
              <resource-root path="properties"/>
          </resources>
      </module>
      

2. Modifier le sous-système ee du fichier de configuration du serveur. Vous pourrez utiliser JBoss CLI, ou bien, vous pourrez éditer le fichier manuellement.
   • Suivez ces étapes pour modifier le fichier de configuration du serveur par le JBoss CLI.
     1. Démarrez le serveur et connectez-vous au Management CLI.
        • Dans Linux, saisir ce qui suit au niveau de la ligne de commande :

          $ EAP_HOME/bin/jboss-cli.sh --connect
          

        • Dans Windows, saisir ce qui suit au niveau de la ligne de commande :

          C:\>EAP_HOME\bin\jboss-cli.bat --connect
          

        Vous devriez voir apparaître le résultat suivant :

        Connected to standalone controller at localhost:9999

     2. Pour créer l'élément <global-modules> myorg-conf dans le sous-système ee, tapez ce qui suit au niveau de la ligne de commande :

        /subsystem=ee:write-attribute(name=global-modules, value=[{"name"=>"myorg-conf","slot"=>"main"}])
        

        Vous devriez voir apparaître le résultat suivant :

        {"outcome" => "success"}
        

   • Suivre ces étapes si vous préférez éditer manuellement le fichier de configuration du serveur.
     1. Arrêter le serveur et ouvrir le fichier de configuration du serveur dans un éditeur de texte. Si vous exécutez sur un serveur autonome, il s'agira du fichier EAP_HOME/standalone/configuration/standalone.xml. Il s'agira du fichier EAP_HOME/domain/configuration/domain.xml si vous exécutez sur un domaine géré.
     2. Chercher le sous-système ee et ajouter le module global de myorg-conf. Ce qui suit est un exemple d'élément du sous-système ee modifié pour inclure l'élément myorg-conf :

        <subsystem xmlns="urn:jboss:domain:ee:1.0" >            
            <global-modules>
                <module name="myorg-conf" slot="main" />            
            </global-modules>
        </subsystem>
        

3. Si vous copiez un fichier nommé my.properties dans l'emplacement de module qui convient, vous pourrez alors charger les fichiers de propriétés en utilisant un code qui ressemble à ceci :

   Thread.currentThread().getContextClassLoader().getResource("my.properties");
   

Procédure 3.4. Mise à jour du code de logging d'application

1. Section 3.1.4.2, « Mise à jour du Code d'application pour les frameworks de Logging (journalisation) de tierce partie »
2. Section 3.1.4.3, « Modifier le code pour utiliser le nouveau framework de JBoss Logging »

Procédure 3.5. Configurer JBoss EAP 6 pour utiliser log4j.properties ou le fichier log4j.xml

1. Créer un jboss-deployment-structure.xml avec le contenu suivant :

   <jboss-deployment-structure>
       <deployment>
           <!-- Exclusions allow you to prevent the server from automatically adding some dependencies -->
           <exclusions>
               <module name="org.apache.log4j" />
           </exclusions>
       </deployment>
   </jboss-deployment-structure>
   

2. Mettez le fichier jboss-deployment-structure.xml dans le répertoire META-INF/ ou WEB-INF/ si vous déployez un WAR, ou dans META-INF/ si vous déployez un EAR. Si votre déploiement inclut des déploiements dépendants supplémentaires, vous devrez également exclure le module de chaque sous-déploiement.
3. Inclure log4j.properties ou le fichier log4j.xml dans le répertoire lib/ de votre EAR, ou dans le répertoire WEB-INF/classes/ de votre déploiement WAR. Si vous souhaitez mettre le fichier dans le répertoire lib/ de votre WAR, vous devrez spécifier le chemin <resource-root> dans le fichier jboss-deployment-structure.xml.

   <jboss-deployment-structure>
       <deployment>
           <!-- Exclusions allow you to prevent the server from automatically adding some dependencies -->
           <exclusions>
               <module name="org.apache.log4j" />
           </exclusions>
           <resources>
               <resource-root path="lib" />
           </resources>
       </deployment>
   </jboss-deployment-structure>
   

4. Démarrer le serveur JBoss EAP 6 avec l'argument de runtime suivant pour éviter de voir apparaître une exception ClassCastException de la console quand vous déployez une application :

   -Dorg.jboss.as.logging.per-deployment=false

5. Déployer votre application.

Procédure 3.6. Configurer les dépendances de journalisation de JBoss EAP 6.3 ou version supérieure

1. Démarrer le serveur JBoss EAP 6 avec l'argument de runtime suivant pour éviter de voir apparaître une exception ClassCastException de la console quand vous déployez une application :

   -Dorg.jboss.as.logging.per-deployment=false

2. Ouvrir un terminal et se connecter au Management CLI.
   • Dans Linux, saisir ce qui suit au niveau de la ligne de commande :

     $ EAP_HOME/bin/jboss-cli.sh --connect
     

   • Dans Windows, saisir ce qui suit au niveau de la ligne de commande :

     C:\>EAP_HOME\bin\jboss-cli.bat --connect
     

3. Modifier l'attribut add-logging-api-dependencies du sous-système de journalisation.
   Cet attribut contrôle si le conteneur ajoute des dépendances d'API de journalisation implicites à votre déploiement.

   • Si défini à true, qui est la valeur par défaut, toutes les dépendances d'API de journalisation implicites seront ajoutées.
   • Si défini à false, les dépendances ne seront pas ajoutées à vos déploiements.
   Pour exclure les dépendances de framework de journalisation, vous devez définir cet attribut à false à l'aide de la commande suivante  :

   /subsystem=logging:write-attribute(name=add-logging-api-dependencies, value=false)

   Cette commande ajoute l'élément <add-logging-api-dependencies> au sous-système logging du fichier de configuration standalone.xml.

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

4. Déployer votre application.

Procédure 3.7. Modifier le code et les dépendances pour utiliser le nouveau framework de JBoss Logging

1. Modifier vos importations et votre code de logging

   Voici un exemple de code qui utilise le framework de JBoss Logging :

   import org.jboss.logging.Level;
   import org.jboss.logging.Logger;
   
   private static final Logger logger = Logger.getLogger(MyClass.class.toString());
   
   if(logger.isTraceEnabled()) {
       logger.tracef("Starting...", subsystem);
   }
   

2. Ajouter la dépendance de logging

   Le JAR qui contient les classes de JBoss Logging se trouve dans le module intitulé org.jboss.logging. Votre fichier MANIFEST-MF devrait ressembler à ceci :

   Manifest-Version: 1.0
   Dependencies: org.jboss.logging
   

   Pour plus d'informations sur la façon de trouver la dépendance de module, consulter Section 3.1.2.3, « Mise à jour des dépendances d'applications en raison des changements de chargement de classes » et Section 4.2.1, « Déboguer et Résoudre les problèmes de migration ».

Procédure 3.8. Modifier l'empaquetage des archives

1. Empaqueter un WAR

   Un WAR est un module simple et toutes les classes du WAR sont chargées par le même chargeur de classes. Cela signifie que les classes packagées dans le répertoire WEB-INF/lib/ sont traitées de la même façon que les classes qui se trouvent dans le répertoire WEB-INF/classes.

2. Empaqueter un EAR

   Un EAR se compose de plusieurs modules. Le répertoire EAR/lib/ est un module unique et chaque sous-déploiement de jar WAR ou EJB du EAR est un module séparé. Les classes n'ont pas accès aux classes dans d'autres modules du EAR, à moins que des dépendances explicites n'aient été définies. Les sous-déploiements ont toujours une dépendance automatique sur le module parent qui leur donne accès aux classes dans le répertoire EAR/lib/. Toutefois, les sous-déploiements n'ont pas toujours une dépendance automatique pour leur permettre de passer de l'un à l'autre. Ce comportement est contrôlé en définissant l'élément <ear-subdeployments-isolated> dans la configuration du sous-système ee comme suit :

   <subsystem xmlns="urn:jboss:domain:ee:1.0" >            
     <ear-subdeployments-isolated>false</ear-subdeployments-isolated>
   </subsystem>

   Défini par défaut à false, ce qui permet aux sous-déploiements de voir les classes qui appartiennent aux autres sous-déploiements du EAR.
   Pour obtenir des informations supplémentaires sur le chargement de classes, voir le chapitre Class Loading and Modules (Chargement de classes et modules) du Development Guide (Guide de développement) de JBoss EAP 6 https://access.redhat.com/site/documentation/JBoss_Enterprise_Application_Platform/.

1. Si votre application utilise une source de données, voir Section 3.1.6.2, « Mise à jour de la Configuration de la Source de données ».
2. Si votre application utilise JPA et regroupe actuellement les JARS Hibernate, voir Section 3.1.6.4, « Configurer la source de données d'Hibernate ou JPA » pour vos options de migration.
3. Si votre application utilise un adaptateur de ressources, voir Section 3.1.6.5, « Mise à jour de la Configuration de l'adaptateur de ressources ».
4. Pour obtenir plus d'informations sur la façon de configurer les changements pour augmenter le niveau de sécurité: Section 3.1.7.1, « Configurer les changements de sécurité d'applications ».

Procédure 3.9. Installer et Configurer le Pilote JDBC

1. Installer le pilote JDBC.

   1. Installer le Pilote JDBC sous forme de déploiement.

      C'est la méthode recommandée pour installer le pilote. Lorsque le pilote JDBC est installé comme un déploiement, il est déployé en tant que JAR ordinaire. Si l'instance de JBoss EAP 6 exécute en serveur autonome, copiez le JAR compatible JDBC 4.0 dans le répertoire EAP_HOME/standalone/deployments/. Si le serveur exécute en domaine géré, vous devez utiliser la Console de gestion ou le Management CLI pour déployer le JAR dans les groupes de serveurs.
      Voici un exemple de pilote MySQL JDBC installé sous forme de déploiement de serveur autonome :

      $cp mysql-connector-java-5.1.15.jar EAP_HOME/standalone/deployments/

      Tout pilote conforme JDBC 4.0 est automatiquement reconnu et installé dans le système avec son nom et sa version. Un JAR conforme JDBC 4.0 contient un fichier-texte nommé META-INF/services/java.sql.Driver qui indique les nom(s) de classe de pilote. Si le pilote n'est pas conforme JDBC 4.0, il peut être rendu déployable par l'un des moyens suivants :

      • Créer et ajouter un fichier java.sql.Driver au JAR dans le chemin META-INF/services/. Ce fichier doit contenir le nom de classe du pilote, par exemple :

        com.mysql.jdbc.Driver

      • Créer un fichier java.sql.Driver dans le répertoire de déploiement. Pour une instance de JBoss EAP 6 exécutant en serveur autonome, le fichier devra aller à l'emplacement suivant : EAP_HOME/standalone/deployments/META-INF/services/java.sql.Driver. Si le serveur est en domaine géré, vous devrez utiliser la Console de gestion ou le Management CLI pour déployer le fichier.
      Les avantages de cette approche :

      • Il s'agit de la méthode la plus aisée car il n'y a nul besoin de définir un module.
      • Quand le serveur exécute dans un domaine géré, les déploiements qui utilisent cette approche sont automatiquement propagés dans tous les serveurs du domaine. Cela signifie que l'administrateur n'a nul besoin de distribuer le JAR Pilote manuellement.

      Les inconvénients de cette approche :

      • Si le pilote JDBC est constitué de plus d'un JAR, par exemple le JAR Pilote, plus un JAR Licence dépendant ou un JAR Localisation, vous ne pouvez pas installer le pilote comme déploiement. Vous devrez alors installer le pilote JDBC comme un module de base.
      • Si le pilote n'est pas conforme à JDBC 4.0, un fichier doit être créé, contenant les noms de classe de pilote et doit être importé dans le JAR ou bien être superposé dans le répertoire deployments/.

   2. Installer un Pilote JDBC comme Core Module.

      Pour installer un pilote JDBC comme module principal, vous devez installer une structure de chemin de fichier sous le répertoire EAP_HOME/modules/. Cette structure contiendra le JAR Pilote JDBC, tout JAR de localisation ou licence supplémentaire, et un fichier module.xml pour définir le module.

      • Installer un Pilote MySQL JDBC comme Core Module

        1. Créer la structure de répertoire de EAP_HOME/modules/com/mysql/main/
        2. Dans le sous-répertoire main/, créer un fichier module.xml qui contient la définition de module suivante pour le pilote MySQL JDBC :

           <?xml version="1.0" encoding="UTF-8"?>
           <module xmlns="urn:jboss:module:1.0" name="com.mysql">
           <resources>
               <resource-root path="mysql-connector-java-5.1.15.jar"/>
           </resources>
           <dependencies>
               <module name="javax.api"/>
           </dependencies>
           </module>
           
           

           Le nom du module "com.mysql" doit correspondre à la structure du répertoire du module. L'élément <dependencies> est utilisé pour spécifier les dépendances de ce module sur les autres modules. Dans un tel cas, comme pour tous les cas comprenant des sources de données JDCB, il sera dépendant des API JDBC qui sont définis dans un autre module nommé javax.api. Ce module se trouve sous le répertoire modules/system/layers/base/javax/api/main/.

           Note

           Veillez à ne PAS laisser d'espace au début du fichier module.xml sinon, vous aurez l'erreur "New missing/unsatisfied dependencies" pour ce pilote.
        3. Copier le pilote JAR MySQL JDBC dans le répertoire EAP_HOME/modules/com/mysql/main/ :

           $ cp mysql-connector-java-5.1.15.jar EAP_HOME/modules/com/mysql/main/

      • Installer le pilote IBM DB2 JDBC et le JAR Licence en tant que module principal.

        Cet exemple est là pour vous démontrer comment déployer les pilotes qui requièrent des JAR en plus du JAR de pilote JDBC.
        1. Créer la structure de répertoire de EAP_HOME/modules/com/ibm/db2/main/
        2. Dans le sous-répertoire main/, créer un fichier module.xml qui contient la définition de module suivante pour le pilote et la licence DB2 JDBC :

           <?xml version="1.0" encoding="UTF-8"?>
           <module xmlns="urn:jboss:module:1.1" name="com.ibm.db2">
             <resources>
               <resource-root path="db2jcc.jar"/>
               <resource-root path="db2jcc_license_cisuz.jar"/>
             </resources>
             <dependencies>
               <module name="javax.api"/>
               <module name="javax.transaction.api"/>
             </dependencies>
           </module>
           

           Note

           Veillez à ne PAS laisser d'espace au début du fichier module.xml sinon, vous aurez l'erreur "New missing/unsatisfied dependencies" pour ce pilote.
        3. Copier le pilote JDBC et le JAR de licence dans le sous-répertoire EAP_HOME/modules/com/ibm/db2/main/

           $ cp db2jcc.jar EAP_HOME/modules/com/ibm/db2/main/
           $ cp db2jcc_license_cisuz.jar EAP_HOME/modules/com/ibm/db2/main/

      Les avantages de cette approche :

      • Il s'agit de la seule approche qui fonctionne quand le pilote JDBC consiste en un JAR au moins.
      • Avec cette approche, les pilotes qui ne sont pas conformes à JDBC 4.0 peuvent être installés sans modifier le JAR Pilote ou créer un fichier superposé.

      Les inconvénients de cette approche :

      • Il est plus difficile de définir un module.
      • Le module doit être copié manuellement dans chaque serveur exécutant dans un domaine géré.

2. Configurer la source de données.

   1. Ajouter le pilote de base de données.

      Ajouter l'élément <driver> à l'élément <drivers> du même fichier. Là aussi, il contiendra les mêmes informations de source de données que celles préalablement définies dans le fichier *-ds.xml.
      Déterminer tout d'abord si le pilote JAR est conforme JDBC 4.0. Un JAR qui est conforme JDBC 4.0 contient un fichier META-INF/services/java.sql.Driver qui indique le nom de la classe du pilote. Le serveur utilise ce fichier pour trouver le nom des classe(s) de pilote du JAR. Un pilote qui est conforme à JDBC 4.0 n'a pas besoin d'élément <driver-class> puisqu'il est déjà spécifié dans le JAR. Voici un exemple d'élément de pilote pour un pilote MySQL conforme JDBC 4.0 :

      <driver name="mysql-connector-java-5.1.15.jar" module="com.mysql"/>
      

      Un pilote qui est conforme JDBC 4.0 a besoin d'un attribut <driver-class> pour identifier la classe du pilote puisqu'il n'y a pas de fichier META-INF/services/java.sql.Driver qui spécifie le nom de classe du pilote. Il s'agit d'un exemple d'élément de pilote non conforme à JDBC 4.0 :

      <driver name="mysql-connector-java-5.1.15.jar" module="com.mysql">
      <driver-class>com.mysql.jdbc.Driver</driver-class></driver>
      

   2. Créer la source de données.

      Créer un élément <datasource> dans la section <datasources> du fichier standalone.xml. Ce fichier contient plus ou moins les mêmes informations de source de données que celles préalablement définies dans le fichier *-ds.xml.

      Important

      Vous devez interrompre le serveur avant de modifier le fichier de configuration du serveur pour que votre changement puisse être persisté au redémarrage du serveur.
      Ce qui suit est un exemple d'élément de source de données MySQL du fichier standalone.xml :

      <datasource jndi-name="java:/YourDatasourceName" pool-name="YourDatasourceName">
        <connection-url>jdbc:mysql://localhost:3306/YourApplicationURL</connection-url>
        <driver>mysql-connector-java-5.1.15.jar</driver>
        <transaction-isolation>TRANSACTION_READ_COMMITTED</transaction-isolation>
        <pool>
          <min-pool-size>100</min-pool-size>
          <max-pool-size>200</max-pool-size>
        </pool>
        <security>
          <user-name>USERID</user-name>
          <password>PASSWORD</password>
        </security>
        <statement>
          <prepared-statement-cache-size>100</prepared-statement-cache-size>
          <share-prepared-statements/>
        </statement>
      </datasource>
      

3. Mettre à jour les références JNDI dans le code d'application.

   Vous devez remplacer les noms de recherche JNDI obsolètes dans le code source d'application pour utiliser les nouveaux noms de source de données standardisés que vous aurez définis. Pour plus d'informations, consulter : Section 3.1.8.4, « Modifier l'application pour qu'elle puisse suivre les nouvelles règles d'espace noms JNDI ».
   Vous devrez également remplacer toute annotation @Resource existante qui accède à la source de données avec le nouveau nom JNDI. Par exemple :

   @Resource(name = "java:/YourDatasourceName").
   

Procédure 3.10. Supprimer le lot Hibernate

1. Supprimer les JAR Hibernate de vos dossiers de bibliothèque d'applications.
2. Supprimer et décommenter l'élément <hibernate.transaction.manager_lookup_class> de votre fichier persistence.xml car cet élément n'est pas utile.

Procédure 3.11. Désactiver les contrôles d'autorisation supplémentaires

• Vous pouvez désactiver le contrôles d'autorisation supplémentaires et continuer d'utiliser les déploiements PicketLink existants par l'une des méthodes suivantes.

  • Définir une propriété système

    Vous pouvez désactiver des contrôles d'autorisation supplémentaires au niveau serveur en définissant la valeur de la propriété système org.jboss.ws.cxf.disableHandlerAuthChecks à true. Cette méthode affecte tout développement effectué dans le serveur d'applications.
    Pour obtenir des informations sur la façon de définir une propriété système, voir la section Configure System Properties Using the Management CLI du guide Administration and Configuration Guide de JBoss EAP.

  • Créer une propriété dans le fichier de descripteur de services Web du déploiement

    Vous pouvez désactiver des contrôles d'authorisation supplémentaires au niveau du déploiement en définissant la valeur de la propriété système org.jboss.ws.cxf.disableHandlerAuthChecks à true dans le fichier jboss-webservices.xml. Cette méthode n'affectera que le déploiement dont il s'agit.
    1. Créer un fichier jboss-webservices.xml dans le répertoire META-INF du déploiement dans lequel vous souhaitez désactiver les contrôles d'authorisation supplémentaires.
    2. Ajouter le contenu suivant :

       <?xml version="1.1" encoding="UTF-8"?>
       <webservices xmlns="http://www.jboss.com/xml/ns/javaee"
         xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
         version="1.2" xsi:schemaLocation="http://www.jboss.com/xml/ns/javaee">
         <property>
           <name>org.jboss.ws.cxf.disableHandlerAuthChecks</name>
           <value>true</value>
         </property>
       </webservices>

Procédure 3.12. Modifier les recherches JNDI

1. Pour en savoir plus Section 3.1.8.2, « Noms JNDI EJB portables »
2. Section 3.1.8.3, « Revue des règles d'espace-noms JNDI »
3. Section 3.1.8.4, « Modifier l'application pour qu'elle puisse suivre les nouvelles règles d'espace noms JNDI »

Procédure 3.13. Configurer l'application

1. Copier les 3 JAR Hibernate dans votre bibliothèque d'applications.

   Vous pourrez sans doute résoudre ce problème en copiant les 3 JAR Hibernate particulières qui contiennent les classes manquantes dans le répertoire de votre application lib/ ou en les ajoutant au chemin de classe par une autre méthode. Dans certains cas, cela peut résulter en ClassCastExceptions ou autre problème de chargement de classe en raison de l'usage mixte de versions Hibernate. Si cela se produit, vous devrez utiliser l'approche suivante.

2. Ordonnez au serveur de n'utiliser que les bibliothèques Hibernate 3.

   JBoss EAP 6 vous permet d'empaqueter les jars de fournisseurs de persistance Hibernate 3.5 (ou version supérieure) dans l'application. Pour instruire le serveur à n'utiliser que les bibiothèques Hibernate 3 et pour exclure les bibliothèques Hibernate 4, vous devrez définir le jboss.as.jpa.providerModule à hibernate3-bundled dans le fichier persistence.xml comme suit :

   <?xml version="1.0" encoding="UTF-8"?>
   <persistence xmlns="http://java.sun.com/xml/ns/persistence" version="1.0">
       <persistence-unit name="plannerdatasource_pu">
           <description>Hibernate 3 Persistence Unit.</description>
           <jta-data-source>java:jboss/datasources/PlannerDS</jta-data-source>
           <properties>
               <property name="hibernate.show_sql" value="false" />
               <property name="jboss.as.jpa.providerModule" value="hibernate3-bundled" />
           </properties>
       </persistence-unit>
   </persistence>
   

   Le déployeur JPA (Java Persistence API) détectera la présence d'un fournisseur de persistences dans l'application et utilisera les bibliothèques d'Hibernate 3. Pour plus d'informations sur les propriétés de la persistence JPA, voir Section 3.2.2.3, « Propriétés d'unité de persistence ».

3. Désactiver le cache Hibernate de second niveau

   Le cache de second niveau d'Hibernate 3 n'a pas le même comportement avec JBoss EAP 6 que dans les versions précédentes. Si vous utilisez un cache Hibernate de second niveau avec votre application, vous devrez le désactiver jusqu'à ce que vous puissiez le mettre à niveau à Hibernate 4. Pour désactiver un cache de second niveau, définir <hibernate.cache.use_second_level_cache> à false dans le fichier persistence.xml.

Procédure 3.14. Mettre à jour l'application pour qu'elle utilise Hibernate 4

1. Le comportement par défaut du générateur de séquence d'auto incrémentation a changé dans JBoss EAP 6. Pour davantage d'informations, consulter Section 3.2.2.5, « Préserve le comportement existant de la valeur de l'identité Hibernate auto-générée ».
2. Déterminer la version d'Hibernate actuellement utilisée par l'application et choisir la procédure de mise à jour qui convient ci-dessous.
   • Section 3.2.2.6, « Migrer votre application Hibernate 3.3.x vers Hibernate 4.x »
   • Section 3.2.2.7, « Migrer votre application Hibernate 3.5.x vers Hibernate 4.x »
3. Voir Section 3.2.2.8, « Modifier les propriétés de persistance pour les applications Seam ou Hibernate migrées qui exécutent dans un environnement clusterisé.  » si vous avez l'intention d'exécuter votre application dans un environnement clusterisé.

1. Mapper le type text à JDBC LONGVARCHAR

   Dans les versions d'Hibernate antérieures à 3.5, le type text était mappé à JDBC CLOB. Un nouveau type Hibernate, materialized_clob, a été ajouté à Hibernate 4 pour mapper les propriétés String Java à JDBC CLOB. Si votre application a des propriétés configurées type="text" qui devraient être mappées à JDBC CLOB, vous devrez faire une des choses suivantes :
   1. Si votre application utilise les fichiers de mappage hbm, modifier la propriété à type="materialized_clob".
   2. Si votre application utilise des annotations, vous devrez remplacer @Type(type = "text") par @Lob.

2. Vérifier le code pour trouver les changements de types de valeurs retournées

   Les projections de critères agrégés numériques renvoient maintenant le même type de valeur que leurs équivalents HQL. De ce fait, les types de renvois des projections suivantes de org.hibernate.criterion ont changé.
   1. En raison de changements dans CountProjection, Projections.rowCount(), Projections.count(propertyName), et Projections.countDistinct(propertyName), les projections de count et count distinct renvoient maintenant une valeur Long.
   2. En raison de changement dans Projections.sum(propertyName), les projections de sum renvoient maintenant un type de valeur qui dépend du type de propriété.

      Note

      Un manquement à modifier votre code d'application pourrait résulter en une exception java.lang.ClassCastException.
      1. Pour les propriétés mappées de type Long, Short, Integer, ou Integer primitifs, une valeur Long est retournée.
      2. Pour les propriétés mappées de type Float, Double, ou Floating point primitive, une valeur Double est retournée.

1. Merger AnnotationConfiguration dans la Configuration.
   Malgré que AnnotationConfiguration est maintenant déprécié, il ne doit pas compromettre votre migration.
   Si vous utilisez encore un fichier hbm.xml, vous devez savoir que la plateforme JBoss EAP 6 utilise maintenant la stratégie de nommage org.hibernate.cfg.EJB3NamingStrategy dans AnnotationConfiguration à la place de org.hibernate.cfg.DefaultNamingStrategy utilisé dans les versions précédentes. Cela peut résulter par des erreurs de nommage. Si vous vous fiez à la stratégie de nommage pour donner un nom de tableau d'association (many-to-many et ensemble d'éléments) par défaut, vous rencontrerez sans doute ce problème. Pour résoudre ceci, vous devez ordonner à Hibernate d'utiliser l'ancienne stratégie org.hibernate.cfg.DefaultNamingStrategy en appelant Configuration#setNamingStrategy et en le passant à org.hibernate.cfg.DefaultNamingStrategy#INSTANCE.
2. Modifier les espace noms pour qu'ils soient conformes aux noms de fichiers DTD Hibernate comme dans le tableau suivant.

   Tableau 3.5. Table de mappage d'espace noms DTD

   Ancien Espace-nom DTD	Nouvel Espace-nom DTD
   http://hibernate.sourceforge.net/hibernate-configuration-3.0.dtd	http://www.hibernate.org/dtd/hibernate-configuration-3.0.dtd
   http://hibernate.sourceforge.net/hibernate-mapping-3.0.dtd	http://www.hibernate.org/dtd/hibernate-mapping-3.0.dtd

3. Modifier les variables d'environnement.
   1. Si vous utilisez Oracle avec les propriétés materialized_clob ou materialized_blob, la variable d'environnement globale hibernate.jdbc.use_streams_for_binary devra être définie à true.
   2. Si vous utilisez PostgreSQL avec les propriétés CLOB ou BLOB, la variable d'environnement globale hibernate.jdbc.use_streams_for_binary devra être définie à false.

Procédure 3.15. Définir les propriétés de persistance pour exécuter dans un environnement clusterisé.

1. Définir la valeur de hibernate.session_factory_name à un nom unique. Ce nom doit être unique pour tous les déploiements d'applications sur l'instance JBoss EAP 6. Par exemple :

   <property name="hibernate.session_factory_name" value="jboss-seam-booking.ear_session_factory"/>
   

2. Définir la valeur de hibernate.ejb.entitymanager_factory_name à un nom unique. Ce nom doit être unique pour tous les déploiements d'applications sur l'instance JBoss EAP 6. Par exemple :

   <property name="hibernate.ejb.entitymanager_factory_name" value="seam-booking.ear_PersistenceUnitName"/>
   

Procédure 3.16. Modifier le fichier persistence.xml pour utiliser Infinispan

1. Configurer Infinispan pour une application JPA dans JBoss EAP 6

   Voici comment vous devez spécifier les propriétés pour obtenir la même configuration pour une application JPA qui utilise Infinispan dans JBoss EAP 6 :

   <property name="hibernate.cache.use_second_level_cache" value="true"/>
   

   De plus, vous devrez spécifier un shared-cache-mode ayant pour valeur ENABLE_SELECTIVE or ALL comme suit :
   • ENABLE_SELECTIVE est la valeur par défaut recommandée. Cela signifie que les entités ne sont pas mises en cache tant que vous ne les avez pas marquées « à mettre en cache » (cachable).

     <shared-cache-mode>ENABLE_SELECTIVE</shared-cache-mode>
     

   • ALL signifie que les entités sont toujours mises en cache, même si vous aviez indiqué qu'elles n'étaient par à mettre en cache.

     <shared-cache-mode>ALL</shared-cache-mode>
     

2. Configurer Infinispan pour une application native Hibernate dans JBoss EAP 6

   Voici comment vous devez spécifier la même configuration pour une application Hibernate native qui utilise Infinispan dans JBoss EAP 6  :

   <property name="hibernate.cache.region.factory_class"
        value="org.jboss.as.jpa.hibernate4.infinispan.InfinispanRegionFactory"/>
   <property name="hibernate.cache.infinispan.cachemanager"
        value="java:jboss/infinispan/container/hibernate"/>     
   <property name="hibernate.transaction.manager_lookup_class"
        value="org.hibernate.transaction.JBossTransactionManagerLookup"/>
   <property name="hibernate.cache.use_second_level_cache" value="true"/>
   
   

   Vous devez également ajouter les dépendances suivantes au fichier MANIFEST.MF :

   Manifest-Version: 1.0
   Dependencies: org.infinispan, org.hibernate
   

Procédure 3.17. Vous devrez sans doute procéder à au moins une des tâches suivantes

1. Accéder au ValidatorFactory par défaut

   JBoss EAP 6 relie la ValidatorFactory par défaut au contexte JNDI sous le nom java:comp/ValidatorFactory.

2. La validation déclenchée par le cycle de vie

   Avec Hibernate Core 4, la validation basée cycle de vie est automatiquement activée par Hibernate Core.
   1. La validation a lieu sur les opérations INSERT, UPDATE, et DELETE.
   2. Vous pouvez configurer les groupes à valider par type d'événement par les propriétés suivantes :

      • javax.persistence.validation.group.pre-persist,
      • javax.persistence.validation.group.pre-update, et
      • javax.persistence.validation.group.pre-remove.

      Les valeurs de ces propriétés sont les noms de classe complets, séparés par des virgules des groupes à valider.
      Les groupes de validation représentent une nouvelle fonctionnalité de Bean Validation. Si vous ne souhaitez pas en profiter, aucun changement n'est requis quand vous migrez vers Hibernate Validator 4.
   3. Vous pouvez désactiver la validation basée cycle de vie en définissant la propriété javax.persistence.validation.mode à none. Les autres valeurs possibles pour cette propriété sont auto (par défaut), callback et ddl.

3. Configurer votre application pour la validation manuelle

   1. Si vous souhaitez contrôler la validation manuellement, vous pourrez créer un Validateur d'une des manières suivantes :

      • Créer une instance de Validator à partir de ValidatorFactory par la méthode getValidator().
      • Injecter des instances de Validateur dans vos EJB,CDI bean ou autre ressource Java EE injectable.
   2. Vous pouvez utiliser le ValidatorContext renvoyé par le ValidatorFactory.usingContext() pour personnaliser votre instance de Validator. Avec cet API, vous pourrez configurer des MessageInterpolator, TraverableResolver et ConstraintValidatorFactory personnalisés. Ces interfaces sont spécifiées dans Bean Validation et sont nouvelles dans Hibernate Validator 4.

4. Modifier le code pour utiliser les nouvelles contraintes de Bean Validation

   Les nouvelles contraintes de validation niveau Bean nécessitent des changements niveau code quand vous migrez vers Hibernate Validator 4.
   1. Pour mettre à niveau vers Hibernate Validator 4, vous devez utiliser les contraintes pour les packages suivants :

      • javax.validation.constraints
      • org.hibernate.validator.constraints
   2. Toutes les contraintes qui existent dans Hibernate Validator 3 sont toujours disponibles dans Hibernate Validator 4. Pour les utiliser, vous aurez besoin d'importer la classe indiquée, et dans certains cas, il vous faudra changer le nom ou le type du paramètre de contrainte.

5. Usage des contraintes personnalisées

   Dans Hibernate Validator 3, une contrainte personnalisée devait implémenter l'interface org.hibernate.validator.Validator. Dans Hibernate Validator 4, vous devez implémenter l'interface javax.validation.ConstraintValidator. Cette interface contient les mêmes méthodes initialize() et isValid() que l'interface précédente, mais la signature de la méthode a changé. De plus, l'altération DDL n'est plus prise en charge dans Hibernate Validator 4.

Procédure 3.18. Créer un pontage JMS

1. Configurer le Pontage sur le serveur JBoss EAP 5.x source

   Pour éviter les conflits de classes entre les sorties, vous devrez suivre les étapes suivantes pour configurer le pontage JMS dans JBoss EAP 5.x. Les noms du répertoire SAR et du pontage sont arbitraires et peuvent être changés si vous le souhaitez.
   1. Créer un sous-répertoire dans le répertoire de déploiement de JBoss EAP 5 qui puisse contenir le SAR, comme par exemple : EAP5_HOME/server/PROFILE_NAME/deploy/myBridge.sar/.
   2. Créer un sous-répertoire nommé META-INF dans EAP5_HOME/server/PROFILE_NAME/deploy/myBridge.sar/.
   3. Créer un fichier jboss-service.xml dans le répertoire EAP5_HOME/server/PROFILE_NAME/deploy/myBridge.sar/META-INF/. Ce fichier devra contenir des informations semblables à celles de l'exemple suivant :

      <server>
         <loader-repository>
            com.example:archive=unique-archive-name
            <loader-repository-config>java2ParentDelegation=false</loader-repository-config>
         </loader-repository> 
      
         <!-- JBoss EAP 6 JMS Provider --> 
         <mbean code="org.jboss.jms.jndi.JMSProviderLoader" name="jboss.messaging:service=JMSProviderLoader,name=EnterpriseApplicationPlatform6JMSProvider">
            <attribute name="ProviderName">EnterpriseApplicationPlatform6JMSProvider</attribute>
            <attribute name="ProviderAdapterClass">org.jboss.jms.jndi.JNDIProviderAdapter</attribute>
            <attribute name="FactoryRef">jms/RemoteConnectionFactory</attribute> 
            <attribute name="QueueFactoryRef">jms/RemoteConnectionFactory</attribute>  
            <attribute name="TopicFactoryRef">jms/RemoteConnectionFactory</attribute>      
            <attribute name="Properties">
               java.naming.factory.initial=org.jboss.naming.remote.client.InitialContextFactory
               java.naming.provider.url=remote://EnterpriseApplicationPlatform6host:4447
               java.naming.security.principal=jbossuser
               java.naming.security.credentials=jbosspass
            </attribute>
         </mbean> 
      
         <mbean code="org.jboss.jms.server.bridge.BridgeService" name="jboss.jms:service=Bridge,name=MyBridgeName" xmbean-dd="xmdesc/Bridge-xmbean.xml">      
            <depends optional-attribute-name="SourceProviderLoader">jboss.messaging:service=JMSProviderLoader,name=JMSProvider</depends>          
            <depends optional-attribute-name="TargetProviderLoader">jboss.messaging:service=JMSProviderLoader,name=EnterpriseApplicationPlatform6JMSProvider</depends>          
            <attribute name="SourceDestinationLookup">/queue/A</attribute>      
            <attribute name="TargetDestinationLookup">jms/queue/test</attribute>       
            <attribute name="QualityOfServiceMode">1</attribute>           
            <attribute name="MaxBatchSize">1</attribute>      
            <attribute name="MaxBatchTime">-1</attribute>           
            <attribute name="FailureRetryInterval">60000</attribute>      
            <attribute name="MaxRetries">-1</attribute>      
            <attribute name="AddMessageIDInHeader">false</attribute>
            <attribute name="TargetUsername">jbossuser</attribute>
            <attribute name="TargetPassword">jbosspass</attribute>
         </mbean>
      </server>
      
      

      Note

      Le load-repository est là pour veiller à ce que le SAR ait un chargeur de classes isolé. Notez également que le JNDI Look-up et que le Pont «cible» incluent les informations d'identification de sécurité pour l'utilisateur "jbossuser" ayant pour mot de passe "jbosspass". C'est parce que JBoss EAP 6 est sécurisé par défaut. L'utilisateur qui ne nomme "jbossuser" et ayant comme mot de passe "jbosspass" a été créé dans Domaine d'application avec le rôle invité utilisant le script EAP_HOME/bin/add_user.sh.
   4. Copier les JAR suivants à partir du répertoire EAP_HOME/modules/system/layers/base/ dans le répertoire EAP5_HOME/server/PROFILE_NAME/deploy/myBridge.sar/. Remplacer chaque VERSION_NUMBER par le numéro de version qui se trouve dans la distro JBoss EAP 6.

      • org/hornetq/main/hornetq-core-VERSION_NUMBER.jar
      • org/hornetq/main/hornetq-jms-VERSION_NUMBER.jar
      • org/jboss/ejb-client/main/jboss-ejb-client-VERSION_NUMBER.jar
      • org/jboss/logging/main/jboss-logging-VERSION_NUMBER.jar
      • org/jboss/logmanager/main/jboss-logmanager-VERSION_NUMBER.jar
      • org/jboss/marshalling/main/jboss-marshalling-VERSION_NUMBER.jar
      • org/jboss/marshalling/river/main/jboss-marshalling-river-VERSION_NUMBER.jar
      • org/jboss/remote-naming/main/jboss-remote-naming-VERSION_NUMBER.jar
      • org/jboss/remoting3/main/jboss-remoting-VERSION_NUMBER.jar
      • org/jboss/sasl/main/jboss-sasl-VERSION_NUMBER.jar
      • org/jboss/netty/main/netty-VERSION_NUMBER.jar
      • org/jboss/remoting3/remote-jmx/main/remoting-jmx-VERSION_NUMBER.jar
      • org/jboss/xnio/main/xnio-api-VERSION_NUMBER.jar
      • org/jboss/xnio/nio/main.xnio-nio-VERSION_NUMBER.jar

      Note

      Ne vous contentez pas de copier EAP_HOME/bin/client/jboss-client.jar parce que les classes API javax vont entrer en conflit avec celles de JBoss EAP 5.x.

2. Configurer un pontage déployé dans de serveur JBoss EAP 6.x de destination

   Dans JBoss EAP 6.1 et dans les versions supérieures, le pontage JMS peut servir à combler des messages depuis n'importe quel serveur compatible JMS 1.1. Comme les ressources JMS source et cible sont recherchées à l'aide de JNDI, les classes de recherche JNDI du fournisseur de messagerie source, ou fournisseur de messages, doivent être regroupées dans un Module de JBoss. Les étapes suivantes utilisent le fournisseur de messages fictive « MyCustomMQ » a titre d'exemple.
   1. Créer le module JBoss pour le fournisseur de messagerie.
      1. Créer une structure de répertoire sous EAP_HOME/modules/system/layers/base/ pour le nouveau module. Le sous-répertoire main/ contiendra les JAR du client et le fichier module.xml. L'exemple suivant est un exemple de structure de répertoires créé pour le fournisseur de messageries MyCustomMQ : EAP_HOME/modules/system/layers/base/org/mycustommq/main/
      2. Dans le sous-répertoire main/, créer un fichier module.xml qui contienne la définition de module suivante pour le fournisseur de messagerie. Ce qui suit est un exemple de module.xml créé pour le fournisseur de messagerie MyCustomMQ.

         <?xml version="1.0" encoding="UTF-8"?>
         <module xmlns="urn:jboss:module:1.1" name="org.mycustommq">
             <properties>
                 <property name="jboss.api" value="private"/>
             </properties> 
         
             <resources>
                 <!-- Insert resources required to connect to the source or target   -->
                 <resource-root path="mycustommq-1.2.3.jar" />
                 <resource-root path="mylogapi-0.0.1.jar" />
             </resources> 
         
             <dependencies>
                <!-- Add the dependencies required by JMS Bridge code                 -->
                <module name="javax.api" />
                <module name="javax.jms.api" />
                <module name="javax.transaction.api"/>
                <!-- Add a dependency on the org.hornetq module since we send         -->
                <!-- messages tothe HornetQ server embedded in the local EAP instance -->
                <module name="org.hornetq" />
             </dependencies>
         </module>
         

      3. Copier les JAR de fournisseur de messagerie requises pour la recherche JNDI des ressources source vers le sous-répertoire main/ du module. La structure du répertoire du module MyCustomMQ ne devra pas ressembler à ce qui suit.

         modules/
         `-- system
             `-- layers
                 `-- base
                     `-- org
                           `-- mycustommq
                               `-- main
                                   |-- mycustommq-1.2.3.jar
                                   |-- mylogapi-0.0.1.jar
                                   |-- module.xml
         

   2. Configurer le pontage JMS dans le sous-système de messaging du serveur JBoss EAP.
      1. Avant de commencer, arrêtez le serveur et sauvegardez les fichiers de configuration du serveur actuel. Si vous exécutez un serveur autonome, il s'agira du fichier EAP_HOME /standalone/configuration/standalone-full-ha.xml. Si vous exécutez un domaine géré, sauvegardez les fichiers EAP_HOME /domain/configuration/host.xml et EAP_HOME /domain/configuration/domain.xml.
      2. Ajouter l'élément jms-bridge au sous-système messaging dans le fichier de configuration du serveur. Les éléments source et target procurent les noms des ressources JMS utlisées pour les recherches JNDI. Si les informations d'authentification user et password sont spécifiées, elles seront passées comme arguments quand une connexion JMS est créée.
         Ce qui suit est un exemple d'élément jms-bridge configuré pour le fournisseur de messagerie MyCustomMQ :

         <subsystem xmlns="urn:jboss:domain:messaging:1.3">
            ...
            <jms-bridge name="myBridge" module="org.mycustommq">
               <source>
                  <connection-factory name="ConnectionFactory"/>
                  <destination name="sourceQ"/>
                  <user>user1</user>
                  <password>pwd1</password>
                  <context>
                     <property key="java.naming.factory.initial" value="org.mycustommq.jndi.MyCustomMQInitialContextFactory"/>
                     <property key="java.naming.provider.url"    value="tcp://127.0.0.1:9292"/>
                  </context>
               </source>
               <target>
                  <connection-factory name="java:/ConnectionFactory"/>
                  <destination name="/jms/targetQ"/>
               </target>
               <quality-of-service>DUPLICATES_OK</quality-of-service>
               <failure-retry-interval>500</failure-retry-interval>
               <max-retries>1</max-retries>
               <max-batch-size>500</max-batch-size>
               <max-batch-time>500</max-batch-time>
               <add-messageID-in-header>true</add-messageID-in-header>
            </jms-bridge>
         </subsystem>
         

         Dans l'exemple suivant, les propriétés JNDI sont définies dans l'élément context pour la source. Si l'élément context est omis, comme dans l'exemple target ci-dessus, les ressources JMS seront recherchées dans l'instance locale.

Procédure 3.19. Avant de commencer

1. Fermer le client et le serveur.
2. Faire une copie de sauvegarde de données JBoss Messaging. Les données du message sont stockées dans la base de données dans des tables ayant pour préfixe JBM_.

Procédure 3.20. Changer le fournisseur en HornetQ

1. Transférer les configurations

   Transférer les configurations JBoss Messaging existantes dans la configuration JBoss EAP 6. Les configurations suivantes se trouvent dans les descripteurs de déploiement qui se situent dans le serveur JBoss Messaging :
   • Configuration du Service des fabriques de connexions
     Cette configuration décrit les fabriques de connexions JMS déployées dans le serveur JBoss Messaging. JBoss Messaging configure les fabriques de connexions dans un fichier nommé connection-factories-service.xml qui se trouve dans le répertoire de déploiement du serveur d'application.
   • Configuration de la destination
     Cette configuration décrit les files d'attente JMS et thèmes déployés avec le serveur JBoss Messaging. Par défaut, JBoss Messaging configure des destinations dans un fichier nommé destination-service.xml qui se trouve dans le répertoire de déploiement du serveur d'application.
   • Configuration du Service de pontage des messages
     Cette configuration comprend les services de pontage déployés dans le serveur JBoss Messaging. Aucun pont n'est déployé par défaut, donc le nom du fichier de déploiement dépend de votre installation JBoss Messaging.

2. Modifier votre code d'application

   Si le code d'application utilise JMS standard, aucune modification de code n'est nécessaire. Cependant, si l'application doit se connecter à un cluster, vous devez soigneusement examiner la documentation HornetQ sur la sémantique de clustering. Clustering déborde le cadre de la spécification JMS. HornetQ et JBoss Messaging ont adopté des approches très différentes dans leurs implémentations respectives de la fonctionnalité de clustering.
   Si l'application utilise les fonctionnalités spécifiques à JBoss Messaging, vous devez modifier le code pour utiliser les fonctionnalités équivalentes disponibles dans HornetQ.
   Pour plus d'informations sur la façon de configurer la messagerie dans HornetQ, voir Section 3.2.7.5, « Configurer la Messagerie dans HornetQ »

3. Migration des messages existants

   Déplacez tous les messages dans la base de données JBoss Messaging du journal de HornetQ à l'aide d'un pont JMS. Les instructions pour configurer le pont JMS se trouvent ici : Section 3.2.7.2, « Configurer un pontage JMS pour migrer les Messages JMS dans JBoss EAP 6 ».

1. Démarrez JBoss EAP 6 avec le clustering activé

   Pour activer le clustering dans JBoss EAP 5.x, vous devrez démarrer vos instances de serveur avec le profil all ou undérivé, comme :

   $ EAP5_HOME/bin/run.sh -c all

   Dans JBoss EAP 6, la méthode d'activation du clustering dépend si les serveurs sont autonomes ou s'ils exécutent dans un domaine géré.

   1. Activer le clustering pour les serveurs qui exécutent dans un domaine géré

      Pour activer le clustering pour les serveurs déjà démarrés, qui utilisent le contrôleur de domaines, mettez à jour votre domain.xml et désignez un groupe de serveurs qui utilise le profil ha et un groupe de liaisons de sockets ha-sockets. Par exemple :

      <server-groups>
        <server-group name="main-server-group" profile="ha">
          <jvm name="default">
            <heap size="64m" max-size="512m"/>
          </jvm>
          <socket-binding-group ref="ha-sockets"/>
        </server-group>
      </server-group>

   2. Activer le clustering pour les serveurs autonomes

      Afin d'activer le clustering dans les serveurs autonomes, démarrez le serveur par le fichier de configuration qui convient comme suit :

      $ EAP_HOME/bin/standalone.sh --server-config=standalone-ha.xml -Djboss.node.name=UNIQUE_NODE_NAME

2. Indiquer l'adresse de liaison

   Dans JBoss EAP 5.x, vous devez normalement indiquer l'adresse de liaison utilisée pour le clustering avec l'argument de ligne de commande -b comme suit :

   $ EAP5_HOME/bin/run.sh -c all -b 192.168.0.2

   JBoss EAP 6 relie les sockets aux adresses IP et aux interfaces contenues dans les éléments <interfaces> des fichiers standalone.xml, domain.xml et host.xml. Les configurations standards fournies dans JBoss EAP incluent deux configurations d'interface :

   <interfaces>
       <interface name="management">
           <inet-address value="${jboss.bind.address.management:127.0.0.1}"/>
       </interface>
       <interface name="public">
          <inet-address value="${jboss.bind.address:127.0.0.1}"/>
       </interface>
   </interfaces>

   Ces configurations d'interface utilisent les valeurs des propriétés système jboss.bind.address.management et jboss.bind.address. Si ces propriétés système ne sont pas définies, la valeur par défaut 127.0.0.1 sera utilisée pour chaque valeur.
   Vous pouvez également spécifier l'adresse de liaison en argument de ligne de commande lorsque vous démarrez le serveur ou vous pouvez la définir explicitement dans le fichier de configuration du serveur JBoss EAP 6.
   • Spécifier l'argument de liaison en ligne de commande quand vous démarrez le serveur JBoss EAP autonome.
     L'exemple suivant explique comment indiquer l'adresse de liaison en ligne de commande pour un serveur autonome :

     EAP_HOME/bin/standalone.sh -Djboss.bind.address=127.0.0.1

     Note

     Vous pouvez également faire usage de l'argument -b, un raccourci de -Djboss.bind.address=127.0.0.1 :

     EAP_HOME/bin/standalone.sh -b=127.0.0.1

     Le format de syntaxe JBoss EAP 5 est également pris en charge :

     EAP_HOME/bin/standalone.sh -b 127.0.0.1

     Notez que l'argument -b ne fait que changer l'interface publique. Il n'affecte pas l'interface de management.
   • Indiquer l'adresse de liaison dans le fichier de configuration du serveur.
     Pour les serveurs qui exécutent en domaines gérés, indiquer les adresses de liaison dans le fichier domain/configuration/host.xml. Pour les serveurs autonomes, indiquer les adresses de liaison dans le fichier standalone-ha.xml.
     Dans l'exemple suivant, l'interface public est spécifiée comme interface par défaut pour tous les sockets au sein du groupe de liaison de socket ha-sockets.

     <interfaces>
       <interface name="management">
         <inet-address value="192.168.0.2"/>
       </interface>
       <interface name="public">
         <inet-address value="192.168.0.2"/>
       </interface>
     </interfaces>

     <socket-binding-groups>
       <socket-binding-group name="ha-sockets" default-interface="public">
         <!-- ... -->
       </socket-binding-group>
     </socket-binding-groups>

     Note

     Si vous spécifiez l'adresse de liaison sous forme de valeur codée en dur et non pas sous forme de propriété système de configuration, vous ne pourrez pas remplacer cette valeur codée par un argument en ligne de commande.

3. Configurer jvmRoute pour supporter mod_jk et mod_proxy

   Dans JBoss EAP 5, le serveur web jvmRoute a été configuré à l'aide d'une propriété dans le fichier server.xml. Dans JBoss EAP 6, l'attribut jvmRoute est configuré dans le sous-système web du fichier de configuration de serveur à l'aide de l'attribut instance-id comme suit :

   <subsystem xmlns="urn:jboss:domain:web:1.1" default-virtual-server="default-host" native="false" instance-id="{JVM_ROUTE_SERVER}">
   

   {JVM_ROUTE_SERVER} ci-dessus doit être remplacé par l'ID du serveur jvmRoute.
   instance-id peut également être défini par le biais de la console de gestion.

4. Indiquer l'adresse multidiffusion et le port

   Dans JBoss EAP 5.x, vous pouvez spécifier l'adresse multidiffusion et le port utilisés pour les communications intra-cluster par les arguments de ligne de commande -u et -m, respectivement, comme ceci :

   $ EAP5_HOME/bin/run.sh -c all -u 228.11.11.11 -m 45688

   Dans JBoss EAP 6, vous pouvez spécifier l'adresse multidiffusion et le port utilisés pour la communication entre les cluster par la liaison de socket référencée par la pile de protocoles JGroup qui convient.

   <subsystem xmlns="urn:jboss:domain:jgroups:1.0" default-stack="udp">
       <stack name="udp">
           <transport type="UDP" socket-binding="jgroups-udp"/>
           <!-- ... -->
       </stack>
   </subsystem>

   <socket-binding-groups>
       <socket-binding-group name="ha-sockets" default-interface="public">
           <!-- ... -->
           <socket-binding name="jgroups-udp" port="55200" multicast-address="228.11.11.11" multicast-port="45688"/>
           <!-- ... -->
       </socket-binding-group>
   </socket-binding-groups>
   

   Si vous voulez spécifier l'adresse de multidiffusion et le port dans la ligne de commande, vous pouvez définir l'adresse de multidiffusion et les ports comme des propriétés système et ensuite utiliser ces propriétés sur la ligne de commande lorsque vous démarrez le serveur. Dans l'exemple suivant, jboss.mcast.addr est le nom de la variable pour l'adresse de multidiffusion et jboss.mcast.port est le nom de la variable pour le port.

   <socket-binding name="jgroups-udp" port="55200"
    multicast-address="${jboss.mcast.addr:230.0.0.4}" multicast-port="${jboss.mcast.port:45688}"/>
   

   Vous pouvez alors démarrer votre serveur en utilisant les arguments de ligne de commande suivants :

   $ EAP_HOME/bin/domain.sh -Djboss.mcast.addr=228.11.11.11 -Djboss.mcast.port=45688

5. Utiliser une pile de protocoles différente

   Dans JBoss EAP 5.x, vous pouviez manipuler la pile de protocoles par défaut utilisée pour tous les services de clustering qui utilisaient la propriété système jboss.default.jgroups.stack.

   $ EAP5_HOME/bin/run.sh -c all -Djboss.default.jgroups.stack=tcp

   Dans JBoss EAP 6, la pile de protocoles par défaut est définie par le sous-système JGroups dans domain.xml ou standalone-ha.xml:

   <subsystem xmlns="urn:jboss:domain:jgroups:1.0" default-stack="udp">
       <stack name="udp">
           <!-- ... -->
       </stack>
   </subsystem>

6. Remplacer la réplication de Buddy

   JBoss EAP 5.x utilise JBoss Cache Buddy Replication pour supprimer la réplication des données dans toutes les instances d'un cluster.
   Dans JBoss EAP 6, la réplication de Buddy a été remplacée par le cache distribué d'Infinispan, connu également sous le nom mode DIST. La distribution est un mode de gestion de clusters puissant qui permet à Infinispan de mettre à échelle en linéaire lorsque un certain nombre de serveurs sont ajoutés au cluster. Voici un exemple sur la façon de configurer le serveur pour utiliser le mode de mise en cache de DIST.
   1. Ouvrir une ligne de commandes et démarrer le serveur avec un Profil HA ou un FUll Profile, comme par exemple :

      EAP_HOME/bin/standalone.sh -c standalone-ha.xml

   2. Ouvrir une nouvelle ligne de commandes et connectez-vous au Management CLI.
      • Dans Linux, saisir ce qui suit au niveau de la ligne de commande :

        $ EAP_HOME/bin/jboss-cli.sh --connect
        

      • Dans Windows, saisir ce qui suit au niveau de la ligne de commande :

        C:\>EAP_HOME\bin\jboss-cli.bat --connect
        

      Vous devriez voir apparaître le résultat suivant :

      Connected to standalone controller at localhost:9999

   3. Lancer les commandes suivantes :

      /subsystem=infinispan/cache-container=web/:write-attribute(name=default-cache,value=dist)
      /subsystem=infinispan/cache-container=web/distributed-cache=dist/:write-attribute(name=owners,value=3)
      :reload
      

      Vous devriez voir la réponse suivante après chaque commande :

      "outcome" => "success"
      

      Ces commandes modifient l'élément dist <distributed-cache> dans la configuration web <cache-container> du sous-système infinispan du fichier standalone-ha.xml comme suit :

      <cache-container name="web" aliases="standard-session-cache" default-cache="dist" module="org.jboss.as.clustering.web.infinispan">
          <transport lock-timeout="60000"/>
          <replicated-cache name="repl" mode="ASYNC" batching="true">
              <file-store/>
          </replicated-cache>
          <replicated-cache name="sso" mode="SYNC" batching="true"/>
          <distributed-cache name="dist" owners="3" l1-lifespan="0" mode="ASYNC" batching="true">
              <file-store/>
          </distributed-cache>
      </cache-container>
      

      Pour plus d'informations, voir le chapitre intitulé Clustering in Web Applications du Development Guide de JBoss EAP 6 qui se situe dans le Portail clients https://access.redhat.com/site/documentation/JBoss_Enterprise_Application_Platform/.

Procédure 3.21. Implémenter un Service HA Singleton

1. Rédiger une application de Service HA Singleton

   Voici un exemple simple de Service se trouvant dans le decorator SingletonService devant être déployé comme service singleton. On trouvera un exemple complet dans le quickstart de cluster-ha-singleton qui est livré avec Red Hat JBoss Enterprise Application Platform 6. Ce quickstart contient toutes les instructions pour générer et déployer l'application.

   1. Créer un service.

      Voici un exemple de service :

      package org.jboss.as.quickstarts.cluster.hasingleton.service.ejb;
      
      import java.util.Date;
      import java.util.concurrent.atomic.AtomicBoolean;
      
      import javax.naming.InitialContext;
      import javax.naming.NamingException;
      
      import org.jboss.logging.Logger;
      import org.jboss.msc.service.Service;
      import org.jboss.msc.service.ServiceName;
      import org.jboss.msc.service.StartContext;
      import org.jboss.msc.service.StartException;
      import org.jboss.msc.service.StopContext;
      
      
      /**
       * @author <a href="mailto:wfink@redhat.com">Wolf-Dieter Fink</a>
       */
      public class HATimerService implements Service<String> {
          private static final Logger LOGGER = Logger.getLogger(HATimerService.class);
          public static final ServiceName SINGLETON_SERVICE_NAME = ServiceName.JBOSS.append("quickstart", "ha", "singleton", "timer");
      
          /**
           * A flag whether the service is started.
           */
          private final AtomicBoolean started = new AtomicBoolean(false);
      
          /**
           * @return the name of the server node
           */
          public String getValue() throws IllegalStateException, IllegalArgumentException {
              LOGGER.infof("%s is %s at %s", HATimerService.class.getSimpleName(), (started.get() ? "started" : "not started"), System.getProperty("jboss.node.name"));
              return "";
          }
      
          public void start(StartContext arg0) throws StartException {
              if (!started.compareAndSet(false, true)) {
                  throw new StartException("The service is still started!");
              }
              LOGGER.info("Start HASingleton timer service '" + this.getClass().getName() + "'");
      
              final String node = System.getProperty("jboss.node.name");
              try {
                  InitialContext ic = new InitialContext();
                  ((Scheduler) ic.lookup("global/jboss-cluster-ha-singleton-service/SchedulerBean!org.jboss.as.quickstarts.cluster.hasingleton.service.ejb.Scheduler")).initialize("HASingleton timer @" + node + " " + new Date());
              } catch (NamingException e) {
                  throw new StartException("Could not initialize timer", e);
              }
          }
      
          public void stop(StopContext arg0) {
              if (!started.compareAndSet(true, false)) {
                  LOGGER.warn("The service '" + this.getClass().getName() + "' is not active!");
              } else {
                  LOGGER.info("Stop HASingleton timer service '" + this.getClass().getName() + "'");
                  try {
                      InitialContext ic = new InitialContext();
                      ((Scheduler) ic.lookup("global/jboss-cluster-ha-singleton-service/SchedulerBean!org.jboss.as.quickstarts.cluster.hasingleton.service.ejb.Scheduler")).stop();
                  } catch (NamingException e) {
                      LOGGER.error("Could not stop timer", e);
                  }
              }
          }
      }
      

   2. Créer un activator qui installe le Service en tant que singleton clusterisé.

      La liste suivante est un exemple d'activtor de service qui installe le HATimerService comme service singleton clusterisé :

      package org.jboss.as.quickstarts.cluster.hasingleton.service.ejb;
      
      import org.jboss.as.clustering.singleton.SingletonService;
      import org.jboss.logging.Logger;
      import org.jboss.msc.service.DelegatingServiceContainer;
      import org.jboss.msc.service.ServiceActivator;
      import org.jboss.msc.service.ServiceActivatorContext;
      import org.jboss.msc.service.ServiceController;
      
      
      /**
       * Service activator that installs the HATimerService as a clustered singleton service
       * during deployment.
       *
       * @author Paul Ferraro
       */
      public class HATimerServiceActivator implements ServiceActivator {
          private final Logger log = Logger.getLogger(this.getClass());
      
          @Override
          public void activate(ServiceActivatorContext context) {
              log.info("HATimerService will be installed!");
      
              HATimerService service = new HATimerService();
              SingletonService<String> singleton = new SingletonService<String>(service, HATimerService.SINGLETON_SERVICE_NAME);
              /*
               * To pass a chain of election policies to the singleton, for example, 
               * to tell JGroups to prefer running the singleton on a node with a
               * particular name, uncomment the following line:
               */
              // singleton.setElectionPolicy(new PreferredSingletonElectionPolicy(new SimpleSingletonElectionPolicy(), new NamePreference("node2/cluster")));
      
              singleton.build(new DelegatingServiceContainer(context.getServiceTarget(), context.getServiceRegistry()))
                      .setInitialMode(ServiceController.Mode.ACTIVE)
                      .install()
              ;
          }
      }
      

      Note

      L'exemple de code ci-dessus utilise une classe, org.jboss.as.clustering.singleton.SingletonService, qui fait partie de l'API privée de JBoss EAP. Une API publique deviendra disponible dans la version EAP 7 et les classes privées seront obsolètes, mais ces classes seront entretenues et rendues disponible pendant toute la durée du cycle de version EAP 6.x.

   3. Créer un fichier ServiceActivator

      Créer un fichier nommé org.jboss.msc.service.ServiceActivator dans le répertoire resources/META-INF/services/ de l'application. Ajouter une ligne contenant le nom complet de la classe de Service Activator créée dans l'étape précédente.

      org.jboss.as.quickstarts.cluster.hasingleton.service.ejb.HATimerServiceActivator 

   4. Créer un bean singleton qui implémente une minuterie de signleton à utiliser dans tout le cluster.

      Ce bean Singleton ne doit pas avoir d'interface distante et ne doit pas référencer son interface locale à partir d'un autre EJB d'application. Cela évite une recherche client ou de la part d'un autre composant et assure un parfait contrôle du Singleton par le SingletonService.

      1. Créer une interface de planification.

         package org.jboss.as.quickstarts.cluster.hasingleton.service.ejb;
         
         /**
          * @author <a href="mailto:wfink@redhat.com">Wolf-Dieter Fink</a>
          */
         public interface Scheduler {
         
             void initialize(String info);
         
             void stop();
         
         }
         

      2. Créer le bean Singleton qui implémente la minuterie de signleton à utiliser dans tout le cluster.

         package org.jboss.as.quickstarts.cluster.hasingleton.service.ejb;
         
         import javax.annotation.Resource;
         import javax.ejb.ScheduleExpression;
         import javax.ejb.Singleton;
         import javax.ejb.Timeout;
         import javax.ejb.Timer;
         import javax.ejb.TimerConfig;
         import javax.ejb.TimerService;
         
         import org.jboss.logging.Logger;
         
         
         /**
          * A simple example to demonstrate a implementation of a cluster-wide singleton timer.
          *
          * @author <a href="mailto:wfink@redhat.com">Wolf-Dieter Fink</a>
          */
         @Singleton
         public class SchedulerBean implements Scheduler {
             private static Logger LOGGER = Logger.getLogger(SchedulerBean.class);
             @Resource
             private TimerService timerService;
         
             @Timeout
             public void scheduler(Timer timer) {
                 LOGGER.info("HASingletonTimer: Info=" + timer.getInfo());
             }
         
             @Override
             public void initialize(String info) {
                 ScheduleExpression sexpr = new ScheduleExpression();
                 // set schedule to every 10 seconds for demonstration
                 sexpr.hour("*").minute("*").second("0/10");
                 // persistent must be false because the timer is started by the HASingleton service
                 timerService.createCalendarTimer(sexpr, new TimerConfig(info, false));
             }
         
             @Override
             public void stop() {
                 LOGGER.info("Stop all existing HASingleton timers");
                 for (Timer timer : timerService.getTimers()) {
                     LOGGER.trace("Stop HASingleton timer: " + timer.getInfo());
                     timer.cancel();
                 }
             }
         }
         

2. Démarrez chaque instance de JBoss EAP 6 avec le clustering activé.

   Pour activer le clustering dans les serveurs autonomes, démarrer chaque serveur par le profil HA, en utilisant un nom de code unique et un offset (décallage) de port pour chaque instance comme suit :
   • Dans Linux, on utilise la commande suivante pour démarrer les serveurs :

     EAP_HOME/bin/standalone.sh --server-config=standalone-ha.xml -Djboss.node.name=UNIQUE_NODE_NAME -Djboss.socket.binding.port-offset=PORT_OFFSET

     Exemple 3.1. Démarrage de multiples serveurs autonomes sur Linux

     $ EAP_HOME/bin/standalone.sh --server-config=standalone-ha.xml -Djboss.node.name=node1
     $ EAP_HOME/bin/standalone.sh --server-config=standalone-ha.xml -Djboss.node.name=node2 -Djboss.socket.binding.port-offset=100

   • Dans Microsoft Windows, on utilise la commande suivante pour démarrer les serveurs :

     EAP_HOME\bin\standalone.bat --server-config=standalone-ha.xml -Djboss.node.name=UNIQUE_NODE_NAME -Djboss.socket.binding.port-offset=PORT_OFFSET

     Exemple 3.2. Démarrage de multiples serveurs autonomes dans Microsoft Windows

     C:> EAP_HOME\bin\standalone.bat --server-config=standalone-ha.xml -Djboss.node.name=node1
     C:> EAP_HOME\bin\standalone.bat --server-config=standalone-ha.xml -Djboss.node.name=node2 -Djboss.socket.binding.port-offset=100

   Note

   Si vous ne souhaitez pas utiliser des arguments en ligne de commande, vous pouvez configurer le fichier standalone-ha.xml pour que chaque instance de serveur puisse se lier à une interface séparée.

3. Déployer l'application dans les serveurs

   Si vous utilisez la commande Maven suivante pour déployer votre application dans un serveur autonome qui exécute sur les ports par défaut.

   mvn clean install jboss-as:deploy

   To deploy to additional servers, pass the server name. if it is on a different host, pass the host name and port number on the command line:

   mvn clean package jboss-as:deploy -Djboss-as.hostname=localhost -Djboss-as.port=10099

   Voir le quickstart cluster-ha-singleton fourni dans JBoss EAP 6 pour la configuration et les détails de déploiement de Maven.

Procédure 3.22. Ajouter une configuration de projet Maven pour l'invocation à distance des session beans

1. Ajouter les dépendances de projet utiles

   Le pom.xml du projet doit être mis à jour pour pouvoir inclure les dépendances nécessaires.

2. Ajouter le fichier jboss-ejb-client.properties

   L'API du client JBoss EJB s'attend à trouver un fichier dans le root du projet nommé jboss-ejb-client.properties qui contient les informations de connexion aux services JNDI. Ajouter ce fichier au répertoire src/main/resources/ de votre projet avec le contenu suivant.

   # In the following line, set SSL_ENABLED to true for SSL
   remote.connectionprovider.create.options.org.xnio.Options.SSL_ENABLED=false
   remote.connections=default
   # Uncomment the following line to set SSL_STARTTLS to true for SSL
   # remote.connection.default.connect.options.org.xnio.Options.SSL_STARTTLS=true
   remote.connection.default.host=localhost
   remote.connection.default.port = 4447
   remote.connection.default.connect.options.org.xnio.Options.SASL_POLICY_NOANONYMOUS=false
   # Add any of the following SASL options if required
   # remote.connection.default.connect.options.org.xnio.Options.SASL_POLICY_NOANONYMOUS=false
   # remote.connection.default.connect.options.org.xnio.Options.SASL_POLICY_NOPLAINTEXT=false
   # remote.connection.default.connect.options.org.xnio.Options.SASL_DISALLOWED_MECHANISMS=JBOSS-LOCAL-USER
   

   Changer le nom d'hôte et le port pour qu'ils correspondent au serveur. 4447 est le numéro de port par défaut. Pour une connexion sécurisée, définir la ligne SSL_ENABLED à true et dé-commenter la ligne SSL_STARTTLS. L'interface éloignée du conteneur supporte les connexions sécurisées et non sécurisées en utilisant le même port.

3. Ajouter des dépendances aux interfaces commerciales à distance.

   Ajouter les dépendances Maven au pom.xml aux interfaces commerciales éloignées des session beans.

   <dependency>
      <groupId>org.jboss.as.quickstarts</groupId>
      <artifactId>jboss-ejb-remote-server-side</artifactId>
      <type>ejb-client</type>
      <version>${project.version}</version>
   </dependency>

Procédure 3.23. Obtenez un Bean Proxy par JNDI et invoquez les méthodes du Bean

1. Exceptions vérifiées par Handle

   Deux des méthodes utilisées dans le code suivant (InitialContext() et lookup()) ont une exception vérifiée du type javax.naming.NamingException. Ces appels de méthode doivent soit être contenus dans un bloc try/catch qui intercepte NamingException ou dans une méthode déclarée pour lancer NamingException. Le Quickstart ejb-remote utilise la seconde technique.

2. Créer un contexte JNDI

   Un objet de contexte JNDI fournit le mécanisme pour demander les ressources dans le serveur. Créer un contexte JNDI avec le code suivant :

   final Hashtable jndiProperties = new Hashtable();
   jndiProperties.put(Context.URL_PKG_PREFIXES, "org.jboss.ejb.client.naming");
   final Context context = new InitialContext(jndiProperties);

   Les propriétés de connexion du service JNDI sont lues à partir du fichier jboss-ejb-client.properties.

3. Utiliser la méthode JNDI Context's lookup() pour obtenir un Bean Proxy

   Invoquer le méthode lookup() du bean proxy et lui faire passer le nom JNDI du session bean dont vous avez besoin. Un objet sera renvoyé et il devra correspondre au type de méthode d'interface commerciale qui contient les méthodes que vous souhaitez invoquer.

   
   final RemoteCalculator statelessRemoteCalculator = (RemoteCalculator) context.lookup(
       "ejb:/jboss-ejb-remote-server-side//CalculatorBean!" + 
       RemoteCalculator.class.getName());
   

   Les noms de session bean JNDI sont définis par une syntaxe particulière. Pour plus d'informations, consulter Section 3.2.10.3, « Référence de nommage EJB JNDI » .

4. Méthodes d'invocation

   Maintenant que vous avez un objet bean proxy, vous pouvez invoquer n'importe quelle méthode qui contient l'interface commerciale distante.

   int a = 204;
   int b = 340;
   System.out.println("Adding " + a + " and " + b + " via the remote stateless calculator deployed on the server");
   int sum = statelessRemoteCalculator.add(a, b);
   System.out.println("Remote calculator returned sum = " + sum);

   Le proxy bean transmet la demande d'invocation de méthode au bean de session sur le serveur, où elle est exécutée. Le résultat est retourné au proxy bean qui, ensuite, le retourne à l'appelant. La communication entre le proxy bean et le bean de session distant est transparente à l'appelant.

Procédure 3.25. Migrer les Archives Seam 2.2

1. Mettre à jour la configuration de la source de données

   Certains exemples Seam 2.2 utilisent la source de données JDBC par défaut nommée java:/ExampleDS. Cette source de données par défaut a changé dans JBoss EAP 6 en java:jboss/datasources/ExampleDS. Si votre application utilise la base de donnée de l'exemple, vous pourrez faire ce qui suit :

   • Si vous voulez utiliser la base de données de l'exemple fourni dans JBoss EAP 6, modifier le fichier META-INF/persistence.xml pour remplacer l'élément jta-data-source existant par le nom JNDI de la source de données :

     <!-- <jta-data-source>java:/ExampleDS</jta-data-source> -->
     <jta-data-source>java:jboss/datasources/ExampleDS</jta-data-source>

   • Si vous préférez conserver votre base de données existante, vous pouvez ajouter la définition de votre base de données dans le fichier EAP_HOME/standalone/configuration/standalone.xml.

     Important

     Vous devez interrompre le serveur avant de modifier le fichier de configuration du serveur pour que votre changement puisse être persisté au redémarrage du serveur.
     Voici une définition qui est une copie de la source de données HSQL par défaut définie dans JBoss EAP 6.

     <datasource name="ExampleDS" jndi-name="java:/ExampleDS" enabled="true" jta="true" use-java-context="true" use-ccm="true">
        <connection-url>jdbc:h2:mem:test;DB_CLOSE_DELAY=-1</connection-url>
        <driver>h2</driver>
        <security>
           <user-name>sa</user-name>
           <password>sa</password>
        </security>
     </datasource>

   • Vous pouvez également ajouter la définition de source de données à l'aide de l'interface de ligne de commande. Voici un exemple de la syntaxe, que vous devez utiliser pour ajouter une source de données. Le « \ » à la fin de la ligne indique la continuation de la commande sur la ligne suivante.

     Exemple 3.3. Exemple de syntaxe à ajouter à la définition de la source de données

     $ EAP_HOME/bin/jboss-cli --connect 
     [standalone@localhost:9999 /] data-source add --name=ExampleDS --jndi-name=java:/ExampleDS \ 
           --connection-url=jdbc:h2:mem:test;DB_CLOSE_DELAY=-1 --driver-name=h2 \ 
           --user-name=sa --password=sa
     

   Pour obtenir plus d'informations sur la façon de configurer une source de données, voir Section 3.1.6.2, « Mise à jour de la Configuration de la Source de données ».

2. Ajouter une dépendance requise

   Comme les applications Seam 2.2 utilisent JSF 1.2, vous devez ajouter des dépendances aux modules de JSF 1.2 et exclure les modules de JSF 2.0. Pour ce faire, vous devez créer un fichier jboss-deployment-structure.xml dans le répertoire EAR META-INF/ qui contient les données suivantes :

   <jboss-deployment-structure xmlns="urn:jboss:deployment-structure:1.0">
     <deployment>
         <dependencies>
           <module name="javax.faces.api" slot="1.2" export="true"/>
                 <module name="com.sun.jsf-impl" slot="1.2" export="true"/>
         </dependencies>
     </deployment>
     <sub-deployment name="jboss-seam-booking.war">
       <exclusions>
           <module name="javax.faces.api" slot="main"/>
                 <module name="com.sun.jsf-impl" slot="main"/>
         </exclusions>
         <dependencies>
           <module name="javax.faces.api" slot="1.2"/>
                 <module name="com.sun.jsf-impl" slot="1.2"/>
         </dependencies>
     </sub-deployment>
   </jboss-deployment-structure>

   Si votre application utilise n'importe quel framework de logging de tiece partie, vous devez ajouter ces dépendances comme décrit ici : Section 3.1.4.1, « Modifier les Dépendances de Logging ».

3. Si votre application utilise Hibernate 3.x, essayez tout d'abord d'exécuter l'application en utilisant les bibliothèques Hibernate 4

   Si votre application n'utilise pas le contexte de persistance gérée par Seam, la recherche Hibernate, la validation ou autres éléments qui ont été modifiés dans Hibernate 4, vous pourrez exécuter avec les bibliothèques d'Hibernate 4. Toutefois, si vous voyez ClassNotFoundExceptions ou ClassCastExceptions pointant vers des classes Hibernate, ou voir des erreurs similaires à ce qui suit, vous devrez suivre les instructions à l'étape suivante et modifier l'application pour utiliser les bibliothèques d'Hibernate 3.3.

           Caused by: java.lang.LinkageError: loader constraint violation in interface itable initialization: when resolving method "org.jboss.seam.persistence.HibernateSessionProxy.getSession(Lorg/hibernate/EntityMode;)Lorg/hibernate/Session;" the class loader (instance of org/jboss/modules/ModuleClassLoader) of the current class, org/jboss/seam/persistence/HibernateSessionProxy, and the class loader (instance of org/jboss/modules/ModuleClassLoader) for interface org/hibernate/Session have different Class objects for the type org/hibernate/Session used in the signature
   

4. Copier les archives dépendantes en provenance de frameworks extérieurs ou d'autres locations.

   Si votre application utilise Hibernate 3.x et que vous n'êtes pas en mesure d'utiliser Hibernate 4 avec succès avec votre application, vous devrez copier les JARs Hibernate 3.x dans le répertoire / lib et exclure le module Hibernate de la section de déploiements de META-INF/jboss-déploiement-structure.xml comme suit :

   <jboss-deployment-structure xmlns="urn:jboss:deployment-structure:1.0">
    <deployment>
      <exclusions>
        <module name="org.hibernate"/>
      </exclusions>
    <deployment>
   </jboss-deployment-structure>

   Il y a des étapes supplémentaires que vous devez prendre pour grouper Hibernate 3.x avec votre application. Pour plus d'informations, consultez Section 3.2.2.2, « Configuration des changements des applications qui utilisent Hibernate et JPA ».

5. Débogger et résoudre les erreurs de Seam 2.2 JNDI

   Quand vous migrez une application Seam 2.2, vous apercevez sans doute les erreurs javax.naming.NameNotFoundException dans le log, sous la forme :

   javax.naming.NameNotFoundException: Name 'jboss-seam-booking' not found in context ''

   Si vous ne voulez pas modifier les recherches JNDI dans tout le code, vous pouvez modifier les fichiers components.xml de l'application comme suit :

   1. Remplacer l'élément core-init existant

      Tout d'abord, vous devrez remplacer l'élément core-init existant comme suit :

      <!-- <core:init jndi-pattern="jboss-seam-booking/#{ejbName}/local" debug="true" distributable="false"/>   -->
      <core:init debug="true" distributable="false"/>
      

   2. Cherchez les messages JNDI binding INFO dans la log du serveur

      Puis, vous devrez chercher les messages JNDI binding INFO dans la log du serveur quand l'application est déployée. Les messages de liaison JNDI ressemblent à ce qui suit :

      INFO org.jboss.as.ejb3.deployment.processors.EjbJndiBindingsDeploymentUnitProcessor (MSC service thread 1-1) JNDI bindings for session bean
      named AuthenticatorAction in deployment unit subdeployment "jboss-seam-booking.jar" of deployment "jboss-seam-booking.ear" are as follows:
          java:global/jboss-seam-booking/jboss-seam-booking.jar/AuthenticatorAction!org.jboss.seam.example.booking.Authenticator
          java:app/jboss-seam-booking.jar/AuthenticatorAction!org.jboss.seam.example.booking.Authenticator
          java:module/AuthenticatorAction!org.jboss.seam.example.booking.Authenticator
          java:global/jboss-seam-booking/jboss-seam-booking.jar/AuthenticatorAction
          java:app/jboss-seam-booking.jar/AuthenticatorAction
          java:module/AuthenticatorAction
      

   3. Ajouter des éléments de composants

      Pour chaque message JNDI binding INFO du log, ajouter un élément component correspondant au fichier components.xml :

      <component class="org.jboss.seam.example.booking.AuthenticatorAction" jndi-name="java:app/jboss-seam-booking.jar/AuthenticatorAction" />

   Pour en savoir davantage sur la façon de déboguer et résoudre les problèmes de migration, voir Section 4.2.1, « Déboguer et Résoudre les problèmes de migration ».
   Pour obtenir une liste des problèmes de migration avec Seam 2, voir Section 3.2.13.2, « Problèmes de Migrations d'archives dans Seam 2.2 ».