Présentation des liaisons d'application EJB 3.0 et EJB 3.1
Avant qu'une application installée sur un serveur d'applications puisse être démarrée, toutes les références de ressource et les références d'EJB (Enterprise JavaBeans) définies dans l'application doivent être liées aux artefacts réels (beans enterprise ou ressources) définis sur le serveur d'applications.
A partir de la version 8.0, la prise en charge des liaisons dans le conteneur EJB a été développée. Le conteneur EJB affecte des liaisons JNDI par défaut aux interfaces métier EJB 3.x en fonction du nom d'application, du nom de module et du nom de composant. Il n'est pas nécessaire de définir explicitement des noms de liaison JNDI pour chaque interface ou objet EJB home dans un module EJB 3.x ou des vues sans interface dans un module EJB 3.1.
Lors de la définition des liaisons, vous devez spécifier les noms JNDI (Java™ Naming and Directory Interface) des artefacts référencés ou pouvant être référencés dans une application. Les valeurs jndiName spécifiées pour les artefacts doivent être des noms de recherche qualifiés.
Il n'est pas nécessaire d'affecter manuellement des noms de liaison JNDI à chaque interface, interface EJB home ou vue sans interface de vos beans enterprise dans les modules EJB 3.x. Si vous ne les définissez pas explicitement, le conteneur EJB affecte lui-même des liaisons par défaut.
Espaces de noms JNDI pour les liaisons EJB par défaut
Les liaisons EJB par défaut peuvent être placées, par le serveur d'applications, dans le jeu d'espaces de noms classiques ou dans le jeu java:[portée].
Le jeu classique est constitué des espaces de noms JNDI ejblocal: et global. Les espaces de noms classiques incluent une extension WebSphere ; ils existaient dans les versions du produit Application Server postérieures à la version 8.0.
Le jeu d'espaces de noms java:[portée] est constitué des espaces java:global, java:app et java:module. Les espaces de noms java:[portée] sont définis par la spécification Java EE 6 et font leur première apparition dans la version 8.0 de WebSphere Application Server. Ils ne remplacent pas les espaces de noms classiques. Ils doivent plutôt être considérés comme un complément à ces derniers.
Détails des espaces de noms classiques
- l'espace de noms ejblocal: dont la portée est la machine virtuelle Java (JVM)
- l'espace de nom JNDI global.
Les interfaces EJB locales, les objets home locaux et les vues sans interface doivent être liées dans un espace de noms ejblocal: classique, dont la portée est la machine virtuelle Java ; ils ne sont accessibles que depuis le même processus de serveur d'applications.
En revanche, les interfaces EJB distantes et les objets home distants doivent toujours être liés dans l'espace de noms JNDI global classique, dont la portée est WebSphere ; ils sont accessibles de partout, y compris depuis les autres processus de serveur et les autres clients distants. Les interfaces locales et les vues sans interface ne peuvent pas être liées dans l'espace de noms JNDI global classique, de même que les interfaces distantes ne peuvent pas être liées dans l'espace de noms ejblocal: dont la portée est la machine virtuelle Java.
Les espaces de noms global et ejblocal: sont séparés et distincts. Par exemple, une interface EJB locale ou une vue sans interface liée à "ejblocal:AccountHome" est différente d'une interface distante liée à "AccountHome" dans l'espace de noms global classique. Ce comportement permet de conserver la distinction entre vos références d'interfaces locales et distantes. L'existence d'un espace de nom local dont la portée est la machine virtuelle Java permet également à vos applications de rechercher ou de référencer directement des interfaces EJB locales et des vues sans interface de n'importe quel endroit dans le processus de serveur JVM, y compris entre les applications Java Platform Enterprise Edition (Java EE).
Liaisons JNDI classiques par défaut pour les interfaces métier EJB dans le conteneur EJB 3.x basées sur les noms d'application, de module et de composant
Le conteneur EJB affecte aux interfaces métier EJB 3.x des liaisons JNDI par défaut classiques, reposant sur le nom d'application, le nom de module et le nom de composant ; par conséquent, il importe de comprendre la façon dont ces noms sont définis. Chacun de ces noms est constitué par une chaîne de caractères.
- Des fichiers JAR (Java Application Archive) pour les modules EJB, les modules de client d'application Java EE et les modules de classes utilitaires
- Des fichiers WAR (Web Application Archive) pour les modules Web
- D'autres modules associés à une technologie spécifique, tels que fichiers RAR (Resource Application Archive), et autres types de modules.
Comme les modules Java EE sont assemblés au sein d'archives d'application Java EE et que les composants Java EE sont eux-mêmes assemblés au sein de modules Java EE, le "chemin d'imbrication" de chaque composant peut être utilisé pour identifier chacun d'eux de manière unique dans une archive d'application Java EE d'après le nom de l'application, le nom de module et le nom de composant correspondants.
Nom d'application utilisé dans les liaisons classiques
- la valeur du nom d'application spécifiée dans la console d'administration du produit ou le paramètre appname indiqué à l'outil de script de ligne de commande wsadmin lors de l'installation de l'application dans le produit,
- La valeur du paramètre <nom-affiché> dans le descripteur de déploiement META-INF/application.xml de l'application.
- Le nom du fichier EAR dépourvu du suffixe .ear. Par exemple, le fichier EAR d'application CustomerServiceApp.ear aura le nom d'application "CustomerServiceApp" dans ce cas.
- La valeur du paramètre <application-name> dans le descripteur de déploiement application.xml de l'application.
- Le nom du fichier EAR dépourvu du suffixe .ear. Par exemple, le fichier EAR d'application CustomerServiceApp.ear aura le nom d'application "CustomerServiceApp". Si l'application est un module autonome, le nom de consultation java:global ne contient pas de composant d'application.
Nom de module utilisé dans les liaisons classiques
Le nom du module correspond à l'URI (Uniform Resource Identifier) du fichier de module, relative à la racine du fichier EAR qui l'héberge. En d'autres termes, le nom du module est celui de son fichier, relatif à la racine du fichier EAR, et incluant tout sous-répertoire dans lequel le fichier de module est imbriqué. Cette convention de dénomination est également vraie lorsqu'un nom de module logique est explicitement spécifié avec l'élément module-name dans le descripteur de déploiement.
CustomerServiceApp.ear:AccountProcessing.jar
com/mycompany/AccountProcessingServiceBean.class AccountProcessingService.class
Utility/FinanceUtils.jar META-INF/ejb-jar.xml
com/mycompany/InterestCalculatorServiceBean.class InterestCalculatorService.class
AppPresentation.war META-INF/web.xml
- La valeur du paramètre <module-name> dans le descripteur de déploiement ejb-jar.xml ou web.xml du module.
- L'URI du module, à l'exception de son suffixe .jar ou .war. Par exemple, un module ayant l'URI CustomerService.jar ou CustomerService.war porte le nom "CustomerService".
Nom de composant EJB utilisé dans les liaisons classiques
- La valeur de la balise ejb-name associée au bean dans le descripteur de déploiement ejb-jar.xml, s'il est présent.
- La valeur du paramètre "name", s'il y figure, dans l'annotation @Stateless, ou @Stateful, associée au bean.
- Le nom de la classe d'implémentation du bean, sans qualificateur de niveau de package.
Liaisons
Les liaisons suivantes sont prises en charge par les modules EJB 3.x et décrites dans les sections ci-après :
- Liaisons par défaut classiques pour les interfaces métier, les interfaces home et les vues sans interface
- Canevas de liaison par défaut classique
- Liaisons java:[portée]
- Liaisons définies par l'utilisateur pour les interfaces EJB métier, les interfaces home et les vues sans interface
- Liaisons définies par l'utilisateur pour la résolution des références et des cibles d'injection
- La résolution par défaut de références EJB et d'injections EJB : la fonction de liaison automatique Autolink
- Résolution des références et des injections d'EJB et de ressource : la fonction lookup
- Remplacement d'entrées d'environnement définies dans des applications
- Remplacement de définitions de source de données
- Considérations relatives à l'attribution de noms dans les environnements en cluster
- Paramètres d'extension EJB définis par l'utilisateur
- Liaisons héritées (XMI)
- Liaisons XML définies par l'utilisateur
Liaisons par défaut classiques pour les interfaces métier, les interfaces home et les vues sans interface EJB
Il n'est pas nécessaire de définir explicitement des noms de liaison JNDI pour chaque interface ou objet EJB home dans un module EJB 3.x ou des vues sans interface dans un module EJB 3.1. Si vous n'affectez pas de liaisons explicitement, le conteneur EJB du produit affecte des liaisons par défaut classiques, selon les règles énoncées ici. Cette procédure est différente de la prise en charge des EJB dans le produit avant l'application de la spécification EJB 3.0.
Le conteneur EJB établit deux liaisons par défaut classiques pour chaque interface (métier, home distante et home locale) ou vue sans interface de chaque bean enterprise. Ces deux liaisons classiques sont appelées ici liaison abrégée et liaison longue des vues avec interface ou sans interface. La liaison abrégée utilise seulement le nom de classe Java de l'interface ou de la vue sans interface, qualifié par son package, alors que la liaison longue utilise l'ID de composant du bean enterprise comme qualificateur supplémentaire avant le nom de classe de la vue sans interface ou de l'interface qualifié par son package, avec un dièse (#) entre l'ID de composant et le nom de classe de l'interface ou de la vue sans interface. Par analogie, vous pouvez vous remémorer les deux formes que peut prendre le nom d'hôte TCP/IP : le nom abrégé (juste le nom de la machine) par opposition à son nom long (nom de la machine précédé du nom du domaine).
Par exemple, les liaisons par défaut classiques abrégée et longue d'une interface ou d'une vue sans interface pourraient être, respectivement, com.mycompany.AccountService et AccountApp/module1.jar/ServiceBean#com.mycompany.AccountService.
Par défaut, l'ID de composant pour les liaisons d'EJB par défaut classiques est formé à partir du nom de l'application, du nom du module et du nom du composant du bean enterprise ; toutefois, vous pouvez lui affecter à la place la chaîne de votre choix. En définissant votre propre chaîne en tant qu'ID de composant, vous pouvez mettre en place une convention de dénomination d'après laquelle les liaisons sous leur forme longue du bean enterprise partagent une portion commune définie par l'utilisateur tout en en comportant une autre définie par le système et basée sur le nom de chaque classe d'interface ou de vue sans interface. Cette opération permet également de rendre les noms de liaison d'EJB par défaut indépendants de la place où vous avez positionné les beans enterprise dans la hiérarchie de modules de l'application. La substitution de l'ID de composant par défaut d'un bean enterprise est décrite dans la section "Liaisons définies par l'utilisateur pour les interfaces EJB métier, les interfaces home et les vues sans interface" de cette rubrique.
Comme mentionné auparavant dans la section consacrée aux espaces de noms classiques (local avec portée JVM et JNDI avec portée globale), toutes les interfaces EJB locales, les interfaces home locales et les vues sans interface doivent être liées dans l'espace de noms classique ejblocal:, lequel n'est accessible que depuis le même processus de serveur (JVM), tandis que les interfaces EJB distantes et les interfaces home distantes doivent être liées dans l'espace de noms classique global, lequel est accessible depuis n'importe quel endroit dans la cellule du produit WebSphere. Comme il se doit, le conteneur EJB se conforme à ces règles pour les liaisons par défaut.
De plus, les liaisons par défaut longues des interfaces distantes suivent les pratiques Java EE recommandées en ce qu'elles sont groupées sous un nom de contexte ejb. Par défaut, les interfaces EJB home et métier distantes sont liées à la racine du contexte de nommage du serveur d'applications. Toutefois, dans une perspective de réduction de l'encombrement, étant donné que ce contexte est aussi utilisé pour d'autres liaisons que les interfaces EJB, il est conseillé de regrouper les liaisons associées aux EJB dans un sous-contexte "ejb" au lieu de les placer directement sous le contexte racine du serveur. Cette approche est similaire à l'utilisation de sous-répertoires sur un volume de disque au lieu d'héberger tous les fichiers sous son répertoire racine.
- Les liaisons abrégées par défaut permettent un accès simple et direct aux interfaces EJB. Le fait de les placer directement sous le contexte racine du serveur et de s'y référer uniquement à l'aide du nom de l'interface ou de son nom précédé par ejblocal: concorde avec cet objectif de simplicité.
- Parallèlement, le positionnement des liaisons longues par défaut sous le contexte ejb, ou sous le contexte ejblocal: dans le cas d'une interface locale, distançait ces liaisons du contexte racine du serveur en réduisant son encombrement, permettant ainsi d'y garder les liaisons abrégées.
- Cette approche assure un certain degré de compatibilité avec d'autres serveurs d'applications Java EE qui utilisent des conventions de dénomination similaires.
Pour résumer, toutes les liaisons par défaut locales, aussi bien les courtes que les longues, sont placées dans l'ejblocal classique, serveur/espace de nom dont la portée est la machine virtuelle Java, alors que les liaisons par défaut distantes sont placées dans le contexte racine du serveur de l'espace de nom classique dont la portée est globale si elles sont courtes ou dans <racine_serveur>/contexte ejb (suivi du contexte racine du serveur) si elles sont longues. Par conséquent, les seules liaisons par défaut sous le contexte racine avec portée globale du serveur sont les liaisons abrégées des interfaces distantes, ce qui constitue le meilleur compromis entre l'existence d'un modèle d'utilisation simple et portable et la volonté de réduction de l'encombrement de ce contexte racine.
Canevas de liaison par défaut classique
Les canevas de chaque type de liaison classique sont présentés dans le tableau ci-dessous. Dans ces canevas, les chaînes écrites en <italique dans des crochets> représentent une valeur. Par exemple, <interface.qualifiée.package> peut être com.mycompany.AccountService et <id-composant> peut être AccountApp/module1.jar/ServiceBean.
Modèles de liaisons | Description |
---|---|
ejblocal:<interface.qualifiée.package> | Interfaces locales, interfaces home et vues sans interface sous forme abrégée |
<interface.qualifiée.package> | Interfaces distantes et home sous forme abrégée |
ejblocal:<id-composant>#<interface.qualifiée.package> | Interfaces locales, interfaces home et vues sans interface sous forme longue |
ejb/<id-composant>#<interface.qualifiée.package> | Interfaces distantes et home sous forme longue |
Le canevas par défaut de l'attribut component-id est <nom-application>>/<nom-module-jar> /<nom-ejb> sauf s'il est remplacé dans le fichier de liaison du module EJB à l'aide de l'attribut component-id comme décrit dans la section "Conflits entre les noms de liaison courts par défaut lorsque plusieurs beans enterprise implémentent la même interface" ci-dessous. La variable <module-jar-name>, lorsqu'elle n'est pas remplacée par le fichier de liaison de module EJB, est le nom du fichier de module physique dans le fichier EAR, y compris l'extension, par exemple .jar, .ear, .war, comme indiqué dans la section précédente "Nom du module", même si un nom de module global est défini dans le descripteur de déploiement.
Conflits entre les noms de liaison classiques courts par défaut lorsque plusieurs beans enterprise implémentent la même interface
Lorsque plusieurs beans enterprise s'exécutant sur le serveur d'applications implémentent une interface ou une vue sans interface donnée, la version courte de son nom de liaison classique par défaut peut être ambiguë étant donné qu'elle peut faire référence à plusieurs JavaBeans Enterprise qui implémentent cette interface ou cette vue sans interface. Afin d'éviter cette situation, vous devez soit définir explicitement une liaison pour chaque Enterprise JavaBeans qui implémente l'interface ou la vue sans interface donnée comme décrit dans la section suivante, soit interdire l'utilisation des versions courtes des liaisons par défaut classiques pour les applications contenant ces Enterprise JavaBeans. Dans ce dernier cas, définissez la propriété personnalisée com.ibm.websphere.ejbcontainer.disableShortDefaultBindings de la JVM du produit WebSphere. Pour plus d'informations sur la définition de la propriété personnalisée JVM, lisez la rubrique relative aux propriétés personnalisées de machine virtuelle Java.
Pour utiliser cette propriété JVM personnalisée, attribuez-lui le nom com.ibm.websphere.ejbcontainer.disableShortFormBinding et la valeur générique * (astérisque) afin de désactiver les liaisons par défaut classiques sous leur forme abrégée pour toutes les applications sur le serveur, ou encore une séquence de noms d'application Java EE délimités par des signes deux-points pour lesquelles ces noms de liaison abrégés par défaut doivent être désactivés. Exemple : PayablesApp:InventoryApp:AccountServicesApp.
Conséquences de l'affectation explicite sur les liaisons par défaut classiques

