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

Pour le niveau EJB 3.x, le produit fournit deux espaces de noms classiques distincts pour les interfaces EJB, selon qu'il s'agit d'une interface locale ou distante. Il en va de même pour les interfaces home EJB et les vues sans interface, qui peuvent être considérées comme des types spéciaux d'interface. Les espaces de noms suivants existent dans le jeu classique :
  • 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.

Les applications Java EE sont assemblées sous un format normalisé dénommé EAR (Enterprise Application Archive). Le fichier EAR est un format de fichier compressé similaire aux formats de fichier .zip et .tar qui peut donc être visualisé comme une collection de fichiers et de répertoires logiques intégrés dans un seul fichier physique. Chaque fichier EAR comporte un ou plusieurs fichiers de module Java EE, pouvant comprendre :
  • 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.
Chaque fichier de module contient généralement un ou plusieurs composants Java EE. En exemple de composants Java EE, on peut citer les beans enterprise, les servlets et les classes principales du client d'application.

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

Le nom d'une application est défini (par ordre de priorité) par les éléments suivants :
  • 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 spécification Java EE 6 fournit des noms de recherche JNDI EJB sous la forme générale, java:global[/appName]/moduleName/beanName. Le composant appName du nom de recherche s'affiche en tant que composant facultatif car il ne s'applique pas aux beans déployés dans des modules autonomes. Seuls les beans stockés dans des fichiers .ear contiennent le composant appName dans le nom de consultation java:global. Les règles qui déterminent la valeur de appName diffèrent des règles décrites précédemment pour les noms d'application. La valeur de appName dans le modèle de nom de consultation java:global montré ci-dessus est définie par les éléments suivants, par ordre de priorité :
  • 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.
La valeur de appName est également une valeur de chaîne liée au nom java:app/AppName selon la spécification Java EE 6.

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.

Dans l'exemple suivant, l'application "CustomerServiceApp" contient trois modules dont les noms sont AccountProcessing.jar, Utility/FinanceUtils.jar et AppPresentation.war :
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 spécification Java EE 6 fournit des noms de recherche JNDI EJB sous la forme générale, java:global[/appName]/moduleName/beanName. Le composant appName du nom de recherche s'affiche en tant que composant facultatif car il ne s'applique pas aux beans déployés dans des modules autonomes. Seuls les beans stockés dans des fichiers .ear contiennent le composant appName dans le nom de consultation java:global. Une autre variante du nom de consultation JNDI comportant le nom du module est java:app/moduleName/beanName. La valeur de moduleName n'est pas le module URI. La valeur de moduleName dans les modèles de nom de consultation java:global et java:app est définie par les éléments suivants, par ordre de priorité :
  • 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".
La valeur de moduleName est également une valeur de chaîne liée au nom java:module/moduleName, selon la spécification Java EE 6. Cela s'applique également aux modules client. Concernant les modules client, le paramètre <module-name> se trouve dans le fichier des descripteurs de déploiement application-client.xml.

Nom de composant EJB utilisé dans les liaisons classiques

Le nom d'un composant EJB est défini par la valeur suivante, par ordre de priorité :
  • 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 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 des interfaces distantes ne sont pas liées dans le contexte ejb. Elles sont situées à l'origine du contexte racine du serveur. Bien que la pratique recommandée vise au regroupement de toutes les liaisons associées aux EJB sous un contexte ejb, d'autres considérations entrent en jeu, notamment les situations suivantes :
  • 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.

Tableau 1. Modèles de liaison par défaut. Modèles de liaison par défaut
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

Si vous affectez explicitement une définition de liaison à une interface, une interface home ou une vue sans interface, aucune liaison par défaut classique (courte ou longue) n'est établie pour cette interface ou cette vue.
Configurations prises en charge Configurations prises en charge: Cette règle s'applique uniquement aux interfaces ou aux vues sans interface spécifiques auxquelles vous affectez une liaison explicite. Les autres interfaces de ce bean enterprise sans liaisons explicites reçoivent des noms de liaison par défaut classique. sptcfg

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

Par exemple, le composant bean MyBeanComponent n'expose qu'une seule interface, com.foo.MyBeanComponentLocalInterface, et est empaqueté dans le module myModule.jar, lui-même empaqueté dans l'archive d'application myApp.ear. En conséquence, les liaisons suivantes sont créées dans les espaces de noms java:[portée] :
  • 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
