EJB 3.0 application bindings overview


 

+

Search Tips   |   Advanced Search

 

EJB resource references are bound to application artifacts, including enterprise beans or resources.

The jndiName values specified for artifacts must be qualified lookup names.

For EJB 3.0 modules, if we do not explicitly assign bindings, the EJB container assigns default bindings.

WAS provides two namespaces for EJB interfaces...

Local EJB interfaces and homes must always be bound into a JVM-scoped ejblocal: namespace; they are accessible only from within the same appserver process.

Remote EJB interfaces and homes must always be bound into the globally-scoped WebSphere JNDI namespace; they can be accessed from anywhere, including other server processes and other remote clients.

Local interfaces cannot be bound into the globally-scoped JNDI namespace, nor can remote interfaces be bound into the JVM-scoped ejblocal: namespace.

The ejblocal: and globally-scoped JNDI namespaces are completely separate and distinct.

For example, an EJB local interface bound at...

ejblocal:AccountHome

...is a not at all the same as a remote interface bound at...

AccountHome

...in the globally-scoped namespace. Having a JVM-scoped local namespace also makes it possible for the applications to directly look up or reference local EJB interfaces from anywhere in the JVM server process, including across Java EE application boundaries.

 

Assign default JNDI bindings using Application, Module, and Component

The WAS V7 EJB container assigns default JNDI bindings for EJB 3.0 business interfaces based on Application Name, Module Name, and Component Name.

Java EE applications are packaged in a standardized format called an EAR file. The EAR is a packed file format similar to a .zip or .tar file format, and can thus be visualized as a collection of logical directories and files packed together into a single physical file. Within each EAR file are one or more Java EE module files, which can include:

Within each module file are typically one or more Java EE components. Examples of Java EE components are enterprise beans, servlets, and application client main classes.

Since Java EE modules are packaged within Java EE application archives, and Java EE components are in turn packaged within Java EE modules, the "nesting path" of each component can be used to uniquely identify every component within a Java EE application archive, according to its application name, module name, and component name.

 

Application name

The name of an application is defined by the following (in order of priority):

 

Module name

The name of a module is defined as the URI of the module file, relative to the root of the EAR file in which it resides.

The module name is the module's file name relative to the root of the EAR file, including any "sub-directories" in which the module file is nested.

In the following example, the CustomerServiceApp application contains three modules named...

ls -l...

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

 

EJB component name

The name of an EJB component is defined by the following, in order of priority:

 

Bindings

Review the following bindings that are supported by EJB 3.0:

 

Default bindings for EJB business interfaces and homes

In WAS V7, it is not necessary for you to explicitly define JNDI binding names for each of the interfaces or EJB homes within an EJB 3.0 module. If we do not explicitly assign bindings, the WAS's EJB container assigns default bindings using the rules outlined here. This is somewhat different from the EJB support in WAS prior to the support of the EJB 3.0 specification.

The container performs two default bindings for each interface (business, remote home, or local home) on each enterprise bean. These two bindings are referred to here as the interface's "short" binding and its "long" binding. The short binding uses just the package-qualified Java class name of the interface, while the long binding uses the enterprise bean's component ID as an extra qualifier before the package-qualified interface class name, with a hash or number sign (# symbol) between the component ID and the interface class name. We can think of the difference between the two forms as being analogous to a "short" TCP/IP hostname (just the machine name) versus a "long" hostname (machine name with domain name prepended to it).

For example, an interface's short and long default bindings might be...

By default, the component ID for EJB default bindings is formed using the enterprise bean's Application Name, Module Name, and Component Name defined above, but we can assign any string you want instead. By defining our own string as the component ID, we can set up a naming convention where the enterprise bean's long-form bindings share a common user-defined portion, yet also have a system-defined portion based on the name of each interface class. It also allows you to make the default EJB binding names independent of how we have packaged the enterprise beans within the application/module hierarchy. Overriding an enterprise bean's default component ID is described in the "User-defined bindings for EJB business interfaces and homes" section of this topic.

All local interfaces and homes must be bound into the ejblocal: namespace, which is accessible only within the same server process (JVM), while remote interfaces and homes must be bound into the globally-scoped namespace, which is accessible from anywhere in the WebSphere product cell. As you would expect, the EJB container follows these rules for the default bindings.

In addition, the "long" default bindings for remote interfaces follow recommended Java EE best practices in that they are grouped under an ejb context name. By default, EJB remote home and business interfaces are bound into the root of the appserver naming context. However, the appserver root context is used for binding more than just EJB interfaces, so to keep this context from getting too cluttered, it is a good practice to group EJB-related bindings into a common "EJB" sub-context rather than placing them directly in the server root context. It is similar to why you would use subdirectories on a disk volume rather than putting all the files in the root directory.

The short default bindings for remote interfaces are not bound in the ejb context.

The short default bindings are located in the root of the server root context.

Even though it is a best practice to group all of the EJB-related bindings under an ejb context, there are other considerations including the following:

To summarize, all local default bindings, both short and long, are placed in the ejblocal: server/JVM-scoped namespace, while remote default bindings are placed in the server's root context of the globally-scoped namespace if they are short, or in the <server_root>/ejb context (just below the server's root context) if they are long. Thus, the only default bindings in the server's globally-scoped root context are the short bindings for remote interfaces, which is the best balance between providing a simple, portable usage model and keeping the server's globally-scoped root context from becoming too cluttered.

 