Espaces noms java:[portée]
Les espaces de noms java:global, java:app et java:module sont des nouveautés propres à la spécification Java EE 6. Ils fournissent un mécanisme pour la liaison et la recherche de ressources, ce mécanisme étant portable entre serveurs d'applications.
Le serveur crée toujours des liaisons longues pour les différentes interfaces EJB, y compris pour la vue sans interface, et les place dans les espaces de noms java:global, java:app et java:module. Une forme courte de chaque liaison est également créée et placée dans les espaces de noms java:global, java:app et java:module, pour le cas où le bean n'expose qu'une seule interface, dont la vue sans interface. Les liaisons par défaut ne sont créées que pour les beans de session. Elles ne sont pas créées pour les beans entity ni pour les beans gérés par message (MDB).
Les formes longue et courte de chaque liaison contiennent toutes les deux le nom de l'application, le nom du module et le nom du composant bean. Le nom de l'application est, par défaut, le nom de base du fichier .ear, sans l'extension. Il peut être remplacé par un autre nom au moyen de l'élément application-name, dans le fichier application.xml. Le nom du module est, par défaut, le nom de chemin du module, sans l'extension, mais avec tous les noms de répertoire. Il peut être remplacé par un autre nom au moyen de l'élément module-name, dans le fichier ejb-jar.xml ou web.xml (selon la nature du module). Le nom du composant bean est, par défaut, le nom non qualifié de la classe du bean. Il peut être remplacé par un autre nom au moyen de l'attribut name, dans l'annotation définissant le composant EJB, ou de l'élément ejb-name dans le fichier ejb-jar.xml.
Dans sa forme longue, la liaison a la structure suivante : java:global/<nomApplication>/<nomModule>/<nom du composant bean>!<nom qualifié complet de l'interface>.
Dans sa forme courte, la liaison a la structure suivante : java:global/<nomApplication>/<nomModule>/<nom du composant bean>.
- java:global/myApp/myModule/MyBeanComponent!com.foo.MyBeanComponentLocalInterface
- java:global/myApp/myModule/MyBeanComponent
- java:app/myModule/MyBeanComponent!com.foo.MyBeanComponentLocalInterface
- java:app/myModule/MyBeanComponent
- java:module/MyBeanComponent!com.foo.MyBeanComponentLocalInterface
- java:module/MyBeanComponent
- Utilisez l'attribut lookup sur l'annotation @EJB ;
par exemple :
@EJB(lookup="java:global/myApp/myModule/MyBeanComponent")
- Utilisez l'élément lookup-name du fichier ejb-jar.xml ;
par exemple :
<lookup-name>java:global/myApp/myModule/MyBeanComponent!com.ibm.MyBeanComponentLocalInterfaces</lookup-name>
- Exécutez une opération lookup sur l'objet
InitialContext ; par exemple :
initialContext.lookup("java:global/myApp/myModule/MyBeanComponent!com.foo.MyBeanComponentLocalInterfaces")
Outre les liaisons par défaut créées par le serveur d'applications, vous pouvez définir des références dans les espaces de noms java:global, java:app et java:module. Les références définies dans les espaces de noms java:global, java:app et java:module ne vont pas dans l'espace de noms des composants (comp). Elles doivent être recherchées ou injectées dans ces espaces de noms. Elles ne peuvent pas être recherchées ni injectées dans l'espace de noms des composants.
Un composant bean peut utiliser l'espace de noms java:module pour déclarer une référence qui soit utilisable par un composant empaqueté dans le même module. Il peut utiliser l'espace de noms java:app pour déclarer une référence qui soit utilisable par un composant empaqueté dans un autre module, mais au sein de la même application. Il peut utiliser l'espace de noms java:global pour déclarer une référence qui soit utilisable par un composant empaqueté dans une autre application.
Les références avec des noms identiques dans les espaces de noms java:global, java:app ou java:module peuvent être en conflit, tout comme peuvent l'être les références avec des noms identiques dans l'espace de noms des composants. Une référence dont la portée est l'espace de nom java:app d'une application particulière n'est pas en conflit avec une référence homonyme, mais dont la portée est l'espace de nom java:app d'une autre application. De même, une référence dont la portée est l'espace de nom java:module d'un module particulier n'est pas en conflit avec une référence homonyme, mais dont la portée est l'espace de nom java:module d'un autre module.
@EJB(name="java:global/env/myBean")
<resource-ref>
<res-ref-name>java:global/env/myDataSource</res-ref-name>
....
</resource-ref>
Pour une documentation plus complète sur les espaces de noms java:[portée], consultez la section 5.2.2 de la spécification Java EE 6 et la section 4.4 de la spécificatiotn JavaBeans 3.1.
Liaisons définies par l'utilisateur pour les interfaces EJB métier, les interfaces home et les vues sans interface
Dans les cas où vous souhaitez définir manuellement des emplacements de liaison au lieu de ceux par défaut du produit, vous pouvez utiliser le fichier de liaison du module EJB afin d'affecter vous-même les emplacements de liaison à des interfaces, des interfaces home et des vues sans interface spécifiques. Vous pouvez également utiliser ce fichier afin de remplacer uniquement la portion relative à l'ID de composant des liaisons par défaut d'un ou de plusieurs beans enterprise du module. Le remplacement de l'ID de composant constitue une solution intermédiaire entre l'utilisation de toutes les liaisons par défaut et la spécification manuelle de l'intégralité du nom de liaison pour chaque interface ou vue sans interface.
Pour spécifier des informations de liaisons définies par l'utilisateur pour des modules EJB 3.x, placez le fichier ibm-ejb-jar-bnd.xml dans le répertoire META-INF du fichier JAR (archive Java) de l'EJB. Le suffixe de ce fichier est XML. Notez également que lorsque vous définissez une liaison classique pour une interface locale ou une vue sans interface, vous devez faire précéder son nom de la chaîne "ejblocal:" afin qu'elle soit liée dans l'espace de noms classique ejblocal: dont la portée est la JVM.
- Les liaisons et les extensions déclarées avec le format de fichier XMI dépendent de la présence d'un descripteur de déploiement ejb-jar.xml correspondant, lequel fait explicitement référence aux numéros d'ID uniques rattachés aux éléments présents dans ce fichier. Ce système n'est plus viable pour les modules EJB 3.0 et ultérieurs qui n'ont plus besoin de contenir un descripteur de déploiement ejb-jar.xml.
- Le format de fichier XMI a été conçu pour une édition machine par les seuls outils de développement et les fonctions de gestion système du produit ; ce format faisait en fait partie de l'implémentation interne du produit et la structure de ce fichier n'a jamais été documentée en externe. Cette caractéristique rendait impossible la modification manuelle des fichiers de liaison ou leur création par les développeurs dans le cadre d'un processus de construction pris en charge mais indépendant de WebSphere.
- Au lieu de se référer aux numéros d'ID codés du descripteur de déploiement ejb-jar.xml, le fichier de liaison reposant sur XML fait référence à un composant EJB en utilisant son nom EJB. Chaque composant EJB d'un module possède un nom d'EJB unique attribué par défaut ou explicitement par le développeur. Ce comportement évite toute ambiguïté lors du ciblage des liaisons et des extensions.
- Les nouveaux fichiers de liaison reposent sur XML et un fichier de définition de schéma (XSD) XML les accompagne pour documenter en externe leur structure. Ces fichiers .xsd peuvent être exploités par de nombreux éditeurs de fichiers XML courants pour l'utilisation de fonctions de vérification de leur syntaxe et d'achèvement du code. Ainsi, les développeurs peuvent à présent créer et modifier les fichiers de liaison et d'extension indépendamment de l'infrastructure du serveur d'applications.
Elément ou attribut | Utilisation | Exemple | Commentaires |
---|---|---|---|
<session> | Déclare un groupe d'affectations de liaisons pour un bean session. | <session name="AccountServiceBean"/> | Requiert un attribut de nom et au moins l'un des attributs suivants : attribut simple-binding-name, attribut local-home-binding-name, attribut remote-home-binding-name ou élément <interface>. |
name | Attribut qui identifie l'élément ejb-name du bean enterprise auquel s'applique un élément <session>, <message-driven>, <entity>, ou un autre élément. | <session name="AccountServiceBean"/> | La valeur de name correspond au nom déclaré dans l'élément <ejb-name> d'un fichier descripteur de déploiement ejb-jar.xml ou à l'attribut 'name' d'une annotation @Stateful, @Stateless, @Singleton ou @MessageDriven. Si aucune valeur <ejb-name> n'est déclarée dans le descripteur de déploiement XML et si aucun attribut 'name' n'est déclaré sur l'une de ces annotations, la valeur de name est, par défaut, le nom non qualifié de la classe d'implémentation d'EJB qui est annotée avec @Session ou @MessageDriven. |
component-id | Attribut qui supplante la valeur d'ID de composant par défaut d'un bean enterprise. La forme longue des liaisons par défaut classiques pour ce bean enterprise utilise l'ID de composant spécifié au lieu de <nom_app>/<nom_jar_module>/<nom_bean>. |
L'exemple précédent désigne le bean dont l'élément ejb-name est AccountServiceBean et dont les interfaces locales par défaut classiques, dans leur forme longue, sont liées à ejblocal:Department549/AccountProcessor#<interface.qualifiée.package> Ses interfaces distantes par défaut classiques, dans leur forme longue, sont liées à ejb/Department549/AccountProcessor#<interface.qualifiée.package> |
Peut être utilisé seul ou combiné avec l'élément <interface>, l'attribut local-home-binding-name ou remote-home-binding-name. Les interfaces pour lesquelles des liaisons explicites n'ont pas été définies peuvent être affectées à des liaisons par
défaut classiques utilisant la valeur de l'ID composant défini par l'utilisateur. Celles auxquelles sont affectées des liaisons explicites seront liées en utilisant les valeurs stipulées. Comme l'attribut de nom de liaison simple (simple-binding-name) est conçu pour s'appliquer à toutes les interfaces définies d'un bean enterprise (aucune interface ne recevant une valeur par défaut), l'application d'un ID de composant en conjonction avec cet attribut ne présente généralement aucune intérêt. |
simple-binding-name | Mécanisme simple pour affecter aux interfaces EJB (Enterprise JavaBeans) des liaisons qui :
|
Cet exemple a pour résultat le bean dont l'élément ejb-name est AccountServiceBean avec
l'interface métier locale ou home, le cas échéant, liée dans ejblocal:ejb/AccountService dans l'espace de nom d'EJB
classique dont la portée est la machine virtuelle Java et l'interface métier distante ou home (le cas échéant) liée dans
ejb/AccountService dans le contexte racine du serveur d'applications de l'espace de nom JNDI classique dont la portée est
globale.
Important : Important :
la valeur exacte de l'attribut, y compris le nom de sous-contexte
"ejb" dans cet exemple spécifique, est utilisée même s'il s'agit d'une interface locale liée dans l'espace de nom ejblocal:. Lorsque des liaisons définies par l'utilisateur sont spécifiées, le nom exact stipulé par l'attribut est utilisé. |
Ne doit pas être utilisé avec les attributs local-home-binding-name
ou remote-home-binding-name, ou l'élément <interface>. De même, ne doit pas être utilisé sur des beans qui implémentent plus d'une interface métier ; dans ce cas, utilisez l'élément
<interface> à la place. Si cet attribut est utilisé sur un bean enterprise qui implémente plusieurs interfaces métier ou combinant une interface métier et une interface de composant locale/distante avec interface home, vous pouvez éviter toute ambiguïté dans les noms de liaison qui en découlent en ajoutant un dièse (#) à la valeur de l'attribut, suivi du nom de classe qualifié par son package de chaque interface et interface home sur le bean enterprise. Cette condition peut toutefois être évitée en utilisant l'élément <interface> pour définir une liaison pour chacune des interfaces métier au lieu d'utiliser un nom de liaison simple (simple-binding-name). Important : Important :
la définition d'un nom de liaison simple sur un bean qui implémente plusieurs interfaces
métier n'équivaut pas à remplacer l'ID de composant par défaut par un bean utilisant l'attribut <component-id>. Les liaisons par défaut d'interfaces distantes définies à l'aide d'un attribut component-id restent regroupées sous le contexte
EJB (comme toutes les autres liaisons par défaut d'interfaces distantes) alors que les liaisons d'interfaces distantes
dont l'ambiguïté a été dissipée par le conteneur EJB en réponse à une utilisation erronée d'un nom de liaison simple
(simple-binding-name) sur un bean comportant plusieurs interfaces ne sont pas rattachées à ce contexte. |
local-home-binding-name | Attribut permettant de spécifier l'emplacement de liaison de l'interface home locale d'un bean enterprise. |
|
Ne doit pas être utilisé de pair avec l'attribut simple-binding-name. Comme les interfaces home locales doivent toujours être liées dans l'espace de noms classique, avec portée JVM, cette valeur doit être précédée du préfixe ejblocal:. |
remote-home-binding-name | Attribut permettant de spécifier l'emplacement de liaison de l'interface home distante d'un bean enterprise. |
|
Ne doit pas être utilisé de pair avec l'attribut simple-binding-name. Cette valeur ne doit pas être précédée du préfixe d'espace de noms classique ejblocal: puisque les interfaces home distantes ne peuvent pas être liées dans ejblocal:. |
<interface> | Sous-élément de l'élément <session> qui affecte une liaison à une interface EJB métier spécifique ou à une vue sans interface. A la différence des attributs simple-binding-name, local-home-binding-name et remote-home-binding-name, un paramètre binding-name et un paramètre de classe sont tous deux requis pour celui-ci (en fait, cette distinction explique pourquoi un élément XML séparé est requis au lieu d'un attribut). Le paramètre de classe spécifie le nom de classe, qualifié par le package associé, de l'interface métier ou de la vue sans interface à lier. |
(déclaré en tant que sous-élément dans un élément <session>). |
Ne doit pas être utilisé de pair avec l'attribut simple-binding-name. Comme les interfaces locales ou les vues sans interface doivent toujours être liées dans l'espace de noms classique avec portée JVM, la valeur binding-name doit être précédée du préfixe ejblocal: lorsque cet élément est appliqué à une interface locale ou à une vue sans interface. |
binding-name | Attribut permettant de spécifier l'emplacement de liaison d'une interface métier liée avec l'élément <interface>. |
(déclaré en tant que sous-élément dans un élément <session>). |
Requis conjointement à l'élément <interface> (et utilisé seulement sur cet élément). Comme les interfaces locales doivent toujours être liées dans l'espace de noms classique avec portée JVM, la valeur binding-name doit être précédée du préfixe ejblocal: lorsque cet élément est appliqué à une interface locale. |
Fichier de liaison : exemple 1
<?xml version="1.0" encoding="UTF-8?">
<ejb-jar-bnd xmlns=http://websphere.ibm.com/xml/ns/javaee xmlns:xsi="
http://www.w3.org/2001/XMLSchema-instance "xsi:schemaLocation"=
http://websphere.ibm.com/xml/ns/javaee
http://websphere.ibm.com/xml/ns/javaee/ibm-ejb-jar-bnd_1_0.xsd "version 1.0">
<session name="S01" component-id="Department549/AccountProcessors"/>
<session name="S02" simple-binding-name="ejb/session/S02"/>
<session name="S03">
<interface class="com.ejbs.BankAccountService" binding-name="ejblocal:session/BAS"/>
</session>
</ejb-jar-bnd>
Résultats du fichier de liaison : - Un ID de composant défini par l'utilisateur est affecté au bean session avec ejb-name S01 et remplace celui par défaut (nom application/nom module/nom bean) pour toutes les interfaces et les vues sans interface de ce bean. Les interfaces locales et les vues sans interface de ce bean sont liées dans ejblocal:Department549/AccountProcessors#<nom.interface.qualifiée.package> alors que les interfaces distantes sont liées dans ejb/Department549/AccountProcessors#<nom.interface.qualifiée.package>
- Le bean de session dont l'élément ejb-name est S02 est supposé comporter une
seule interface métier EJB 3.x ou une vue sans interface EJB 3.1. Il pourrait, tout aussi bien, avoir une interface "composant" pré-EJB 3.0 avec interface home locale, home distante, ou les deux. L'interface métier, ou les interfaces home de l'interface du composant sont liées dans ejblocal:ejb/session/S02 si elles sont locales ou dans ejb/session/S02
si elles sont distantes.
Si le bean S02 comporte plusieurs interfaces métier ou une ou plusieurs interfaces métier et Home, un nom de liaison simple est ambigu. Dans ce cas, le conteneur dissipe l'ambiguïté relative aux affectations de liaison en ajoutant #<nom.interface.qualifiée.package> au nom de liaison simple, ejb/session/S02, pour chaque interface du bean.
- L'interface métier EJB 3.x ou la vue sans interface EJB 3.1 com.ejbs.BankAccountService sur le bean de session avec l'élément ejb-name S03 est liée dans ejblocal:session/BAS.
La section suivante développe cet exemple en introduisant des éléments pour la résolution des cibles de divers types de références et entrées d'injection déclarées soit dans le descripteur de déploiement XML, soit via des annotations.
Liaisons définies par l'utilisateur pour la résolution des références et des cibles d'injection
La section précédente décrit des exemples d'affectation de noms de liaison définis par l'utilisateur pour des interfaces métier, des interfaces home et des vues sans interface. Cette section porte sur la résolution des cibles de liaison pour les références, les directives d'injection et les destinations de bean de gestion des messages.
Elément ou attribut | Utilisation | Exemple | Commentaires |
---|---|---|---|
<jca-adapter> | Définit la spécification d'activation JCA 1.5 et un emplacement message-destination JNDI pour la distribution des messages à un bean géré par message. |
|
Requiert l'attribut activation-spec-binding-name. Si le bean correspondant généré par un message n'identifie pas sa destination de message à l'aide de l'élément <message-destination-link>, l'attribut destination-binding-name est également requis. Peut éventuellement inclure un attribut activation-spec-auth-alias. |
<ejb-ref> | Résout la cible d'une déclaration ejb-ref, déclarée via l'annotation @EJB ou via ejb-ref dans le descripteur de déploiement ejb-jar.xml, en fournissant le lien entre le nom déclaré dans l'espace de nom java:comp/env à portée composant et le nom du bean enterprise cible dans l'espace de noms classique ejblocal: à portée JVM ou dans l'espace de noms JNDI classique à portée globale. |
|
Requiert les attributs name et binding-name. |
<message-driven> | Déclare un groupe d'affectations de liaisons pour un bean géré par message. |
|
Requiert l'attribut name et le sous-élément <jca-adapter>. |
<message-destination> | Associe le nom d'une destination de message, lequel est un nom logique défini dans le descripteur de déploiement du module Java EE, avec un nom JNDI global spécifique, lequel est un nom réel dans l'espace de nom JNDI. Les éléments <message-destination-ref> dans le descripteur de déploiement du module Java EE ou les directives d'injection @Resource injectant des destinations de message peuvent ensuite utiliser l'élément <message-destination-line> pour se référer à cette destination de message d'après son nom logique au lieu de nécessiter des entrées de liaisons individuelles <message-destination-ref> dans le fichier de liaisons pour chaque élément message-destination-ref défini. |
|
Requiert les attributs name et binding-name. |
<message-destination-ref> | Résout la cible d'une déclaration message-destination-ref déclarée via l'annotation @Resource ou via l'élément message-destination-ref dans ejb-jar.xml, en fournissant le lien entre le nom déclaré dans l'espace de nom java:comp/env à portée composant et le nom de l'environnement de ressources cible dans l'espace de nom JNDI global. |
|
Requiert les attributs name et binding-name. |
<resource-ref> | Résout la cible d'une déclaration resource-ref déclarée via l'annotation @Resource annotation ou via l'élément resource-ref dans ejb-jar.xml, en fournissant le lien entre le nom déclaré dans l'espace de nom java:comp/env à portée composant et le nom de la ressource cible dans l'espace de nom JNDI global. |
|
Requiert les attributs name et binding-name. Peut inclure les attributs authentication-alias ou custom-login-configuration. |
<resource-env-ref> | Résout la cible d'une déclaration resource-env-ref déclarée via l'annotation @Resource ou via l'élément resource-env-ref dans ejb-jar.xml, en fournissant le lien entre le nom déclaré dans l'espace de nom java:comp/env à portée composant et le nom de l'environnement de ressources cible dans l'espace de nom JNDI global. |
|
Requiert les attributs name et binding-name. |
<env-entry> | Remplace une entrée d'environnement par la valeur spécifiée au format chaîne ou objet accessible via une recherche JNDI lancée sur le nom de consultation spécifié appliqué au contexte initial par défaut. |
|
Requiert l'attribut de nom, et la valeur ou l'attribut binding-name, mais pas les deux. |
<data-source> | Remplace une définition de source de données, qui est déclarée via l'annotation @DataSourceDefinition ou via l'élément data-source dans l'application, ou un descripteur de déploiement de module, par une ressource gérée. |
|
Requiert les attributs name et binding-name. |
name | Attribut qui identifie l'emplacement de nommage (par exemple, dans ejb-ref, resource-ref, resource-env-ref, message-destination, ou message-destination-ref), généralement dans l'espace de nom java:comp/env spécifique au composant, qui définit la partie "source" dans un couplage référence/cible. |
|
|
binding-name | Attribut qui identifie l'emplacement de nommage (par exemple, dans ejb-ref, resource-ref, resource-env-ref, message-destination, ou message-destination-ref) dans l'espace de noms classique ejblocal: ou dans l'espace de noms classique JNDI à portée globale qui définit la partie "cible" d'un couplage référence/cible. |
|
|
valeur | Attribut qui indique la valeur à utiliser pour une liaison env-entry. |
|
|
activation-spec-binding-name | Attribut qui identifie l'emplacement JNDI de la spécification d'activation associée à l'adaptateur JCA 1.5 à utiliser pour la distribution de messages à un bean géré par message. |
|
Il doit s'agir du nom d'une spécification d'activation JCA 1.5 définie dans WebSphere Application Server. |
activation-spec-auth-alias | Attribut facultatif identifiant le nom d'un alias d'authentification J2C utilisé pour l'authentification des connexions avec un adaptateur de ressource JCA. Cet alias indique l'ID utilisateur et le mot de passe utilisés pour authentifier la création d'une connexion à l'adaptateur de ressources JCA. |
|
Il doit s'agir du nom d'un alias d'autorisation J2C défini dans WebSphere Application Server. |
destination-binding-name | Attribut identifiant le nom JNDI utilisé par le bean géré par message pour la recherche de sa destination JMS dans l'espace de nom JNDI. |
|
Ce nom doit correspondre à celui d'une file d'attente ou d'une rubrique JMS définies dans WebSphere Application Server. |
authentication -alias | Sous-élément facultatif de l'élément de liaison <resource-ref>. Si la référence de ressource concerne une fabrique de connexions, une configuration de connexion JAAS facultative peut être spécifiée ; dans ce cas, un simple nom d'alias d'authentification. |
|
Ce nom doit correspondre à celui d'un alias d'authentification JAAS défini dans WebSphere Application Server. |
custom-login-configuration | Sous-élément facultatif de l'élément de liaison <resource-ref>. Si la référence de ressource concerne une fabrique de connexions, une configuration de connexion JAAS facultative peut être spécifiée ; dans ce cas, un jeu de propriétés (paires nom/valeur). |
|
Ce nom doit correspondre à celui d'une configuration de connexion JAAS définie dans WebSphere Application Server. |
Fichier de liaison : exemple 2
<?xml version="1.0" encoding="UTF-8"?>
<ejb-jar-bnd xmlns="http://websphere.ibm.com/xml/ns/javaee" "xmlns:xsi"=
"http://www.w3.org/2001/XMLSchema-instance"
xsi:schemaLocation="http://websphere.ibm.com/xml/ns/javaee"
"http://websphere.ibm.com/xml/ns/javaee/ibm-ejb-jar-bnd_1_0.xsd version" "1.0">
<session name="S01" component-id="Department549/AccountProcessors"/>
<session name="S02" simple-binding-name="ejb/session/S02"/>
<session name="S03">
<interface class="com.ejbs.BankAccountService"
binding-name="ejblocal:session/BAS"/>
<ejb-ref name="com.ejbs.BankAccountServiceBean/goodBye"
binding-name="ejb/session/S02"/>
<resource-ref name="com.ejbs.BankAccountServiceBean/dataSource"
binding-name="jdbc/Default"/>
</session>
<message-driven name="MO1">
<jca-adapter activation-spec-binding-name="jms/InternalProviderSpec"
destination-binding-name=jms/"ServiceQueue"/>
</message-driven>
<session name="S04" simple-binding-name="ejb/session/S04">
<resource-ref name="ejbs.S04Bean/dataSource"
binding-name="jdbc/Default">
<authentication-alias name="defaultlogin"/>
</resource-ref>
</session>
<session name="S05">
<interface class="com.ejbs.InventoryService"
binding-name="ejb/session/S05Inventory"/>
<resource-ref name="ejbs.S05Bean/dataSource"
binding-name="jdbc/Default">
<custom-login-configuration name="customLogin">
<property name="loginParm1" value="ABC123"/>
<property name="loginParm2" value="DEF456"/>
</custom-login-configuration>
</resource-ref>
</session>
</ejb-jar-bnd>
Résultats de cette liaison : - Les liaisons d'interface métier, d'interface home et de vue sans interface pour les beans session nommés S01, S02 et S03 sont inchangées par rapport à celles de l'exemple précédent.
- Le bean session dont l'élément ejb-name est S03 inclut désormais deux liaisons de résolution de référence cible :
- La liaison ejb-ref résout la référence EJB définie dans java:comp/env/com.ejbs.BankAccountServiceBean/goodBye
vers l'emplacement JNDI ejb/session/S02 sous le contexte JNDI racine du serveur d'applications. La référence EJB peut aussi être définie
par une injection @EJB dans la classe com.ejbs.BankAccountServiceBean, dans une variable d'instance nommée
"goodBye". Remarque : ejb/session/S02 désigne l'emplacement JNDI du bean session S02 également défini dans le même fichier de liaison, c'est à dire que la référence pointe vers le bean session nommé S02.
- La liaison resource-ref résout la référence de ressource définie à java:comp/env/com.ejbs.BankAccountServiceBean/dataSource en indiquant l'emplacement JNDI jdbc/Default. La référence de ressource aurait aussi pu être définie par une injection @Resource dans la classe com.ejbs.BankAccountServiceBean, dans une variable d'instance nommée "dataSource".
- La liaison ejb-ref résout la référence EJB définie dans java:comp/env/com.ejbs.BankAccountServiceBean/goodBye
vers l'emplacement JNDI ejb/session/S02 sous le contexte JNDI racine du serveur d'applications. La référence EJB peut aussi être définie
par une injection @EJB dans la classe com.ejbs.BankAccountServiceBean, dans une variable d'instance nommée
"goodBye".
- Des liaisons sont définies pour un bean géré par message ayant le nom d'EJB M01. Ce bean reçoit des messages à partir d'une destination JMS, dont le nom JNDI est jms/ServiceQueue, définie dans WebSphere Application Server, via un adaptateur JCA 1.5 dont l'activation JCA 1.5 a été définie dans WebSphere Application Server avec le nom jms/InternalProviderSpec.
- Le bean session dont l'élément ejb-name est S04 est supposé comporter une seule interface métier ou vue sans interface liée dans ejb/session/S04, si elle est distante ou dans ejblocal:ejb/session/S04, si elle est locale. Il dispose d'une resource-ref qui a pour nom java:comp/env/ejbs/S04Bean/dataSource. Il peut également s'agir de la classe ejbs.S04Bean, avec une injection @Resource dans une variable nommée, dataSource. Cette resource-ref s'est résolue en l'emplacement JNDI par défaut, jdbc/Default. L'élément resource-ref fait référence à une connexion J2C et établit une connexion à cette ressource via un alias d'authentification simple nommé defaultlogin qui a été défini dans WebSphere Application Server.
- Une liaison d'interface métier est définie pour l'interface dont le nom de classe est com.ejbs.InventoryService et qui est implémentée par le bean session dont l'élément ejb-name est S05 ; l'interface est supposée être distante car elle ne comporte pas le préfixe "ejblocal:" et peut donc être liée dans ejb/session/S05Inventory dans le contexte JNDI racine du serveur dans l'espace de nom classique dont la portée est globale. Des liaisons par défaut classiques sont affectées à tout autre interface métier implémentée par ce bean. Le bean comprend une ressource nommée java:comp/env/ejbs.S05Bean/dataSource (ou une injection a @Resource dans la classe ejbs.S05Bean, dans une variable nommée "dataSource") dont la résolution donne l'emplacement JNDI jdbc/Default. L'élément resource-ref fait référence à une connexion J2C et se connecte à cette ressource à l'aide d'une configuration de connexion personnalisée comportant deux paires nom/valeur.
Fichier de liaison : exemple 3
Cet exemple ci-dessous décrit comment définir et résoudre des liaisons de références EJB pour effectuer des recherches JNDI à travers plusieurs instances de serveur d'applications dans la même cellule WebSphere Application Server. Il utilise deux beans EJB : un bean appelé qui définit une liaison explicite à l'aide de l'attribut simple-binding-name, et un bean appelant qui effectue une injection @EJB et utilise l'élément ejb-ref dans son fichier de liaisons associé afin de résoudre la référence en pointant sur le bean appelé, lequel réside dans un autre processus de serveur d'applications.
ibm-ejb-jar-bnd.xml (called bean)
<?xml version="1.0" encoding="UTF-8"?>
<ejb-jar-bnd xmlns="http://websphere.ibm.com/xml/ns/javaee"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xsi:schemaLocation="http://websphere.ibm.com/xml/ns/javaee"
"http://websphere.ibm.com/xml/ns/javaee/ibm-ejb-jar-bnd_1_0.xsd" version="1.0">
<session name="FacadeBean" simple-binding-name="ejb/session/FacadeBean"/>
</ejb-jar-bnd>
Le contenu de ce fichier de liaison suppose que le bean session dont l'élément ejb-name est "FacadeBean" implémente une
interface métier unique et que, par conséquent, l'attribut simple-binding-name peut être utilisé, au lieu du sous-élément <interface>. Dans ce cas précis, FacadeBean implémente une interface métier unique, liée à ejb/session/FacadeBean dans le contexte JNDI racine du serveur d'applications sur lequel réside ce bean.Fragment de code (bean appelant)
@EJB(name="ejb/FacadeRemoteRef")
FacadeRemote remoteRef;
try {
output = remoteRef.orderStatus(input);
}
catch (Exception e) {
// Handle exception, etc.
}
Ce fragment de code effectue une injection de ressource EJB dans la variable d'instance nommée "remoteRef", qui est du type FacadeRemote. L'injection remplace le paramètre "name", en définissant le nom de référence ejb-ref résultant à ejb/FacadeRemoteRef. Le code appelle une méthode métier sur la référence injectée.ibm-ejb-jar-bnd.xml (bean appelant)
<?xml version="1.0" encoding="UTF-8"?>
<ejb-jar-bnd xmlns="http://websphere.ibm.com/xml/ns/javaee"
"xmlns:xsi="
"http://www.w3.org/2001/XMLSchema-instance"
xsi:schemaLocation="http://websphere.ibm.com/xml/ns/javaee"
"http://websphere.ibm.com/xml/ns/javaee/ibm-ejb-jar-bnd_1_0.xsd" version="1.0">
<session name="CallingBean">
<ejb-ref name="ejb/FacadeRemoteRef"
binding-name="cell/nodes/S35NLA1/servers/S35serverA1/ejb/session/FacadeBean"/>
</session>
</ejb-bnd-jar>
Enfin, ce fichier de liaison résout la référence EJB dont le nom
ejb-ref est ejb/FacadeRemoteRef pour qu'il désigne le nom JNDI classique avec portée globale
cellule/noeuds/S35NLA1/servers/S35serverA1/ejb/session/FacadeBean. Ce nom JNDI classique avec portée globale représente une interface liée dans ejb/session/FacadeBean sous le contexte racine du
serveur "S35serverA1" sur le noeud "S35NLA1" dans la cellule
WebSphere
Application Server du bean appelant. Pour pointer vers un emplacement dans une cellule WebSphere
Application Server différente,
un nom du type CORBAName peut être
utilisé au lieu du nom JNDI standard. La procédure à suivre pour modifier le fichier ibm-ejb-jar-bnd.xml est décrite dans la rubrique Méthodes de mise à jour des fichiers d'application.
Relation entre injections et références
Une correspondance de type 'un à un' existe entre les directives d'injection et les déclarations de références : chaque injection définit explicitement une référence d'un certain type, et, réciproquement, chaque référence peut aussi (optionnellement) définir une injection. Une annotation d'injection peut être perçue comme un mécanisme permettant de définir des références via des annotations au lieu de les spécifier dans le descripteur de déploiement XML.
Par défaut, une injection définit une référence à l'aide d'un nom formé par le nom de classe qualifié par son package du composant effectuant l'injection, suivi d'une barre oblique (/), puis du nom de la variable ou de la propriété destinataire de l'injection. Par exemple, une injection réalisée avec la classe com.ejbs.AccountService, dans une variable ou propriété intitulée "depositService" débouche sur une référence nommée java:comp/env/com.ejbs.AccountService/depositService. Cependant, l'utilisation du paramètre facultatif "name" sur la directive d'injection remplace ce nom de référence par défaut en lui substituant la valeur spécifiée dans le paramètre "name".
Connaissant cette règle, vous pouvez constater qu'un fichier de liaison peut être utilisé non seulement pour résoudre les cibles de références déclarées dans un descripteur de déploiement XML mais aussi pour celles déclarées implicitement par une directive d'injection via annotation. Il suffit pour cela d'utiliser la valeur du paramètre "name" sur l'annotation d'injection, ou le nom de référence par défaut du nom de classe et le nom de variable/propriété si le paramètre "name" n'a pas été spécifié, comme s'il s'agissait du nom de la référence déclarée dans un descripteur de déploiement XML.
Résolution par défaut de références EJB et d'injections EJB : les fonctions EJBLink et AutoLink
Les fonctions EJBLink et AutoLink constituent deux mécanismes différents qui résolvent des références en composants EJB conditionnés dans la même application et le même processus de serveur d'applications que le composant référent. Elles suppriment toutes les deux la nécessité de résoudre explicitement la référence EJB avec des informations de liaison. La fonction EJBLink est définie par la spécification EJB alors que la fonction AutoLink est une extension de WebSphere Application Server.
Les fonctions EJBLink et AutoLink utilisent des critères de recherche différents pour localiser le composant de bean ciblé. EJBLink recherche le composant de bean ciblé à l'aide du nom de bean spécifié explicitement. AutoLink recherche le composant de bean ciblé à l'aide de l'interface que le bean implémente. Si aucune liaison explicite n'est fournie mais qu'un nom de bean est indiqué, la fonction EJBLink est utilisée. Si aucune liaison explicite n'est fournie et qu'aucun nom de bean n'est indiqué, la fonction AutoLink est utilisée. Les fonctions EJBLink et AutoLink ne sont jamais utilisées ensemble dans un même processus de recherche.
A l'exception des critères de recherche, les fonctions EJBLink et AutoLink sont similaires. Les deux fonctions recherchent d'abord un module spécifique, puis, si nécessaire, recherchent les autres modules dans la même application et le même processus de serveur d'applications. Pour les deux fonctions, les critères de recherche doivent trouver un composant de bean exactement ; elles considèrent qu'une erreur est survenue si plusieurs composants de bean sont trouvés. Une erreur se produit car le serveur d'applications ne peut pas déterminer le composant bean à utiliser parmi les composants bean. Dans ce cas, l'exception com.ibm.websphere.ejbcontainer.AmbiguousEJBReferenceException est émise lors de l'exécution lorsque le composant référençant tente de trouver le composant de bean ciblé.
- Le premier format spécifie uniquement le nom du composant bean. Exemple : MonBean.
- Le deuxième format spécifie le nom du fichier de module physique, y compris l'extension, qui contient le composant de bean ciblé, suivi du caractère #, suivi du nom du composant bean. Exemple : monModule.jar#MonBean
- Le troisième format spécifie le nom logique du module qui contient le composant de bean ciblé, le caractère barre oblique (/), suivi du nom du composant bean. Exemple : MonModule/MonBean.
Le nom logique du module est spécifié en option avec l'élément module-name dans le descripteur de déploiement EJB d'un module ejb-jar ou avec l'élément module-name dans le descripteur de déploiement Web d'un module WAR incluant du contenu EJB. Dans le cas d'un module WAR incluant le contenu de l'EJB, l'élément module-name spécifié dans le descripteur de déploiement de l'EJB est ignoré et l'élément module-name spécifié dans le descripteur de déploiement Web est traité. Lorsqu'aucune valeur module-name n'est spécifiée dans le descripteur de déploiement, un nom logique par défaut est affecté au module. Le nom de module logique par défaut est le nom de base du fichier de module sans l'extension. Par exemple, le fichier de module MyModule.jar a le nom de module logique par défaut MyModule.
La spécification du nom du fichier de module physique est pris en charge même lorsque le module a un nom logique. La spécification du nom logique du module est pris en charge même lorsqu'aucun nom de module logique n'est configuré dans le descripteur de déploiement. Dans ce cas, le nom de base du module est utilisé comme nom logique du module.
Le conteneur incorporable d'EJB prend en charge tous les formats EJBLink. Pour prendre en charge le format de fichier de module physique, le conteneur incorporable d'EJB n'autorise pas le démarrage de plusieurs modules ayant le même nom de base.
AutoLink est une fonctionnalité à valeur ajoutée de WebSphere Application Server qui élimine le besoin de résoudre explicitement les cibles de références EJB dans certains scénarios d'utilisation. Dans WebSphere Application Server version 8, la fonction AutoLink est implémentée dans les limites de chaque processus WebSphere Application Server. L'algorithme d'AutoLink opère comme suit :
Lorsque le conteneur EJB du produit rencontre une référence EJB dans un module EJB donné, il vérifie d'abord si vous avez explicitement résolu sa cible par le biais de l'inclusion d'une entrée dans le fichier de liaison du module. Si aucune résolution explicite de sa cible n'existe dans le fichier de liaison, le conteneur recherche dans le module associé un bean enterprise qui implémente le type d'interface ou la vue sans interface définie dans la référence.
S'il trouve dans le module exactement un bean enterprise qui implémente l'interface ou la vue sans interface, il l'utilise comme cible de la référence EJB. Si le conteneur ne trouve pas un bean enterprise de ce type dans le module, il étend la portée de la recherche à l'application dont fait partie le module et effectue des recherches dans les autres modules, dans l'application, affectés au même serveur d'applications que le module de référencement. A nouveau, si le conteneur identifie exactement un bean enterprise qui implémente la vue sans interface ou l'interface cible parmi les autres modules de l'application affectés au même serveur que le module initial, il utilise ce bean comme cible de la référence.
La portée de la fonctionnalité AutoLink est restreinte à l'application dans laquelle apparaît la référence EJB et au serveur d'applications auquel est affecté le module référant. Les références aux beans enterprise dans une application différente, aux beans enterprise dans un module affecté à un serveur d'applications différent ou aux beans enterprise qui résident dans un module qui a été affecté à un cluster WebSphere Application Server doivent être résolues explicitement en utilisant des liaisons cible de référence dans le fichier ibm-ejb-jar-bnd.xml du module EJB ou le fichier ibm-web-bnd.xmi du module Web.
Notez que la fonction AutoLink n'est prise en charge que pour les références EJB, bien qu'elle puisse être utilisée à partir du conteneur EJB, le conteneur Web et le conteneur du client d'application. De plus, comme sa portée dans le Feature Pack est limitée au serveur auquel est affecté le module référent, ou dans le cas du conteneur client Java EE, au serveur d'amorçage JNDI pour lequel est configuré le conteneur client, son utilité principale réside actuellement dans les environnements de développement et divers scénarios d'utilisation d'un serveur unique. Même compte tenu de ses limitations actuelles, cette fonction peut avoir une valeur significative lors du cycle de développement en supprimant le besoin de résoudre explicitement les références EJB.
Résolution des références et des injections d'EJB et de ressource : la fonction lookup
La fonction lookup (recherche) est définie par la spécification EJB 3.1 comme mécanisme qui résout les références aux EJB ou aux ressources au moyen d'un nom JNDI explicite. Vous pouvez spécifier l'attribut lookup sur l'annotation javax.ejb.EJB ou sur l'annotation javax.annotation.Resource. Dans le fichier ejb-jar.xml, l'attribut XML correspondant, <lookup-name>, est appliqué à l'un des éléments suivants : <ejb-ref>, <ejb-local-ref>, <env-entry>, <resource-ref>, <resource-env-ref>, <message-destination-ref>. La valeur de lookup ou de <lookup-name> est un nom JNDI relatif au contexte de nommage java:comp/env.
Sur une référence d'EJB, lookup ou <lookup-name> ne doit pas être spécifié avec beanName ni avec <ejb-link>. La console d'administration affiche lookup-name et ejb-link comme valeurs en lecture seule. Si toutefois un nom JNDI est spécifié à l'étape d'installation de l'application intitulée "Mappage de références EJB avec des beans", il supplante la valeur de l'attribut lookup-name ou ejb-link.
Remplacement d'entrées d'environnement définies dans des applications
<env-entry name="name" value="value"/>
où nom est le nom de env-entry tel qu'il est défini
dans l'application et valeur la valeur affectée à env-entry
au format chaîne. La chaîne valeur est analysée en fonction du type
de l'entrée d'environnement comme si la valeur avait été spécifiée dans descripteur de déploiement
à l'aide de env-entry-value. Par exemple,<env-entry name="java:module/env/taxYear" value="2010"/>
associe l'élément env-entry nommé "java:module/env/taxYear"
à une valeur "2010". <env-entry name="name" binding-name="lookupName"/>
où nom est le nom de env-entry
tel qu'il est défini dans l'application et lookupName
est un nom JNDI qui est résolu lorsqu'il est appliqué à une recherche dans le contexte
initial par défaut. Exemple,
<env-entry name="java:module/env/taxYear" binding-name="cell/persistent/MyApp/MyModule/taxYear"/>
associe l'élément env-entry nommé "java:module/env/taxYear"
à une valeur renvoyée par une recherche lancée dans un contexte initial par défaut
sur "cell/persistent/MyApp/MyModule/taxYear". Vous êtes responsable de
la création de la liaison de l'objet JNDI. La classe de l'objet lié doit pouvoir
être affectée au type d'objet de l'élément env-entry associé. Les entrées d'environnement peuvent être définies au niveau de l'application et dans les modules EJB, Web et client. Ces niveaux correspondent aux fichiers de liaison application-bnd.xml, ejb-jar-bnd.xml, web-app-bnd.xml et application-client-bnd.xml.
Remplacement de définitions de source de données
Java EE 6 vous permet de développer des applications qui définissent des sources de données à l'aide de l'annotation @DataSourceDefinition ou de l'entrée du descripteur de déploiement <data-source>.
<data-source name="name" binding-name="lookupName"/>
où nom est le nom de env-entry
tel qu'il est défini dans l'application et lookupName
est un nom JNDI qui est résolu lorsqu'il est appliqué à une recherche dans le contexte
initial par défaut. Exemple,
<data-source name="java:module/env/myDS" binding-name="jdbc/DB2DS"/>
résout les recherches lancées sur "java:module/env/myD" en une source de données
liée au nom "jdbc/DB2DS" relatif au contexte initial par défaut. La source de données liée à jdbc/DB2DS
peut être créée, par exemple, à l'aide de la console d'administration.Les sources de données peuvent être définies au niveau de l'application et dans les modules EJB, Web et client. Ces niveaux correspondent aux fichiers de liaison application-bnd.xml, ejb-jar-bnd.xml, web-app-bnd.xml et application-client-bnd.xml.
Considérations relatives à l'attribution de noms dans les environnements en cluster et à plusieurs serveurs
cell/clusters/<cluster-name>/<name-binding-location>
Par exemple, dans le cas d'un emplacement de liaison d'une interface EJB sous le contexte racine du serveur d'applications :
ejb/Department549/AccountProcessors/CheckingAccountReconciler
cell/clusters/Cluster47/ejb/Department549/AccountProcessors/CheckingAccountReconciler
cell/nodes/<node-name>/servers/<server-name>/<name binding location>
Et donc, dans le cas d'un emplacement de liaison d'une interface EJB sous le contexte racine du serveur d'applications :
ejb/Department549/AccountProcessors/CheckingAccountReconciler
cell/nodes/S47NLA1/servers/Server47A1/ejb/Department549/AccountProcessors/CheckingAccountReconciler
Paramètres d'extension EJB définis par l'utilisateur
Au cas où vous voudriez indiquer des valeurs pour les paramètres d'extension EJB de WebSphere Application Server, vous pouvez utiliser un fichier d'extension de module EJB pour attribuer ces paramètres aux types EJB spécifiques de ce module. Vous indiquez des informations sur les paramètres d'extension pour les modules EJB 3.x en plaçant un fichier, ou les deux, dans le répertoire META-INF du fichier JAR de l'EJB, selon le type d'extension défini. Les noms des deux fichiers sont ibm-ejb-jar-ext.xml et ibm-ejb-jar-ext-pme.xml.
- Les liaisons et les extensions déclarées avec le format de fichier xmi dépendent de la présence d'un descripteur de déploiement ejb-jar.xml correspondant, lequel fait référence explicitement aux numéros d'ID uniques rattachés aux éléments de ce fichier. Ce système n'est plus viable pour les modules EJB 3.0 et ultérieurs qui n'ont plus besoin de contenir un descripteur de déploiement ejb-jar.xml.
- Le format de fichier xmi a été conçu pour une édition machine par les seuls outils de développement et les fonctions de gestion système de WebSphere ; ce format faisait en fait partie de l'implémentation interne de WebSphere et la structure de ce fichier n'a jamais été documentée en externe. Cette caractéristique rendait impossible la création ou la modification manuelle des fichiers de liaison ou d'extension, ainsi que leur création par les développeurs dans le cadre d'un processus de construction pris en charge mais indépendant de WebSphere.
- Au lieu de se référer aux numéros d'ID codés du fichier ejb-jar.xml, le format de fichier d'extension basé sur XML fait référence aux composants EJB par leur nom EJB. Chaque composant EJB d'un module est assuré de disposer d'un nom EJB unique, soit qu'il lui soit attribué par défaut, soit par affectation explicite par le développeur, permettant ainsi de cibler sans équivoque des liaisons et des extensions.
- Les nouveaux formats de fichiers de liaison et d'extension sont des fichiers basés XML et les fichiers xsd (XML Schema Definition) sont fournis pour documenter leur structure de l'extérieur. Ces fichiers .xsd peuvent être exploités par de nombreux éditeurs de fichiers XML courants pour l'utilisation de fonctions de vérification de leur syntaxe et d'achèvement du code. Par conséquent, les développeurs peuvent à présent créer et modifier les fichiers de liaison et d'extension indépendamment de l'infrastructure de WebSphere Application Server, à l'aide d'un éditeur XML générique ou du système de script de leur choix.
Extensions définies dans META-INF/ibm-ejb-jar-ext.xml
Élément ou attribut | Description | Exemple | Remarques d'utilisation |
---|---|---|---|
<session> | Déclare un groupe de paramètres d'extension pour un bean session. |
|
Requiert l'attribut name. Pour qu'il soit effectif, incluez également un sous-élément de définition de paramètre d'extension au moins. |
<message-driven> | Déclare un groupe de paramètres d'extension pour un bean géré par message. |
|
Requiert l'attribut name. Pour qu'il soit effectif, incluez également un sous-élément de définition de paramètre d'extension au moins. |
Élément ou attribut | Description | Exemple | Remarques d'utilisation |
---|---|---|---|
<time-out> | Sous-élément de l'élément <session> qui déclare, en option, la durée en secondes entre les invocations de méthodes après lesquelles un bean session avec état n'est plus disponible. |
|
Requiert l'attribut valeur, un entier positif. Remarque : Applicable
seulement aux beans session avec état ; ne doit pas être utilisé sur les beans sans état.
Valeur par défaut de l'attribut : 300 (5 minutes) |
<bean-cache> | Sous-élément de l'élément <session> utilisé pour déclarer les paramètres d'activation/passivation des beans avec état. |
|
Afin d'avoir un attribut, incluez également l'attribut activation-policy. |
activation-policy | Attribut de l'élément <bean-cache> qui déclare les
conditions selon lesquelles l'instance de bean peut être activée et passivée. Applicable aux beans session avec état. Les valeurs admises et leur signification
sont :
|
|
Valeur par défaut de l'attribut : ONCE pour les beans session avec état. |
Élément ou attribut | Description | Exemple | Remarques d'utilisation |
---|---|---|---|
<global-transaction> | Sous-élément des éléments <session> et <message-driven> qui peuvent être utilisés pour déclarer le délai des transactions (en secondes) démarrées par ce type d'EJB spécifique (en remplaçant le paramètre de serveur du délai de transaction global) et qui peuvent également déclarer si ce type d'EJB propage ou non le contexte de transaction global reçu par des transactions atomiques de services Web, dans l'environnement hétérogène de service Web. |
|
Requiert au moins un des attributs transaction-time-out ou send-wsat-context . Valeur par défaut de l'attribut : Paramètre de délai de transaction de serveur pour transaction-time-out ; FALSE pour send-wsat-context |
<local-transaction> | Sous-élément des éléments <session> et <message-driven>
qui peuvent être utilisés pour déclarer des paramètres liés aux transactions locales. Les attributs admis sont limite, résolveur et action non résolue ;
Ces attributs configurent, pour le composant, le comportement de l'environnement de
confinement de transaction locale (LTC) du conteneur que celui-ci établit en l'absence
de transaction globale. Les significations des attributs sont les suivantes : Limite Ce paramètre définit la limite de confinement à laquelle toutes les transactions locales du gestionnaire de ressources (RMLT) contenues doivent être terminées. Ses valeurs admises sont :
Programme de résolution Ce paramètre définit le composant responsable du démarrage et de l'arrêt des RMLT. Ses valeurs admises sont :
Action non résolue Ce paramètre indique la direction que
le conteneur demande aux RMLT de prendre si ces transactions ne sont pas résolues
à la fin de la limite LTC et que le programme de résolution est défini à Application. Ses valeurs admises sont :
|
|
Requiert au moins un des attributs limite, résolveur
ou action non résolue.
Valeur par défaut de l'attribut :
|
Élément ou attribut | Description | Exemple | Remarques d'utilisation |
---|---|---|---|
<method> | Sous-élément des éléments <method-session-attribute> et
<run-as-mode> utilisé pour indiquer le nom de la méthode, la signature de
méthode ou les types de méthode auxquels est appliqué un paramètre donné. Les attributs
admis sont type, name et params. Chaque attribut
est décrit comme suit : type
name Nom de la méthode à laquelle le paramètre s'applique ou astérisque (*) si le paramètre doit s'appliquer à toutes les méthodes indépendamment du nom. params Signature de paramètre de la méthode à laquelle s'applique le paramètre. Elle peut être utilisée pour qualifier de façon unique une méthode particulière au cas où plusieurs méthodes utilisent le même nom. La signature de paramètre est une liste de types Java, séparés par des virgules. Les types primitifs sont spécifiés uniquement par leur nom ; les types non primitifs sont spécifiés par leur nom de classe ou d'interface qualifié complet, comprenant les packages Java et les tableaux de types Java sont indiqués par le type d'élément de tableau suivi par une ou plusieurs paires de crochets (par exemple int[][]). |
|
|
<run-as-mode> | Sous-élément des éléments <session> et <message-driven> qui peut être utilisé pour déclarer l'identité de sécurité qu'une méthode d'EJB donnée utilisera lorsqu'elle appelle une autre méthode. L'identité peut être définie pour utiliser l'identité de l'appelant (mode = CALLER_IDENTITY), l'identité du serveur EJB (mode = SYSTEM_IDENTITY) ou l'identité d'un rôle de sécurité spécifique (mode = SPECIFIED_IDENTITY). |
|
Requiert l'attribut mode et le sous-élément <method>. Si le mode est SPECIFIED_IDENTITY, le sous-élément <specified-identity est également requis. |
<start-at-app-start> | Sous-élément des éléments <session> et <message-driven> pouvant être utilisé pour informer le conteneur EJB que le type EJB spécifié peut être initialisé au moment où l'application est démarrée, plutôt que lorsque le type EJB est utilisé par l'application pour la première fois. |
|
Requiert l'attribut value. Valeur par défaut de l'attribut : FALSE (initialisez le type EJB lorsqu'il est utilisé par l'application pour la première fois) pour les beans autres que les beans gérés par message. Toujours TRUE pour les beans gérés par message. |
<resource-ref> | Sous-élément des éléments <session> et <message-driven>
pouvant être utilisé pour déclarer des paramètres supplémentaires sur une référence de
ressource Java EE, comme le niveau d'isolement à utiliser sur les transactions transmises
par la connexion mentionnée par la référence. Les attributs autorisés comprennent isolation-level. Les attributs sont définis comme suit : isolation-level
|
|
Requiert l'attribut name. Afin d'avoir un attribut, incluez également l'attribut isolation-level. |
Extensions définies dans le fichier META-INF/ibm-ejb-jar-ext-pme.xml
Élément ou attribut | Description | Exemple | Remarques d'utilisation |
---|---|---|---|
<internationalization> | Elément pouvant être utilisé pour déclarer l'environnement local pouvant être utilisé par le type EJB (environnement local de l'appelant ou du serveur). |
|
Pour plus d'informations sur cette extension,
reportez-vous à la rubrique Attributs d'internationalisation des conteneurs
: WebSphere
Application Server. Compte tenu de la complexité de cette fonction, vous pouvez utiliser un outil dédié à WebSphere Application Server, tel que Rational Application Developer, pour produire les stanzas de fichier d'extension requises, puis modifier le fichier XML de manière appopriée. |
<activity-sessions> | Elément qui déclare éventuellement le type de gestion d'une session d'activité à utiliser sur un bean session désigné (BEAN ou CONTENEUR) et pour les sessions d'activité gérées par conteneur, le type de comportement de session d'activité à fournir par le conteneur. |
|
Pour plus d'informations sur cette extension, reportez-vous à la rubrique Définition des attributs de déploiement d'une session
ActivitySession dans un module EJB. Compte tenu de la complexité de cette fonction, vous pouvez utiliser un outil dédié à WebSphere Application Server, tel que Rational Application Developer. |
<app-profiles> | Elément qui déclare facultativement les paramètres du profil d'application pour un ou plusieurs fichiers d'EJB |
|
Compte tenu de la complexité de cette fonction, vous pouvez utiliser un outil dédié à WebSphere Application Server, tel que Rational Application Developer, pour produire les stanzas de fichier d'extension requises, puis modifier le fichier XML de manière appopriée. |
Liaisons héritées (XMI)
Les modules et applications existants peuvent continuer à exploiter dans le produit des liaisons héritées et vous pouvez donc utiliser les outils et assistants existants afin de spécifier les informations de liaison et d'extension de ces modules et applications. La prise en charge de liaisons héritées se limite aux fichiers EAR et aux modules utilisant des descripteurs de déploiement XML de type J2EE 1.4.
Les modules EJB qui utilisent un schéma de descripteur de déploiement XML de la version 3.x ou qui ne comportent pas de fichier de descripteur de déploiement XML doivent utiliser soit des liaisons adoptant des valeurs par défaut avec AutoLink, soit des fichiers de liaisons XML spécifiés par l'utilisateur.
Les beans entity CMP doivent toujours être assemblés dans des modules avec schéma de descripteur de déploiement XML version 2.1 XML afin de pouvoir utiliser les outils existants avec prise en charge des mappages, liaisons et extensions.
Liaisons XML spécifiées par l'utilisateur
Les liaisons par défaut de chaque interface et la résolution par AutoLink de chaque référence peuvent être supplantées en spécifiant des liaisons pour le module EJB à travers la création d'un fichier META-INF/ibm-ejb-jar-bnd.xml.
- Beans session utilisant l'élément <session>.
- Beans gérés par message utilisant l'élément <message-driven>.
- Attribut id
- Attribut name
- Attribut simple-binding-name
- Attribut component-id
- Elément ejb-ref
- Elément resource-ref et ses attributs
- Elément resource-env-ref et ses attributs
- Elément message-destination-ref et ses attributs
- Elément env-entry
- Elément data-source
- Attribut id
- Attribut name
- Attribut jca-adapter
- Elément ejb-ref et ses attributs
- Elément resource-ref et ses attributs
- Elément resource-env-ref et ses attributs
- Elément message-destination-ref et ses attributs
- Elément env-entry
- Elément data-source