Empaquetage des modules EJB 3.x - Vue d'ensemble
Cette rubrique décrit l'empaquetage des applications utilisant des EJB (Enterprise JavaBeans) 3.x.
L'empaquetage des applications utilisant des beans EJB 3.x a des exigences similaires à celles de l'assemblage d'applications Java™ Platform, Enterprise Edition (Java EE) 1.4, à savoir que les composants sont empaquetés dans des modules, eux-mêmes enveloppés dans des fichiers d'archive d'application d'entreprise (EAR). Les composants, tout comme les modules, comportent des métadonnées de description fournies dans un descripteur de déploiement XML (Extensible Markup Language). La spécification EJB 3.x prévoit une méthode supplémentaire de fourniture des métadonnées et d'empaquetage des unités de persistance.
- Fichiers JAR (Java application archive) pour modules EJB. Modules de client d'application Java EE et modules de classe utilitaire.
- Fichiers WAR (Web application archive) pour modules Web ou contenu EJB. Un fichier WAR ne peut inclure du contenu EJB que s'il est au niveau de version 2.5 ou supérieur.
- Autres modules associés à une technologie spécifique, tels que fichiers RAR (resource application archive), et autres types de modules.
Modules EJB sans descripteur de déploiement
Vous pouvez assembler des modules EJB sans descripteur de déploiement si vous utilisez des beans EJB 3.x. Pour ce faire, vous devez créer un fichier JAR ou un fichier WAR avec des métadonnées dans une annotation située dans le composant EJB. Les beans EJB 3.x ne nécessitent pas d'entrée dans le fichier ejb-jar.xml pour les métadonnées définies via des annotations.
Avec la spécification EJB 3.0, le comportement par défaut consistait à examiner les annotations lors de l'installation d'un module EJB 3.0. Dans WebSphere Application Server Version 9.0, par défaut, les modules antérieurs à Java EE 5 ne sont pas examinés lors de l'installation de l'application ou du démarrage du serveur.
Pour conserver la rétrocompatibilité avec les composants Feature Pack for EJB 3.0 et Feature Pack for Web Services, vous devez choisir si les modules Web existants seront analysés pour rechercher des métadonnées supplémentaires. Une commutation de niveau de serveur est définie pour chaque comportement d'analyse de regroupement de fonctionnalités. Si la valeur par défaut ne convient pas, la commutation doit être définie sur chaque serveur et serveur d'administration nécessitant une modification de la valeur par défaut. Les commutateurs sont des propriétés personnalisées du serveur appelées com.ibm.websphere.webservices.UseWSFEP61ScanPolicy={true|false} et com.ibm.websphere.ejb.UseEJB61FEPScanPolicy={true|false}. Pour définir ces propriétés dans la console d'administration, cliquez sur
.Modules EJB avec descripteurs de déploiement
Vous pouvez continuer à utiliser des modules EJB avec des descripteurs de déploiement. Les modules avec descripteurs de déploiement peuvent gérer un niveau quelconque de spécification EJB, y compris EJB 3.x, mais ces descripteurs devraient généralement refléter les exigences d'implémentation des composants inclus dans le module.
Un module EJB peut avoir un descripteur de déploiement de niveau EJB 3.x, 2.x ou 1.x.
Les descripteurs de déploiement EJB 2.x ou 1.x sont censés contenir les métadonnées complètes du module. Pour cette raison, aucune analyse complémentaire des annotations n'a lieu.
L'analyse des annotations par le conteneur EJB est effectuée sur les modules EJB qui ne comportent pas de descripteur de déploiement ou qui ont un descripteur de déploiement ejb-jar.xml obéissant au schéma de la spécification EJB 3.0, avec l'attribut XML metadata-complete réglé à 'false' ou omis. Consultez la section Comportement d'examen des annotations, qui décrit toutes les règles appliquées par le serveur pour déterminer s'il doit ou non examiner les annotations.
Comportement d'examen des annotations
Le serveur peut rechercher et examiner le contenu des annotations dans les fichiers de classe du module. Cette recherche porte sur les annotations qui définissent un composant, une référence à une ressource ou un comportement particulier. Par exemple, des annotations peuvent être utilisées pour définir un composant EJB ou pour déclarer une référence à une source de données qui doit être utilisée par un composant EJB, ou encore pour déclarer les attributs transactionnels ou de sécurité associés à une méthode EJB. Ce processus d'inspection est appelé examen des annotations (de l'anglais "annotation scanning"). Si les fichiers de classe dans le module contiennent des annotations qui doivent être respectées par le serveur, celui-ci doit être configuré pour examiner les annotations. Si, au contraire, les fichiers de classe dans le module ne contiennent pas d'annotations, alors vous pouvez gagner en performances en configurant le serveur de telle sorte que l'examen des annotations n'ait pas lieu.
- Existence ou non d'un fichier descripteur de déploiement ejb-jar.xml
- Version du descripteur de déploiement ejb-jar.xml, lorsqu'il existe
- Valeur de l'attribut metadata-complete dans le descripteur de déploiement ejb-jar.xml, lorsqu'il existe
- Version du descripteur de déploiement web.xml, lorsque le contenu EJB est empaqueté dans un module WAR et que le descripteur de déploiement ejb-jar.xml n'existe pas
- Valeur de l'attribut metadata-complete dans le descripteur de déploiement web.xml, lorsque le contenu EJB est empaqueté dans un module WAR et que le descripteur de déploiement ejb-jar.xml n'existe pas
Les tableaux suivants indiquent comment est prise la décision d'examiner ou non les annotations pour le contenu EJB empaqueté dans un module JAR d'EJB (premier cas) et pour le contenu EJB empaqueté dans un module WAR (second cas).
Fichier ejb-jar.xml | Valeur de metadata-complete dans ejb-jar.xml | Annotations examinées ? |
---|---|---|
Est présent - version 2.x ou inférieure | N/A | Non |
Est présent - version 3.x ou supérieure | true | Non |
Est présent - version 3.x ou supérieure | false (ou omis) | Oui |
Est absent | N/A | Oui |
Fichier ejb-jar.xml | Valeur de metadata-complete dans ejb-jar.xml | Fichier web.xml | Valeur de metadata-complete dans web.xml | Annotations examinées ? |
---|---|---|---|---|
Est présent - version 3.x ou supérieure | true | N/A | N/A | Non |
Est présent - version 3.x ou supérieure | false (ou omis) | N/A | N/A | Oui |
Est présent - version 2.x ou inférieure | N/A | N/A | N/A | Non |
Est absent | N/A | Est présent - version 2.5 ou supérieure | true | Non |
Est absent | N/A | Est présent - version 2.5 ou supérieure | false (ou omis) | Oui |
Est absent | N/A | Est présent - version 2.4 ou inférieure | N/A | Non |
Est absent | N/A | Est absent | N/A | Oui |
Il est important de bien faire la distinction entre l'attribut metadata-complete de l'élément ejb-jar du descripteur de déploiement ejb-jar.xml et le paramètre metadata-complete dont la valeur peut être spécifiée durant l'installation de l'application ou du module.
L'attribut metadata-complete de l'élément ejb-jar du fichier ejb-jar.xml est un attribut XML. Il est utilisé par le serveur pour déterminer s'il doit examiner les annotations dans les classes, conformément aux règles décrites dans les tableaux ci-dessus.
En revanche, le paramètre metadata-complete, qui peut être spécifié à l'installation de l'application ou du module, est utilisé par le serveur pour aider à générer le fichier ejb-jar.xml. Si aucun fichier ejb-jar.xml n'existe dans le module et que le paramètre metadata-complete est réglé à true durant l'installation, le serveur examine le contenu des annotations et l'utilise pour générer un fichier ejb-jar.xml, puis il met à true l'attribut XML metadata-complete dans ce même fichier.
Unités de persistance
Les unités de persistance, notamment le fichier persistence.xml et les classes qui lui sont associées, peuvent être empaquetées dans le module pour lequel elles sont requises. Elles peuvent aussi être incluses dans le fichier d'utilitaire JAR séparé intégré dans le fichier EAR avec son module dépendant.
Conditionnement d'application
Vous pouvez combiner dans la même application des beans EJB versions 2.x et antérieures avec des beans EJB 3.x. Les beans EJB 3.x ne sont toutefois pas reconnus dans les modules EJB 2.x ou EJB 1.x.
- Le nom de l'application est présumé être le même que celui du fichier EAR, mais en omettant l'extension de fichier EAR.
- Les fichiers se terminant par l'extension .war sont présumés être des modules Web. La racine de contexte du module Web est le nom du fichier relatif à la racine du package de l'application, en supprimant l'extension de nom de fichier WAR.
- Les fichiers se terminant par l'extension .jar, qui ne sont pas dans le répertoire /lib et qui contiennent soit un fichier ejb-jar.xml, soit au moins une classe définissant une annotation @Stateful, @Stateless, @Singleton ou @MessageDriven sont présumés être des modules EJB.
- Les autres fichiers JAR hors du répertoire /lib ne sont pas présumés représenter des modules EJB.
Conditionnement JPA
Il est recommandé d'assembler les unités de persistance dans des fichiers JAR séparés pour les rendre plus accessibles et réutilisables. Elles peuvent être testés en dehors de leur conteneur, que la persistance effective de base de données intervienne ou non. Les unités de persistance peuvent être incluses dans des applications autonomes ou dans des fichiers EAR sous formes de fichiers utilitaires JAR. En raison de la diversité des scénarios d'utilisation et des problèmes de performance potentiels lors de l'analyse d'une grande quantité de classes, il est recommandé que l'unité de persistance définisse les classes des unités de persistance.
Façades de session utilisées pour le scénario de persistance
Un des schémas usuels consiste à utiliser des façades de session pour la persistance. L'utilisation de façades de bean session pour conduire JPA est prise en charge. L'interface EntityManager n'assure pas le cloisonnement des unités d'exécution et, par conséquent, les servlets ne devraient jamais injecter @PersistenceContext. Les servlets doivent soit utiliser le modèle de façade, soit une instance EntityManagerFactory pour créer un objet EntityManager lors de chaque requête.
Il est recommandé que les unités de persistance JPA soient définies dans un fichier JAR propre, distinct des façades de bean session. Cette pratique optimale offre non seulement plus de flexibilité pour le partage mais aussi évite des problèmes dus à la combinaison de classes annotées JPA et non JPA.
Généralement, un fichier JAR est créé pour héberger les classes d'entité et la définition JPA persistence.xml, puis ajouté au fichier EAR en tant que fichier utilitaire JAR. Le module EJB 3.x ajoute une dépendance sur le fichier JAR en la déclarant dans le fichier MANIFEST.MF du module. Par exemple, si une archive EAR contient les fichiers TradeApp.ear, TradeWeb.war, EJB3Trade.jar et TradeInfo.jar, le fichier EJB3Trade.jar doit contenir une section MANIFEST.MF similaire à ceci :
Manifest-Version: 1.0
Class-Path: TradeInfo.jar
La façade de session dans le fichier EJB3Trade.jar fait référence aux classes d'entité JPA et aux unités de persistance situées dans le fichier TradeInfo.jar. L'application Web définie dans le fichier TradeWeb.war peut faire de même pour opérer sur les objets entité en tant qu'objets de transfert de données circulant entre les niveaux de conteneur Web et EJB.
Scénario de références entre beans de session inter-niveaux et inter-versions
Vous pouvez définir et utiliser des références à des beans de session EJB 3.x de plusieurs manières. Dans le cas de références de session à session EJB 3.x, la cible d'injection @EJB peut être utilisée. Pour les références inter-niveaux (par exemple, application Web à session EJB 3.x) ou inter-versions (par exemple, session EJB 2.1 à session EJB 3.x), une référence du descripteur de déploiement XML peut être utilisée pour définir ejb-refs et ejb-local-refs. Deux variantes sont utilisables, selon qu'il est fait référence à une interface métier EJB 3.x ou à une interface de composant pré-EJB 3.x définissant également une interface EJBLocalHome. Les applications Web et client peuvent également recourir à l'annotation @EJB si le composant référencé peut être résolu via la fonction AutoLink.
Le scénario précédent utilise une combinaison client de style EJB 2.1 avec une implémentation de bean de session EJB 3.x. Pour un style de client plus actuel, le côté client peut être modifié afin de rechercher directement l'interface métier du bean de session au lieu de passer par une interface home. Dans ce cas, il n'est pas nécessaire de définir l'annotation @LocalHome(<localhome>.class). Vous pouvez utiliser une variante des définitions ejb-ref et ejb-local-ref à cet effet. Utilisez une valeur null pour l'élément local-home et liez l'élément ejb-local-ref à la liaison ejblocal: du bean session au lieu de la liaison home. Exemple :
<ejb-local-ref id="EJBLocalRef_1154112538064">
<description>com.ibm.persistence.ejb3.order.facadecom.ibm.persistence.ejb3.order.facade</description>
<ejb-ref-name>ejb/OrderEJB</ejb-ref-name>
<ejb-ref-type>Session</ejb-ref-type>
<local-home></local-home>
<local>com.ibm.persistence.ejb3.order.facade.OrderProcessor</local>
</ejb-local-ref>
Le code client doit également être adapté pour effectuer le transtypage approprié à l'objet recherché. Dans ce cas, l'interface métier au lieu de l'interface home :
try {
InitialContext ctx = new InitialContext();
orderProcessor = (OrderProcessor)ctx.lookup("java:comp/env/ejb/OrderEJB");
}
catch(Exception e) {
e.printStackTrace(System.out);
throw new ServletException(e);
}