Default binding pattern

The patterns for each type of binding are displayed in the table. In these patterns, strings written in <bracketed italics> represent a value.

For example, <package.qualified.interface> might be com.mycompany.AccountService and <component-id> might be something like AccountApp/module1.jar/ServiceBean.

Table 1. Default binding patterns

Short form local interfaces and homes

ejblocal:<package.qualified.interface>

Short form remote interfaces and homes

<package.qualified.interface>

Long form local interfaces and homes

ejblocal:<component-id>#<package.qualified.interface>

Long form remote interfaces and homes

ejb/<component-id>#<package.qualified.interface>

The component-id defaults to <application-name>/<module-jar-name> /<ejb-name> unless it is overridden in the EJB module binding file using the component-id attribute

 

Conflicts in short default binding names when multiple enterprise beans implement the same interface

When more than one enterprise bean that is running in the appserver implements a given interface, the short default binding name becomes ambiguous because the short name might refer to any of the Enterprise Java Beans that implement this interface. In order to avoid this situation, either explicitly define a binding for each Enterprise Java Beans that implements the given interface, or disable short default bindings for applications containing these Enterprise Java Beans by defining a WebSphere product "JVM custom property"....

com.ibm.websphere.ejbcontainer.disableShortDefaultBindings

To use this JVM custom property, set the property name to com.ibm.websphere.ejbcontainer.disableShortFormBinding and the property value to either * (asterisk} as a wildcard value to disable short form default bindings for all applications in the server, or to a colon-delimited sequence of the Java EE application names for which you want to disable short default bindings, for example...

PayablesApp:InventoryApp:AccountServicesApp

 

Effect of explicit assignment on default bindings

If we explicitly assign a binding definition for an interface or home, no short or long default bindings are performed for that interface.

This only applies to the specific interfaces for which you assign an explicit binding. Other instances on that enterprise bean, without explicitly-assigned bindings, are bound by using default binding names.

 

User-defined bindings for EJB business interfaces and homes

For cases where you want to manually assign binding locations rather than using default bindings, we can use the EJB module binding file to assign our own binding locations to specific interfaces and homes. We can also use this file to only override the component ID portion of the default bindings on one or more enterprise beans in the module. Overriding the component ID provides a middle ground between allowing the bindings to completely default, versus completely specifying the binding name for each interface.

To specify user-defined bindings information for EJB 3.0 modules, place a file named, ibm-ejb-jar-bnd.xml, in the EJB JAR module's META-INF directory.

The suffix on this file is XML, not XMI, as in prior versions of WAS.

Also, when defining a binding for a local interface, preface the name with the string "ejblocal:" so it is bound into the JVM-scoped ejblocal: namespace.

The ibm-ejb-jar-bnd.xml file is used for EJB 3.0 modules that run on WAS, whereas the ibm-ejb-jar.bnd.xmi file is used for pre-EJB 3.0 modules and for Web modules. The binding file format in ibm-ejb-jar.bnd.xml is different from the XMI file format for the following reasons:

The following table lists the ibm-ejb-jar-bnd.xml elements and attributes that are used to assign bindings to EJB interfaces and homes for EJB 3.0 modules in WAS V7.

ibm-ejb-jar-bnd.xml elements and attributes

<session>

Declares a group of binding assignments for a session bean.

<session name="AccountServiceBean"/>

Requires name attribute and at least one of the following: simple-binding-name attribute, local-home-binding-name attribute, remote-home-binding-name attribute, or <interface> element.

name

Attribute that identifies the ejb-name of the enterprise bean that a <session>, <message-driven>, or <entity>, or other element applies to.

<session name="AccountServiceBean"/>

The ejb-name value is the name declared in the <ejb-name> element of an ejb-jar.xml deployment descriptor file, the name parameter of a @Session or @MessageDriven annotation, or defaults to the unqualified class name of the EJB implementation class annotated with the @Session or @MessageDriven annotation (if no <ejb-name> value is declared in the XML deployment descriptor and no name parameter is declared on the annotation).

component-id

Attribute that overrides the default component ID value for an enterprise bean. The default long-form bindings for this enterprise bean uses the specified component ID instead of <app_name>/<module_jar_name>/<bean_name>.

<session name="AccountServiceBean" component-id="Dept549/ AccountProcessor"/>

The above example results in the bean whose ejb-name is AccountServiceBean, having its long-form default local interfaces bound at

ejblocal:Department549 /AccountProcessor# <package.qualified. interface>

Its long-form default remote interfaces are bound at

ejblocal:Department549 /AccountProcessor# <package.qualified. interface>

Can be used alone, or in combination with the <interface> element, the local-home-binding-name attribute, or the remote-home-binding-name attribute. Interfaces that are not assigned explicit bindings will have default bindings performed using the user-specified component ID value. Interfaces that are assigned explicit bindings are bound using those values.

Since the simple-binding-name attribute is intended to apply to all defined interfaces on a given enterprise bean (leaving no interfaces defaulted), applying a component-id in combination with simple-binding-name is typically not useful.

simple-binding-name

A simple mechanism for assigning interface bindings for Enterprise Java Beans that:

The value of the attribute is used as the binding location of the enterprise bean's business interface, or the binding location of the Enterprise Java Beans local and/or remote homes. The binding is placed in the ejblocal: namespace if the interface or home is local, and placed in the appserver's root context of the globally-scoped JNDI namespace if the interface or home is remote.