Vous pouvez obtenir le bean MyBeanComponent auprès des espaces de noms java:[portée] en appliquant l'une des techniques suivantes :
  • 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.

Une référence peut être déclarée dans l'espace de nom java:global au moyen d'annotations ; par exemple :
@EJB(name="java:global/env/myBean")
Une référence peut être déclarée dans le fichier ejb-jar.xml ; par exemple :
<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.

Le fichier ibm-ejb-jar-bnd.xml est utilisé pour les modules EJB 3.0 et suivants qui exécutent le produit, alors que le fichier ibm-ejb-jar.bnd.xmi est utilisé pour les modules pré-EJB 3.0 et les modules Web. Le format de fichier dans le fichier ibm-ejb-jar.bnd.xml est différent du format de fichier XMI pour les raisons suivantes :
  • 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.
Le tableau suivant répertorie les éléments ibm-ejb-jar-bnd.xml et les attributs utilisés pour affecter des liaisons aux interfaces EJB et aux interfaces home pour les modules EJB 3.x ainsi qu'aux vues sans interface pour les modules EJB 3.1.
Tableau 2. Attributs et éléments du fichier ibm-ejb-jar-bnd.xml. Attributs et éléments du fichier ibm-ejb-jar-bnd.xml
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>.
<session name="AccountServiceBean" 
component-id="Dept549/AccountProcessor"/>

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 :
  • Implémentent une interface métier EJB 3.x unique.
  • Implémentent une interface de type pré-EJB 3.0 (locale, distante, ou des deux types) accompagnée d'une interface EJB home.
