J2EE.5.3 Enterprise JavaBeans (EJB) References

This section describes the programming and deployment descriptor interfaces that allow the application component provider to refer to the homes of enterprise beans using "logical" names called EJB references. The EJB references are special entries in the application component's naming 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 application component to an enterprise bean contained in an EJB JAR file in the same J2EE application. The link is an instruction to the tools used by the deployer describing the binding of the EJB reference to the home of the specified target enterprise bean.

J2EE.5.3.1 Application Component Provider's Responsibilities

This subsection describes the application component provider's view and responsibilities with respect to EJB references. It does so in two sections, the first describing the API for accessing EJB references, and the second describing the syntax for declaring the EJB references.

J2EE.5.3.1.1 Programming Interfaces for EJB References

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

• Assign an entry in the application component's environment to the reference. (See Section J2EE.5.3.1.2 for information on how EJB references are declared in the deployment descriptor.)

• This specification recommends, but does not require, that all references to enterprise beans be organized in the ejb subcontext of the application component's environment (i.e., in the java:comp/env/ejb JNDI context).

• Look up the home interface of the referenced enterprise bean in the application component's environment using JNDI.

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

 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 application component provider assigned the environment entry ejb/EmplRecord as the EJB reference name to refer to the home of an enterprise bean.

J2EE.5.3.1.2 Declaration of EJB References

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

Each ejb-ref element describes the interface requirements that the referencing application component 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 application component 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 Java types of the referenced enterprise bean's home and remote interfaces.

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

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

J2EE.5.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 to an enterprise bean as follows:

• The application assembler uses the optional ejb-link element of the ejb-ref element of the referencing application component. 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 any EJB JAR file in the same J2EE application as the referencing application component.

• 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 Java type-compatible with the interfaces declared in the EJB reference.

The following example illustrates the use of the ejb-link element in the deployment descriptor. The enterprise bean reference should be satisfied by the bean named EmployeeRecord . The EmployeeRecord enterprise bean may be packaged in the same module as the component making this reference, or it may be packaged in another module within the same J2EE application as the component making this reference.

 ...  <ejb-ref>     <description>            This is a reference to the entity bean that            encapsulates access to employee records. It            has been linked to the entity bean named            EmployeeRecord in this application.     </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-link>EmployeeRecord</ejb-link>  </ejb-ref>  ... 

J2EE.5.3.3 Deployer's Responsibilities

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

J2EE.5.3.4 J2EE Product Provider's Responsibilities

The J2EE product 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 J2EE product 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.