Configuring an Environment Reference to a Local EJB

You can define an EJB reference to the local interface of a target enterprise bean using one of the following approaches (in increasing order of assembly and deployment flexibility):

Configure an <ejb-local-ref> element in the appropriate client EJB deployment descriptor that specifies the actual name of the target bean (see "Configuring ejb-local-ref in the Client: No Indirection").
Configure an <ejb-local-ref> element in the appropriate client EJB deployment descriptor that specifies a logical name and an <ejb-link> element that associates this logical name with the actual bean (see "Configuring ejb-local-ref in the Client: Using ejb-link to Resolve Indirection").
Configure an <ejb-local-ref> element in the appropriate client EJB deployment descriptor that specifies a logical name and an <ejb-ref-mapping> in the appropriate OC4J-specific deployment descriptor that associates this logical name with the actual bean (see "Configuring ejb-local-ref in the Client: Using orion-ejb-jar.xml ejb-ref-mapping to Resolve Indirection").

Note:

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

For information on looking up a target enterprise bean, see "Accessing an Enterprise Bean From a Client".

Configuring ejb-local-ref in the Client: No Indirection

Choose this option if the bean interfaces are unique (for example, only one session bean uses the interface Cart.class) or you do not want to use indirection that offers some assembly and deployment flexibility:

Define an <ejb-local-ref> element in the appropriate client deployment descriptor (see "Where do you Configure an EJB Environment Reference?") and configure the following subelements, as Example 19-1 shows:
- <ejb-ref-name>: the actual name of the target enterprise bean.
- <ejb-ref-type>: the target bean's type: Session or Entity.
- <local-home>: the package and class name of the target bean's local home interface.
- <local>: the package and class name of the target bean's local component interface.
Example 19-7 Configuring ejb-local-ref-name
```
<ejb-local-ref>
 <ejb-ref-name>myBeans/BeanA</ejb-ref-name>
 <ejb-ref-type>Session</ejb-ref-type>
 <local-home>myBeans.BeanAHome</home>
 <local>myBeans.BeanA</remote>
</ejb-ref>
```

Configuring ejb-local-ref in the Client: Using ejb-link to Resolve Indirection

Choose this option if the bean interfaces are not unique, or if you want to use indirection that offers some assembly and deployment flexibility:

Define an <ejb-local-ref> element in the appropriate client deployment descriptor (see "Where do you Configure an EJB Environment Reference?") and configure the following subelements, as Example 19-8 shows:
- <ejb-ref-name>: the logical name of the target enterprise bean.
- <ejb-ref-type>: the target bean's type: Session or Entity.
- <local-home>: the package and class name of the target bean's local home interface.
- <local>: the package and class name of the target bean's local component interface.
- <ejb-link>: actual name of the target bean
Example 19-8 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</home>
 <local>myBeans.BeanA</remote>
 <ejb-link>myBeans/BeanA</ejb-link>
</ejb-ref>
```

Configuring ejb-local-ref in the Client: Using orion-ejb-jar.xml ejb-ref-mapping to Resolve Indirection

Choose this option if the following is true:

The bean interfaces are not unique.
You want to use indirection that offers the most assembly and deployment flexibility.

Define an <ejb-ref> element in the appropriate client deployment descriptor (see "Where do you Configure an EJB Environment Reference?") and configure the following subelements, as Example 19-9 shows:
- <ejb-ref-name>: the logical name of the target enterprise bean.
- <ejb-ref-type>: the target bean's type: Session or Entity.
- <local-home>: the package and class name of the target bean's local home interface.
- <local>: the package and class name of the target bean's local component interface.
Example 19-9 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</home>
 <local>myBeans.BeanA</remote>
</ejb-ref>
```
Within 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-10 shows.
Example 19-10 Mapping Logical Name to Actual Name With ejb-ref-mapping
```
<ejb-ref-mapping name="ejb/nextVal" location="myBeans/BeanA"/>
```
As Figure 19-5 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-10, the logical name ejb/nextVal is mapped to the actual name of the target bean myBeans/BeanA.

Figure 19-5 Associating ejb-ref-name and ejb-ref-mapping

Description of "Figure 19-5 Associating ejb-ref-name and ejb-ref-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.