La valeur de l'attribut est utilisée en tant qu'emplacement de liaison de l'interface métier du bean enterprise ou de l'interface Enterprise JavaBeans home locale ou distante, ou les deux. La liaison est placée dans l'espace de noms classique ejblocal: si l'interface ou l'interface home est locale ; elle est placée dans le contexte racine du serveur d'applications de l'espace de noms JNDI global classique si l'interface ou l'interface home est distante.
<session name="AccountServiceBean"
simple-binding-name="ejb/AccountService"/>
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.
De plus, l'inclusion du nom de classe qualifié par son package intervient toujours pour les liaisons par défaut classiques sous leur forme longue tandis qu'avec un nom de liaison simple (simple-binding-name), elle ne survient qu'en situation d'erreur, où l'ambiguïté doit être résolue. Ne vous reposez pas sur le nom de liaison créé pour éviter les ambiguïtés dans la mesure ou cette médiation peut intervenir ou non selon que le bean est modifié afin d'implémenter plus ou moins d'interfaces.
local-home-binding-name Attribut permettant de spécifier l'emplacement de liaison de l'interface home locale d'un bean enterprise.
<session name="AccountServiceBean"
 local-home-binding-name="ejblocal:AccountService"/>
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.
<session name="AccountServiceBean"
 remote-home-binding-name=
 "ejb/services/AccountService"/>
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.
<interface class="com.ejbs.InventoryService" 
binding-name="ejb/Inventory"/> 
(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>.
<interface class="com.ejbs.InventoryService" 
binding-name="ejb/Inventory"/>
(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

L'exemple ci-après est un fichier ibm-ejb-jar-bnd.xml de base qui contient uniquement les éléments et les attributs qui affectent des noms de liaison aux interfaces EJB et aux vues sans interface. Il remplace l'ID de composant utilisé par les liaisons par défaut sur le bean enterprise nommé S01 et affecte des liaisons explicites à certaines interfaces des beans enterprise S02 et S03 dans ce module.
<?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.
Toutes les autres interfaces métier, les interfaces home et les vues sans interface de ce bean, si elles existent, se voient affecter des liaisons par défaut classiques. L'interface com.ejbs.BankAccountService est présumée être locale puisqu'elle a été rattachée à l'espace de nom ejblocal: dans cet exemple ; une erreur survient si l'interface n'est pas locale.

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.

Tableau 3. Eléments et attributs utilisés pour résoudre les cibles de liaison pour les références et les cibles d'injection. Eléments et attributs utilisés pour résoudre les cibles de liaison pour les références et les cibles d'injection
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.
<jca-adapter 
activation-spec-binding-name="jms/InternalProviderSpec"
destination-binding-name="jms/ServiceQueue"/>
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.
<ejb-ref name="com.ejbs.BankAccountServiceBean/s02Ref" 
binding-name="ejb/session/S02"/>
Requiert les attributs name et binding-name.
<message-driven> Déclare un groupe d'affectations de liaisons pour un bean géré par message.
<message-driven name="EventRecorderBean">
<jca-adapter 
activation-spec-binding-name="jms/InternalProviderSpec" 
destination-binding-name="jms/ServiceQueue"/>
</message-driven>
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.
<message-destination name="EventProcessingDestination"
binding-name="jms/ServiceQueue"/>
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.
<message-destination-ref
name="com.ejbs.BankAccountServiceBean/serviceQueue"
binding-name="jms/ServiceQueue"/>
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.
<resource-ref 
name="com.ejbs.BankAccountServiceBean/dataSource" 
binding-name="jdbc/Default"/>
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.
<resource-env-ref 
name="com.ejbs.BankAccountServiceBean/dataFactory"
binding-name="jdbc/Default"/>
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.
<env-entry name="java:module/env/taxYear" value="2010"/>
<env-entry name="java:module/env/taxYear" 
binding-name="cell/persistent/MyApp/MyModule/taxYear"/
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.
<data-source name="java:module/env/myDS" 
binding-name="jdbc/DB2DS"/>
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.
<ejb-ref name="com.ejbs.BankAccountServiceBean/goodBye"
binding-name="ejb/session/S02"/>
 
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.
<ejb-ref name="com.ejbs.BankAccountServiceBean/goodBye"
binding-name="ejb/session/S02"/>
 
valeur Attribut qui indique la valeur à utiliser pour une liaison env-entry.
<env-entry name="java:module/env/taxYear" value="2010"/>
 
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.
<jca-adapter 
activation-spec-binding-name="jms/InternalProviderSpec"
destination-binding-name="jms/ServiceQueue"/>
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.
<jca-adapter 
activation-spec-binding-name="jms/InternalProviderSpec"
activation-spec-auth-alias="jms/Service47Alias"
destination-binding-name="jms/ServiceQueue"/>
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.
<jca-adapter 
activation-spec-binding-name="jms/InternalProviderSpec"
destination-binding-name="jms/ServiceQueue"/>
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.
<resource-ref
name="com.ejbs.BankAccountServiceBean/dataSource"
binding-name="jdbc/Default">
<authentication-alias name="defaultAuth"/>
<resource-ref>
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).
<resource-ref 
name="com.ejbs.BankAccountServiceBean/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>
Ce nom doit correspondre à celui d'une configuration de connexion JAAS définie dans WebSphere Application Server.

Fichier de liaison : exemple 2

L'exemple suivant est une extension du fichier de base ibm-ejb-jar-bnd.xml présenté dans l'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"/>
  <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 :
  1. 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.
  2. 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".
  3. 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.
  4. 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.
  5. 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é.

La fonction EJBLink prend en charge trois formats différents.
  • 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

Les applications peuvent définir des entrées d'environnement avec des valeurs adaptées pour un test d'unité, mais pas pour un test d'intégration ni pour un contexte de production. Si vous souhaitez remplacer une valeur d'entrée d'environnement, vous pouvez ajouter l'élément suivant au fichier de liaison correspondant :
<env-entry name="name" value="value"/>
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".
Autrement, vous pouvez configurer env-entry en tant que référence à un autre objet accessible via JNDI. L'objet renvoyé par la recherche JNDI est utilisé comme valeur pour env-entry. L'élément de cette option a la forme suivante :
<env-entry name="name" binding-name="lookupName"/>
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>.

Vos applications doivent rechercher des références de ressource et non des définitions de source de données directement. Si vous installez une application existante contenant des recherches directes lancées sur une définition de source de données et que vous souhaitez qu'une autre définition de source de données soit utilisée, vous pouvez remplacer la définition de source de données par une liaison résolue en une ressource gérée créée par vous. Créez la liaison en ajoutant l'élément suivant au fichier de liaison :
<data-source name="name" binding-name="lookupName"/> 
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

Les conventions de dénomination JNDI globale classique décrites dans les sections précédentes s'appliquent aux environnements non organisés en cluster ou lorsque la cible de la recherche est située dans le même cluster que la source de la recherche. Lorsqu'une recherche est effectuée depuis l'extérieur du cluster sur une liaison située dans un cluster donné, la chaîne de recherche doit être qualifiée en spécifiant le nom du cluster qui héberge la cible, en respectant la convention suivante :
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  
Si l'EJB qui implémente cette interface est affecté à un serveur d'applications membre d'un cluster nommé Cluster47, la chaîne de recherche depuis l'extérieur du cluster sera la suivante :
cell/clusters/Cluster47/ejb/Department549/AccountProcessors/CheckingAccountReconciler
Lorsqu'une recherche est effectuée depuis un processus du serveur d'applications vers un autre processus, la chaîne de recherche doit être qualifiée en indiquant le nom du noeud et du serveur qui héberge la cible, en respectant la convention suivante :
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 
Si le bean enterprise qui implémente cette interface est affecté à un serveur d'applications nommé Server47A1 et situé sous le noeud S47NLA1, la chaîne de recherche inter-processus du serveur sera la suivante :
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.

Remarque : À la différence des versions antérieures de WebSphere Application Server, ces fichiers portent l'extension XML et non plus XMI.
Les fichiers ibm-ejb-jar-ext.xml et ibm-ejb-jar-ext-pme.xml sont utilisés pour les modules EJB 3.x exécutés dans WebSphere Application Server, alors que les fichiers ibm-ejb-jar-ext.xmi et ibm-ejb-jar-ext-pme.xmi sont utilisés pour les modules antérieurs à EJB 3.0. WebSphere Application Server Version 8.0 utilise un nouveau format de ficher d'extension XML à la place du format de fichier .xmi précédent pour les raisons suivantes :
  1. 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.
  2. 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.
  3. 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.
  4. 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

Les tableaux suivants répertorient les éléments et les attributs d'extension qui doivent être placés dans le fichier META-INF/ibm-ejb-jar-ext.xml . La section suivante énumère les éléments et les attributs qui figurent dans un fichier distinct, META-INF/ibm-ejb-jar-ext-pme.xml.
Tableau 4. Eléments et attributs du fichier META-INF/ibm-ejb-jar-ext.xml. Eléments et attributs du fichier 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.
<session name="AccountServiceBean"/>
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.
<message-driven name="EventProcessorBean"/>
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.
Tableau 5. Eléments et attributs du fichier META-INF/ibm-ejb-jar-ext.xml. Eléments et attributs du fichier META-INF/ibm-ejb-jar-ext.xml
É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.
<session
 name="ShoppingCartBean">
 <time-out value="600"/>
</session>
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.
<session
 name="ShoppingCartBean">
 <bean-cache
  activation-policy="TRANSACTION"/>
</session>
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 :
  • TRANSACTION : Indique que le bean est activé au début d'une transaction et est passivée (et supprimée du cache d'instance EJB actif) à la fin de la transaction.
  • ONCE : Indique que le bean est activé lorsqu'on y accède dans le processus serveur et il est passivé (et supprimé du cache d'instance EJB actif) selon le conteneur, par exemple lorsque le cache est plein.
  • ACTIVITY_SESSION : Indique le bean est activé et passivé comme suit :
    1. Sur une limite de ActivitySession, en présence d'un contexte ActivitySession lors de l'activation
    2. Sur une limite de transaction en présence d'un contexte de transaction (et non d'un contexte ActivitySession) lors de l'activation, ou
    3. sur une limite d'appel.
