EJB 3.0 and EJB 3.1 application bindings overview
Prior to starting an application that is installed on an application server, all Enterprise JavaBeans (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 Version 8.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. You 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, you 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.
You 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 you 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 theWebSphere Application Server in Version 8. They are not a replacement for the classic namespaces. Rather, they are added in addition to the classic namespaces.
Classic namespace details
- Java virtual machine (JVM)-scoped, ejblocal: namespace
- Global JNDI namespace
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 your local and remote interface references.
Having a JVM-scoped local namespace also makes it possible for your applications to directly look up
or reference local EJB interfaces and no-interface views from anywhere in the JVM server process,
including across Java Platform, Enterprise Edition (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 Application Archive (JAR) files for EJB modules, Java EE application client modules and utility class modules
- Web Application Archive (WAR) files for web modules
- Other technology-specific modules such as Resource Application Archive (RAR) files and other types of modules
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 value of the application name specified to the product administrative console, or the appname parameter supplied to the wsadmin command-line scripting tool, during installation of the application into the product.
- The value of the <display-name> parameter within the META-INF/application.xml deployment descriptor for the application.
- The EAR file name, excluding the .ear file suffix. For example, an
application EAR file named CustomerServiceApp.ear would have an application
name of
CustomerServiceApp
in this case.
- The value of the <application-name> parameter within the application.xml deployment descriptor for the application.
- The EAR file name, excluding the .ear file suffix. For example, an
application EAR file named CustomerServiceApp.ear has an application name of
CustomerServiceApp
. If the application is a stand-alone module, the java:global lookup name does not contain an application component.
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.
CustomerServiceAppapplication 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 value of the <module-name> parameter within the ejb-jar.xml or web.xml deployment descriptor for the module.
- The module URI, excluding its .jar or .war suffix. For
example, a module with a URI of CustomerService.jar or
CustomerService.war has a module name of
CustomerService
.
EJB component name used in classic bindings
- The value of the ejb-name tag associated with the bean in the ejb-jar.xml deployment descriptor, if present.
- The value of the
name
parameter, if present, in the @Stateless or @Stateful annotation associated with the bean. - The name of the bean implementation class, without any package-level qualifier.
Bindings
Review the following bindings that are supported by EJB 3.x modules:
- Default classic bindings for business interfaces, homes, and no-interface views
- Default classic binding pattern
- java:[scope] bindings
- User-defined bindings for EJB business interfaces, homes, and no-interface views
- User-defined bindings for resolving references and injection targets
- Default resolution of EJB references and EJB injections: The AutoLink feature
- Resolution of EJB and resource references and injections: The lookup feature
- Overriding environment entries defined in applications
- Overriding data source definitions
- Naming considerations in clustered environments
- User-defined EJB extension settings
- Legacy (XMI) bindings
- User-specified XML bindings
Default classic bindings for EJB business interfaces, homes, and no-interface views
You 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 you 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. You 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 you can assign any string you want instead. By defining your own string as the component ID, you 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 you to make the default EJB binding names independent of how you 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 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
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 you would use subdirectories on a disk volume
rather than putting all the files in the root directory.
- The short default bindings provide a simple, direct way to access an EJB interface. Placing them directly in the server root context and referring to them by just the interface name or the interface name prepended with ejblocal: was in keeping with that goal of simplicity.
- At the same time, placing the long default bindings in the ejb context, or the ejblocal: context in the case of a local interface, kept those bindings out of the root context of the server and reduced the clutter there enough to allow having the short bindings in the root context.
- It provides a degree of cross-compatibility with other Java EE application servers that use similar naming conventions.
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 that is 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, you 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 you want to disable short default classic bindings, for example, PayablesApp:InventoryApp:AccountServicesApp.
Effect of explicit assignment on default classic bindings
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.xml files. 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>.
- java:global/myApp/myModule/MyBeanComponent!com.foo.MyBeanComponentLocalInterface
- java:global/myApp/myModule/MyBeanComponent
- java:app/myModule/MyBeanComponent!com.foo.MyBeanComponentLocalInterface
- java:app/myModule/MyBeanComponent
- java:module/MyBeanComponent!com.foo.MyBeanComponentLocalInterface
- java:module/MyBeanComponent
- Use the lookup attribute on the @EJB annotation; for example:
@EJB(lookup="java:global/myApp/myModule/MyBeanComponent")
- Use the lookup-name element in ejb-jar.xml; for example:
<lookup-name>java:global/myApp/myModule/MyBeanComponent!com.ibm.MyBeanComponentLocalInterfaces</lookup-name>
- Complete a lookup on the InitialContext object; for example:
initialContext.lookup("java:global/myApp/myModule/MyBeanComponent!com.foo.MyBeanComponentLocalInterfaces")
In addition to the default bindings created by the application server, you 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.
@EJB(name="java:global/env/myBean")
<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 you want to manually assign binding locations rather than using the product default bindings, you can use the EJB module binding file to assign your own binding locations to specific interfaces, homes, and no-interface views. You 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 Java archive (JAR) file. The suffix on this file is XML. Also, when defining a classic binding
for a local interface or no-interface view, you must preface the name with the string
ejblocal:
so it is bound into the classic JVM-scoped ejblocal: namespace.
- Bindings and extensions that are declared in the XMI file format depend on the presence of a corresponding ejb-jar.xml deployment descriptor file that explicitly refers to unique ID numbers that are 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.
- The XMI file format was designed to be machine-edited only by the product development tools and system management functions; it was effectively part of the internal implementation of the product and the file structure was never documented externally. This made it impossible for developers to manually edit binding files, or create them as part of a WebSphere independent build process, in a supported way.
- Rather than referring to encoded ID numbers in the ejb-jar.xml deployment descriptor, the XML-based binding file refers to an EJB component by its EJB name. Each EJB component in a module has a unique EJB name, either by default or through explicit assignment by the developer. Therefore, this behavior provides an unambiguous way to target bindings and extensions.
- The new binding files are XML-based, and an XML Schema Definition (XSD) file is provided to externally document the structure. These .xsd files can 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 the binding and extension files independently of the application server infrastructure.
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>. |
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 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 a simple-binding-name is typically not useful. |
simple-binding-name | A simple mechanism for assigning interface bindings for Enterprise JavaBeans that:
|
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 ejbsubcontext 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, by 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.
|
local-home-binding-name | Attribute to specify the binding location of the local home of an enterprise bean. |
|
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. |
|
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. |
(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. | (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
<?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: - 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 and no-interface views on that bean. Local interfaces and no-interface views 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>
- The session bean with ejb-name S02 is assumed to have a single EJB 3.x
business interface or EJB 3.1 no-interface view. 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 the home or homes of the component interface 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 interfaces 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 interfaces.
- The EJB 3.x business interface or EJB 3.1 no-interface view, com.ejbs.BankAccountService, on the session bean with ejb-name S03 is bound at ejblocal:session/BAS.
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. |
|
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 classic JVM-scoped ejblocal:, or classic globally scoped JNDI namespace. |
|
Requires the name and binding-name attributes. |
<message-driven> | Declares a group of binding assignments for a message-driven bean. |
|
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. |
|
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. |
|
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. |
|
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. |
|
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. |
|
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. |
|
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 sourceside of a reference/target linkage, such as in ejb-ref, resource-ref, resource-env-ref, message-destination, or message-destination-ref. |
|
|
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 targetside of a reference/target linkage, such as in ejb-ref, resource-ref, resource-env-ref, message-destination, or message-destination-ref. |
|
|
value | Attribute that specifies the value to use for an env-entry binding. |
|
|
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. |
|
This name must match the name of a JCA 1.5 activation specification that you define to WebSphere Application Server. |
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. |
|
This name must match the name of a J2C authorization alias that you define to WebSphere Application Server |
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. |
|
This name must match the name of a JMS queue or topic that you define to WebSphere Application Server. |
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. |
|
This name must match the name of a JAAS authentication alias that you define to WebSphere Application Server. |
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). |
|
This name must match the name of a JAAS login configuration that you define to WebSphere Application Server. |
Binding file Example 2
<?xml version="1.0" encoding="UTF-8"?>
<ejb-jar-bnd xmlns="http://websphere.ibm.com/xml/ns/javaee" "xmlns:xsi"=
"http://www.w3.org/2001/XMLSchema-instance"
xsi:schemaLocation="http://websphere.ibm.com/xml/ns/javaee"
"http://websphere.ibm.com/xml/ns/javaee/ibm-ejb-jar-bnd_1_0.xsd version" "1.0">
<session name="S01" component-id="Department549/AccountProcessors"/>
<session name="S02" simple-binding-name="ejb/session/S02"/>
<session name="S03">
<interface class="com.ejbs.BankAccountService"
binding-name="ejblocal:session/BAS"/>
<ejb-ref name="com.ejbs.BankAccountServiceBean/goodBye"
binding-name="ejb/session/S02"/>
<resource-ref name="com.ejbs.BankAccountServiceBean/dataSource"
binding-name="jdbc/Default"/>
</session>
<message-driven name="MO1">
<jca-adapter activation-spec-binding-name="jms/InternalProviderSpec"
destination-binding-name=jms/"ServiceQueue"/>
</message-driven>
<session name="S04" simple-binding-name="ejb/session/S04">
<resource-ref name="ejbs.S04Bean/dataSource"
binding-name="jdbc/Default">
<authentication-alias name="defaultlogin"/>
</resource-ref>
</session>
<session name="S05">
<interface class="com.ejbs.InventoryService"
binding-name="ejb/session/S05Inventory"/>
<resource-ref name="ejbs.S05Bean/dataSource"
binding-name="jdbc/Default">
<custom-login-configuration name="customLogin">
<property name="loginParm1" value="ABC123"/>
<property name="loginParm2" value="DEF456"/>
</custom-login-configuration>
</resource-ref>
</session>
</ejb-jar-bnd>
This binding has the following results: - The business interface, home, and no-interface view bindings for the session beans named S01, S02, and S03 are unchanged from the previous example.
- 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
.Note: 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
.
- 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
- 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 WebSphere Application Server with the name jms/InternalProviderSpec.
- 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 WebSphere Application Server.
- 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 nameddataSource
) 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 WebSphere Application Server 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="https://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 FacadeBeanimplements 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
nameparameter, 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="
"https://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 S35serverA1on the node named
S35NLA1within the WebSphere Application Server cell of the calling bean. To point to a location within a different WebSphere Application Server 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, 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 WebSphere Application Server 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.
- Specify only the name of the bean component. For example, MyBean.
- Specify the name of the physical module file, including the extension, that contains the targeted bean component, followed by the # character, followed by the name of the bean component. For example, myModule.jar#MyBean
- Specify the logical name of the module that contains the targeted bean component, the slash character (/), followed by the name of the bean component. For example, MyModule/MyBean.
You 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 you can use the module-name element in the web deployment descriptor file for a WAR module that contains 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 MyModule.
Specifying 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 you to start multiple modules with the same base name.
AutoLink is a value-add feature of WebSphere Application Server that eliminates the need to explicitly resolve EJB reference targets in certain usage scenarios. In WebSphere Application Server V8, AutoLink is implemented within the boundaries of each WebSphere Application Server 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 you 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 you 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 that are 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. You 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 that is labeled Map EJB references to beans, it overrides the lookup-name or ejb-link value.
Overriding environment entries defined in applications
<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/taxYearwith a value of
2010.
<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/taxYearwith a value returned from a default initial context lookup operation on
cell/persistent/MyApp/MyModule/taxYear. You 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, you can develop applications that define data sources using the @DataSourceDefinition annotation or <data-source> deployment descriptor entry.
<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/myDSto 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
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
cell/clusters/Cluster47/ejb/Department549/AccountProcessors/CheckingAccountReconciler
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
cell/nodes/S47NLA1/servers/Server47A1/ejb/Department549/AccountProcessors/CheckingAccountReconciler
User-defined EJB extension settings
For cases where you want to specify values for WebSphere Application Server EJB Extension settings, you 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.
- 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.
- 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.
- 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.
- 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 WebSphere Application Server infrastructure, using a generic XML editor or scripting system of their choice.
Extensions defined in META-INF/ibm-ejb-jar-ext.xml
Element or Attribute | Description | Example | Usage notes |
---|---|---|---|
<session> | Declares a group of extension settings for a session bean. |
|
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. |
|
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. |
|
Requires value attribute, a positive integer. Note: 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. |
|
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:
|
|
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. |
|
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:
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:
|
|
Requires at least one of boundary, resolver, or unresolved-action attributes.
Attribute
default:
|
Element or Attribute | Description | Example | Usage notes |
---|---|---|---|
<method> | Sub-element to the <method-session-attribute> and <run-as-mode> elements
that is 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
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 brackets (for example int[][]). |
|
|
<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). |
|
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. |
|
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
|
|
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
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). |
|
For information about this extension, see Container internationalization
attributes: WebSphere Application Server. Due to the complexity of this function, you might want to use a tool designed for WebSphere Application Server 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. |
|
For information about this extension, see Setting EJB module ActivitySession
deployment attributes. Due to the complexity of this function, you might want to use a tool designed for WebSphere Application Server such as Rational Application Developer |
<app-profiles> | Element that optionally declares application profile settings for one or more EJB files. |
|
Due to the complexity of this function, you might want to use a tool designed for WebSphere Application Server 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.
- Session beans using the <session> element.
- Message Driven beans using the <message-driven> element
- id attribute
- name attribute
- simple-binding-name attribute
- component-id attribute
- ejb-ref element
- resource-ref element and its attributes
- resource-env-ref element and its attributes
- message-destination-ref element and its attributes
- env-entry element
- data-source element
- id attribute
- name attribute
- jca-adapter attribute
- ejb-ref element and its attributes
- resource-ref element and its attributes
- resource-env-ref element and its attributes
- message-destination-ref element and its attributes
- env-entry element
- data-source element