+

Search Tips   |   Advanced Search

EJB 3.0 and EJB 3.1 application bindings overview

Prior to starting an application installed on an application server, all EJB references and resource references defined in the application must be bound to the actual artifacts (enterprise beans or resources) defined in the application server.

Starting in v8.0, bindings support in the EJB container is expanded. The EJB container assigns default JNDI bindings for EJB 3.x business interfaces based on application name, module name, and component name. We do not have to explicitly define JNDI binding names for each of the interfaces or EJB homes within an EJB 3.x module or no-interface views within an EJB 3.1 module.

When defining bindings, we specify Java Naming and Directory Interface (JNDI) names for the referenceable and referenced artifacts in an application. The jndiName values specified for artifacts must be qualified lookup names.

We do not need to manually assign JNDI bindings names for each of the interfaces, EJB homes, or no-interface views on your enterprise beans in EJB 3.x modules. If we do not explicitly assign bindings, the EJB container assigns default bindings.


Namespaces for default EJB JNDI bindings

Default EJB bindings may be placed by the application server into both the classic and java:[scope] sets of namespaces.

The set of classic namespaces consists of the ejblocal: and Global JNDI namespaces. The classic namespaces include a WebSphere extension, and they existed in the application server prior to version 8.0.

The set of java:[scope] namespaces consists of the java:global, java:app, and java:module namespaces. The java:[scope] namespaces are defined by the Java EE 6 specification, and are introduced into theWAS in v8. They are not a replacement for the classic namespaces. Rather, they are added in addition to the classic namespaces.


Classic namespace details

For the EJB 3.x level, WAS v9 provides two distinct classic namespaces for EJB interfaces, depending on whether the interface is local or remote. The same provision applies to EJB homes and no-interface views, which can be considered special types of interfaces. The following classic namespaces exist:

Local EJB interfaces, homes, and no-interface views must be bound into a JVM-scoped classic ejblocal: namespace; they are accessible only from within the same application server process.

In contrast, remote EJB interfaces and homes must always be bound into the classic globally scoped WebSphere JNDI namespace; they can be accessed from anywhere, including other server processes and other remote clients. Local interfaces and no-interface views cannot be bound into the classic globally scoped JNDI namespace, nor can remote interfaces be bound into the JVM-scoped classic ejblocal: namespace.

The classic ejblocal: and classic globally scoped JNDI namespaces are separate and distinct. For example, an EJB local interface or no-interface view bound at "ejblocal:AccountHome" is a not the same as a remote interface bound at "AccountHome" in the classic globally scoped namespace. This behavior helps maintain the distinction between the local and remote interface references. Having a JVM-scoped local namespace also makes it possible for the applications to directly look up or reference local EJB interfaces and no-interface views from anywhere in the JVM server process, including across Java EE application boundaries.


Default classic JNDI bindings for EJB business interfaces in the EJB 3.x container based on Application, Module, and Component names

The EJB container assigns default classic JNDI bindings for EJB 3.x business interfaces based on application name, module name, and component name, so it is important to understand how these names are defined. Each of these names is a character string.

Java EE applications are packaged in a standardized format called an Enterprise Application Archive (EAR) file. The EAR is a packed file format like 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.

Because 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 used in classic bindings

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

The Java EE 6 specification provides for EJB JNDI lookup names of the general form, java:global[/appName]/moduleName/beanName. The appName component of the lookup name is shown as optional because it does not apply to beans deployed in stand-alone modules. Only beans packaged in .ear files contain the appName component in the java:global lookup name. The rules that determine the value for appName are different from the rules described previously for application names. The appName value in the java:global lookup name template shown previously is defined by the following, in order of priority:

The value for appName is also the string value bound under the name, java:app/AppName, in accordance with the Java EE 6 specification.


Module name used in classic bindings

The name of a module is defined as the Uniform Resource Identifier (URI) of the module file, relative to the root of the EAR file in which it resides. Stated another way, the module name is the file name of the module relative to the root of the EAR file, including any subdirectories in which the module file is nested. This naming convention is still true even when a logical module name is explicitly specified using the module-name element in the deployment descriptor.

In the following example, the "CustomerServiceApp" application contains three modules whose names are AccountProcessing.jar, Utility/FinanceUtils.jar, and 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

