Configuring Environment References

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

This section describes configuring an environment reference to:

EJB Environment References
Resource Manager Connection Factory Environment References
Environment Variable Environment References
Web Service Environment References

In EJB 3.0, you can use annotations, resource injection, and default JNDI names (based on class and interface names) instead of defining environment references.

In EJB 2.1, you must define <ejb-ref> or <ejb-local-ref> elements in the appropriate deployment descriptor (see "Where Do You Configure an EJB Environment Reference?").

When you define an environment reference, you can use the actual JNDI name or use a logical name ("Should You Use Logical Names?") associated with it to increase deployment flexibility.

EJB Environment References

Before one EJB, acting in the role of a client can access another EJB, you must define an EJB reference to the target EJB.

For more information, see "Configuring an Environment Reference to an 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 annotations and 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:

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

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 EJB invoking an EJB from within the container.	`ejb-jar.xml`	`orion-ejb-jar.xml`
Stand-alone client	A pure-Java client invoking an EJB from outside of the container.	`application-client.xml`	`orion-application-client.xml`
Servlet or JSP	A servlet or JSP invoking an EJB from outside of the container.	`web.xml`	`orion-web.xml`

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