Before an application that is installed on an application server can start, all enterprise bean (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.
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. An example referenceable artifact is an EJB defined in an application. An example referenced artifact is an EJB or a resource reference used by the application.
Binding definitions are stored in the ibm-xxx-bnd.xml or ibm-xxx-bnd.xmi files of an application. Version 7.0 or later binding definitions support files with the suffix of XML for EJB 3.x and Web 2.5 and later modules. Modules earlier than Java EE 5 continue to use binding definition files with the suffix of XMI as in previous versions of WebSphere® Application Server. The xxx can be ejb-jar, web, application or application-client.
See the following information about bindings:
Times when bindings can be defined
You can define bindings at the following times:
- During application development
An application developer can create binding definitions in ibm-xxx-bnd.xml files for EJB 3.x and Web 2.5 and later modules and in ibm-xxx-bnd.xmi files for pre-Java EE 5 modules. The application developer can create the files using a tool such as an IBM® Rational® developer tool or, for EJB 3.x or Web 2.5 and later modules, using an XML editor or text editor. The developer then gives an enterprise application (.ear file) complete with bindings to an application assembler or deployer. When assembling the application, the assembler does not modify the bindings. Similarly, when installing the application onto a server supported by WebSphere Application Server, the deployer does not modify or override the bindings or generate default bindings unless changes to the bindings are necessary for successful deployment of the application.
- During application assembly
An application assembler can define bindings in annotations or deployment descriptors of an application. Java EE 5 or later modules contain annotations in the source code. To declare an annotation, an application assembler precedes a keyword with an @ character ("at" sign). Bindings for pre-Java EE 5 modules are specified in the WebSphere Bindings section of a deployment descriptor editor. Modifying the deployment descriptors might change the binding definitions in the ibm-xxx-bnd.xmi files created when developing an application. After defining the bindings, the assembler gives the application to a deployer. When installing the application onto a server supported by WebSphere Application Server, the deployer does not modify or override the bindings or generate default bindings unless changes to the bindings are necessary to deploy the application.
- During application installation
An application deployer or server administrator can modify the bindings when installing the application onto a server supported by WebSphere Application Server using the administrative console. New binding definitions can be specified on the installation wizard pages.
Also, a deployer or administrator can select to generate default bindings during application installation. Selecting Generate default bindings during application installation instructs the product to enter default values for the incomplete bindings in the application. Existing bindings are not changed.Restriction: You cannot define or override bindings during application installation for application clients. You must define bindings for application client modules during assembly and store the bindings in the ibm-application-client-bnd.xmi file.
- During configuration of an installed
After an application is installed onto a server supported by WebSphere Application Server, an application deployer or server administrator can modify the bindings by changing values in administrative console pages such as those accessed from the settings page for the enterprise application.
Before an application can be successfully deployed, bindings must be defined for references to the following artifacts:
- EJB JNDI names
- For each EJB 2.1 or earlier enterprise bean (EJB), you must specify a JNDI name. The name is
used to bind an entry in the global JNDI name space for the EJB home object. An example JNDI name
for a Product EJB in a Store application might be
store/ejb/Product. The binding definition is stored in the
If a deployer chooses to generate default bindings when installing the application, the installation wizard assigns EJB JNDI names having the form prefix/EJB_name to incomplete bindings. The default prefix is ejb, but can be overridden. The EJB_name is as specified in the deployment descriptor
During and after application installation, EJB JNDI names can be specified on the Provide JNDI names for beans page. After installation, click in the administrative console.
You do not need to specify JNDI binding names for each of the EJB 3.x home or business interfaces on your enterprise beans because the EJB container assigns default bindings.
- Data sources for entity beans
- Entity beans such as container-managed persistence (CMP) beans store persistent data in data
stores. With CMP beans, an EJB container manages the persistent state of the beans. You specify
which data store a bean uses by binding an EJB module or an individual enterprise bean to a data
source. Binding an EJB module to a data source causes all entity beans in that module to use the
same data source for persistence.
An example JNDI name for a Store data source in a Store application might be store/jdbc/store. For modules earlier than Java EE 5, the binding definition is stored in IBM binding files such as ibm-ejb-jar-bnd.xmi. A deployer can also specify whether authentication is handled at the container or application level.
WebSphere Application Server Version 8.x supports CMP beans in EJB 2.x or 1.x modules. Version 8.x does not support CMP beans in EJB 3.0 modules.
If a deployer chooses to generate default bindings when installing the application, the installation wizard generates the following for incomplete bindings:
- For EJB 2.x .jar files, connection factory bindings based on the JNDI name and authorization information specified
- For EJB 1.1 .jar files, data source bindings based on the JNDI name, data source user name and password specified
The generated bindings provide default connection factory settings for each EJB 2.x .jar file and default data source settings for each EJB 1.1 .jar file in the application being installed. No bean-level connection factory bindings or data source bindings are generated unless they are specified in the custom strategy rule supplied during default binding generation.
During and after application installation, you can map data sources to 2.x entity beans on the 2.x CMP bean data sources page and on the 2.x entity bean data sources page. After installation, click 2.x CMP bean data sources or 2.x entity bean data sources. You can map data sources to 1.x entity beans on the Map data sources for all 1.x CMP beans page and on the Provide default data source mapping for modules containing 1.x entity beans page. After installation, access console pages like those for 2.x CMP beans, except click links for 1.x CMP beans.in the administrative console, then select
- Backend ID for EJB modules
- If an EJB .jar file that defines CMP beans contains mappings for multiple
backend databases, specify the appropriate backend ID that determines which persister classes are
loaded at run time.
Specify the backend ID during application installation. You cannot select a backend ID after the application is installed onto a server.
To enable backend IDs for individual EJB modules:
- During application installation, select Deploy enterprise beans on the Select installation options page. Selecting Deploy enterprise beans enables you to access the Provide options to perform the EJB Deploy page.
- On the Provide options to perform the EJB Deploy page, set the database type to "" (null).
During application installation, if you select Deploy enterprise beans on the Select installation options page and specify a database type for the EJB deployment tool on the Provide options to perform the EJB Deploy page, previously defined backend IDs for all of the EJB modules are overwritten by the chosen database type.
The default database type is DB2UDB_V81.
The EJB deployment tool does not run during installation of EJB 3.0 or later modules.
For information about backend databases, refer to V8.5.5 documentation about the EJB deployment tool and the ejbdeploy command.
- EJB references
- An enterprise bean (EJB) reference is a logical name used to locate the home interface of an
enterprise bean. EJB references are specified during deployment. At run time, EJB references are
bound to the physical location (global JNDI name) of the enterprise beans in the target operational
environment. EJB references are made available in the
java:comp/env/ejbJava naming subcontext, or in another
java:namespace if the reference name is a
java:globalURL. EJB references with URL names are bound into the corresponding namespace according to the URL.
The product assigns default JNDI values for or automatically resolves incomplete EJB 3.0 reference targets.
For each EJB 2.1 or earlier EJB reference, you must specify a JNDI name. An example JNDI name for a Supplier EJB reference in a Store application might be store/ejb/Supplier. The binding definition is stored in IBM binding files such as ibm-ejb-jar-bnd.xmi. When the referenced EJB is also deployed in the same application server, you can specify a server-scoped JNDI name. But if the referenced EJB is deployed on a different application server or if ejb-ref is defined in an application client module, then you should specify the global cell-scoped JNDI name.
If a deployer chooses to generate default bindings when installing the application, the installation wizard binds EJB references as follows: If an
<ejb-link>is found, it is honored. If the ejb-name of an EJB defined in the application matches the
ejb-refname, then that EJB is chosen. Otherwise, if a unique EJB is found with a matching home (or local home) interface as the referenced bean, the reference is resolved automatically.
During and after application installation, you can specify EJB reference JNDI names on the Map EJB references to beans page. After installation, click in the administrative console.Tip: To enable EJB reference targets to resolve automatically if the references are from EJB 2.1 or earlier modules or from Web 2.3 or earlier modules, select Generate default bindings on the Preparing for application installation page or select Allow EJB reference targets to resolve automatically on the Select installation options, Map EJB references to beans, or EJB references console pages.
- Resource references
- A resource reference is a logical name used to locate an external resource for an application.
Resource references are specified during deployment. At run time, the references are bound to the
physical location (global JNDI name) of the resource in the target operational environment. Resource
references that do not use a URL for the JNDI name are made available as follows:
Table 1. Resource reference subcontexts. JNDI java:comp/env names are used for resource reference subcontexts. Resource reference type Subcontext declared in Java DataBase Connectivity (JDBC) data source java:comp/env/jdbc JMS connection factory java:comp/env/jms JavaMail connection factory java:comp/env/mail Uniform Resource Locator (URL) connection factory java:comp/env/url
Applications alternatively can assign names to resource references that are
java:URLs with prefixes such as
java:global. The URLs map to namespaces other than the component namespace, which contains
java:comp/envname bindings. Resource references with URL names are bound into the corresponding namespace according to the URL.
For each resource reference, you must specify a JNDI name. If a deployer chooses to generate default bindings when installing the application, the installation wizard generates resource reference bindings derived from the
<res-ref-name>tag, assuming that the java:comp/env name is the same as the resource global JNDI name.
During application installation, you can specify resource reference JNDI names on the Map resource references to references page. Specify JNDI names for the resources that represent the logical names defined in resource references. You can optionally specify login configuration name and authentication properties for the resource. After specifying authentication properties, click OK to save the values and return to the mapping step. Each resource reference defined in an application must be bound to a resource defined in your WebSphere Application Server configuration. After installation, click in the administrative console to access the Resource references page.
- Virtual host bindings for web modules
- You must bind each web module to a specific virtual host. The binding informs a web server
plug-in that all requests that match the virtual host must be handled by the web application. An
example virtual host to be bound to a Store web application might be
store_host. The binding definition is stored in IBM binding files such as
If a deployer chooses to generate default bindings when installing the application, the installation wizard sets the virtual host to default_host for each .war file.
During and after application installation, you can map a virtual host to a web module defined in your application. On the Map virtual hosts for web modules page, specify a virtual host. The port number specified in the virtual host definition is used in the URL that is used to access artifacts such as servlets and JavaServer Pages (JSP) files in the web module. For example, an external URL for a web artifact such as a JSP file is http://host_name:virtual_host_port/context_root/jsp_path. After installation, click in the administrative console.
- Message-driven beans
- For each message-driven bean, you must specify a queue or topic to which the bean will listen. A
message-driven bean is invoked by a Java Messaging Service (JMS) listener when a message arrives on
the input queue that the listener is monitoring. A deployer specifies a listener port or JNDI name
of an activation specification as defined in a connector module (.rar file)
under WebSphere Bindings on the Beans page of an assembly tool EJB deployment
descriptor editor. An example JNDI name for a listener port to be used by a Store
application might be StoreMdbListener. The binding definition is stored in
IBM bindings files such as ibm-ejb-jar-bnd.xmi. If a deployer chooses to generate default bindings when installing the application, the installation wizard assigns JNDI names to incomplete bindings.
- For EJB 2.0 or later message-driven beans deployed as JCA 1.5-compliant resources, the installation wizard assigns JNDI names corresponding to activationSpec instances in the form eis/MDB_ejb-name.
- For EJB 2.0 or later message-driven beans deployed against listener ports, the listener ports
are derived from the message-driven bean
<ejb-name>tag with the string
During application installation using the administrative console, you can specify a listener port name or an activation specification JNDI name for every message-driven bean on the Bind listeners for message-driven beans page. A listener port name must be provided when using the JMS providers: Version 5 default messaging, WebSphere MQ, or generic. An activation specification must be provided when the application's resources are configured using the default messaging provider or any generic J2C resource adapter that supports inbound messaging. If neither is specified, then a validation error is displayed after you click Finish on the Summary page.
After application installation, you can specify JNDI names and configure message-driven beans on console pages underor under .Restriction: You can only bind message driven-beans that are defined in an EJB 3.0 or later module to an activation specification.
- Message destination references
- A message destination reference is a logical name used to locate an enterprise bean in an EJB
module that acts as a message destination. Message destination references exist only in J2EE 1.4 and
later artifacts such as--
- J2EE 1.4 application clients
- EJB 2.1 projects
- 2.4 web applications
If multiple message destination references are associated with a single message destination link, then a single JNDI name for an enterprise bean that maps to the message destination link, and in turn to all of the linked message destination references, is collected during deployment. At run time, the message destination references are bound to the administered message destinations in the target operational environment.
If a message destination reference and a message-driven bean are linked by the same message destination, both the reference and the bean should have the same destination JNDI name. When both have the same name, only the destination JNDI name for the message-driven bean is collected and applied to the corresponding message destination reference.
If a deployer chooses to generate default bindings when installing the application, the installation wizard assigns JNDI names to incomplete message destination references as follows: If a message destination reference has a
<message-destination-link>, then the JNDI name is set to ejs/message-destination-linkName. Otherwise, the JNDI name is set to eis/message-destination-refName.
Depending on the references in and artifacts used by your application, you might need to define bindings for other references and artifacts.
Application resource conflicts
Before Version 8 of the product, application-defined resources such as references and environment
entries were bound into the component namespace relative to
Version 8.0 and later, an application developer can assign a name to a resource that is a
java: URL prefixed with
java:global. Each of these URLs resolves to distinct namespaces, different from the
component namespace. A
java:module namespace is shared among all components in a
java:app namespace is shared among all modules in an application, and a
java:global namespace is shared among all applications in a cell. Because the
namespaces are shared, different resources might be assigned the same name, resulting in
Conflicts at the module scope can occur only if two components in the module define resources
with the same name. Because of the small size of this scope, it is unlikely for a module to have
true conflicts. However, if multiple instances of the same resource definition exist, they must be
configured the same. For example, two EJB references to a particular EJB type which are both
assigned the same
java:module name must both be configured with the same binding
data. Otherwise, the two resources will conflict and the application configuration action will
Application-scoped resources are like module-scoped resources. The only difference is that the definitions can originate from any module in the application. As with module-scoped resources, all application-scoped resources that have the same name must be the same type of resource and must be configured with the same binding data.
Global-scoped resources differ from application- and module-scoped resources in that conflicts can occur among different applications. When a conflict occurs, conflicting applications cannot coexist if the resources are not logically the same. If multiple occurrences of a global-scoped resource all identify logically the same resource, they must all be configured with the same binding data in order to not be detected by the product as conflicting. To edit a global-scoped resource for which occurrences for multiple applications exist, all defining applications must be edited in the same session so as not to introduce a conflict. Failure to do so will result in a failure when the session is saved.