EJB.14.3 EJB References | Java 2 Platform, Enterprise Edition: Platform and Component Specifications

This section describes the programming and deployment descriptor interfaces that allow the bean provider to refer to the homes of other enterprise beans using "logical" names called EJB references . The EJB references are special entries in the enterprise bean's environment. The deployer binds the EJB references to the enterprise bean's homes in the target operational environment.

The deployment descriptor also allows the application assembler to link an EJB reference declared in one enterprise bean to another enterprise bean contained in the same EJB JAR file, or in another EJB JAR file in the same J2EE application unit. The link is an instruction to the tools used by the deployer that the EJB reference must be bound to the home of the specified target enterprise bean.

EJB.14.3.1 Bean Provider's Responsibilities

This subsection describes the bean provider's view and responsibilities with respect to EJB references.

EJB.14.3.1.1 EJB Reference Programming Interfaces

The bean provider must use EJB references to locate the home interfaces of other enterprise beans as follows .

Assign an entry in the enterprise bean's environment to the reference. (See Section EJB.14.3.1.2 for information on how EJB references are declared in the deployment descriptor.)
The EJB specification recommends, but does not require, that all references to other enterprise beans be organized in the ejb subcontext of the bean's environment (i.e., in the java:comp/env/ejb JNDI context).
Look up the home interface of the referenced enterprise bean in the enterprise bean's environment using JNDI.