The Java EE 6 specification provides for EJB JNDI lookup names of the general form, java:global[/appName]/moduleName/beanName. The appName component of the lookup name is shown as optional because it does not apply to beans deployed in stand-alone modules. Only beans packaged in .ear files contain the appName component in the java:global lookup name. Another JNDI lookup name variant that includes the module name is java:app/moduleName/beanName. The value for moduleName is not the module URI. The moduleName value in the java:global and java:app lookup name templates is defined by the following, in order of priority:

The value for moduleName is also the string value bound under the name, java:module/moduleName, in accordance with the Java EE 6 specification. This also applies to client modules. For client modules, the <module-name> parameter is located in the application-client.xml deployment descriptor file.


EJB component name used in classic bindings

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


Bindings

Review the following bindings supported by EJB 3.x modules:


Default classic bindings for EJB business interfaces, homes, and no-interface views

We do not have to explicitly define JNDI binding names for each of the interfaces or EJB homes within an EJB 3.x module or no-interface views within an EJB 3.1 module. If we do not explicitly assign bindings, the EJB container of the product assigns default classic bindings using the rules outlined here. This is different from the EJB support in the product prior to the EJB 3.0 specification being supported.

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

For example, the short and long default classic bindings for an interface or no-interface view might be com.mycompany.AccountService and AccountApp/module1.jar/ServiceBean#com.mycompany.AccountService, respectively.

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

As mentioned earlier in the section on the classic JVM-scoped local namespace and the classic globally scoped JNDI namespace, all local interfaces, homes, and no-interface views must be bound into the classic ejblocal: namespace, which is accessible only within the same server process (JVM), while remote interfaces and homes must be bound into the classic globally scoped namespace, which is accessible from anywhere in the WebSphere product cell. As we 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 application server naming context. However, the application server 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" subcontext rather than placing them directly in the server root context. It is like why we 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 the EJB-related bindings under an ejb context, there are other considerations including the following situations:

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


Default classic binding pattern

The patterns for each type of classic 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 AccountApp/module1.jar/ServiceBean.

Binding patterns Description
ejblocal:<package.qualified.interface> Short form local interfaces, homes, and no-interface views
<package.qualified.interface> Short form remote interfaces and homes
ejblocal:<component-id>#<package.qualified.interface> Long form local interfaces, homes, and no-interface views
ejb/<component-id>#<package.qualified.interface> Long form remote interfaces and homes

The component-id default pattern is <application-name>/<module-jar-name>/<ejb-name> unless it is overridden in the EJB module binding file using the component-id attribute as described in the next section, "Conflicts in short default binding names when multiple enterprise beans implement the same interface". The <module-jar-name> variable, when not overridden by the EJB module binding file, is the name of the physical module file within the EAR including the extension, for example, .jar, .ear, .war, as described in the previous "Module name" section, even if a logical module name is specified in the deployment descriptor.

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

When more than one enterprise bean running in the application server implements a given interface or no-interface view, the short default classic binding name becomes ambiguous because the short name might refer to any of the Enterprise JavaBeans that implement this interface or no-interface view. To avoid this situation, we must either explicitly define a binding for each Enterprise JavaBeans that implements the given interface or no-interface view as described in the next section, or disable short default classic bindings for applications containing these Enterprise JavaBeans by defining a WebSphere product JVM custom property, com.ibm.websphere.ejbcontainer.disableShortDefaultBindings. For more information about defining the JVM custom property, read about Java Virtual machine custom properties.

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 classic bindings for all applications in the server, or to a colon-delimited sequence of the Java EE application names for which we want to disable short default classic bindings, for example, PayablesApp:InventoryApp:AccountServicesApp.

Effect of explicit assignment on default classic bindings

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

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


java:[scope] namespaces

The java:global, java:app, and java:module namespaces are introduced by the Java EE 6 specification. They provide a mechanism for binding and looking up resources that are portable across application servers.

The server always creates a default long-form binding for each EJB interface, including the no-interface view, and places them into the java:global, java:app, and java:module namespaces. A short-form binding is also created and placed into the java:global, java:app, and java:module namespaces, if the bean exposes only one interface, including the no-interface view. The default bindings are only created for session beans. They are not created for entity beans or message driven beans.

