Procédure 1.14. Remplacer l'application web Welcome par défaut par votre propre application web

1. Désactiver l'application Welcome

   Utiliser le script d'interface CLI EAP_HOME/bin/jboss-cli.sh pour exécuter la commande suivante. Vous aurez sans doute besoin de modifier un profil de domaine géré, ou retirer une portion de la commande /profile=default du serveur autonome.

   /profile=default/subsystem=web/virtual-server=default-host:write-attribute(name=enable-welcome-root,value=false)

2. Configurer votre application web par le contexte root.

   Afin de configurer votre application web, pour qu'elle utilise (/) comme adresse URL, modifier son fichier jboss-web.xml, qui se trouve dans le répertoire META-INF/ ou WEB-INF/. Remplacer sa directive <context-root> par une autre directive qui ressemble à ce qui suit.

   <jboss-web>
       <context-root>/</context-root>
   </jboss-web>

3. Déployer votre application.

   Déployer votre application pour le groupe de serveurs ou le serveur que vous avez modifié lors de la première étape. L'application est maintenant disponible sur http://SERVER_URL:PORT/.

1. Aller dans Apache Maven Project - Download Maven et télécharger la dernière distribution de votre système d'exploitation.
2. Voir la documentation Maven pour les informations sur le façon de télécharger et d'installer Apache Maven sur votre système d'exploitation.

Procédure 2.1. Télécharger et installer le référentiel Maven de JBoss EAP 6 sur le système de fichier local.

1. Ouvrir un navigateur web, et accéder à cet URL: https://access.redhat.com/jbossnetwork/restricted/listSoftware.html?product=appplatform.
2. Chercher "Red Hat JBoss Enterprise Application Platform VERSION Maven Repository" dans la liste.
3. Cliquer sur le bouton Télécharger pour télécharger un fichier .zip contenant le référentiel.
4. Décompresser le fichier sur votre système de fichiers local dans un répertoire de votre choix.
5. Section 2.3.2, « Configurer le référentiel JBoss EAP 6 Platform Maven Repository par les paramètres de configuration de Maven ».

Procédure 2.2. Télécharger l'archive ZIP du référentiel Maven de JBoss EAP 6

1. Ouvrir un navigateur web, et accéder à cet URL: https://access.redhat.com/jbossnetwork/restricted/listSoftware.html?product=appplatform.
2. Chercher "Red Hat JBoss Enterprise Application Platform <VERSION> Maven Repository" dans la liste.
3. Cliquer sur le bouton Télécharger pour télécharger un fichier .zip contenant le référentiel.
4. Décompresser les fichiers dans un répertoire qui soit accessible au serveur Apache.
5. Configurer Apache pour lui donner la permission écriture et pour permettre la navigation dans le répertoire créé.
6. Section 2.3.2, « Configurer le référentiel JBoss EAP 6 Platform Maven Repository par les paramètres de configuration de Maven ».

Procédure 2.3. Télécharger l'archive ZIP du référentiel Maven de JBoss EAP 6

1. Ouvrir un navigateur web, et accéder à cet URL: https://access.redhat.com/jbossnetwork/restricted/listSoftware.html?product=appplatform.
2. Chercher "Red Hat JBoss Enterprise Application Platform <VERSION> Maven Repository" dans la liste.
3. Cliquer sur le bouton Télécharger pour télécharger un fichier .zip contenant le référentiel.
4. Décompresser les fichiers dans un répertoire de votre choix sur le serveur qui héberge Nexus.

Procédure 2.4. Ajouter le référentiel Maven de JBoss EAP 6 en utilisant le gestionnaire de référentiels Nexus Maven

1. Connectez-vous à Nexus en tant qu'administrateur.
2. Sélectionner la section Référentiels à partir du menu Vues → Référentiels qui se trouve à gauche du gestionnaire de référentiels.
3. Cliquer sur le menu déroulant Ajouter..., puis sélectionner Référentiel hébergé.
4. Donner un nom et une ID au nouveau référentiel.
5. Saisir le chemin du disque qui mène au référentiel décompressé dans le champ d'emplacement Remplacement du stockage local.
6. Continuer si vous souhaitez que l'artéfact soit disponible dans un groupe de référentiels. Ne pas continuer avec cette procédure si ce n'est pas ce que vous souhaitez.
7. Sélectionner le groupe de référentiels.
8. Cliquer sur l'onglet Configurer.
9. Déplacez le nouveau référentiel JBoss Maven de la liste Référentiels disponibles vers la liste Référentiels de groupes ordonnancés sur la gauche.

   Note

   Notez que l'ordre de cette liste détermine la priorité de recherche d'artefacts Maven.
10. Section 2.3.2, « Configurer le référentiel JBoss EAP 6 Platform Maven Repository par les paramètres de configuration de Maven ».

Procédure 2.5. Configurer les paramètres Maven pour qu'ils utilisent le référentiel Maven de JBoss EAP 6

1. Configurer le référentiel Maven par les paramètres Maven

   Nous vous conseillons cette dernière approche. Les paramètres Maven utilisés avec un gestionnaire de référentiel ou un référentiel sur un serveur partagé offrent un meilleur contrôle et une meilleure gestion des projets. Les paramètres offrent également la capacité d'utiliser un miroir alternatif pour rediriger toutes les demandes de recherche pour un référentiel spécifique vers un gestionnaire de référentiel sans changer les fichiers du projet. Pour plus d'informations concernant les miroirs, veuillez consulter http://maven.apache.org/guides/mini/guide-mirror-settings.html.
   Cette méthode de configuration s'applique à tous les projets Maven, tant que le fichier POM du projet ne contient pas de configuration de référentiel.
   Section 2.3.2, « Configurer le référentiel JBoss EAP 6 Platform Maven Repository par les paramètres de configuration de Maven ».

2. Configurer le référentiel Maven pour qu'il utilise le fichier POM du projet.

   Cette méthode de configuration est généralement déconseillée. Si vous décidez de configurer des référentiels dans le fichier POM de votre projet, planifiez de manière prudente et souvenez-vous que cela pourrait ralentir votre build et que vous pourriez vous retrouver avec des artefacts ne provenant pas du référentiel attendu.

   Note

   Dans le cas d'une entreprise, où un gestionnaire de référentiel est généralement utilisé, Maven doit interroger tous les artefacts pour tous les projets en utilisant ce gestionnaire. Maven utilise tous les référentiels déclarés pour trouver les artéfacts manquants. Par conséquent, s'il ne peut trouver ce qu'il cherche, il pourra le chercher dans la centrale de référentiels (définie dans le fichier POM parent intégré). Pour remplacer cet emplacement central, vous pouvez ajouter une définition avec central de manière à ce que la centrale de référentiels devienne également votre gestionnaire de référentiel. Cela fonctionne bien avec les projets établis, mais pose un problème pour les projets vierges ou récents puisque cela crée une dépendance cyclique.

   Les fichiers POM inclus de manière transitive représentent également un problème avec ce type de configuration. Maven doit interroger ces référentiels externes pour trouver les artefacts manquants. Non seulement cela ralentira votre build, mais vous fera également perdre le contrôle sur la provenance de vos artefacts et risquera d'endommager votre build.
   Cette méthode de configuration remplace les configuration utilisateur et globales pour le projet configuré.
   Section 2.3.4, « Configurer le référentiel JBoss EAP 6 Platform Maven Repository par le Projet POM ».

Procédure 2.6. Configurer Maven par les paramètres fournis dans les exemples Quickstart

1. Cette procédure remplace le fichier de configuration Maven existant, donc vous devrez sauvegarder le fichier settings.xml Maven existant.
   1. Chercher le répertoire d'installation Maven qui corresponde à votre système d'exploitation. Il se trouve normalement dans le répertoire USER_HOME/.m2/.

      • Dans Linux ou Mac, c'est: ~/.m2/
      • Pour Windows, c'est : \Documents and Settings\USER_NAME\.m2\ ou \Users\USER_NAME\.m2\
   2. Si vous avez un fichier USER_HOME/.m2/settings.xml existant, renommer le et faire une copie de sauvegarde afin de pouvoir le restaurer plus tard.
2. Télécharger et décompresser les exemples quickstart fournis dans JBoss EAP 6. Pour plus d'informations, voir Section 1.4.1.1, « Accès aux Quickstarts »
3. Copier le fichier QUICKSTART_HOME/settings.xml dans le répertoire USER_HOME/.m2/ .
4. Si vous modifiez le fichier settings.xml tandis que Red  Hat JBoss Developer Studio est en cours d'exécution, suivre la procédure ci-dessous intitulée Refresh the JBoss Developer Studio User Settings.

Procédure 2.7. Modifier et configurer les paramètres Maven manuellement pour qu'ils utilisent le référentiel Maven de JBoss EAP 6 en ligne