<session
 name="ShoppingCartBean">
 <bean-cache
  activation-policy="ONCE"/>
</session>
Valeur par défaut de l'attribut : ONCE pour les beans session avec état.
Tableau 6. Eléments et attributs du fichier META-INF/ibm-ejb-jar-ext.xml. Eléments et attributs du fichier META-INF/ibm-ejb-jar-ext.xml
É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.
<session
 name="AccountServiceBean"
 <global-transaction
  <global-transaction
 transaction-time-out="180" 
  send-wsat-context="FALSE"/>
</session>
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 :
  • BEAN_METHOD : Ceci est la valeur par défaut. Si vous sélectionnez cette option, les RMLT doivent être résolues dans la même méthode de bean dans laquelle elles ont été lancées.
  • ACTIVITY_SESSION : les RMLT doivent être résolues dans la portée du contexte ActivitySession dans lequel elles ont été lancées ou, en l'absence de contexte ActivitySession, dans la même méthode de bean dans laquelle elles ont été lancées.

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 :
  • APPLICATION : Ceci est la valeur par défaut. L'application est responsable du démarrage et de l'arrêt des RMLT et de leur réalisation dans la limite de confinement de transaction locale (LTC). Les RMLT qui ne sont pas terminées à la fin de la limite LTC sont nettoyées par le conteneur en fonction de l'attribut Action non résolue.
  • CONTAINER_AT_BOUNDARY: Le conteneur est responsable du démarrage des RMLT et de leur réalisation dans la limite de confinement de transaction locale (LTC). Le conteneur démarre une RMLT lorsqu'une connexion est d'abord utilisée dans la portée LTC et la termine automatiquement à la fin de la portée LTC. Si Limite prend la valeur ActivitySession, les RMLT sont répertoriées comme ressources ActivitySession et leur réalisation est régie par ActivitySession. Si Limite prend la valeur BeanMethod, les RMLT sont validées à la fin de la méthode par le conteneur.

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 :
  • ROLLBACK : Ceci est la valeur par défaut. A la fin de la limite LTC, le conteneur indique d'annuler toutes les RMLT non résolues.
  • COMMIT : A la fin de la limite LTC, le conteneur indique de valider toutes les RMLT non résolues. Le conteneur demande aux RMLT de procéder à la validation uniquement en l'absence d'une exception non gérée. Si la méthode d'application s'exécutant dans le contexte de transaction locale se termine avec une exception, toutes les RMLT non résolues sont annulées par le conteneur. Ce comportement est le même pour les transactions globales.
