Sun Microsystems Inc.

•A tool to allow the System Administrator to add, remove, and configure a resource manager for the EJB Server.

•A mechanism to pool connections to the resources for the enterprise beans and otherwise manage the use of resources by the Container. The pooling must be transparent to the enterprise beans.

19.4.4 System Administrator’s responsibility

The System Administrator is typically responsible for the following:

• Add, remove, and configure resource managers in the EJB Server environment.

In some scenarios, these tasks can be performed by the Deployer.

19.5 Resource environment references

This section describes the programming and deployment descriptor interfaces that allow the Bean Provider to refer to administered objects that associated with resources (for example, JMS Destinations) by using “logical” names called resource environment references. Resource environment references are special entries in the enterprise bean’s environment. The Deployer binds the resource environment references to administered objects in the target operational environment.

19.5.1 Bean Provider’s responsibilities

This subsection describes the Bean Provider’s view and responsibilities with respect to resource environment references.

19.5.1.1 Resource environment reference programming interfaces

The Bean Provider must use resource environment references to locate administered objects, such as JMS Destinations, that are associated with resources as follows.

•Assign an entry in the enterprise bean’s environment to the reference. (See subsection 19.5.1.2 for information on how resource environment references are declared in the deployment descriptor.)

•The EJB specification recommends, but does not require, that all resource environment references be organized in the appropriate subcontext of the bean’s environment for the resource type (e.g. in the java:comp/env/jms JNDI context for JMS Destinations).

•Look up the administered object in the enterprise bean’s environment using JNDI.

Sun Microsystems Inc

The following example illustrates how an enterprise bean uses a resource environment reference to locate a JMS Destination .

public class StockServiceBean implements SessionBean {

public void processStockInfo(...) {

...

//Obtain the default initial JNDI context. Context initCtx = new InitialContext();

//Look up the JMS StockQueue in the environment. Object result = initCtx.lookup(

"java:comp/env/jms/StockQueue");

//Convert the result to the proper type. javax.jms.Queue queue = (javax.jms.Queue)result;

}

}

In the example, the Bean Provider of the StockServiceBean enterprise bean assigned the environment entry jms/StockQueue as the resource environment reference name to refer to a JMS queue.

19.5.1.2 Declaration of resource environment references in deployment descriptor

Although the resource environment 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 references to administered objects associated with resources using the resource-env-ref elements of the deployment descriptor. This allows the ejb-jar consumer to discover all the resource environment references used by the enterprise bean.

Each resource-env-ref element describes the requirements that the referencing enterprise bean has for the referenced administered object. The resource-env-ref element contains an optional description element; and the mandatory resource-env-ref-name and resource-env-ref-type elements.

The resource-env-ref-name element specifies the resource environment reference name; its value is the environment entry name used in the enterprise bean code. The name of the environment entry is relative to the java:comp/env context (e.g., the name should be jms/StockQueue rather than java:comp/env/jms/StockQueue). The resource-env-ref-type element specifies the expected type of the referenced object. For example, in the case of a JMS Destination; its value must be either javax.jms.Queue or javax.jms.Topic.

A resource environment reference is scoped to the enterprise bean whose declaration contains the resource-env-ref element. This means that the resource environment reference is not accessible to other enterprise beans at runtime, and that other enterprise beans may define resource-env-ref elements with the same resource-env-ref-name without causing a name conflict.