1. Chercher le répertoire d'installation Maven qui corresponde à votre système d'exploitation. Il se trouve normalement dans le répertoire USER_HOME/.m2/.

   • Dans Linux ou Mac, c'est ~/.m2/
   • Pour Windows, c'est \Documents and Settings\USER_NAME\.m2\ ou \Users\USER_NAME\.m2\
2. Si vous ne trouvez pas de fichier settings.xml, copier le fichier settings.xml du répertoire USER_HOME/.m2/conf/ dans le répertoire USER_HOME/.m2/.
3. Copier l'XML suivant dans l'élément <profiles> du fichier.

   <!-- Configure the JBoss GA Maven repository -->
   <profile>
     <id>jboss-ga-repository</id>
     <repositories>
       <repository>
         <id>jboss-ga-repository</id>
         <url>http://maven.repository.redhat.com/techpreview/all</url>
         <releases>
           <enabled>true</enabled>
         </releases>
         <snapshots>
           <enabled>false</enabled>
         </snapshots>
       </repository>
     </repositories>
     <pluginRepositories>
       <pluginRepository>
         <id>jboss-ga-plugin-repository</id>
         <url>http://maven.repository.redhat.com/techpreview/all</url>
         <releases>
           <enabled>true</enabled>
         </releases>
         <snapshots>
           <enabled>false</enabled>
         </snapshots>
       </pluginRepository>
     </pluginRepositories>
   </profile>
   <!-- Configure the JBoss Early Access Maven repository -->
   <profile>
     <id>jboss-earlyaccess-repository</id>
     <repositories>
       <repository>
         <id>jboss-earlyaccess-repository</id>
         <url>http://maven.repository.redhat.com/earlyaccess/all/</url>
         <releases>
           <enabled>true</enabled>
         </releases>
         <snapshots>
           <enabled>false</enabled>
         </snapshots>
       </repository>
     </repositories>
     <pluginRepositories>
       <pluginRepository>
         <id>jboss-earlyaccess-plugin-repository</id>
         <url>http://maven.repository.redhat.com/earlyaccess/all/</url>
         <releases>
           <enabled>true</enabled>
         </releases>
         <snapshots>
           <enabled>false</enabled>
         </snapshots>
       </pluginRepository>
     </pluginRepositories>
   </profile>
   

   Copier l'XML suivant dans l'élément <activeProfiles> de settings.xml.

   <activeProfile>jboss-ga-repository</activeProfile>
   <activeProfile>jboss-earlyaccess-repository</activeProfile>
   

4. Si vous modifiez le fichier settings.xml tandis que Red  Hat JBoss Developer Studio est en cours d'exécution, suivre la procédure ci-dessous intitulée Refresh the JBoss Developer Studio User Settings.

Procédure 2.8. Configurer les paramètres pour pouvoir utiliser un référentiel JBoss EAP installé localement

1. Chercher le répertoire d'installation Maven qui corresponde à votre système d'exploitation. Il se trouve normalement dans le répertoire USER_HOME/.m2/.

   • Dans Linux ou Mac, c'est ~/.m2/
   • Pour Windows, c'est \Documents and Settings\USER_NAME\.m2\ ou \Users\USER_NAME\.m2\
2. Si vous ne trouvez pas de fichier settings.xml, copier le fichier settings.xml du répertoire USER_HOME/.m2/conf/ dans le répertoire USER_HOME/.m2/.
3. Copier l'XML suivant dans l'élément <profiles> du fichier settings.xml. Veillez bien à changer l'<url> à l'emplacement de référentiel lui-même.

   <profile>
     <id>jboss-eap-repository</id>
     <repositories>
       <repository>
         <id>jboss-eap-repository</id>
         <name>JBoss EAP Maven Repository</name>
         <url>file:///path/to/repo/jboss-eap-6.x-maven-repository</url>
         <layout>default</layout>
         <releases>
           <enabled>true</enabled>
           <updatePolicy>never</updatePolicy>
         </releases>
         <snapshots>
           <enabled>false</enabled>
           <updatePolicy>never</updatePolicy>
         </snapshots>
       </repository>
     </repositories>
     <pluginRepositories>
       <pluginRepository>
         <id>jboss-eap-repository-group</id>
         <name>JBoss EAP Maven Repository</name>
         <url>
         file:///path/to/repo/jboss-eap-6.x-maven-repository
         </url>
         <layout>default</layout>
         <releases>
           <enabled>true</enabled>
           <updatePolicy>never</updatePolicy>
         </releases>
         <snapshots>
           <enabled>false</enabled>
           <updatePolicy>never</updatePolicy>
         </snapshots>
       </pluginRepository>
     </pluginRepositories>
   </profile>
   

   Copier l'XML suivant dans l'élément <activeProfiles> de settings.xml.

   <activeProfile>jboss-eap-repository</activeProfile>
   

4. Si vous modifiez le fichier settings.xml tandis que Red  Hat JBoss Developer Studio est en cours d'exécution, suivre la procédure ci-dessous intitulée Refresh the JBoss Developer Studio User Settings.

Procédure 2.9. Réactualiser les paramètres de configuration d'utilisateur de Red Hat JBoss Developer Studio

1. À partir du menu, sélectionner Window → Preferences.
2. Dans la fenêtre Window Preferences, étendre Maven et sélectionner User Settings.
3. Cliquer sur le bouton Update Settings (Mise à jour Configuration) pour réactualiser les configurations utilisateur de Maven dans Red Hat JBoss Developer Studio.
   

   Figure 2.1. Mise à jour des paramètres de configuration de l'utilisateur Maven

Procédure 2.10. Configurer Maven dans Red Hat JBoss Developer Studio

1. Cliquer sur Window→Preferences, puis JBoss Tools et sélectionner JBoss Maven Integration.
   

   Figure 2.2. Panneau d'intégration de JBoss Maven dans la fenêtre Préférences

2. Cliquer sur Configure Maven Repositories.
3. Cliquer sur Add Repository pour configurer le référentiel de JBoss GA Tech Preview Maven. Remplir les champs de Add Maven Repository comme suit :
   1. Définir les valeurs de Profile ID, Repository ID, et Repository Name à jboss-ga-repository.
   2. Définir la valeur de Repository URL à http://maven.repository.redhat.com/techpreview/all.
   3. Cliquer sur la case Active by default pour activer le référentiel Maven.
   4. Cliquer sur OK
   

   Figure 2.3. Ajouter le référentiel Maven - JBoss Tech Preview

4. Cliquer sur Add Repository pour configurer le référentiel JBoss Early Access Maven. Remplir les champs de Add Maven Repository comme suit :
   1. Définir les valeurs de Profile ID, Repository ID, et Repository Name à jboss-earlyaccess-repository.
   2. Définir la valeur de Repository URL à http://maven.repository.redhat.com/techpreview/all.
   3. Cliquer sur la case Active by default pour activer le référentiel Maven.
   4. Cliquer sur OK
   

   Figure 2.4. Ajouter le référentiel Maven - JBoss Early Access

5. Vérifier les référentiels et cliquer sur Finish.
   

   Figure 2.5. Vérifier les référentiels Maven

6. Le message suivant appraîtra "Are you sure you want to update the file 'MAVEN_HOME/settings.xml'?". Cliquer sur Yes pour mettre les paramètres de configuration à jour. Clqiuer sur OK pour fermer la boîte de dialogue.
   Le référentiel Maven est maintenant configuré pour utilisation dans Red Hat JBoss Developer Studio

1. Ouvrir le fichier pom.xml de votre projet dans un éditeur de texte.
2. Ajouter la configuration du référentiel suivant. S'il y a déjà une configuration <repositories> qui se trouve dans le fichier, lui ajouter l'élément <repository>. Veillez bien à modifier l'<url> pour qu'il corresponde bien à l'emplacement du référentiel.

   <repositories>
      <repository>
         <id>jboss-eap-repository-group</id>
         <name>JBoss EAP Maven Repository</name>
         <url>file:///path/to/repo/jboss-eap-6.x.0-maven-repository/</url>
         <layout>default</layout>
         <releases>
            <enabled>true</enabled>
            <updatePolicy>never</updatePolicy>
         </releases>
         <snapshots>
            <enabled>true</enabled>
            <updatePolicy>never</updatePolicy>
         </snapshots>
      </repository>
   </repositories>
   

3. Ajouter la configuration de référentiel de plug-in suivante. S'il existe déjà une configuration <pluginRepositories> dans le fichier, lui ajouter l'élément <pluginRepository>.

   <pluginRepositories>
      <pluginRepository>
         <id>jboss-eap-repository-group</id>
         <name>JBoss EAP Maven Repository</name>
         <url>file:///path/to/repo/jboss-eap-6.x.0-maven-repository/</url>
         <releases>
            <enabled>true</enabled>
         </releases>
         <snapshots>
            <enabled>true</enabled>
         </snapshots>
      </pluginRepository>
   </pluginRepositories>
   