<session
 name>="AccountServiceBean">
 <local-transaction
  boundary="BEAN_METHOD" 
  resolver="APPLICATION" 
  unresolved-action="ROLLBACK"/>
</session>
Requiert au moins un des attributs limite, résolveur ou action non résolue.
Valeur par défaut de l'attribut :
boundary="BEAN_METHOD";
resolver="APPLICATION";
unresolved-action=
"ROLLBACK"
Tableau 7. Eléments et attributs du fichier META-INF/ibm-ejb-jar-ext.xml. Eléments et attributs du fichier META-INF/ibm-ejb-jar-ext.xml
É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

  • UNSPECIFIED : Le paramètre s'applique à toutes les méthodes correspondant aux attributs name et params, indépendamment du type d'interface.
  • REMOTE : Le paramètre s'applique aux méthodes d'interface métier distantes et d'interface composant distantes correspondant aux attributs name et params.
  • LOCAL : Le paramètre s'applique à l'interface métier locale, aux méthodes d'interface métier locales et aux vues sans interface correspondant à l'attribut name ou params, ou au deux.
  • HOME : Le paramètre s'applique aux méthodes d'interface home distantes correspondant aux attributs name et params.
  • LOCAL_HOME : Le paramètre s'applique aux méthodes d'interface home locales correspondant aux attributs name et params.
  • SERVICE_ENDPOINT : Le paramètre s'applique aux méthodes sur le SEI (service endpoint interface) JAX-RPC correspondant aux attributs name et params.

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[][]).

<session
 /name="AccountServiceBean">
 <method-session-attribute
  type="REQUIRES_NEW">
 <method
  type="LOCAL"
  name="debitAccount" 
  params="java.lang.String[], int,
     com.xyz.CustomerInfo"/>
 </method-session-attribute;>
</session>
 
<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).
<session
 name="AccountServiceBean">
 <run-as-mode
   mode="SPECIFIED_IDENTITY">
 <specified-identity
   role="admin"/>
 <method type="UNSPECIFIED" 
   name="testRunAsRole"/>
 </run-as-mode>
</session>
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.
<session
 name="AccountServiceBean">
 <start-at-app-startvalue="TRUE"/>
</session>
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
  • TRANSACTION_REPEATABLE_READ : Ce niveau d'isolement interdit la lecture de pages modifiées et la lecture non reproductible, mais il autorise la lecture fantôme.
  • TRANSACTION_READ_COMMITTED : Ce niveau d'isolement interdit la lecture de pages modifiées, mais il autorise la lecture non reproductible et la lecture fantôme.
  • TRANSACTION_READ_UNCOMMITTED : Ce niveau d'isolement autorise la lecture de modifications non validées (données modifiées par une transaction différente, toujours en cours d'exécution). Il autorise également la lecture de pages modifiées, la lecture non reproductible et la lecture fantôme.
  • TRANSACTION_SERIALIZABLE: Ce niveau d'isolement interdit les types de lecture suivants:
    1. La lecture de pages modifiées, dans laquelle une transaction lit une ligne de base de données contenant des modifications non validées d'une seconde transaction,
    2. La lecture non reproductible, dans laquelle une transaction lit une ligne, puis une seconde transaction modifie cette même ligne et la première transaction relit la ligne et obtient une valeur différente, et
    3. La lecture fantôme, dans laquelle une transaction lit toutes les lignes qui remplissent une condition SQL WHERE, puis une seconde transaction insère une ligne qui remplit également cette condition et la première transaction applique la même condition WHERE et obtient la ligne insérée par la seconde transaction.
  • TRANSACTION_NONE : Ce niveau d'isolement indique que les transactions ne sont pas prises en charge sur ce type de ressource.