The long-form and short-form bindings both contain the application name, the module name, and the bean component name. The application name is defaulted to the base name of the .ear file, without the extension. The application name can be overridden using the application-name element in the application.xml file. The module name is defaulted to the path name of the module, with the extension removed and any directory names included. The module name can be overridden using the module-name element in the ejb-jar.xml or web.xmlfiles. The bean component name defaults to the unqualified name of the bean class. The bean component name can be overridden using the name attribute on the EJB component defining annotation, or the ejb-name element in the ejb-jar.xml file.

The long-form binding pattern is java:global/<applicationName>/<moduleName>/<bean component name>!<fully qualified interface name>.

The short-form binding pattern is java:global/<applicationName>/<moduleName>/<bean component name>.

For example, the bean component MyBeanComponent exposes just the one com.foo.MyBeanComponentLocalInterface interface, and is packaged in the myModule.jar module in the myApp.ear file. As a result, the following bindings are created in the java:[scope] namespaces:

The MyBeanComponent bean can be obtained from the java:[scope] namespaces using one of the following techniques:

In addition to the default bindings created by the application server, we can define references in the java:global, java:app, and java:module namespaces. References defined in the java:global, java:app, and java:module namespaces do not go into the component namespace. References defined in the java:global, java:app, or java:module namespaces must be looked up or injected from those namespaces. They cannot be looked up or injected from the component namespace.

A bean component can use the java:module namespace to declare a reference that is usable by a component packaged in the same module. It can use the java:app namespace to declare a reference that is usable by a component packaged in a different module within the same application. It can use the java:global namespace to declare a reference that is usable by a component packaged in a different application.

References with identical names in the java:global, java:app, or java:module namespaces might conflict with each other, just as references with identical names in the component namespace might conflict. A reference scoped to the java:app namespace for one application does not conflict with an identically named reference scoped to the java:app namespace for a different application. Likewise, a reference scoped to the java:module namespace for one module does not conflict with an identically named reference scoped to the java:module namespace for a different module.

A reference can be declared in the java:global namespace using annotations; for example: 

@EJB(name="java:global/env/myBean")

A reference can be declared in the ejb-jar.xml file; for example: 

<resource-ref>
    <res-ref-name>java:global/env/myDataSource</res-ref-name>
    ....
</resource-ref>

For additional documentation on the java:[scope] namespaces, see section 5.2.2 of the Java EE 6 specification and section 4.4 of the Enterprise JavaBeans 3.1 specification.


User-defined bindings for EJB business interfaces, homes, and no-interface views

For cases where we want to manually assign binding locations rather than using the product default bindings, we can use the EJB module binding file to assign our own binding locations to specific interfaces, homes, and no-interface views. 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 using all default bindings and completely specifying the binding name for each interface or no-interface view.

To specify user-defined bindings information for EJB 3.x modules, place the file ibm-ejb-jar-bnd.xml, in the META-INF directory for the EJB JAR file. The suffix on this file is XML. Also, when defining a classic binding for a local interface or no-interface view, we must preface the name with the string "ejblocal:" so it is bound into the classic JVM-scoped ejblocal: namespace.

The ibm-ejb-jar-bnd.xml file is used for EJB 3.0 and later modules that run on the product, 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 the ibm-ejb-jar.bnd.xml file is different from the XMI file format for the following reasons:

The following table lists the ibm-ejb-jar-bnd.xml elements and attributes used to assign bindings to EJB interfaces and homes for EJB 3.x modules and no-interface views for EJB 3.1 modules.

Element or attribute How used Example Comments
<session> Declares a group of binding assignments for a session bean. <session name="AccountServiceBean"/> Requires name attribute and at least one of the following attributes: 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 name value is the name declared in the <ejb-name> element of an ejb-jar.xml deployment descriptor file, the name attribute of a @Stateful, @Stateless, @Singleton, 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 classic 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 previous example results in the bean whose ejb-name is AccountServiceBean, having its long-form default classic local interfaces bound at ejblocal:Department549/AccountProcessor#<package.qualified.interface> Its long-form default classic remote interfaces are bound at ejb/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 might have default classic bindings performed using the user-specified component ID value. Interfaces 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 a simple-binding-name is typically not useful.

simple-binding-name A simple mechanism for assigning interface bindings for Enterprise JavaBeans that:

  • Implement a single EJB 3.x business interface
  • Implement a pre-EJB 3.0 style component interface (local, remote or both types) with a companion EJB home.