Procédure 2.11. Mise à jour du référentiel Maven

1. Ouvrir un navigateur et connectez-vous dans https://access.redhat.com.
2. Sélectionnez Téléchargements du menu en haut de la page.
3. Cherchez Red Hat JBoss Enterprise Application Platform dans la liste et cliquez dessus.
4. Sélectionner la version de JBoss EAP qui convient à partir du menu déroulant Version qui apparaît sur l'écran, puis cliquer sur Correctifs.
5. Chercher Red Hat JBoss Enterprise Application Platform<VERSION>CPx Incremental Maven Repository dans la liste et cliquer sur Download.
6. Vous êtes invité à sauvegarder le fichier ZIP dans un répertoire de votre choix. Sélectionner un répertoire et sauvegarder le fichier.
7. Chercher le chemin d'accès vers le répertoire JBoss EAP dont il s'agit dans les commandes ci-dessous, sous EAP_MAVEN_REPOSITORY_PATH, correspondant à votre système d'exploitation. Pour obtenir plus d'informations sur la façon d'installer le référentiel Maven sur le système de fichiers local, voir Section 2.2.3, « Installer le référentiel Maven de JBoss EAP 6 localement ».
8. Décompresser le fichier de correctifs Maven dans le répertoire d'installation de JBoss EAP <VERSION>.x.
   • Dans Linux, ouvrir un terminal et saisir la commande suivante :

     [standalone@localhost:9999 /] unzip -o jboss-eap-<VERSION>.x-incremental-maven-repository.zip -d EAP_MAVEN_REPOSITORY_PATH

   • Dans Windows, utiliser l'utilitaire pour extraire le fichier ZIP pour le mettre dans la racine du répertoireEAP_MAVEN_REPOSITORY_PATH .

1. Ajouter le fichier du descripteur de déploiement

   Ajouter le fichier de descripteur de déploiement jboss-deployment-structure.xml au répertoire META-INF de l'EAR s'il n'existe pas déjà et ajouter le contenu suivant :

   <jboss-deployment-structure>
   
   </jboss-deployment-structure>

2. Ajouter l'élément <ear-subdeployments-isolated>

   Ajouter l'élément <ear-subdeployments-isolated> au fichier jboss-deployment-structure.xml s'il n'existe pas déjà dans le contenu de false.

   <ear-subdeployments-isolated>false</ear-subdeployments-isolated>

1. Ajouter Imports

   Ajouter les déclarations d'importation des espace-noms de classe JBoss Logging que vous allez utiliser. Vous devrez importer au minimum import org.jboss.logging.Logger.

   import org.jboss.logging.Logger;

2. Créer un objet Logger

   Créer une instance de org.jboss.logging.Logger et l'initialiser en utilisant la méthode statique Logger.getLogger(Class). Red Hat vous recommande de la créer en tant que variable à instance unique pour chaque classe.

   private static final Logger LOGGER = Logger.getLogger(HelloWorld.class);

3. Ajouter les messages de journalisation

   Ajouter des appels aux méthodes de l'objet Logger à votre code, là où vous souhaitez qu'il envoie des messages. L'objet Logger comprend un certain nombre de méthodes contenant des paramètres différents suivant les types de messages. Les plus faciles à utiliser sont les suivants :

   debog(message objet)

   info(message objet)

   erreur(message objet)

   trace(message objet)

   fatal(message objet)

   Ces méthodes envoient un message de journalisation avec un niveau de journalisation correspondant et le paramètre message comme string.

   LOGGER.error("Configuration file not found.");

   Pour obtenir une liste complète des méthodes JBoss Logging, consulter le package org.jboss.logging dans JBoss EAP 6 API Documentation.

Procédure 5.1. Ajouter le fichier de configuration à l'application

• Le répertoire auquel le fichier de configuration est ajouté dépend de la méthode de déploiement : EAR, WAR ou JAR.

  • Déploiement EAR

    Copier le fichier de configuration de journalisation dans le répertoire META-INF.

  • Déploiement WAR ou JAR

    Copier le fichier de configuration de journalisation dans le répertoire META-INF ou WEB-INF/classes.

Procédure 5.2. Ajouter une configuration de profil de journalisation à une application

• Modifier MANIFEST.MF

  Si votre application ne possède pas de fichier MANIFEST.MF : le créer avec le contenu suivant, en remplaçant NAME par le nom de profil qui convient.

  Manifest-Version: 1.0
  Logging-Profile: NAME

  Si votre application contient déjà un fichier MANIFEST.MF : ajouter la ligne suivante, en remplaçant NAME par le nom du profil qui convient.

  Logging-Profile: NAME

Procédure 7.1. Créer un projet EJB dans le Red Hat JBoss Developer Studio

1. Créer un nouveau projet

   Pour ouvrir l'Assistant New EJB Project, naviguer jusqu'au menu Fichier, sélectionner Nouveau puis Projet EJB.
   

   Figure 7.1. Assistant New EJB Project

2. Détails

   Fournir les informations suivantes :
   • Nom du projet.
     Il s'agira du nom du projet qui apparaît dans Red Hat JBoss Developer Studio, et également le nom du fichier par défaut du fichier JAR déployé.
   • Emplacement du projet
     Le répertoire où les fichiers du projet seront sauvegardés. La valeur par défaut est un répertoire qui se trouve dans l'espace de travail en cours.
   • Runtime cible.
     Il s'agit du runtime de serveur utilisé pour le projet. Il devra être défini au même runtime JBoss EAP 6, qui est utilisé par le serveur dans lequel vous souhaitez déployer.
   • Version de module EJB. Il s'agit de la version de la spécification EJB avec laquelle vos beans enterprise devront se conformer. Red Hat recommande que vous utilisiez 3.1.
   • Configuration. Cela vous permet d'ajuster les fonctionnalités prises en charge par votre projet. Utiliser la configuration par défaut pour le runtime que vous avez sélectionné.
   Cliquer sur Suivant pour continuer.

3. Java Build Configuration

   Cet écran vous permet de personnaliser les répertoires qui contiennent les fichiers source de Java et le répertoire où les résultats de la génération se trouvent.
   Conservez cette configuration sans y apporter aucun changement et cliquer sur le bouton Suivant.

4. Paramétrage du Module EJB

   Cocher la case Générer descripteur de déploiement ejb-jar.xml si un descripteur de déploiement est requis. Le descripteur de déploiement est une option dans EJB 3.1, et peut être rajouté plus tard si nécessaire.
   Cliquer sur le bouton Terminé et le projet sera créé. Il s'affichera dans Project Explorer.
   

   Figure 7.2. Nouveau projet EJB créé dans Project Explorer

5. Ajouter l'artifact généré dans le serveur en vue du déploiement

   Ouvrir le dialogue Ajouter et Supprimer en cliquant à droite sur le serveur dans lequel vous souhaitez générer l'artefact dans l'onglet serveur, et sélectionner 'Ajouter et Supprimer'.
   Sélectionner la ressource à déployer à partir de la colonne Disponible et cliquer sur le bouton Ajouter. La ressource sera déplacée dans la colonne Configurer, Cliquer sur Terminé pour fermer le dialogue.
   

   Figure 7.3. Ajouter et Supprimer le dialogue

Procédure 7.2. Créer un projet EJB Archive dans Maven

1. Créer le projet Maven

   Un projet EJB peut être créé en utilisant le système archétype de Maven et l'archétype ejb-javaee6. Pour ce faire, exécuter la commande mvn avec les paramètres suivants :

    mvn archetype:generate -DarchetypeGroupId=org.codehaus.mojo.archetypes -DarchetypeArtifactId=ejb-javaee6 

   Maven vous demandera le groupId, le artifactId, la version et le package de votre projet.

   [localhost]$ mvn archetype:generate -DarchetypeGroupId=org.codehaus.mojo.archetypes -DarchetypeArtifactId=ejb-javaee6
   [INFO] Scanning for projects...
   [INFO]                                                                         
   [INFO] ------------------------------------------------------------------------
   [INFO] Building Maven Stub Project (No POM) 1
   [INFO] ------------------------------------------------------------------------
   [INFO] 
   [INFO] >>> maven-archetype-plugin:2.0:generate (default-cli) @ standalone-pom >>>
   [INFO] 
   [INFO] <<< maven-archetype-plugin:2.0:generate (default-cli) @ standalone-pom <<<
   [INFO] 
   [INFO] --- maven-archetype-plugin:2.0:generate (default-cli) @ standalone-pom ---
   [INFO] Generating project in Interactive mode
   [INFO] Archetype [org.codehaus.mojo.archetypes:ejb-javaee6:1.5] found in catalog remote
   Define value for property 'groupId': : com.shinysparkly
   Define value for property 'artifactId': : payment-arrangments
   Define value for property 'version':  1.0-SNAPSHOT: : 
   Define value for property 'package':  com.shinysparkly: : 
   Confirm properties configuration:
   groupId: com.company
   artifactId: payment-arrangments
   version: 1.0-SNAPSHOT
   package: com.company.collections
   Y: : 
   [INFO] ------------------------------------------------------------------------
   [INFO] BUILD SUCCESS
   [INFO] ------------------------------------------------------------------------
   [INFO] Total time: 32.440s
   [INFO] Finished at: Mon Oct 31 10:11:12 EST 2011
   [INFO] Final Memory: 7M/81M
   [INFO] ------------------------------------------------------------------------
   [localhost]$

