Configuring an Environment Reference to an EJB

Before one EJB, acting in the role of a client (call it the source EJB), can access another EJB (call it the target EJB), you must define an EJB reference to the target EJB in the deployment descriptor of the source EJB.

Note:

In EJB 3.0, an environment reference to a target EJB is not needed. You can access a target EJB directly using annotations and resource injection (see "Accessing an EJB 3.0 EJB").

This section describes:

Configuring an Environment Reference to a Remote EJB
Configuring an Environment Reference to a Local EJB

Configuring an Environment Reference to a Remote EJB

To define an EJB reference to the remote interface of a target EJB, you configure an <ejb-ref> element in the appropriate deployment descriptor.

Note:

In EJB 3.0, an environment reference to a target EJB is not needed. You can access a target EJB directly using annotations and resource injection (see "Accessing an EJB 3.0 EJB").

For information on looking up a target EJB, see "Accessing an EJB from a Client".

To define a reference to the remote interface of an EJB 2.1 EJB:

Define an <ejb-ref> element in the appropriate client deployment descriptor (see "Where Do You Configure an EJB Environment Reference?").
Within the <ejb-ref> element, define the <home> and <remote> sub-elements with the package and class name of the target EJB remote home and remote component interface, respectively.
Within the <ejb-ref> element, define the <ejb-ref-type> to the target bean's type: Session or Entity.
Within the <ejb-ref> element, define the <ejb-ref-name> and, optionally, the <ejb-link> sub-elements.

Note:
If the bean interfaces are unique (for example, only one session bean uses the interface Cart.class) then the <ejb-link> is not required.

You can choose one of the following options:
1. Configure <ejb-ref-name> with a logical name and configure <ejb-link> with the actual name of the target bean as Example 19-1 shows.
  
  This option provides indirection that offers assembly and deployment flexibility.
  Example 19-1 Configuring ejb-ref-name with a Logical Name Resolved by ejb-link
```
<ejb-ref>
 <ejb-ref-name>ejb/nextVal</ejb-ref-name>
 <ejb-ref-type>Session</ejb-ref-type>
 <home>myBeans.BeanAHome</home>
 <remote>myBeans.BeanA</remote>
 <ejb-link>myBeans/BeanA</ejb-link>
</ejb-ref>
```
2. Configure <ejb-ref-name> with a logical name as Example 19-2 shows and, in the orion-ejb-jar.xml deployment descriptor, define an <ejb-ref-mapping> element that maps the logical name to the actual name of the target bean as Example 19-3 shows.
  
  This option provides indirection that offers the most assembly and deployment flexibility.
  Example 19-2 Configuring ejb-ref-name with a Logical Name Resolved by ejb-ref-mapping
```
<ejb-ref>
 <ejb-ref-name>ejb/nextVal</ejb-ref-name>
 <ejb-ref-type>Session</ejb-ref-type>
 <home>myBeans.BeanAHome</home>
 <remote>myBeans.BeanA</remote>
</ejb-ref>
```
  As Figure 19-1 shows, in the <ejb-ref-mapping> element, configure the name attribute to match the <ejb-ref-name> and configure the location attribute with the actual name of the target bean. In Example 19-3, the logical name ejb/nextVal is mapped to the actual name of the target bean myBeans/BeanA.
  Example 19-3 Mapping Logical Name to Actual Name with ejb-ref-mapping
```
<ejb-ref-mapping name="ejb/nextVal" location="myBeans/BeanA"/>
```
  Figure 19-1 EJB Reference Mapping
  
  Description of "Figure 19-1 EJB Reference Mapping"
  
  OC4J maps the logical name to the actual JNDI name on the client-side. The server-side receives the JNDI name and resolves it within its JNDI tree.

Configuring an Environment Reference to a Local EJB

Before you can look up a target EJB from your client, you must define an EJB reference to the target EJB. To define an EJB reference to the local interface of a target EJB, you configure an <ejb-local-ref> element in the ejb-jar.xml deployment descriptor.

Note:

In EJB 3.0, an environment reference to a target EJB is not needed. You can access a target EJB directly using annotations and resource injection (see "Accessing an EJB 3.0 EJB").

For information on looking up a target EJB, see "Accessing an EJB from a Client".

To define a reference to the local interface of an EJB:

Define an <ejb-local-ref> element in the appropriate client deployment descriptor (see "Where Do You Configure an EJB Environment Reference?").
Within the <ejb-local-ref> element, define the <local-home> and <local> sub-elements with the package and class name of the target EJB remote home and remote component interface, respectively.
Within the <ejb-local-ref> element, define the <ejb-ref-type> to the target bean's type: Session or Entity.
Within the <ejb-local-ref> element, define the <ejb-ref-name> and, optionally, the <ejb-link> sub-elements.

Note:
If the bean interfaces are unique (for example, only one session bean uses the interface Cart.class) then the <ejb-link> is not required.

You can choose one of the following options:
1. Configure <ejb-ref-name> with a logical name and configure <ejb-link> with the actual name of the target bean as Example 19-1 shows.
  
  This option provides indirection that offers assembly and deployment flexibility.
  Example 19-4 Configuring ejb-ref-name with a Logical Name Resolved by ejb-link
```
<ejb-local-ref>
 <ejb-ref-name>ejb/nextVal</ejb-ref-name>
 <ejb-ref-type>Session</ejb-ref-type>
 <local-home>myBeans.BeanAHome</local-home>
 <local>myBeans.BeanA</local>
 <ejb-link>myBeans/BeanA</ejb-link>
</ejb-local-ref>
```
2. Configure <ejb-ref-name> with a logical name as Example 19-2 shows and, in the orion-ejb-jar.xml deployment descriptor, define an <ejb-ref-mapping> element that maps the logical name to the actual name of the target bean as Example 19-3 shows.
  
  This option provides indirection that offers the most assembly and deployment flexibility.
  Example 19-5 Configuring ejb-ref-name with a Logical Name Resolved by ejb-ref-mapping
```
<ejb-local-ref>
 <ejb-ref-name>ejb/nextVal</ejb-ref-name>
 <ejb-ref-type>Session</ejb-ref-type>
 <local-home>myBeans.BeanAHome</local-home>
 <local>myBeans.BeanA</local>
</ejb-local-ref>
```
  In the <ejb-ref-mapping> element, configure the name attribute to match the <ejb-ref-name> and configure the location attribute with the actual name of the target bean. In Example 19-3, the logical name ejb/nextVal is mapped to the actual name of the target bean myBeans/BeanA.
  Example 19-6 Mapping Logical Name to Actual Name with ejb-ref-mapping
```
<ejb-ref-mapping name="ejb/nextVal" location="myBeans/BeanA"/>
```
  OC4J maps the logical name to the actual JNDI name on the client-side. The server-side receives the JNDI name and resolves it within its JNDI tree.