Configuring Environment References

Before you can access essential resources from your EJB at run time using JNDI, you must define environment references to them. Environment references are static and cannot be changed by the bean.

This section describes configuring the following:

• EJB Environment References

• Resource Manager Connection Factory Environment References

• Environment Variable Environment References

• Web Service Environment References

• Persistence Context References

In EJB 3.0, instead of defining environment references, you can use annotations, resource injection, and default JNDI names (based on class and interface names). Alternatively, you can define environment references using either OC4J-specific deployment descriptors or OC4J-proprietary annotations.

In EJB 2.1, you must define <ejb-ref> or <ejb-local-ref> elements in the appropriate deployment descriptor.

In either case, when you define an environment reference, you can use the actual JNDI name or use a logical name associated with it to increase deployment flexibility.

For more information, see the following:

• "Where do you Configure an EJB Environment Reference?"

• "Should you use Logical Names?"

EJB Environment References

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

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 more information, see the following:

• Configuring an Environment Reference to a Remote EJB: Clustered or Combined Web Tier and EJB Tier

• Configuring an Environment Reference to a Remote EJB: Unclustered Separate Web Tier and EJB Tier

• Configuring an Environment Reference to a Local EJB

Resource Manager Connection Factory Environment References

You can define an environment reference to resource manager connection factories that provide connections to such services as a JDBC data source, JMS topic or queue, Java mail, or an HTTP URL. These references are logical names that OC4J binds at deployment time to the actual resource manager connection factories that it provides.

Note:

In EJB 3.0, an environment reference to a resource manager connection factory is not needed. You can access a resource manager connection factory directly using resource injection (see "Looking Up an EJB 3.0 Resource Manager Connection Factory").

For each client in which you want to access a resource manager connection factory, you must either inject it in the client source code or define an environment reference to it in the client's deployment descriptor.

For more information, see the following:

• "Configuring an Environment Reference to a JDBC Data Source Resource Manager Connection Factory"

• "Configuring an Environment Reference to a JMS Destination Resource Manager Connection Factory (JMS 1.1)"

• "Configuring an Environment Reference to a JMS Destination or Connection Resource Manager Connection Factory (JMS 1.0)"

Environment Variable Environment References

You can define an enviornment variable with an enviornment reference to make the environment variable value accessible using JNDI.

For more information, see "Configuring an Environment Reference to an Environment Variable"

Web Service Environment References

You can define a Web service with an enviornment reference to make the Web service accessible using JNDI

For more information, see "Configuring an Environment Reference to a Web Service".

Persistence Context References

The preferred way to access an entity manager is using annotations and dependency injection (see "Acquiring the OC4J Default Entity Manager" and "Acquiring an Entity Manager Using JNDI").

To acquire an entity manager in a class that does not support annotations and injection, namely helper classes and Web clients, you must first define a persistence context reference and then lookup the entity manager using JNDI.

For more information, see the following:

• "Configuring an Environment Reference to a Persistence Context"

• "Acquiring an Entity Manager in a Helper Class"

Where do you Configure an EJB Environment Reference?

If you choose to use environment references, where you configure the EJB reference depends on the type of client, as Table 19-1 shows.

Table 19-1 Deployment Descriptor by Client Type

Client Type	Description	Deployment Descriptor	OC4J-Specific Deployment Descriptor
EJB	Another enterprise bean invoking an enterprise bean from within the container.	ejb-jar.xml	orion-ejb-jar.xml
Standalone client	A pure-Java client invoking an enterprise bean from outside of the container.	application-client.xml	orion-application-client.xml
Servlet or JSP	A servlet or JSP invoking an enterprise bean from outside of the container.	web.xml	orion-web.xml

In EJB 3.0, if you wish to define an EJB environment reference, you can use OC4J-proprietary annotations as an alternative to OC4J-specific deployment descriptors.

Should you use Logical Names?

When you define an environment reference, you can identify the resource by a logical name or by its JNDI name. To maximize application assembly and deployment flexibility, you typically develop an EJB application by referring to resources by a logical name that you define in your application environment. This indirection enables the bean developer to refer to enterprise beans, other resources (such as a JDBC DataSource), and environment variables without specifying the actual name, which may change depending on how an application is assembled and deployed. The procedures in this chapter explain how to configure either logical or JNDI names.