2. Ajouter vos beans enterprise

   Ecrire vos beans enterprise et les ajouter au projet sous le répertoire src/main/java dans le sous-répertoire approprié pour le paquetage du bean.

3. Créer votre projet

   Pour construire ce projet, exécuter la commande mvn package dans le même répertoire que le fichier pom.xml. Cela compilera les classes Java et empaquettera le fichier JAR. Le fichier JAR construit se nomme artifactId-version.jar et se trouve dans le répertoire target/.

Procédure 7.3. Créer un projet EAR contenant un projet EJB

1. Ouvrir le nouvel Assistant de Projet de l'Application EAR.

   Naviguer vers le menu Fichier, sélectionner Nouveau, puis Projet et l'assistant Nouveau Projet apparaîtra. Sélectionner Java EE/Enterprise Application Project et cliquer sur le bouton Suivant.
   

   Figure 7.4. Nouvel Assistant de Projet de l'Application EAR.

2. Fournir des Informations

   Fournir les informations suivantes :
   • Nom du projet.
     Il s'agira du nom du projet qui apparaît dans Red Hat JBoss Developer Studio, et également le nom du fichier par défaut du fichier EAR déployé.
   • Emplacement du projet
     Le répertoire où les fichiers du projet seront sauvegardés. La valeur par défaut est un répertoire qui se trouve dans l'espace de travail en cours.
   • Runtime cible.
     Il s'agit du runtime de serveur utilisé pour le projet. Il devra être défini au même runtime JBoss EAP 6, qui est utilisé par le serveur dans lequel vous souhaitez déployer.
   • Version EAR.
     C'est la version des spécifications de Java Enterprise Edition auquel votre projet devra se conformer. Red Hat recommande d'en utiliser 6.
   • Configuration. Cela vous permet d'ajuster les fonctionnalités prises en charge par votre projet. Utiliser la configuration par défaut pour le runtime que vous avez sélectionné.
   Cliquer sur Suivant pour continuer.

3. Ajouter un nouveau module EJB.

   Les nouveaux Modules peuvent être ajoutés à partir de la page Enterprise Application de l'assistant. Pour ajouter un nouveau Projet EJB en tant que module, veuillez suivre les étapes suivantes :

   1. Ajouter un nouveau Module EJB.

      Cliquer sur Nouveau Module, décocher la case Créer Modules par Défaut, sélectionner Enterprise Java Bean et cliquer sur Suivant. L'assistant Nouveau Projet EJB apparaîtra.

   2. Créer un Projet EJB.

      L'assistant Nouveau Projet EJB est le même que l'assistant utilisé pour créer de nouveaux projets EJB autonomes et est décrit dans Section 7.2.1, « Créer un projet d'archives EJB avec le Red Hat Studio JBoss Developer ».
      Les détails minimales requis pour créer le project sont les suivants :
      • Nom du Projet
      • Runtime de la cible
      • Version Module EJB
      • Configuration
      Toutes les autres étapes de l'assistant sont optionnelles. Cliquer sur Terminé pour finir de créer le Projet EJB.
   Le Projet EJB tout juste créé est listé dans les dépendances du module Java EE et la case est cochée.

4. Optionnel : ajouter un descripteur de déploiement application.xml

   Cocher la case Générer descripteur de déploiement d'application.xml le cas échéant.

5. Cliquer sur Finish

   Deux nouveaux projets vont apparaître, le projet EJB et le projet EAR.

6. Ajouter l'artifact généré dans le serveur en vue du déploiement

   Ouvrir la boîte de dialogue Ajouter et Supprimer en cliquant avec le bouton droit de la souris, dans l'onglet Serveurs, sur le serveur dans lequel vous souhaitez déployer l'artéfact de la build dans l'onglet serveur, et sélectionner Ajouter et Supprimer.
   Sélectionner la ressource EAR à déployer depuis la colonne Disponible et cliquer sur le bouton Ajouter. La ressource sera déplacée vers la colonne Configuré. Cliquer sur Terminé pour fermer la boîte de dialogue.
   

   Figure 7.5. Ajouter et Supprimer le dialogue

Procédure 7.4. Ajouter un descripteur de déploiement à un projet EJB.

1. Ouvrir le projet

   Ouvrir un projet dans Red Hat JBoss Developer Studio.

2. Ajouter un descipteur de déploiement

   Cliquer à droite sur le dossier Descripteur de déploiement dans la vue du projet et sélectionner Generate Deployment Descriptor Stub (Générer Descripteur de déploiement).
   

   Figure 7.6. Ajouter un descripteur de déploiement

Procédure 7.5. Ajouter des Session Beans à un Projet dans Red Hat JBoss Developer Studio

1. Ouvrir le projet

   Ouvrir un projet dans Red Hat JBoss Developer Studio.

2. Ouvrir l'assistant "Create EJB 3.x Session Bean" (Créer EJB 3.x Session Bean)

   Pour ouvrir l'assistant Créer EJB 3.x Session Bean, naviguer dans le menu File, et sélectionner New, puis Session Bean (EJB 3.x).
   

   Figure 7.7. Créer un assistant EJB 3.x Session Bean

3. Indiquer les informations de classe

   Fournir les informations suivantes :
   • Projet
     Verifier que le projet qui convient a bien été sélectionné.
   • Dossier source
     Il s'agit du dossier dans lequel les fichiers source de Java seront créés. Cela n'a pas normalement besoin d'être changé.
   • Package
     Indiquer le package auquel cette classe appartient.
   • Nom de la classe
     Indiquer le nom de la classe qui représentera le session bean.
   • Superclass
     La classe de session bean peut hériter d'une Superclass. Indiquer ici si votre session a une Superclass.
   • Type d'état
     Indiquer le type d'état du session bean: stateless, stateful, ou singleton.
   • Interfaces commerciales
     Par défaut, la case No-interface est cochée, donc aucune interface ne sera créée. Cocher les cases des interfaces que vous souhaitez définir et ajuster les noms si nécessaire.
     Nous vous rappelons que les beans Enterprise d'un WAR (Web Archive) ne supportent qu'EJB 3.1 Lite, et que cela n'inclut pas les interfaces commerciales distantes.
   Cliquer sur Next.

4. Informations spécifiques aux Session Bean

   Vous pouvez saisir des informations supplémentaires ici pour personnaliser encore plus le session bean. Vous n'avez pas besoin de changer quoi que ce soit ici.
   Les items que vous pouvez changer sont :
   • Nom de bean.
   • Nom mappé.
   • Type de transaction (géré conteneur ou géré bean).
   • On peut fournir des interfaces supplémentaires que le bean doit implémenter.
   • Vous pouvez également spécifier des interfaces EJB 2.x Home et Component si nécessaire.

5. Terminer

   Cliquer sur le bouton Finish et le nouveau session bean sera créé, et ajouté au projet. Les fichiers de toute nouvelle interface commerciale seront également créés, s'ils ont été spécifiés.

Procédure 7.6. Ajouter un Message-Driven Bean basé JMS dans Red Hat JBoss Developer Studio

1. Ouvrir l'assistant Create EJB 3.x Message-Driven Bean

   Aller à File → New → Other. Sélectionner EJB/Message-Driven Bean (EJB 3.x) et cliquer sur le bouton Next.
   

   Figure 7.9. Créer l'assistant Message-Driven Bean EJB 3.x

2. Indiquer les détails de la destination de fichier de classe

   Il existe trois ensembles de détails à indiquer pour la classe de bean : le projet, la classe Java et le message de destination.

   Projet

   • Si plusieurs projets existent dans Workspace, veillez à ce que le bon projet soit sélectionné dans le menu Project.
   • Le dossier où le fichier source du nouveau bean sera créé est ejbModule sous le répertoire du projet sélectionné. Ne peut être changé que pour répondre à des cas particuliers.

   Classe Java

   • Les champs obligatoires sont les suivants : Java Package et class name.
   • Il n'est pas nécessaire de fournir une Superclass à moins que la logique commerciale de votre application ne l'exige.

   Destination du message

   Voici les informations à fournir pour un Message-Driven Bean basé JMS :

   • Destination name. C'est la file d'attente ou le nom du sujet qui contient les messages auxquels le bean répondra.
   • La case JMS est sélectionnée par défaut. Veuillez ne pas la changer.
   • Définir Destination type comme Queue ou Topic selon ce que l'on vous demande.

   Cliquer sur le bouton Next.