The value of the attribute is used as the binding location of the enterprise bean business interface, or the binding location of the Enterprise JavaBeans local, remote homes, or both. The binding is placed in the classic ejblocal: namespace if the interface or home is local, and placed in the root context of the application server of the classic 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 classic local JVM-scoped EJB namespace, and its remote business interface or home (if any) bound at ejb/AccountService in the root context of the application server of the classic globally scoped JNDI namespace.

Important: Important: 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, must 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, home, or both on the enterprise bean. This condition can be avoided, however, using the <interface> element to define a binding for each of the business interfaces instead of using simple-binding-name.

Important: Important: 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 classic bindings, whereas with simple-binding-name it occurs only on error conditions, where disambiguation is necessary. Do not depend on the binding name created through disambiguation, since whether that effect occurs might change if the bean is changed to implement more or fewer interfaces.

local-home-binding-name Attribute to specify the binding location of the local home of an enterprise bean. 
<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 classic JVM-scoped namespace, the value must begin with the ejblocal: prefix.
remote-home-binding-name Attribute to specify the binding location of the remote home of an enterprise bean. 
<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 classic ejblocal: prefix, since remote homes cannot be bound into the classic ejblocal: namespace.
<interface> A subelement of the <session> element that assigns a binding to a specific EJB business interface or no-interface view. 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 or no-interface view class to be bound. 
<interface class="com.ejbs.InventoryService" 
binding-name="ejb/Inventory"/>
(declared as a subelement inside a <session> element) 		Not to be used in combination with the simple-binding-name attribute. Since local interfaces and no-interface views must always be bound into the classic JVM-scoped namespace, the binding-name value must begin with the ejblocal: prefix when this element is applied to a local interface or no-interface view.
binding-name Attribute to specify the binding location of a business interface bound with the <interface> element. 
<interface class="com.ejbs.InventoryService" 
binding-name="ejb/Inventory"/>
(declared as a subelement 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 classic 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 example is a basic ibm-ejb-jar-bnd.xml file containing only the elements and attributes that assign binding names to EJB interfaces and no-interface views. 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 has the following results:

All other business interfaces, homes, and no-interface views on this bean, if present, are assigned default classic bindings. The com.ejbs.BankAccountService interface is assumed to be local since it was designated for the ejblocal: namespace in this example; an error occurs if the interface is 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 examples of assigning user-defined binding names for business interfaces, homes, and no-interface views. This section covers resolving linkage targets for references, injection directives, and message-driven bean destinations.

Element or attribute How used Example Comments
<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 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 classic JVM-scoped ejblocal:, or classic 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> subelement.
<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="EventProcessingDestination"
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.
<env-entry> Overrides an environment entry with the specified value represented in string format or object which can be accessed with a JNDI lookup on the specified lookup name applied to the default initial context. 
<env-entry name="java:module/env/taxYear" value="2010"/>
<env-entry name="java:module/env/taxYear" 
binding-name="cell/persistent/MyApp/MyModule/taxYear"/
Requires the name attribute and either the value or the binding-name attribute, but not both.
<data-source> Overrides a data source definition, which is declared through the @DataSourceDefinition annotation or through the data-source element in the application, or a module deployment descriptor, with a managed resource. 
<data-source name="java:module/env/myDS" 
binding-name="jdbc/DB2DS"/>
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 classic ejblocal: or classic globally scoped JNDI namespace, or java:global 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"/>

value Attribute that specifies the value to use for an env-entry binding. 
<env-entry name="java:module/env/taxYear" value="2010"/>

activation-spec-binding-name Attribute that identifies the JNDI location of the activation specification 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 specification 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 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 defined 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 defined to WAS.
authentication -alias Optional subelement 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 defined to WAS.
custom-login-configuration Optional subelement 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 defined to WAS.

Binding file Example 2

The following example 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 has the following results:

  1. The business interface, home, and no-interface view 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 root JNDI context of the application server. The EJB reference can also be 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 WAS, 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 or no-interface view, 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 in 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 might thus be bound at ejb/session/S05Inventory in the root JNDI context of the server in the classic globally-scoped namespace. Any other business interfaces implemented by this bean are assigned default classic 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 connects to this resource using a custom login configuration that includes two name-value pairs.

Bindings file Example 3

This example later in this section demonstrates how to define and resolve EJB reference bindings to perform JNDI lookups across application server instances within the same WAS cell. It uses two EJB beans: a called bean that defines an explicit binding using the simple-binding-name attribute, and a calling bean that performs an @EJB injection and uses the ejb-ref element within its associated binding file to resolve the reference so it points at the called bean, that resides in a different application server process.

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>
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> subelement. 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 classic globally scoped JNDI name of cell/nodes/S35NLA1/servers/S35serverA1/ejb/session/FacadeBean. This classic 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. We 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, as if it were the name of the reference declared in an XML deployment descriptor.


Default resolution of EJB references and EJB injections: The EJBLink and AutoLink features

The EJBLink and AutoLink features are two different mechanisms that resolve references to EJB components that are packaged in the same application and application server process as the referring component. Both EJBLink and AutoLink remove the need to explicitly resolve the EJB reference with binding information. The EJBLink feature is defined by the EJB specification, while the AutoLink feature is a WAS extension.

The EJBLink and AutoLink features use different search criteria to locate the targeted bean component. EJBLink searches for the targeted bean component using the explicitly specified bean name. AutoLink searches for the targeted bean component using the interface that the bean implements. If no explicit bindings are provided, but a bean name is provided, then the EJBLink feature is used. If no explicit bindings are provided, and no bean name is provided, then the AutoLink feature is used. The EJBLink and AutoLink features are never used together as part of the same search process.

Except for the search criteria, the EJBLink and AutoLink features are similar. Both features search a specific module first, and then if needed fall back to searching the other modules in the same application and application server process. Both features require that the search criteria resolve to exactly one bean component, and consider it an error condition when the search criteria resolves to multiple bean components. An error condition exists because the application server does not know that which of the multiple bean components must be used. In this case, the exception com.ibm.websphere.ejbcontainer.AmbiguousEJBReferenceException occurs. This exception is thrown at run time when the referencing component attempts to find the targeted bean component.

The EJBLink feature supports three different formats.

We can optionally specify the logical name of the module using the module-name element in the EJB deployment descriptor for an ejb-jar module, or we can use the module-name element in the web deployment descriptor file for a WAR module containing EJB content. For a WAR module that contains EJB content, the module-name element specified in the EJB deployment descriptor is ignored, and the module-name element specified in the web deployment descriptor is processed. When no module-name value is specified in the deployment descriptor, a default logical name is assigned to the module. The default logical module name is the base name of the module file, minus the extension. For example, the module file, MyModule.jar, has the default logical module name yModule.

Specify the name of the physical module file is still supported even when the module has a logical name. Specifying the logical name of the module is still supported even when no logical module name is configured in the deployment descriptor. In this case, the base name of the module is used as the logical name of the module.

The embeddable EJB container supports all EJBLink formats. To support the physical module file format, the embeddable EJB container does not allow us to start multiple modules with the same base name.

AutoLink is a value-add feature of WAS that eliminates the need to explicitly resolve EJB reference targets in certain usage scenarios. In WAS V8, AutoLink is implemented within the boundaries of each WAS process. The AutoLink algorithm works as follows.

When the EJB container in the product 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 binding file of the module. 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 or no-interface view we have defined within the reference.

If it finds exactly one enterprise bean within the module that implements the interface or no-interface view, 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 searches other modules within that application assigned to the same application server as the referring module. Again, if the container finds exactly one enterprise bean that implements the target interface or no-interface view, within the other modules of the application 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 application server on which the referring module is assigned. References to enterprise beans in a different application, enterprise beans in a module assigned to a different application server, or to enterprise beans residing in a module that has been assigned to a WebSphere Application Server cluster, must be explicitly resolved using reference target bindings in the ibm-ejb-jar-bnd.xml file of the EJB module, or the ibm-web-bnd.xmi file of the web module.

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.


Resolution of EJB and resource references and injections: The lookup feature

The lookup feature is defined by the EJB 3.1 specification as a mechanism that resolves references to EJBs or resources, by an explicit JNDI name. We can specify the lookup attribute on the javax.ejb.EJB annotation or on the javax.annotation.Resource annotation. The corresponding XML attribute in the ejb-jar.xml file is <lookup-name>, on one of the following elements: <ejb-ref>, <ejb-local-ref>, <env-entry>, <resource-ref>, <resource-env-ref>, or <message-destination-ref>. lookup or <lookup-name> is a JNDI name relative to the java:comp/env naming context.

On an EJB reference, lookup or <lookup-name> must not be specified with beanName or with <ejb-link>. The administrative console displays lookup-name and ejb-link as read-only. However, if a JNDI name is specified in the application installation step "Map EJB references to beans", it overrides the lookup-name or ejb-link value.


Overriding environment entries defined in applications

Applications might define environment entries with values that are suitable for unit testing, but not for integration testing or production use. To override an environment entry value, we can add the following element to the corresponding binding file: 

<env-entry name="name" value="value"/>
where name is the env-entry name as it is defined in the application and value is the value assigned to the env-entry represented in string format. The string for value is parsed according to the type of the environment entry as if the value had been specified in the deployment descriptor using env-entry-value. For example, 
<env-entry name="java:module/env/taxYear" value="2010"/>
associates the env-entry named "java:module/env/taxYear" with a value of "2010".

Alternatively, we can configure an env-entry as a reference to another object accessible through JNDI. The object returned from the JNDI lookup is used as the env-entry value. The element for that option has the following form: 

<env-entry name="name" binding-name="lookupName"/>
where name is the env-entry name as it is defined in the application and lookupName is a JNDI name that resolves when applied to a lookup on the default initial context. For example, 
<env-entry name="java:module/env/taxYear" binding-name="cell/persistent/MyApp/MyModule/taxYear"/>
associates the env-entry named "java:module/env/taxYear" with a value returned from a default initial context lookup operation on "cell/persistent/MyApp/MyModule/taxYear". We are responsible for creating the JNDI object binding. The class of the bound object must be assignable to the object type of the associated env-entry.

Environment entries can be defined at the application level and in EJB, web, and client modules. Those levels correspond to the binding files application-bnd.xml, ejb-jar-bnd.xml, web-app-bnd.xml, and application-client-bnd.xml.


Overriding data source definitions

With Java EE 6, we can develop applications that define data sources using the @DataSourceDefinition annotation or <data-source> deployment descriptor entry.

The applications should look up resource references as opposed to looking up data source definitions directly. If we are installing an existing application containing direct lookups to a data source definition, and we want it to use another data source definition, we can override the data source definition with a binding that resolves to a managed resource that we create. Create the binding by adding the following element to your binding file: 

<data-source name="name" binding-name="lookupName"/>
where name is the env-entry name as it is defined in the application and lookupName is a JNDI name that resolves when applied to a lookup on the default initial context. For example, 
<data-source name="java:module/env/myDS" binding-name="jdbc/DB2DS"/>
causes lookups on "java:module/env/myDS" to resolve to the data source bound with the name, "jdbc/DB2DS", relative to the default initial context. The data source bound under jdbc/DB2DS can be created, for example, through the administrative console.

Data sources can be defined at the application level and in EJB, web, and client modules. Those levels correspond to the binding files application-bnd.xml, ejb-jar-bnd.xml, web-app-bnd.xml, and application-client-bnd.xml.


Naming considerations in clustered and cross-server environments

The classic 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 application server root context: 
ejb/Department549/AccountProcessors/CheckingAccountReconciler

If the EJB implementing this interface is assigned to an application server 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 application server 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 application server root context: 
ejb/Department549/AccountProcessors/CheckingAccountReconciler

If the enterprise bean that is implementing this interface is assigned to an application server named Server47A1 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

For cases where we want to specify values for WAS EJB Extension settings, we can use an EJB module extension file to assign these settings to specific EJB types within that module. You specify extension settings information for EJB 3.x modules by placing one, or both, of two files into the META-INF directory for the EJB JAR file, depending on the type of extension being defined. The names of the two files are ibm-ejb-jar-ext.xml and ibm-ejb-jar-ext-pme.xml.

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.x modules running in WAS, whereas the ibm-ejb-jar-ext.xmi and ibm-ejb-jar-ext-pme.xmi files are used for pre-3.0 EJB modules. WAS v8.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 structure of the file 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 might 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 outlines extension elements and attributes that must be placed in the META-INF/ibm-ejb-jar-ext.xml file. The subsequent section lists elements and attributes that appear in a separate file, META-INF/ibm-ejb-jar-ext-pme.xml.

Element or Attribute Description Example Usage notes
<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 subelement.
<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 subelement.

Element or Attribute Description Example Usage notes
<time-out> Subelement to the <session> element that optionally declares the number of seconds between method invocations after which a stateful session bean might no longer be available. 
<session
 name="ShoppingCartBean">
 <time-out value="600"/>
</session>
Requires value attribute, a positive integer.

Only applicable to stateful session beans; must not be used on stateless beans.

Attribute default: 300 (5 minutes)

<bean-cache> Subelement of <session> element used to declare bean activation/passivation settings for stateful session beans. 
<session
 name="ShoppingCartBean">
 <bean-cache
  activation-policy="TRANSACTION"/>
</session>
To have any effect, also include the activation-policy attribute.
activation-policy Attribute of <bean-cache> element that declares the conditions under which the bean instance might be activated and passivated. Applicable to stateful session beans. Allowable values and their meanings are:

  • TRANSACTION: Indicates that the bean activates at the start of a transaction and passivates (and is removed from the active EJB instance cache) at the end of the transaction.
  • ONCE: Indicates that the bean activates when it is first accessed in the server process, and passivates (and is removed from the active EJB instance cache) at the discretion of the container, for example, when the cache becomes full.
  • ACTIVITY_SESSION: Indicates that the bean activates and passivates as follows:

    1. On an ActivitySession boundary, if an ActivitySession context is present on activation

    2. On a transaction boundary, if a transaction context (but no ActivitySession context) is present on activation, or
    3. on an invocation boundary. 

<session
 name="ShoppingCartBean">
 <bean-cache
  activation-policy="ONCE"/>
</session>
Attribute default: ONCE for stateful session beans.

Element or Attribute Description Example Usage notes
<global-transaction> Subelement 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 might declare whether this EJB type propagates global transaction context received through web service atomic transactions, across the heterogeneous web service environment. 
<session
 name="AccountServiceBean"
 <global-transaction
  <global-transaction
 transaction-time-out="180" 
  send-wsat-context="FALSE"/>
</session>
Requires at least one of transaction-time-out or send-wsat-context attributes.

Attribute default: Server transaction timeout setting for transaction-time-out; FALSE for send-wsat-context

<local-transaction> Subelement to the <session> and <message-driven> elements that can be used to declare settings related to local transactions. Supported attributes are boundary, resolver, and unresolved-action; these attributes configure, for the component, the behavior of the local transaction containment (LTC) environment of the container 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:

  • BEAN_METHOD: This is the default value. If we select this option, RMLTs must be resolved within the same bean method in which they were started.
  • ACTIVITY_SESSION: RMLTs must be resolved within the scope of any ActivitySession in which they were started or, if no ActivitySession context is present, within the same bean method in which they were started.

Resolver

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

  • APPLICATION: This is the default value. The application is responsible for starting RMLTs and for completing them within the local transaction containment (LTC) boundary. Any RMLTs that are not completed by the end of the LTC boundary are cleaned up by the container according to the value of the Unresolved action attribute.
  • CONTAINER_AT_BOUNDARY: The container is responsible for starting RMLTs and for completing them within the LTC boundary. The container begins an RMLT when a connection is first used within the LTC scope, and completes it automatically at the end of the LTC scope. If Boundary is set to ActivitySession, the RMLTs are enlisted as ActivitySession resources and directed to complete by the ActivitySession. If Boundary is set to BeanMethod, the RMLTs are committed at the end of the method by the container.

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:

  • ROLLBACK: This is the default value. At end of the LTC boundary scope, the container instructs all unresolved RMLTs to roll back.
  • COMMIT: At the end of the LTC boundary scope, the container instructs all unresolved RMLTs to commit. The container instructs the RMLTs to commit only in the absence of an unhandled exception. If the application method running in the local transaction context ends with an exception, any unresolved RMLTs are rolled back by the container. This is the same behavior as for global transactions. 

<session
 name>="AccountServiceBean">
 <local-transaction
  boundary="BEAN_METHOD" 
  resolver="APPLICATION" 
  unresolved-action="ROLLBACK"/>
</session>
Requires at least one of boundary, resolver, or unresolved-action attributes.

Attribute default: 

boundary="BEAN_METHOD";
resolver="APPLICATION";
unresolved-action=
"ROLLBACK"

Element or Attribute Description Example Usage notes
<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 might apply. Supported attributes are type, name, and params. Each attribute is described as follows:

type

  • UNSPECIFIED: The setting applies to all methods matching the name and params attributes, regardless of interface type.
  • REMOTE: The setting applies to remote business interface and remote component interface methods matching the name and params attributes.
  • LOCAL: The setting applies to local business interface, local component interface methods, and no-interface views that match the name attribute, params attribute, or both.
  • HOME: The setting applies to remote home interface methods matching the name and params attributes matching the name and params attributes.
  • LOCAL_HOME: The setting applies to local home interface methods matching the name and params attributes.
  • SERVICE_ENDPOINT: The setting applies to methods on the JAX-RPC service endpoint interface matching the name and params attributes.

name

The name of the method to which the setting is 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 is 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 type of the array element 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.xyz.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 use when invoking another method. The identity can be set to use the identity of the caller (mode = CALLER_IDENTITY), the identity of the EJB server (mode = SYSTEM_IDENTITY), or the identity of a specific security role (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>
Requires mode attribute and <method> subelement. If the mode is SPECIFIED_IDENTITY, the <specified-identity subelement is also required.
<start-at-app-start> Subelement to the <session> and <message-driven> elements that can be used to inform the EJB container that specified EJB type might 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"/>
</session>
Requires value attribute.

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

<resource-ref> Subelement to the <session> and <message-driven> elements, that might 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 attributes are defined as follows:

isolation-level

  • TRANSACTION_REPEATABLE_READ: This isolation level prohibits dirty reads and nonrepeatable reads, but it allows phantom reads.
  • TRANSACTION_READ_COMMITTED: This isolation level prohibits dirty reads, but allows nonrepeatable reads and phantom reads.
  • TRANSACTION_READ_UNCOMMITTED: This isolation level allows reading uncommitted changes (data changed by a different transaction that is still in progress). It also allows dirty reads, nonrepeatable reads, and phantom reads.
  • TRANSACTION_SERIALIZABLE: This isolation level prohibits the following types of reads:

    1. Dirty reads, in which a transaction reads a database row containing uncommitted changes from a second transaction,
    2. Nonrepeatable reads, in which one transaction reads a row, a second transaction changes the same row, and the first transaction rereads the row and gets a different value, and
    3. Phantom reads, in which one transaction reads all rows that satisfy an SQL WHERE condition, a second transaction inserts a row that also satisfies the WHERE condition, and the first transaction applies the same WHERE condition and gets the row inserted by the second transaction.

  • TRANSACTION_NONE: This isolation level indicates that transactions are not supported on this type of resource. 

<session
 name="AccountServiceBean">
 <resource-ref
  name="jdbc/Default" 
  isolation-level="TRANSACTION_NONE">
</session>
Requires name attribute. To have any effect, also include the isolation-level attribute.

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

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

Element or Attribute Description Example Usage notes
<internationalization> Element that might be used to declare the locale that might be used by the EJB type (locale of the caller or locale of the server). 
<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 about this extension, see Container internationalization attributes: WAS.

Due to the complexity of this function, we might want to use a tool designed for WAS such as Rational Application Developer to produce the wanted extension file stanzas, then modify the XML file as wanted.

<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 about this extension, see Setting EJB module ActivitySession deployment attributes.

Due to the complexity of this function, we might want to use a tool designed for WAS such as Rational Application Developer

<app-profiles> Element that optionally declares application profile settings for one or more EJB files. 
<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, we might want to use a tool designed for WAS such as Rational Application Developer to produce the wanted extension file stanzas, then modify the XML file as wanted.


Legacy (XMI) bindings

Existing modules and applications can continue to use the legacy binding support provided in the product, 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.x 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 the <WAS_HOME>/properties/schemas directory. This form of bindings specification can only be used for modules containing either no XML deployment descriptor or an EJB 3.x 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 beans:

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:

  • EJB modules
  • Ways to update enterprise application files
  • Application bindings
  • Exporting enterprise application files
  • Exporting enterprise applications
  • Developing enterprise beans
  • Task overview: Using enterprise beans in applications
  • 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