<session name="AccountServiceBean" simple-binding-name ="ejb/AccountService"/>

This example results in the bean whose ejb-name is AccountServiceBean, having its local business interface or home, if any, bound at

ejblocal:ejb/ AccountService
in the local JVM-scoped EJB namespace, and its remote business interface or home (if any) bound at

ejb/AccountService
in the appserver's root context of the globally-scoped JNDI namespace.

It is important to note here that the exact value of the attribute, including, in this specific example, the "ejb" subcontext name is used even if the interface is a local interface bound into the ejblocal: namespace. When user-defined bindings are specified, the exact name specified by the attribute is used.)

Not to be used in combination with local-home-binding-name or remote-home-binding-name attributes, or the <interface> element. Also, should not be used on beans that implement more than one business interface (use the <interface> element in that case instead).

If this attribute is used on an enterprise bean that implements more than one business interface, or a combination of business interface and local/remote component interface with home, the resulting bindings are disambiguated by appending a hash or number sign (# symbol) to the attribute value, followed by the package-qualified class name of each interface and/or home on the enterprise bean. This condition can be avoided, however, by using the <interface> element to define a binding for each of the business interfaces instead of using simple-binding-name.

 

Defining a simple-binding-name on a bean that implements more than one business interface is not the same as overriding the default component ID for a bean using <component-id>.

Remote interface default bindings defined with a component-id are still grouped under the ejb context (as all remote interface default bindings are), while remote interface bindings disambiguated by the EJB container in response to erroneous use of simple-binding-name on a bean with multiple interfaces are not grouped under the ejb context.

Additionally, the inclusion of the package-qualified class name always occurs for long-form default bindings, whereas with simple-binding-name it occurs only on error conditions, where disambiguation is necessary. It should not be considered a good practice to depend on the binding name created through disambiguation, since whether that effect occurs may change if the bean is changed to implement more or fewer interfaces.

local-home-binding-name

Attribute to specify the binding location of an enterprise bean's local home.

<session name="AccountServiceBean" local-home-binding -name="ejblocal: AccountService"/>

Not to be used in combination with the simple-binding-name attribute. Since local homes must always be bound into the JVM-scoped namespace, the value must begin with the ejblocal: prefix.

remote-home-binding-name

Attribute to specify the binding location of an enterprise bean's remote home.

<session name="AccountServiceBean" remote-home-binding-name="ejb/services/ AccountService"/>

Not to be used in combination with the simple-binding-name attribute. The value cannot begin with the ejblocal: prefix, since remote homes cannot be bound into the ejblocal: namespace.

<interface>

A sub-element of the <session> element that assigns a binding to a specific EJB business interface. In contrast to the simple-binding-name, local-home-binding-name and remote-home-binding-name attributes, both a binding-name parameter and a class parameter are necessary (in fact, this distinction is why a separate XML element is necessary rather than an attribute). The class parameter specifies the package-qualified name of the business interface class to be bound.

<interface class="com.ejbs. Inventory Service" binding-name="ejb/Inventory"/>
(declared as a sub-element inside a <session> element)

Not to be used in combination with the simple-binding-name attribute. Since local interfaces must always be bound into the JVM-scoped namespace, the binding-name value must begin with the ejblocal: prefix when this element is applied to a local interface.

binding-name

Attribute to specify the binding location of a business interface bound with the <interface> element.

<interface class="com.ejbs.Inventory Service" binding-name ="ejb/Inventory"/>
(declared as a sub-element inside a <session> element)

Required in combination with the <interface> element (and used on that element only). Since local interfaces must always be bound into the JVM-scoped namespace, the binding-name value must begin with the ejblocal: prefix when applied to a local interface.

 

Binding file Example 1

The following is a basic ibm-ejb-jar-bnd.xml file containing only the elements and attributes that assign binding names to EJB interfaces. It overrides the component ID used for default bindings on the enterprise bean that is named "S01", and assigns explicit bindings to some of the interfaces on the enterprise beans, "S02" and "S03", in this 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>

The binding file results in the following:

  1. The session bean with ejb-name "S01" is assigned a user-defined component ID, overriding the default component ID (application name/ejb-jar module name/bean name) for all interfaces on that bean. Local interfaces on this bean are bound at

    ejblocal:Department549/AccountProcessors#<package.qualified.interface.name>
    while remote interfaces are bound at

    ejb/Department549/AccountProcessors#<package.qualified.interface.name>
    .

  2. The session bean with ejb-name "S02" is assumed to have a single EJB 3.0 business interface. Alternatively, it could have a pre-EJB 3.0 "component" interface with local home, remote home, or both local and remote homes. The business interface, or component interface's home(s) are bound at

    ejblocal:ejb/session/S02
    if it is local, or

    ejb/session/S02
    if it is remote.

    If bean S02 has more than one business interface, or business interface(s) and home, a simple-binding-name is ambiguous. In that case, the container disambiguates the binding assignments by appending #<package.qualified.interface.name> to the simple binding name ejb/session/S02 for each of the bean's interfaces.

  3. The EJB 3.0 business interface com.ejbs.BankAccountService on the session bean with ejb-name "S03" is bound at ejblocal:session/BAS.
All other business interfaces and homes on this bean, if present, are assigned default bindings. The com.ejbs. BankAccountService interface is assumed to be local since it was designated for the ejblocal: namespace in this example; an error would occur if the interface were not local.

The next section expands on this example, introducing elements for resolving the targets of various kinds of reference and injection entries that are declared either in the XML deployment descriptor or through annotations.

 

User-defined bindings for resolving references and injection targets

The previous section showed you how to assign user-defined binding names for business interfaces and homes. This section covers how to resolve linkage targets for references, injection directives and message-driven bean destinations.

Elements and attributes to resolve linkage targets for references and injection targets

<jca-adapter>

Defines the JCA 1.5 adapter activation spec, and a message-destination

JNDI location, for delivery of messages to a message-driven bean.

<jca-adapter activation-spec-binding-name="jms/ InternalProviderSpec" destination-binding-name="jms/ServiceQueue"/>

Requires activation-spec-binding-name attribute.

If the corresponding message-drive bean does not identify its message destination by using the <message-destination-link> element, then the destination-binding-name attribute is also required. Can optionally include activation-spec-auth-alias attribute.

<ejb-ref>

Resolves the target of an ejb-ref declaration, which is declared through the @EJB annotation or through the ejb-ref in the ejb-jar.xml deployment descriptor, providing the linkage between the name declared in the component-scoped java:comp/env namespace and the name of the target enterprise bean in the JVM-scoped ejblocal:, or globally-scoped JNDI namespace.

<ejb-ref name="com.ejbs. BankAccountServiceBean/ s02Ref" binding-name="ejb/session/S02"/>

Requires the name and binding-name attributes.

<message-driven>

Declares a group of binding assignments for a message-driven bean.

<message-driven name="EventRecorderBean"> <jca-adapter activation-spec-binding-name="jms/ InternalProviderSpec" destination-binding-name="jms/ServiceQueue"/> </message-driven>

Requires name attribute and <jca-adapter> sub-element.

<message-destination>

Associates the name of a message destination, which is a logical name defined in a Java EE module deployment descriptor, with a specific global JNDI name, which is an actual name in the JNDI namespace.<message-destination-ref> elements in the Java EE module deployment descriptor, or @Resource injection directives that inject message destinations, can then use the <message-destination-line> element to refer to this message-destination by the destination logical name, rather than requiring individual <message-destination-ref> binding entries in the binding file for each defined message-destination-ref.

<message-destination name="EventProcessing Destination" binding-name="jms/ ServiceQueue"/>

Requires name and binding-name attributes.

<message-destination-ref>

Resolves the target of a message-destination-ref declaration that is declared through the @Resource annotation or through the message-destination-ref in ejb-jar.xml, providing the linkage between the name declared in the component-scoped java:comp/env namespace and the name of the target resource environment in the global JNDI namespace.

<message-destination-ref name="com.ejbs. BankAccountServiceBean/ serviceQueue" binding-name="jms/ServiceQueue"/>

Requires the name and binding-name attributes.

<resource-ref>

Resolves the target of a resource-ref declaration that is declared through the @Resource annotation or through resource-ref in ejb-jar.xml, providing the linkage between the name declared in the component-scoped java:comp/env namespace and the name of the target resource in the global JNDI namespace.

<resource-ref name="com.ejbs.BankAccountServiceBean/ dataSource" binding-name="jdbc/Default"/>

Requires the name and binding-name attributes.Can include the authentication-alias or custom-login-configuration attributes.

<resource-env-ref>

Resolves the target of a resource-env-ref declaration that is declared through the @Resource annotation or through resource-env-ref in ejb-jar.xml, providing the linkage between the name declared in the component-scoped java:comp/env namespace and the name of the target resource environment in the global JNDI namespace.

<resource-env-ref name="com.ejbs. BankAccountServiceBean/ dataFactory" binding-name="jdbc/ Default"/>

Requires the name and binding-name attributes.

name

Attribute that identifies the naming location, typically within the component-specific java:comp/env namespace, that defines the "source" side of a reference/target linkage, such as in ejb-ref, resource-ref, resource-env-ref, message-destination, or message-destination-ref.

<ejb-ref name="com.ejbs.BankAccountServiceBean/goodBye" binding-name="ejb/session/S02"/>

 

binding-name

Attribute that identifies the naming location within the ejblocal: or globally-scoped JNDI namespace that defines the "target" side of a reference/target linkage, such as in ejb-ref, resource-ref, resource-env-ref, message-destination, or message-destination-ref.

<ejb-ref name="com.ejbs.BankAccountServiceBean/goodBye" binding-name="ejb/session/S02"/>

 

activation-spec-binding-name

Attribute that identifies the JNDI location of the activation spec associated with the JCA 1.5 adapter to be used to deliver messages to a message-driven bean.

<jca-adapter activation-spec-binding-name="jms/InternalProviderSpec" destination-binding-name="jms/ServiceQueue"/>

This name must match the name of a JCA 1.5 activation spec that you define to WAS.

activation-spec-auth-alias

Optional attribute that identifies the name of a J2C authentication alias used for authentication of connections to the JCA resource adapter.A J2C authentication alias specifies the user ID and password that is used to authenticate the creation of a new connection to the JCA resource adapter.

<jca-adapter activation-spec-binding-name="jms/InternalProviderSpec" activation-spec-auth-alias="jms/Service47Alias" destination-binding-name="jms/ServiceQueue"/>

This name must match the name of a J2C authorization alias that you define to WAS.

destination-binding-name

Attribute that identifies the JNDI name that the message-driven bean uses to look up its JMS destination in the JNDI name space.

<jca-adapter activation-spec-binding-name="jms/InternalProviderSpec" destination-binding-name="jms/ServiceQueue"/>

This name must match the name of a JMS queue or topic that you define to WAS.

authentication-alias

Optional sub-element of the <resource-ref> binding element.If the resource reference is for a connection factory, then an optional JAAS login configuration can be specified; in this case a simple authentication alias name.

<resource-ref name="com.ejbs.BankAccountServiceBean/dataSource" binding-name="jdbc/Default"> <authentication-alias name="defaultAuth"/> <resource-ref>

This name must match the name of a JAAS authentication alias that you define to WAS.

custom-login-configuration

Optional sub-element of the <resource-ref> binding element.If the resource reference is for a connection factory, then an optional JAAS login configuration can be specified; in this case a set of properties (name/value pairs).

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

This name must match the name of a JAAS login configuration that you define to WAS.

 

Binding file Example 2

Shown below is an expansion of the basic ibm-ejb-jar-bnd.xml file introduced in Example 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>

This binding results in the following:

  1. The business interface and home bindings for the session beans named S01, S02 and S03 are unchanged from the previous example.

  2. The session bean whose ejb-name is "S03" now includes two reference target resolution bindings:

    • The ejb-ref binding resolves the EJB reference defined at java:comp/env/com.ejbs.BankAccountServiceBean/goodBye, to the JNDI location ejb/session/S02 within the appserver's root

      JNDI context.The EJB reference could also have been defined by an @EJB injection in the class com.ejbs.BankAccountServiceBean, into an instance variable named "goodBye."

      ejb/session/S02 is the JNDI location of session bean "S02" also defined in this same binding file, which means that the reference points to the session bean whose name is "S02."

    • The resource-ref binding resolves the resource reference defined at java:comp/env/com.ejbs.BankAccountServiceBean/dataSource, to the JNDI location jdbc/Default.The resource reference could also have been defined by a @Resource injection in the class com.ejbs.BankAccountServiceBean, into an instance variable named "dataSource."

  3. Bindings are defined for a message-driven bean whose ejb-name is "M01".

    The MDB receives messages from a JMS destination defined to WebSphere Application Server, whose JNDI name is jms/ServiceQueue, using a JCA 1.5 adapter whose JCA 1.5 activation spec has been defined to WAS with the name jms/InternalProviderSpec.

  4. The session bean whose ejb-name is "S04" is assumed to have a single business interface, which is bound at ejb/session/S04 if remote, or ejblocal:ejb/session/S04 if local.It has a resource-ref with name, java:comp/env/ejbs/S04Bean/dataSource.

    This can also be the class, ejbs.S04Bean, with an @Resource injection into a variable named, dataSource.This resource-ref resolved to the JNDI location jdbc/Default.The resource-ref refers to a J2C connection and connects to this resource using a simple authentication alias named "defaultlogin" that has been defined to WAS.

  5. A business interface binding is defined for the interface whose class name is com.ejbs.InventoryService implemented by the session bean whose ejb-name is "S05"; the interface is assumed to be remote since it is not prefixed with "ejblocal:" and will thus be bound at ejb/session/S05Inventory in the server's root JNDI context in the globally-scoped namespace.Any other business interfaces implemented by this bean is assigned default bindings.The bean has a resource-ref with name java:comp/env/ejbs.S05Bean/dataSource (or a @Resource injection in the class ejbs.S05Bean into a variable named "dataSource") that is resolved to the JNDI location jdbc/Default.The resource-ref refers to a J2C connection and will connect to this resource using a custom login configuration that includes two name-value pairs.

 

Bindings file Example 3

This example demonstrates how to define and resolve EJB reference bindings to perform JNDI lookups across appserver instances within the same WAS cell.It uses two EJB beans:

 

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-ej b-jar-bnd_1_0.xsd" version="1.0"> <session name="FacadeBean" simple-binding-name="ejb/session/FacadeBean"/> </ejb-jar-bnd>

This binding file content assumes that the session bean whose ejb-name is "FacadeBean" implements a single business interface (and thus the simple-binding-name attribute can be used, as an alternative to the <interface> sub-element).In this case, the FacadeBean implements a single remote business interface, bound at ejb/session/FacadeBean in the server root JNDI context of the application server where the FacadeBean resides.

 

Code snippet (calling bean)

@EJB(name="ejb/FacadeRemoteRef") FacadeRemote remoteRef; try { output =remoteRef.orderStatus(input); } catch (Exception e) { // Handle exception, etc. }

This code snippet performs an EJB resource injection into the instance variable named "remoteRef", which is of type FacadeRemote.The injection overrides the "name" parameter, setting the resulting ejb-ref reference name to ejb/FacadeRemoteRef.

The code invokes a business method on the injected reference.

 

ibm-ejb-jar-bnd.xml (calling 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="CallingBean"> <ejb-ref name="ejb/FacadeRemoteRef" binding-name="cell/nodes/S35NLA1/servers/S35serverA1/ejb/session/FacadeBean"/> </session> </ejb-bnd-jar>

Finally, this binding file resolves the EJB reference with an ejb-ref name of ejb/FacadeRemoteRef to point to the globally-scoped JNDI name of cell/nodes/S35NLA1/servers/S35serverA1/ejb/session/FacadeBean.

This globally-scoped JNDI name represents an interface bound at ejb/session/FacadeBean under the server root context of the server named "S35serverA1" on the node named "S35NLA1" within the WAS cell of the calling bean.To point to a location within a different WAS cell, a CORBAName-style name can be used instead of a standard JNDI name.

Instructions on how to modify the ibm-ejb-jar-bnd.xml file can be found in the topic, Ways to update application files.

 

The relationship between injections and references

There is a one-to-one correspondence between injection directives and reference declarations -every injection implicitly defines a reference of some type, and conversely, every reference can optionally also define an injection.

You can think of an injection annotation as being the mechanism to define references through annotations rather than defining them in the XML deployment descriptor.

By default, an injection defines a reference with a name formed from the package-qualified class name of the component performing the injection, a forward slash (/), then the name of the variable or property being injected into.

For example, an injection performed in the class com.ejbs.AccountService, into a variable or property named "depositService", results in a reference named java:comp/env/com.ejbs.AccountService/depositService.However, specifying the optional "name" parameter on the injection directive overrides this default name and causes the reference to be named according to the value of the "name" parameter.

Knowing this rule, it is easy to see how a bindings file can be used not only to resolve targets for references declared in an XML deployment descriptor, but also to resolve targets for references implicitly declared by an annotation injection directive.Simply use the value of the "name" parameter on the injection annotation, or the default reference name from the class name and variable/property name if no "name" parameter is specified, just as if it were the name of the reference declared in an XML deployment descriptor.

 

Default resolution of EJB references and EJB injections: The AutoLink feature

AutoLink is a value-add feature of WAS that eliminates the need to explicitly resolve EJB reference targets in certain usage scenarios.In WebSphere Application Server V7, AutoLink is implemented within the boundaries of each WebSphere

Application Server process.The AutoLink algorithm works as follows.

When the WebSphere EJB container encounters an EJB reference within a given EJB module, it first checks to see if we have explicitly resolved the target of that reference through inclusion of an entry in the module's binding file. If it finds no explicit resolution of the target in the binding file, the container searches within the referring module for an enterprise bean that implements the interface type we have defined within the reference.If it finds exactly one enterprise bean within the module that implements the interface, it uses that enterprise bean as the target for the EJB reference. If the container cannot locate an enterprise bean of that type within the module, it expands the search scope to the application that the module is part of, and search other modules within that application that are assigned to the same appserver as the referring module.Again, if the container finds exactly one enterprise bean that implements the target interface, within the application's other modules assigned to the same server as the referring module, it uses that enterprise bean as the reference target.

The scope of AutoLink is limited to the application in which the EJB reference appears, and to the appserver on which the referring module is assigned. References to enterprise beans in a different application, enterprise beans in a module assigned to a different appserver, or to enterprise beans residing in a module that has been assigned to a WAS cluster, must be explicitly resolved using reference target bindings in the EJB module's ibm-ejb-jar-bnd.xml file, or the Web module's ibm-web-bnd.xmi file.

It is important to note that AutoLink is only supported for EJB references, not other types of references although it is supported from the EJB container, the Web container, and the application client container.Also, because the scope of the AutoLink function is limited to the server that the referring module is assigned to, or in the case of the Java EE client container, to the server that the client container is configured as its JNDI bootstrap server, it is useful mainly in development environments and other single-server usage scenarios.Even with these present limitations, it can be a significant value during the development experience by removing the need to explicitly resolve EJB references.

 

Naming considerations in clustered and cross-server environments

The global JNDI naming conventions in the previous sections apply in non-clustered environments and when the lookup target is within the same cluster as the source of the lookup.When a lookup is performed from outside a cluster on a binding that is within a given cluster, the lookup string must be qualified to indicate the name of the cluster in which the target resides, according to the following convention:

cell/clusters/<cluster-name>/<name-binding-location>

For example, given an EJB interface binding location within the appserver root context:

ejb/Department549/AccountProcessors/CheckingAccountReconciler

If the EJB implementing this interface is assigned to an appserver that is a member of a cluster named Cluster47, the lookup string external to that cluster is as follows:

cell/clusters/Cluster47/ejb/Department549/AccountProcessors/CheckingAccountReconciler

When a lookup is performed across appserver processes, the lookup string must be qualified to indicate the name of the node and server in which the target resides, according to the following convention:

cell/nodes/<node-name>/servers/<server-name>/<name binding location>
Again, given an EJB interface binding location within the appserver root context:

ejb/Department549/AccountProcessors/CheckingAccountReconciler

If the enterprise bean that is implementing this interface is assigned to an appserver named Server47A1 that is located on a node named S47NLA1, the cross-server lookup string is as follows:

cell/nodes/S47NLA1/servers/Server47A1/ejb/Department549/AccountProcessors/CheckingAccountReconciler

 

User-defined EJB extension settings

To specify values for WAS EJB Extension settings, use an EJB module extension file. You specify extension settings information for EJB 3.0 modules by placing one, or both, of two files into the EJB JAR module's META-INF directory, depending on the type of extension being defined.

The suffix on these files are XML, not XMI as in prior versions of WAS. The ibm-ejb-jar-ext.xml and ibm-ejb-jar-ext-pme.xml files are used for EJB 3.0 modules running in WebSphere Application Server, whereas the ibm-ejb-jar-ext.xmi and ibm-ejb-jar-ext-pme.xmi files are used for pre-3.0 EJB modules.WAS Version 7.0 uses a new XML-based extension file format instead of the previous xmi file format for the following reasons:

  1. Bindings and extensions declared in the xmi file format depend on the presence of a corresponding ejb-jar.xml deployment descriptor file, explicitly referring to unique ID numbers attached to elements in that file.This system is no longer viable for EJB 3.0 and later modules, where it is no longer a requirement for the module to contain an ejb-jar.xml deployment descriptor.

  2. The xmi file format was designed to be machine-edited only by WebSphere development tools and system management functions; it was effectively part of WebSphere's internal implementation and the file's structure was never documented externally.This made it impossible for developers to manually create or edit binding or extension files, or create them as part of a WebSphere-independent build process, in a supported manner.

  3. Rather than referring to encoded ID numbers in ejb-jar.xml, the XML-based extension file format refers to EJB components by their EJB name.Each EJB component in a module is guaranteed to have a unique EJB name, either by default or through explicit assignment by the developer, so this provides an unambiguous way to target bindings and extensions.

  4. The new binding and extension file formats are XML-based, and XML Schema

    Definition (xsd) files are provided to externally document their structure.

    These .xsd files may be consumed by many common XML file editors to assist in syntactic verification and code completion functions.As a result, it is now possible for developers to produce and edit these binding and extension files independently of WAS infrastructure, using a generic XML editor or scripting system of their choice.

 

Extensions defined in META-INF/ibm-ejb-jar-ext.xml

The following tables list extension elements and attributes that must be placed in the META-INF/ibm-ejb-jar-ext.xml file.The next section lists elements and attributes that appear in a separate file, META-INF/ibm-ejb-jar-ext-pme.xml.

Elements and attributes of the META-INF/ibm-ejb-jar-ext.xml file

<session>

Declares a group of extension settings for a session bean.

<session name="AccountServiceBean"/>

Requires name attribute.In order to have any effect, also include at least one extension setting definition sub-element.

<message-driven>

Declares a group of extension settings for a message-driven bean.

<message-driven name="EventProcessorBean"/>

Requires name attribute.In order to have any effect, also include at least one extension setting definition sub-element.

Elements and attributes of the META-INF/ibm-ejb-jar-ext.xml file

<time-out>

Sub-element to the <session> element that optionally declares the number of seconds between method invocations after which a stateful session bean will be no longer available.

<session name="ShoppingCartBean"> <time-out value="600"/></session>

300 (10 minutes)

Requires value attribute, a positive integer.Only applicable to stateful session beans; must not be used on stateless beans.

<bean-cache>

Sub-element of <session> element used to declare bean activation/passivation settings for stateful session beans.

<session name="ShoppingCartBean> <bean-cache activation-policy="TRANSACTION"/> </session>

 

In order to have any effect, should also include the activation-policy attribute.

activation-policy

Attribute of <bean-cache> element that declares the conditions under which the bean instance will be activated and passivated.

Applicable to stateful session beans.Allowable values and their meanings are:

<session name="ShoppingCartBean> <bean-cache activation-policy="ONCE"/></session>

ONCE for stateful session beans.

 

Elements and attributes of the META-INF/ibm-ejb-jar-ext.xml file

<global-transaction>

Sub-element to the <session> and <message-driven> elements that can be used to declare the transaction timeout (in seconds) to be used on transactions started by this specific EJB type (overriding the server setting for global transaction timeout) and also may declare whether this EJB type will propagate global transaction context received through web service atomic transactions, across the heterogeneous Web service environment.

<session name="AccountServiceBean" <global-transaction transaction-timeout="180" send-wsat-context="FALSE"/> </session>

Server transaction timeout setting for transaction-timeout;

FALSE for send-wsat-context

Requires at least one of transaction-timeout or send-wsat-context attributes.

<local-transaction>

Sub-element to the <session> and <message-driven> elements that can be used to declare settings related to local transactions.

Allowed attributes are boundary, resolver, and unresolved-action; these attributes configure, for the component, the behavior of the container's local transaction containment (LTC) environment that the container establishes whenever a global transaction is not present.The meaning of each attribute is as follows:

 

Boundary

This setting specifies the containment boundary at which all contained resource manager local transactions (RMLTs) must be completed.Possible values are:

 

Resolver

This setting specifies the component responsible for initiating and ending RMLTs.Possible values are:

 

Unresolved Action

This setting specifies the direction that the container requests RMLTs to take, if those transactions are unresolved at the end of the LTC boundary scope and the Resolver is set to Application. Possible values are:

<session name>="AccountServiceBean"> <local-transaction boundary="BEAN_METHOD" resolver="APPLICATION" unresolved-action="ROLLBACK"/> </session>

boundary="BEAN_ METHOD"; resolver="APPLICATION"; unresolved-action="ROLLBACK"

Requires at least one of boundary, resolver, or unresolved-action attributes.

 

 

 

 

 

Elements and attributes of the META-INF/ibm-ejb-jar-ext.xml file

<method>

Sub-element to the <method-session-attribute> and <run-as-mode> elements used to specify the method name, method signature, or method types to which a given setting will apply.Allowed attributes are type, name, and params.The meaning of each attribute is as follows:

 

type

 

name

The name of the method to which the setting will be applied, or an asterisk (*) if the setting is to be applied to all methods regardless of name.

 

params

The parameter signature of the method to which the setting will be applied.This can be used to uniquely qualify a particular method in cases where more than a single method uses the same name.The parameter signature is a comma-separated list of Java types. Primitive types are specified using their name only; non-primitive types are specified using their fully-qualified class or interface name including any Java package, and arrays of Java types are specified by the array element's type followed by one or more pair of square brackets (for example int[][]).

<session /name="AccountServiceBean"> <method-session-attribute type="REQUIRES_NEW"> <method type="LOCAL" name="debitAccount" params="java.lang. String[], int, com.abc. CustomerInfo"/> </method-session-attribute;> </session>

 

 

<run-as-mode>

Sub-element to the <session> and <message-driven> elements that can be used to declare the security identity that a given EJB method will have while the method is being executed.The identity can be set to use the identity of the caller (mode =CALLER_IDENTITY), the identity of the EJB server (mode =SERVER_IDENTITY), or the identity of a specific security role (mode =SPECIFIED_IDENTITY).

<session name="AccountServiceBean"> <start-at-app-startvalue="TRUE"/> </session>

 

Requires mode attribute and <method> sub-element.If the mode is SPECIFIED_IDENTITY, the <specified-identity sub-element is also required.

<start-at-app-start>

Sub-element to the <session> and <message-driven> elements that can be used to inform the EJB container that specified EJB type shall be initialized at the time the application is first started, rather than the time the EJB type is first used by the application.

<session name="AccountServiceBean"> <start-at-app-startvalue="TRUE"/></sesssion>

FALSE (initialize EJB type when EJB is first used by application) for beans other than message-driven beans.Always TRUE for message-driven beans.

Requires value attribute

<resource-ref>

Sub-element to the <session> and <message-driven> elements, that may be used to declare additional settings on a Java EE resource reference, such as isolation level to be used on transactions driven through the connection referred to by the reference.Allowable attributes include isolation-level.

The meaning of each attribute is as follows: isolation-level

<session name="AccountServiceBean"> <resource-ref name="jdbc/Default" isolation-level="TRANSACTION_NONE"> </session>

 

Requires name attribute.In order to have any effect, must also include the isolation-level attribute.

 

Extensions defined in META-INF/ibm-ejb-jar-ext-pme.xml

The following tables list extension elements and attributes that must be placed in the META-INF/ibm-ejb-jar-ext-pme.xml file.

Extensions defined in META-INF/ibm-ejb-jar-ext-pme.xml

<internationalization>

Element that may be used to declare the locale that will be used by the EJB type (caller's locale or server's locale).

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

 

For information on this extension, see

http://publib.boulder .ibm.com/infocenter/a diehelp/index.jsp?top ic=/com.ibm.etools.j2 ee.pme.ui.doc/concept s/cin_containerattrib ute.html
.Due to the complexity of this function, you may wish to use tooling designed for WAS such as Rational Application Developer (RAD) to produce the desired extension file stanzas, then modify the XML file as desired.

<activity-sessions>

Element that optionally declares the type of activity session management to be used on a designated session bean (BEAN or CONTAINER) and for container-managed activity sessions, the type of activity session behavior to be provided by the container.

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

 

For information on this extension, see

http://publib. boulder.ibm.com/ infocenter/ adiehelp/index. jsp?topic=/com.ibm.etools. j2ee.pme.ui.doc/ tasks/tas_ depejb2.html
.Due to the complexity of this function, you may wish to use tooling designed for WAS such as Rational Application Developer

<app-profiles>

Element that optionally declares application profile settings for one or more EJBs

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

 

Due to the complexity of this function, you may wish to use tooling designed for WAS such as Rational Application Developer (RAD) to produce the desired extension file stanzas, then modify the XML file as desired.

 

Legacy (XMI) bindings

Existing modules and applications can continue to use the legacy binding support provided in WAS, therefore, the existing tools and wizards can be used to specify binding and extension information for applications and modules.Use of the legacy support is limited to EAR files and modules using J2EE 1.4-style XML deployment descriptors.

EJB modules that use a version 3.0 XML deployment descriptor schema or do not have an XML deployment descriptor file must use either defaulted bindings and AutoLink, or user-specified XML binding files.

It is required that CMP entity beans always be packaged in a module with a 2.1 XML deployment descriptor schema version so that existing tools can be used to provide mappings, bindings, and extension support.

 

User-specified XML bindings

The default bindings for each interface and AutoLink reference resolution for each reference can be overridden by specifying bindings for the EJB module by creating a META-INF/ibm-ejb-jar-bnd.xml file.

The schema files that describe the format are located in...

<WAS_HOME>/properties/schemas

This form of bindings spec can only be used for modules containing either no XML deployment descriptor or an EJB 3.0 deployment descriptor.

It is not required to specify all bindings. Any binding name or reference that is not defined uses the default bindings and AutoLink support.

Bindings can be specified for the following:

The only attributes and sub-elements supported for the <session> element are:

The only attributes and sub elements supported for the <message-driven> element are:




Related concepts



EJB modules
Ways to update enterprise application files
Application bindings

 

Related tasks


Exporting enterprise application files
Exporting enterprise apps
Develop enterprise beans
Task overview: Using enterprise beans in applications

 

Related


Options for the AdminApp object install, installInteractive, edit, editInteractive, update, and updateInteractive commands
Java virtual machine custom properties
Lookup names support in deployment descriptors and thin clients