3. Saisir les informations spécifiques aux Message-Driven Bean

   Les valeurs par défaut sont appropriées pour un Message-Driven Bean basé JMS utilisant des transactions gérées conteneur.
   • Changer le type de transaction à Bean si le Bean doit utiliser des transactions Bean-managed (gérées bean).
   • Changer le nom du Bean s'il est demandé un nom de bean différent du nom de classe.
   • L'interface JMS Message Listener sera déjà listée. Vous n'aurez pas besoin d'ajouter ou de supprimer des interfaces, à moins qu'elles soient spécifiques à votre logique commerciale d'applications.
   • Laisser les cases décochées pour créer les méthodes stub sélectionnées.
   Cliquer sur le bouton Finish.

Procédure 7.7. Implémenter la substitution de propriétés dans une application MDB

1. Configurer le serveur JBoss EAP pour activer la substituion de propriété.

   Le serveur JBoss EAP doit être configuré pour activer la substitution de propriété. Pour cela, définir l'attribut <annotation-property-replacement> qui se trouve dans le sous-système ee du fichier de configuration du serveur à true.
   1. Sauvegarder le fichier de configuration du serveur. L'exemple de guide de démarrage rapide helloworld-mdb nécessite un profil complet pour les serveurs autonomes, donc il s'agit du standalone/configuration/standalone-full.xml. Si vous exécutez votre serveur dans un domaine géré, il s'agira du fichier domain/configuration/domain.xml.
   2. Démarrer le serveur JBos EAP avec le profil complet.
      Dans Linux :

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

      Dans Windows :

      EAP_HOMEbin\standalone.bat -c standalone-full.xml

   3. Lancer l'interface CLI par la commande pour votre système d'exploitation.
      Dans Linux :

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

      Dans Windows :

      EAP_HOME\bin\jboss-cli.bat --connect

   4. Saisir la commande suivante pour activer la substitution de propriété d'annotation.

      /subsystem=ee:write-attribute(name=annotation-property-replacement,value=true) 

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

      {"outcome" => "success"}

   6. Réviser les changements apportés au fichier de configuration du serveur JBoss EAP. Le sous-système ee doit maintenant contenir l'XML suivant.

      <subsystem xmlns="urn:jboss:domain:ee:1.2">
          <spec-descriptor-property-replacement>false</spec-descriptor-property-replacement>
          <jboss-descriptor-property-replacement>true</jboss-descriptor-property-replacement>
          <annotation-property-replacement>true</annotation-property-replacement>
      </subsystem>

2. Définir les propriétés système.

   Vous pouvez spécifier les propriétés du système dans le fichier de configuration du serveur ou vous pouvez les passer comme arguments de ligne de commande lorsque vous démarrez le serveur JBoss EAP. Les propriétés système définies dans le fichier de configuration de serveur ont la priorité sur celles passées sur la ligne de commande lorsque vous démarrez le serveur.
   • Vous devez définir les propriétés système dans le fichier de configuration.
     1. Démarrez le serveur JBoss EAP et le Management API comme indiqué dans les étapes précédentes.
     2. Utiliser la syntaxe de commande suivante pour configurer une propriété système dans le serveur JBoss EAP :

        /system-property=PROPERTY_NAME:add(value=PROPERTY_VALUE) 

        Pour le guide de démarrage rapide helloworld-mdb, nous configurons les propriétés système suivantes :

        /system-property=property.helloworldmdb.queue:add(value=java:/queue/HELLOWORLDMDBPropQueue)
        /system-property=property.helloworldmdb.topic:add(value=java:/topic/HELLOWORLDMDBPropTopic)
        /system-property=property.connection.factory:add(value=java:/ConnectionFactory)

     3. Réviser les changements apportés au fichier de configuration du serveur JBoss EAP. Les propriétés système suivantes doivent maintenant apparaître après les <extensions>.

        <system-properties>
            <property name="property.helloworldmdb.queue" value="java:/queue/HELLOWORLDMDBPropQueue"/>
            <property name="property.helloworldmdb.topic" value="java:/topic/HELLOWORLDMDBPropTopic"/>
            <property name="property.connection.factory" value="java:/ConnectionFactory"/>
        </system-properties>

   • Passez les propriétés système comme arguments de ligne de commande quand vous démarrez le serveur JBoss EAP sous la forme d'un -DPROPERTY_NAME=PROPERTY_VALUE. Ce qui suit est un exemple de la façon dont on passe les arguments dans les propriétés système définies dans l'étape précédente.

     EAP_HOME/bin/standalone.sh -c standalone-full.xml -Dproperty.helloworldmdb.queue=java:/queue/HELLOWORLDMDBPropQueue -Dproperty.helloworldmdb.topic=java:/topic/HELLOWORLDMDBPropTopic -Dproperty.connection.factory=java:/ConnectionFactory

3. Modifier le code pour utiliser les substitutions de propriétés système.

   Remplacer les valeurs d'annotation @ActivationConfigProperty et @Resource codées en dur par des substitutions pour les propriétés système nouvellement définies. Voici des exemples sur la façon de changer le guide de démarrage rapide helloworld-mdb pour qu'il utilise les substitutions de propriétés système nouvellements définies pour les annotations qui se trouvent dans le code source.
   1. Modifier la valeur de propriété @ActivationConfigProperty destination qui se trouve dans la classe HelloWorldQueueMDB afin d'utiliser la substitution pour la propriété système. L'annotation @MessageDriven devra ressembler à ceci :

      @MessageDriven(name = "HelloWorldQueueMDB", activationConfig = {
          @ActivationConfigProperty(propertyName = "destinationType", propertyValue = "javax.jms.Queue"),
          @ActivationConfigProperty(propertyName = "destination", propertyValue = "${property.helloworldmdb.queue}"),   
          @ActivationConfigProperty(propertyName = "acknowledgeMode", propertyValue = "Auto-acknowledge") })
      

   2. Modifier la valeur de propriété @ActivationConfigProperty destination qui se trouve dans la classe HelloWorldTopicMDB afin d'utiliser la substitution pour la propriété système. L'annotation @MessageDriven devra ressembler à ceci :

      @MessageDriven(name = "HelloWorldQTopicMDB", activationConfig = {
          @ActivationConfigProperty(propertyName = "destinationType", propertyValue = "javax.jms.Topic"),
          @ActivationConfigProperty(propertyName = "destination", propertyValue = "${property.helloworldmdb.topic}"),   
          @ActivationConfigProperty(propertyName = "acknowledgeMode", propertyValue = "Auto-acknowledge") })

   3. Modifier les annotations @Resource qui se trouvent dans la classe HelloWorldMDBServletClient afin d'utiliser les substitutions de propriétés système. Le code devra ressembler à ceci :

      @Resource(mappedName = "${property.connection.factory}")
      private ConnectionFactory connectionFactory;
      
      @Resource(mappedName = "${property.helloworldmdb.queue}")   
      private Queue queue;
      
      @Resource(mappedName = "${property.helloworldmdb.topic}")
      private Topic topic;
      

   4. Modifier le fichier hornetq-jms.xml pour pouvoir utiliser les valeurs de substitution de propriétés système.

      <?xml version="1.0" encoding="UTF-8"?>
      <messaging-deployment xmlns="urn:jboss:messaging-deployment:1.0">
          <hornetq-server>
              <jms-destinations>
                  <jms-queue name="HELLOWORLDMDBQueue">
                      <entry name="${property.helloworldmdb.queue}"/>
                  </jms-queue>
                  <jms-topic name="HELLOWORLDMDBTopic">
                      <entry name="${property.helloworldmdb.topic}"/>
                  </jms-topic>
              </jms-destinations>
          </hornetq-server>
      </messaging-deployment>

4. Déployer l'application. L'application utilisera maintenant les valeurs indiquées par les propriétés système comme valeurs de propriété pour @Resource et @ActivationConfigProperty.

Procédure 7.8. 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 la racine 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 7.9. 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 7.8.1, « 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 contienne 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 7.10. Configurer un EJB en utilisant un contexte scoped basé mappage

1. Configurer les propriétés

   Configurer les propriétés client EJB par programmation, en indiquant le même ensemble de propriétés utilisées dans le fichier jboss-ejb-client.properties standard. Pour activer le contexte scoped, vous devez indiquer la propriété org.jboss.ejb.client.scoped.context et configurer sa valeur sur true. Voici un exemple de configuration des propriétés par programmation :

   // Configure  EJB Client properties for the InitialContext
   Properties ejbClientContextProps = new Properties();
   ejbClientContextProps.put(“remote.connections”,”name1”);
   ejbClientContextProps.put(“remote.connection.name1.host”,”localhost”);
   ejbClientContextProps.put(“remote.connection.name1.port”,”4447”);
   // Property to enable scoped EJB client context which will be tied to the JNDI context
   ejbClientContextProps.put("org.jboss.ejb.client.scoped.context", “true”);
   