<session
 name="AccountServiceBean">
 <resource-ref
  name="jdbc/Default" 
  isolation-level="TRANSACTION_NONE">
</session>
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

Les tableaux suivants répertorient les éléments et attributs d'extension qui doivent être placés dans le fichier META-INF/ibm-ejb-jar-ext-pme.xml.
Tableau 8. Extensions définies dans META-INF/ibm-ejb-jar-ext-pme.xml. Extensions définies dans 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).
<internationalization>
  <application>
   <ejb name="S01"/>
   <ejb name="S02"/>
  </application>
  <run-as-caller>
   <method type="LOCAL" name="getFoo" params="int">
     <ejb name="C01"/>
   </method>
  </run-as-caller>
  <run-as-server>
   <method type="LOCAL" name="getBar" params="int">
    <ejb name="C02"/>
   </method>
  </run-as-server>
  <run-as-specified name="North American English">
   <locale lang="en" country="US" variant="foo"/>
   <locale lang="en" country="CA" variant="bar" /> 
   <time-zone name="GMT"/> 
   <method type="LOCAL" name="getFoo" params="int"> 
    <ejb name="C03"/>
   </method>
  </run-as-specified>
  <run-as-specified name="North American French"> 
   <locale lang="fr" country="US" variant="foo"/>
   <locale lang="fr" country="US" variant="bar" /> 
   <time-zone name="GMT"  /> 
   <method type="LOCAL" name="getBar" params="int"> 
   <ejb name="C04"/>
   </method>
  </run-as-specified>
</internationalization>
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.
<activity-sessions>
 <container-activity-session 
  name="Foo" type="NOT_SUPPORTED">
  <methodtype="HOME" name="findByPrimaryKey"
    params="int">
   <ejb name="C01"/>
  </method>
 </container-activity-session>
<./activity-sessions>
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
<app-profiles>
 <defined-access-intent-policy name="foo">
  <collection-scope type"SESSION"/>
  <optimistic-read/>
  <read-ahead-hint hint="foo.bar.baz"/>
 </defined-access-intent-policy>
 <run-as-task 
  name="TestEJB1.ejbs.C01LocalHome.createjava.lang.Integer" 
  type="RUN_AS_SPECIFIED_TASK">
  <task name=“/>
  <method type="LOCAL" name="getFoo" params="int">
   <ejb name="C01"/>
  </method>
 </run-as-task>
 <ejb-component-extension ejb="C01"> 
  <task name="SomeTask"/>
 </ejb-component-extension>
</app-profiles>
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.

Les fichiers de schéma qui décrivent son format sont situés sous le répertoire <REP_WAS>/properties/schemas. Cette forme de spécification de liaisons ne peut être utilisée que pour les modules ne comportant pas de descripteur de déploiement XML ou contenant un descripteur de déploiement EJB 3.x.
Remarque : Il n'est pas nécessaire de spécifier chaque liaison. Les noms de liaisons ou les références non définies reçoivent des liaisons par défaut, avec prise en charge par AutoLink.
Des liaisons peuvent être spécifiées pour les beans suivants :
  • Beans session utilisant l'élément <session>.
  • Beans gérés par message utilisant l'élément <message-driven>.
Les seuls attributs et sous-éléments pris en charge pour l'élément <session> sont les suivants :
  • 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
Les seuls attributs et sous-éléments pris en charge pour l'élément <message-driven> sont les suivants :
  • 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

Icône indiquant le type de rubrique Rubrique de concept



Icône d'horodatage Dernière mise à jour: last_date
http://www14.software.ibm.com/webapp/wsbroker/redirect?version=cord&product=was-nd-mp&topic=cejb_bindingsejbfp
Nom du fichier : cejb_bindingsejbfp.html