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 ResponsibilitiesThis subsection describes the bean provider's view and responsibilities with respect to EJB references. EJB.14.3.1.1 EJB Reference Programming InterfacesThe bean provider must use EJB references to locate the home interfaces of other enterprise beans as follows .
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 DescriptorAlthough 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 ResponsibilitiesThe 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 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 ResponsibilityThe deployer is responsible for the following:
EJB.14.3.4 Container Provider's ResponsibilityThe 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:
|