2. Passer les propriétés en création de contexte

   // Create the context using the configured properties
   InitialContext ic = new InitialContext(ejbClientContextProps);
   MySLSB bean = ic.lookup("ejb:myapp/ejb//MySLSBBean!" + MySLSB.class.getName());
   

Procédure 7.11. Créer le fichier de descripteur pour configurer l'intercepteur de conteneur

1. Créer un fichier jboss-ejb3.xml dans le répertoire META-INF du déploiement EJB.
2. Configurer les éléments de l'intercepteur du conteneur dans le fichier du descripteur.
   1. Utiliser l'espace-nom urn:container-interceptors:1.0 pour indiquer la configuration des éléments de l'intercepteur du conteneur.
   2. Utiliser l'élément <container-interceptors> pour indiquer les intercepteurs du conteneur.
   3. Utiliser les éléments <interceptor-binding> pour relier l'intercepteur du conteneur aux EJB. Les intercepteurs peuvent être reliés d'une des manières suivantes :
      • Relier l'intercepteur à tous les EJB du déploiement par le caractère générique *.
      • Relier l'intercepteur au niveau bean individuel par le nom spécifique de l'EJB.
      • Relier l'intercepteur au niveau de méthode spécifique des EJB.

      Note

      Ces éléments sont configurés par EJB 3.1 XSD de la même façon que pour les intercepteurs Java EE.
3. Vérifier les exemples d'éléments ci-dessus dans le fichier de descripteur suivant.

   Exemple 7.3. jboss-ejb3.xml

   <jboss xmlns="http://www.jboss.com/xml/ns/javaee"
          xmlns:jee="http://java.sun.com/xml/ns/javaee"
          xmlns:ci ="urn:container-interceptors:1.0">
    
       <jee:assembly-descriptor>
           <ci:container-interceptors>
               <!-- Default interceptor -->
               <jee:interceptor-binding>
                   <ejb-name>*</ejb-name>
                   <interceptor-class>org.jboss.as.test.integration.ejb.container.interceptor.ContainerInterceptorOne</interceptor-class>
               </jee:interceptor-binding>
               <!-- Class level container-interceptor -->
               <jee:interceptor-binding>
                   <ejb-name>AnotherFlowTrackingBean</ejb-name>
                   <interceptor-class>org.jboss.as.test.integration.ejb.container.interceptor.ClassLevelContainerInterceptor</interceptor-class>
               </jee:interceptor-binding>
               <!-- Method specific container-interceptor -->
               <jee:interceptor-binding>
                   <ejb-name>AnotherFlowTrackingBean</ejb-name>
                   <interceptor-class>org.jboss.as.test.integration.ejb.container.interceptor.MethodSpecificContainerInterceptor</interceptor-class>
                   <method>
                       <method-name>echoWithMethodSpecificContainerInterceptor</method-name>
                   </method>
               </jee:interceptor-binding>
               <!-- container interceptors in a specific order -->
               <jee:interceptor-binding>
                   <ejb-name>AnotherFlowTrackingBean</ejb-name>
                   <interceptor-order>
                       <interceptor-class>org.jboss.as.test.integration.ejb.container.interceptor.ClassLevelContainerInterceptor</interceptor-class>
                       <interceptor-class>org.jboss.as.test.integration.ejb.container.interceptor.MethodSpecificContainerInterceptor</interceptor-class>
                       <interceptor-class>org.jboss.as.test.integration.ejb.container.interceptor.ContainerInterceptorOne</interceptor-class>
                   </interceptor-order>
                   <method>
                       <method-name>echoInSpecificOrderOfContainerInterceptors</method-name>
                   </method>
               </jee:interceptor-binding>
           </ci:container-interceptors>
       </jee:assembly-descriptor>
   </jboss>
   
   

   L'XSD de l'espace-nom urn:container-interceptors:1.0 se trouve dans EAP_HOME/docs/schema/jboss-ejb-container-interceptors_1_0.xsd.

Procédure 7.12. Modifier l'identité du contexte de sécurité

1. Créer l'intercepteur côté client

   Cet intercepteur côté client doit implémenter l'interface org.jboss.ejb.client.EJBClientInterceptor. L'intercepteur doit passer l'identité requise par le mappage de données contextuelles, par l'intermédiaire d'un appel EJBClientInvocationContext.getContextData(). Voici un exemple de code d'intercepteur côté client  :

   public class ClientSecurityInterceptor implements EJBClientInterceptor {
   
       public void handleInvocation(EJBClientInvocationContext context) throws Exception {
           Principal currentPrincipal = SecurityActions.securityContextGetPrincipal();
   
           if (currentPrincipal != null) {
               Map<String, Object> contextData = context.getContextData();
               contextData.put(ServerSecurityInterceptor.DELEGATED_USER_KEY, currentPrincipal.getName());
           }
           context.sendRequest();
       }
   
       public Object handleInvocationResult(EJBClientInvocationContext context) throws Exception {
           return context.getResult();
       }
   }
   

   Les applications utilisateur peuvent insérer l'intercepteur dans la chaîne d'intercepteur dans le EJBClientContext par l'un des moyens suivants  :

   • Par programmation

     Par cette approche, vous appelez la méthode org.jboss.ejb.client.EJBClientContext.registerInterceptor(int order, EJBClientInterceptor interceptor) et passez l'instance order et l'instance interceptor. L'instance order est utilisé pour déterminer où exactement cet intercepteur est placé dans la chaîne d'intercepteur.

   • Mécanisme ServiceLoader

     Cette approche nécessite la création d'un fichier META-INF/services/org.jboss.ejb.client.EJBClientInterceptor et de le placer ou le mettre dans le chemin de classe de l'application client. Les règles du fichier sont dictées par le Java ServiceLoader Mechanism. Ce fichier doit contenir, dans chaque ligne distincte, le nom de classe qualifié complet de l'implémentation d'intercepteur de client EJB. Les classes d'intercepteur de client EJB doivent être disponibles dans le chemin de classe. Les intercepteurs de client EJB ajoutés en utilisant le mécanisme de ServiceLoader sont ajoutés à la fin de la chaîne d'intercepteur de client, dans l'ordre dans lequel ils se trouvent dans le chemin de classe (classpath). Le démarrage rapide ou quickstart ejb-security-interceptors utilise cette approche.