The following example illustrates how an enterprise bean uses an EJB reference to locate the home interface of another enterprise bean.

 public class EmployeeServiceBean implements SessionBean {    public void changePhoneNumber(...) {       ...        // Obtain the default initial JNDI context.        Context initCtx = new InitialContext();        // Look up the home interface of the EmployeeRecord        // enterprise bean in the environment.        Object result = initCtx.lookup(          "java:comp/env/ejb/EmplRecord");        // Convert the result to the proper type.        EmployeeRecordHome emplRecordHome = (EmployeeRecordHome)           javax.rmi.PortableRemoteObject.narrow(result,                  EmployeeRecordHome.class);        ...     }  }

In the example, the bean provider of the EmployeeServiceBean enterprise bean assigned the environment entry ejb/EmplRecord as the EJB reference name to refer to the home of another enterprise bean.

EJB.14.3.1.2 Declaration of EJB References in Deployment Descriptor

Although the EJB reference is an entry in the enterprise bean's environment, the bean provider must not use a env-entry element to declare it. Instead, the bean provider must declare all the EJB references using the ejb-ref elements of the deployment descriptor. This allows the EJB JAR consumer (i.e., application assembler or deployer) to discover all the EJB references used by the enterprise bean.

Each ejb-ref element describes the interface requirements that the referencing enterprise bean has for the referenced enterprise bean. The ejb-ref element contains an optional description element and the mandatory ejb-ref-name, ejb-ref-type , home, and remote elements.

The ejb-ref-name element specifies the EJB reference name; its value is the environment entry name used in the enterprise bean code. The ejb-ref-type element specifies the expected type of the enterprise bean; its value must be either Entity or Session . The home and remote elements specify the expected types in the Java programming language of the referenced enterprise bean's home and remote interfaces.

An EJB reference is scoped to the session or entity bean whose declaration contains the ejb-ref element. This means that the EJB reference is not accessible to other enterprise beans at runtime, and that other enterprise beans may define ejb- ref elements with the same ejb-ref-name without causing a name conflict.

The following example illustrates the declaration of EJB references in the deployment descriptor.

 ...  <enterprise-beans>     <session>        ...        <ejb-name>EmployeeService</ejb-name>        <ejb-class>           com.wombat.empl.EmployeeServiceBean        </ejb-class>        ...        <ejb-ref>           <description>              This is a reference to the entity bean that              encapsulates access to employee records.           </description>           <ejb-ref-name>ejb/EmplRecord</ejb-ref-name>           <ejb-ref-type>Entity</ejb-ref-type>           <home>com.wombat.empl.EmployeeRecordHome</home>           <remote>com.wombat.empl.EmployeeRecord</remote>        </ejb-ref>        <ejb-ref>           <ejb-ref-name>ejb/Payroll</ejb-ref-name>           <ejb-ref-type>Entity</ejb-ref-type>           <home>com.aardvark.payroll.PayrollHome</home>           <remote>com.aardvark.payroll.Payroll</remote>        </ejb-ref>        <ejb-ref>           <ejb-ref-name>ejb/PensionPlan</ejb-ref-name>           <ejb-ref-type>Session</ejb-ref-type>           <home>com.wombat.empl.PensionPlanHome</home>           <remote>com.wombat.empl.PensionPlan</remote>           </ejb-ref>           ...     </session>     ...  </enterprise-beans>  ...

EJB.14.3.2 Application Assembler's Responsibilities

The application assembler can use the ejb-link element in the deployment descriptor to link an EJB reference to a target enterprise bean. The link will be observed by the deployment tools.

The application assembler specifies the link between two enterprise beans as follows:

The application assembler uses the optional ejb-link element of the ejb-ref element of the referencing enterprise bean. The value of the ejb-link element is the name of the target enterprise bean. (It is the name defined in the ejb- name element of the target enterprise bean.) The target enterprise bean can be in the same EJB JAR file, or in another EJB JAR in the same J2EE application unit as the referencing enterprise bean.
The application assembler must ensure that the target enterprise bean is type-compatible with the declared EJB reference. This means that the target enterprise bean must be of the type indicated in the ejb-ref-type element, and that the home and remote interfaces of the target enterprise bean must be type-compatible with the interfaces declared in the EJB reference.

The following illustrates an ejb-link in the deployment descriptor.

 ...  <enterprise-beans>     <session>           ...        <ejb-name>EmployeeService</ejb-name>        <ejb-class>           com.wombat.empl.EmployeeServiceBean        </ejb-class>        ...        <ejb-ref>           <ejb-ref-name>ejb/EmplRecord</ejb-ref-name>           <ejb-ref-type>Entity</ejb-ref-type>           <home>com.wombat.empl.EmployeeRecordHome</home>           <remote>com.wombat.empl.EmployeeRecord</remote>           <ejb-link>EmployeeRecord</ejb-link>        </ejb-ref>        ...     </session>     ...     <entity>        <ejb-name>EmployeeRecord</ejb-name>        <home>com.wombat.empl.EmployeeRecordHome</home>        <remote>com.wombat.empl.EmployeeRecord</remote>        ...     </entity>     ...  </enterprise-beans>  ...

The application assembler uses the ejb-link element to indicate that the EJB reference "EmplRecord" declared in the EmployeeService enterprise bean has been linked to the EmployeeRecord enterprise bean.

EJB.14.3.3 Deployer's Responsibility

The deployer is responsible for the following:

The deployer must ensure that all the declared EJB references are bound to the homes of enterprise beans that exist in the operational environment. The deployer may use, for example, the JNDI LinkRef mechanism to create a symbolic link to the actual JNDI name of the target enterprise bean's home.
The deployer must ensure that the target enterprise bean is type-compatible with the types declared for the EJB reference. This means that the target enterprise bean must of the type indicated in the ejb-ref-type element, and that the home and remote interfaces of the target enterprise bean must be Java type-compatible with the home and remote interfaces declared in the EJB reference.
If an EJB reference declaration includes the ejb-link element, the deployer must bind the enterprise bean reference to the home of the enterprise bean specified as the link's target.

EJB.14.3.4 Container Provider's Responsibility

The container provider must provide the deployment tools that allow the Deployer to perform the tasks described in the previous subsection. The deployment tools provided by the EJB container provider must be able to process the information supplied in the ejb-ref elements in the deployment descriptor.

At the minimum, the tools must be able to:

Preserve the application assembly information in the ejb-link elements by binding an EJB reference to the home interface of the specified target enterprise bean.
Inform the deployer of any unresolved EJB references, and allow him or her to resolve an EJB reference by binding it to a specified compatible target enterprise bean.