Chapitre 3. Migration de votre application

1. Veuillez, tout d'abord, regarder 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'application liées à des changements de chargement de classes »

2. Si votre application a une journalisation, vous devez spécifier les dépendances du module qui convient. Voir Section 3.1.4.1, « Modifier les Dépendances de Logging »
3. 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 Enterprise Application Platform 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 un 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 Enterprise Application Platform 6 https://access.redhat.com/site/documentation/JBoss_Enterprise_Application_Platform/.

Procédure 3.2. 

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

      $ 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
          $ Connected to standalone controller at localhost:9999
          

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

          C:\>EAP_HOME\bin\jboss-cli.bat --connect
          C:\> Connected to standalone controller at localhost:9999
          

     2. Pour créer le sous-système myorg-conf<global-modules> element in the 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 Logging (journalisation) de JBoss Logging »

Procédure 3.5. Configurer JBoss Enterprise Application Platform 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.
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.
4. Déployer votre application.

Procédure 3.6. 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'application liées à des changements de chargement de classes » et Section 4.2.1, « Débogger et Résoudre les problèmes de migration ».

Procédure 3.7. 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 d'accéder 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 Enterprise Application Platform 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.8. 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 Enterprise Application Platform 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é, copier le JAR dans le répertoire EAP_HOME/domain/deployments/.
      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 de 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 Enterprise Application Platform 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é, le fichier devra être mis à l'endroit suivant : EAP_HOME/domain/deployments/META-INF/services/java.sql.Driver.
      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>
      
      

Procédure 3.9. 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.10. Modifier les recherches JNDI

1. Pour en savoir plus Section 3.1.8.2, « Syntaxe de nommage JNDI portable »

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 suive les nouvelles règles d'espace-nom JNDI »