2. Créer et configurer l'intercepteur du conteneur côté serveur

   Les classes d'intercepteur de conteneur sont de simples Plain Old Java Objects (POJOs). Elles utilisent @javax.annotation.AroundInvoke pour marquer la méthode qui sera invoquée lors de l'invocation sur le bean. Pour plus d'informations sur les intercepteurs de conteneur, consulter : Section 7.6.1, « Intercepteurs de conteneurs ».

   1. Créer l'intercepteur de conteneur

      Cet intercepteur reçoit le InvocationContext en même temps que l'identité et demande le changement d'identité nouvelle. Ce qui suit est une version modifiée de l'exemple de code  :

          public class ServerSecurityInterceptor {
      
          private static final Logger logger = Logger.getLogger(ServerSecurityInterceptor.class);
      
          static final String DELEGATED_USER_KEY = ServerSecurityInterceptor.class.getName() + ".DelegationUser";
      
          @AroundInvoke
          public Object aroundInvoke(final InvocationContext invocationContext) throws Exception {
              Principal desiredUser = null;
              UserPrincipal connectionUser = null;
      
              Map<String, Object> contextData = invocationContext.getContextData();
              if (contextData.containsKey(DELEGATED_USER_KEY)) {
                  desiredUser = new SimplePrincipal((String) contextData.get(DELEGATED_USER_KEY));
      
                  Collection<Principal> connectionPrincipals = SecurityActions.getConnectionPrincipals();
      
                  if (connectionPrincipals != null) {
                      for (Principal current : connectionPrincipals) {
                          if (current instanceof UserPrincipal) {
                              connectionUser = (UserPrincipal) current;
                              break;
                          }
                      }
      
                  } else {
                      throw new IllegalStateException("Delegation user requested but no user on connection found.");
                  }
              }
      
      
              ContextStateCache stateCache = null;
              try {
                  if (desiredUser != null && connectionUser != null
                      && (desiredUser.getName().equals(connectionUser.getName()) == false)) {
                      // The final part of this check is to verify that the change does actually indicate a change in user.
                      try {
                          // We have been requested to use an authentication token
                          // so now we attempt the switch.
                          stateCache = SecurityActions.pushIdentity(desiredUser, new OuterUserCredential(connectionUser));
                      } catch (Exception e) {
                          logger.error("Failed to switch security context for user", e);
                          // Don't propagate the exception stacktrace back to the client for security reasons
                          throw new EJBAccessException("Unable to attempt switching of user.");
                      }
                  }
      
                  return invocationContext.proceed();
              } finally {
                  // switch back to original context
                  if (stateCache != null) {
                      SecurityActions.popIdentity(stateCache);;
                  }
              }
          }
      

   2. Configurer l'intercepteur du conteneur

      Pour plus d'informations sur la façon de configurer les intercepteurs de conteneurs côté serveur, consulter : Section 7.6.3, « Configurer un intercepteur de conteneur ».

3. Créer le JAAS LoginModule

   Ce composant doit vérifier que l'utilisateur est en mesure d'exécuter les requêtes selon l'identité de la requête. Les exemples de code abrégés suivants indiquent les méthodes de login et de validation :

       @SuppressWarnings("unchecked")
       @Override
       public boolean login() throws LoginException {
           if (super.login() == true) {
               log.debug("super.login()==true");
               return true;
           }
   
           // Time to see if this is a delegation request.
           NameCallback ncb = new NameCallback("Username:");
           ObjectCallback ocb = new ObjectCallback("Password:");
   
           try {
               callbackHandler.handle(new Callback[] { ncb, ocb });
           } catch (Exception e) {
               if (e instanceof RuntimeException) {
                   throw (RuntimeException) e;
               }
               return false; // If the CallbackHandler can not handle the required callbacks then no chance.
           }
   
           String name = ncb.getName();
           Object credential = ocb.getCredential();
   
           if (credential instanceof OuterUserCredential) {
               // This credential type will only be seen for a delegation request, if not seen then the request is not for us.
   
               if (delegationAcceptable(name, (OuterUserCredential) credential)) {
   
                   identity = new SimplePrincipal(name);
                   if (getUseFirstPass()) {
                       String userName = identity.getName();
                       if (log.isDebugEnabled())
                           log.debug("Storing username '" + userName + "' and empty password");
                       // Add the username and an empty password to the shared state map
                       sharedState.put("javax.security.auth.login.name", identity);
                       sharedState.put("javax.security.auth.login.password", "");
                   }
                   loginOk = true;
                   return true;
               }
           }
   
           return false; // Attempted login but not successful.
       }
   
       protected boolean delegationAcceptable(String requestedUser, OuterUserCredential connectionUser) {
       if (delegationMappings == null) {
           return false;
       }
   
       String[] allowedMappings = loadPropertyValue(connectionUser.getName(), connectionUser.getRealm());
       if (allowedMappings.length == 1 && "*".equals(allowedMappings[1])) {
           // A wild card mapping was found.
           return true;
       }
       for (String current : allowedMappings) {
           if (requestedUser.equals(current)) {
               return true;
           }
       }
       return false;
   }
   

Procédure 7.13. Information de sécurité pour l'authentification EJB

1. Créer l'intercepteur côté client

   Cet intercepteur doit implémenter org.jboss.ejb.client.EJBClientInterceptor. L'intercepteur doit passer le token de sécurité supplémentaire par le mappage de données contextuelles, par l'intermédiaire d'un appel EJBClientInvocationContext.getContextData(). Voici un exemple de code d'intercepteur côté client qui crée un token de sécurité supplémentaire :

   public class ClientSecurityInterceptor implements EJBClientInterceptor {
   
       public void handleInvocation(EJBClientInvocationContext context) throws Exception {
           Principal currentPrincipal = SecurityActions.securityContextGetPrincipal();
   
           if (currentPrincipal != null) {
               Map<String, Object> contextData = context.getContextData();
               contextData.put(ServerSecurityInterceptor.DELEGATED_USER_KEY, currentPrincipal.getName());
           }
   
           context.sendRequest();
       }
   
       public Object handleInvocationResult(EJBClientInvocationContext context) throws Exception {
           return context.getResult();
       }
   
   }
   

   Pour obtenir des informations sur la façon de connecter l'intercepteur client dans une application, voir Section 7.6.6, « Utiliser un intercepteur côté client dans une application ».

2. Créer et configurer l'intercepteur du conteneur côté serveur

   Les classes d'intercepteur de conteneur sont de simples Plain Old Java Objects (POJOs). Elles utilisent @javax.annotation.AroundInvoke pour marquer la méthode qui est invoquée lors de l'invocation sur le bean. Pour plus d'informations sur les intercepteurs de conteneur, consulter : Section 7.6.1, « Intercepteurs de conteneurs ».

   1. Créer l'intercepteur de conteneur

      Cet intercepteur récupère le jeton d'authentification de sécurité du contexte et le passe au domaine JAAS (Java Authentication and Autorisation Service) pour vérification. Voici un exemple de code d'intercepteur de conteneur :

      public class ServerSecurityInterceptor {
      
          private static final Logger logger = Logger.getLogger(ServerSecurityInterceptor.class);
      
          static final String DELEGATED_USER_KEY = ServerSecurityInterceptor.class.getName() + ".DelegationUser";
      
          @AroundInvoke
          public Object aroundInvoke(final InvocationContext invocationContext) throws Exception {
              Principal desiredUser = null;
              UserPrincipal connectionUser = null;
      
              Map<String, Object> contextData = invocationContext.getContextData();
              if (contextData.containsKey(DELEGATED_USER_KEY)) {
                  desiredUser = new SimplePrincipal((String) contextData.get(DELEGATED_USER_KEY));
      
                  Collection<Principal> connectionPrincipals = SecurityActions.getConnectionPrincipals();
      
                  if (connectionPrincipals != null) {
                      for (Principal current : connectionPrincipals) {
                          if (current instanceof UserPrincipal) {
                              connectionUser = (UserPrincipal) current;
                              break;
                          }
                      }
      
                  } else {
                      throw new IllegalStateException("Delegation user requested but no user on connection found.");
                  }
              }
      
      
              ContextStateCache stateCache = null;
              try {
                  if (desiredUser != null && connectionUser != null
                      && (desiredUser.getName().equals(connectionUser.getName()) == false)) {
                      // The final part of this check is to verify that the change does actually indicate a change in user.
                      try {
                          // We have been requested to use an authentication token
                          // so now we attempt the switch.
                          stateCache = SecurityActions.pushIdentity(desiredUser, new OuterUserCredential(connectionUser));
                      } catch (Exception e) {
                          logger.error("Failed to switch security context for user", e);
                          // Don't propagate the exception stacktrace back to the client for security reasons
                          throw new EJBAccessException("Unable to attempt switching of user.");
                      }
                  }
      
                  return invocationContext.proceed();
              } finally {
                  // switch back to original context
                  if (stateCache != null) {
                      SecurityActions.popIdentity(stateCache);;
                  }
              }
          }
      
      

   2. Configurer l'intercepteur du conteneur

      Pour plus d'informations sur la façon de configurer les intercepteurs de conteneurs côté serveur, consulter : Section 7.6.3, « Configurer un intercepteur de conteneur ».

3. Créer le JAAS LoginModule

   Ce module personnalisé exécute l'authentification à l'aide de l'information de la connexion authentifiée existante ainsi qu'à l'aide qu'un jeton de sécurité supplémentaire. Voici un exemple de code réduit qui utilise le jeton de sécurité supplémentaire et qui exécute l'authentification. On peut trouver l'exemple de code complet dans le quickstart ejb-security-interceptors fourni dans JBoss EAP 6.3 ou version supérieure.

   public class DelegationLoginModule extends AbstractServerLoginModule {
   
       private static final String DELEGATION_PROPERTIES = "delegationProperties";
   
       private static final String DEFAULT_DELEGATION_PROPERTIES = "delegation-mapping.properties";
   
       private Properties delegationMappings;
   
       private Principal identity;
   
       @Override
       public void initialize(Subject subject, CallbackHandler callbackHandler, Map<String, ?> sharedState, Map<String, ?> options) {
           addValidOptions(new String[] { DELEGATION_PROPERTIES });
           super.initialize(subject, callbackHandler, sharedState, options);
   
           String propertiesName;
           if (options.containsKey(DELEGATION_PROPERTIES)) {
               propertiesName = (String) options.get(DELEGATION_PROPERTIES);
           } else {
               propertiesName = DEFAULT_DELEGATION_PROPERTIES;
           }
           try {
               delegationMappings = loadProperties(propertiesName);
           } catch (IOException e) {
               throw new IllegalArgumentException(String.format("Unable to load properties '%s'", propertiesName), e);
           }
       }
   
       @SuppressWarnings("unchecked")
       @Override
       public boolean login() throws LoginException {
           if (super.login() == true) {
               log.debug("super.login()==true");
               return true;
           }
   
           // Time to see if this is a delegation request.
           NameCallback ncb = new NameCallback("Username:");
           ObjectCallback ocb = new ObjectCallback("Password:");
   
           try {
               callbackHandler.handle(new Callback[] { ncb, ocb });
           } catch (Exception e) {
               if (e instanceof RuntimeException) {
                   throw (RuntimeException) e;
               }
               return false; // If the CallbackHandler can not handle the required callbacks then no chance.
           }
   
           String name = ncb.getName();
           Object credential = ocb.getCredential();
   
           if (credential instanceof OuterUserCredential) {
               // This credential type will only be seen for a delegation request, if not seen then the request is not for us.
   
               if (delegationAcceptable(name, (OuterUserCredential) credential)) {
   
                   identity = new SimplePrincipal(name);
                   if (getUseFirstPass()) {
                       String userName = identity.getName();
                       if (log.isDebugEnabled())
                           log.debug("Storing username '" + userName + "' and empty password");
                       // Add the username and an empty password to the shared state map
                       sharedState.put("javax.security.auth.login.name", identity);
                       sharedState.put("javax.security.auth.login.password", "");
                   }
                   loginOk = true;
                   return true;
               }
           }
   
           return false; // Attempted login but not successful.
       }
   
   
   

4. Ajouter le LoginModule personnalisé à la chaîne

   Vous devez ajouter le nouveau LoginModule personnalisé à l'endroit qui convient dans la chaîne pour qu'il soit invoqué dans le bon ordre. Dans cet exemple, le SaslPlusLoginModule doit être mis dans la chaîne avant le LoginModule qui charge les rôles par l'option password-stacking .

   • Configurer l'ordonnancement du LoginModule par le Management CLI

     Ce qui suit est un exemple de commandes de Management CLI qui enchaînent le SaslPlusLoginModule personnalisé avant que le LoginModule RealmDirect définisse l'option password-stacking.

     /subsystem=security/security-domain=quickstart-domain:add(cache-type=default)
     /subsystem=security/security-domain=quickstart-domain/authentication=classic:add
     /subsystem=security/security-domain=quickstart-domain/authentication=classic/login-module=DelegationLoginModule:add(code=org.jboss.as.quickstarts.ejb_security_plus.SaslPlusLoginModule,flag=optional,module-options={password-stacking=useFirstPass})
     /subsystem=security/security-domain=quickstart-domain/authentication=classic/login-module=RealmDirect:add(code=RealmDirect,flag=required,module-options={password-stacking=useFirstPass})

     Pour plus d'informations sur le Management CLI, voir le chapitre intitulé Management Interfaces du guide Administration and Configuration Guide de JBoss EAP 6 qui se trouve sur le portail clients https://access.redhat.com/site/documentation/JBoss_Enterprise_Application_Platform/

   • Configurer l'ordonnancement du LoginModule manuellement

     Ce qui suit est un exemple de XML qui configure l'ordonnancement du LoginModule dans le sous-système de security du fichier de configuration du serveur. Le SaslPlusLoginModule doit précéder le LoginModule RealmDirect pour qu'il puisse vérifier l'utilisateur distant avant que les rôles utilisateurs ne soient chargés et l'option password-stacking définie.

     <security-domain name="quickstart-domain" cache-type="default">
         <authentication>
             <login-module code="org.jboss.as.quickstarts.ejb_security_plus.SaslPlusLoginModule" flag="required">
                 <module-option name="password-stacking" value="useFirstPass"/>
             </login-module>
             <login-module code="RealmDirect" flag="required">
                 <module-option name="password-stacking" value="useFirstPass"/>
             </login-module>
         </authentication>
     </security-domain>
     

5. Créer le client distant

   Dans l'exemple de code suivant, on assume que le fichier additional-secret.properties auquel accède le JAAS LoginModule ci-dessus contient la propriété suivante :

   quickstartUser=7f5cc521-5061-4a5b-b814-bdc37f021acc
   

   Le code suivant montre comment créer un token de sécurité et comment le définir avant l'appel EJB. Le token secret est codé en dur dans des buts de démonstration uniquement. Ce client se contente d'afficher les résultats sur la console.

   import static org.jboss.as.quickstarts.ejb_security_plus.EJBUtil.lookupSecuredEJB;
   
   public class RemoteClient {
   
       /**
        * @param args
        */
       public static void main(String[] args) throws Exception {
           SimplePrincipal principal = new SimplePrincipal("quickstartUser");
           Object credential = new PasswordPlusCredential("quickstartPwd1!".toCharArray(), "7f5cc521-5061-4a5b-b814-bdc37f021acc");
   
           SecurityActions.securityContextSetPrincipalCredential(principal, credential);
           SecuredEJBRemote secured = lookupSecuredEJB();
   
           System.out.println(secured.getPrincipalInformation());
       }
   }
   

Procédure 7.14. Connecter l'intercepteur

• • Par programmation

    Par cette approche, vous appelez l'API org.jboss.ejb.client.EJBClientContext.registerInterceptor(int order, EJBClientInterceptor interceptor) et passez l'instance order et l'instance interceptor. L'instance order est utilisée pour déterminer où exactement cet interceptor est placé dans la chaîne d'intercepteur du client.

  • Mécanisme ServiceLoader

    Cette approche nécessite la création d'un fichier META-INF/services/org.jboss.ejb.client.EJBClientInterceptor et le placer ou le mettre dans le chemin de classe de l'application client. Les règles du fichier sont dictées par le Java ServiceLoader Mechanism. Ce fichier devrait contenir, dans chaque ligne distincte, le nom de classe qualifié complet de l'implémentation d'intercepteur de client EJB. Les classes d'intercepteur de client EJB doivent être disponibles dans le chemin de classe. Les intercepteurs de client EJB ajoutés en utilisant le mécanisme de ServiceLoader sont ajoutés à la fin de la chaîne d'intercepteur de client, dans l'ordre dans lequel ils se trouvent dans le chemin de classe (classpath). Le démarrage rapide ou quickstart ejb-security-interceptors utilise cette approche.

Procédure 9.1. Configurer le cache de session web

1. Modifier le mode cache par défaut en DIST.

   /profile=ha/subsystem=infinispan/cache-container=web/:write-attribute(name=default-cache,value=dist)
   

2. Définir le nombre de propriétaires de cache distribué.

   La commande suivante définit 5 propriétaires. La valeur par défaut est 2.

   /profile=ha/subsystem=infinispan/cache-container=web/distributed-cache=dist/:write-attribute(name=owners,value=5)
   

3. Modifier le mode cache par défaut en REPL.

   /profile=ha/subsystem=infinispan/cache-container=web/:write-attribute(name=default-cache,value=repl)
   

4. Relancer le serveur

   Après avoir modifié le mode cache du web, vous devez relancer le serveur.

Procédure 9.2. Rendez votre Application Distribuable

1. Prérequis : indiquer que votre application est distribuable

   Si votre application n'apparaît pas comme distribuable, ses sessions ne seront jamais distribuées. Ajouter l'élément <distributable/> dans la balise <web-app> du fichier descriptif web.xml de votre application. Voici un exemple :

   Exemple 9.1. Configuration minimum pour une application distribuable

   <?xml version="1.0"?>
   <web-app  xmlns="http://java.sun.com/xml/ns/j2ee"
             xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" 
             xsi:schemaLocation="http://java.sun.com/xml/ns/j2ee 
                                 http://java.sun.com/xml/ns/j2ee/web-app_2_4.xsd" 
             version="2.4">
             
         <distributable/>
       
   </web-app>
   
   

2. Modifier le comportement de réplication par défaut si vous le souhaitez.

   Si vous souhaitez changer une des valeurs qui affectent la réplique de session, vous pouvez les changer dans l'élément <replication-config> qui est un dépendant de l'élément enfant de l'élément <jboss-web> du fichier jboss-web.xml de votre application. Pour un exemple donné, ne l'inclure que si vous souhaitez remplacer les valeurs par défaut. L'exemple suivant énumère tous les paramètres par défaut, et est suivi d'un tableau qui explique les options les plus fréquemment modifées.

   Exemple 9.2. Valeurs <replication-config> par défaut

   <!DOCTYPE jboss-web PUBLIC
       "-//JBoss//DTD Web Application 5.0//EN"
       "http://www.jboss.org/j2ee/dtd/jboss-web_5_0.dtd">
   
   <jboss-web>
      
      <replication-config>
         <cache-name>custom-session-cache</cache-name>
         <replication-trigger>SET</replication-trigger>
         <replication-granularity>ATTRIBUTE</replication-granularity>
         <use-jk>false</use-jk>
         <max-unreplicated-interval>30</max-unreplicated-interval>
         <snapshot-mode>INSTANT</snapshot-mode>
         <snapshot-interval>1000</snapshot-interval>
         <session-notification-policy>com.example.CustomSessionNotificationPolicy</session-notification-policy>
     </replication-config>
   
   </jboss-web>