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 journalisation »
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 en 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 en verrez des traces, du style 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 des Modules) au chapitre Class Loading and Module (Chargement de classes et module) 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 l'emplacement 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 contienne 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 contienne 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 pouvez utiliser l'interface en ligne de commande JBoss CLI, ou bien, vous pouvez éditer le fichier manuellement.
   • Suivez ces étapes pour modifier le fichier de configuration du serveur par l'interface en ligne de commande 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, saisir ce qui suit dans 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 ou 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 :

        Exemple 3.1. é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 :

   Exemple 3.2. Télécharger le fichier de propriétés

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

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

1. Section 3.1.4.2, « Mise à jour du code d'application pour les frameworks de 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 ulté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 journalisation

   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 journalisation

   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 qui leur permette 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é, voir 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 classes 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 pilote JAR manuellement.

      Les inconvénients de cette approche :

      • Si le pilote JDBC est constitué de plusieurs JAR, par exemple d'un JAR de pilote, et d'un JAR de licence dépendant ou d'un JAR de 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 il devra être importé dans le JAR ou bien être superposé dans le répertoire deployments/.

   2. Installer un pilote JDBC comme module de base.

      Pour installer un pilote JDBC comme module de base, vous devez installer une structure de chemin de fichier sous le répertoire EAP_HOME/modules/. Cette structure contiendra le JAR de 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 module de base

        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 de licence en tant que module de base.

        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 de 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'autorisations 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 (Configurer les propriétés système par l'interface en ligne de commandes) 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'authorisations 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 »