EJB.14.2 Bean Environment as JNDI Naming Context | Java 2 Platform, Enterprise Edition: Platform and Component Specifications

The enterprise bean's environment is a mechanism that allows customization of the enterprise bean's business logic during deployment or assembly. The enterprise bean's environment allows the enterprise bean to be customized without the need to access or change the enterprise bean's source code.

The container implements the enterprise bean's environment, and provides it to the enterprise bean instance through the JNDI interfaces. The enterprise bean's environment is used as follows :

The enterprise bean's business methods access the environment using the JNDI interfaces. The bean provider declares in the deployment descriptor all the environment entries that the enterprise bean expects to be provided in its environment at runtime.
The container provides an implementation of the JNDI API naming context that stores the enterprise bean environment. The container also provides the tools that allow the deployer to create and manage the environment of each enterprise bean.
The deployer uses the tools provided by the container to create the environment entries that are declared in the enterprise bean's deployment descriptor. The deployer can set and modify the values of the environment entries.
The container makes the environment naming context available to the enterprise bean instances at runtime. The enterprise bean's instances use the JNDI interfaces to obtain the values of the environment entries.

Each enterprise bean defines its own set of environment entries. All instances of an enterprise bean within the same home share the same environment entries; the environment entries are not shared with other enterprise beans. Enterprise bean instances are not allowed to modify the bean's environment at runtime.

If an enterprise bean is deployed multiple times in the same container, each deployment results in the creation of a distinct home. The deployer may set different values for the enterprise bean environment entries for each home.

Note

Terminology warning ”The enterprise bean's "environment" should not be confused with the "environment properties" defined in the JNDI API documentation.

The following subsections describe the responsibilities of each EJB role.

EJB.14.2.1 Bean Provider's Responsibilities

This section describes the bean provider's view of the enterprise bean's environment, and defines his or her responsibilities.

EJB.14.2.1.1 Access to Enterprise Bean's Environment

An enterprise bean instance locates the environment naming context using the JNDI interfaces. An instance creates a javax.naming.InitialContext object by using the constructor with no arguments, and looks up the environment naming via the InitialContext under the name java:comp/env . The enterprise bean's environment entries are stored directly in the environment naming context, or in any of its direct or indirect subcontexts.

The value of an environment entry is of the type in the Java programming language declared by the bean provider in the deployment descriptor.

The following code example illustrates how an enterprise bean accesses its environment entries.

 public class EmployeeServiceBean implements SessionBean {    ...     public void setTaxInfo(int numberOfExemptions, ...)            throws InvalidNumberOfExemptionsException {       ...        // Obtain the enterprise bean's environment naming context.        Context initCtx = new InitialContext();        Context myEnv = (Context)initCtx.lookup("java:comp/env");        // Obtain the maximum number of tax exemptions        // configured by the Deployer.        Integer max = (Integer)myEnv.lookup("maxExemptions");        // Obtain the minimum number of tax exemptions        // configured by the Deployer.        Integer min = (Integer)myEnv.lookup("minExemptions");        // Use the environment entries to customize business logic.        if (numberOfExeptions > maxExemptions            numberOfExemptions < minExemptions)              throw new InvalidNumberOfExemptionsException();       // Get some more environment entries. These environment        // entries are stored in subcontexts.        String val1 = (String)myEnv.lookup("foo/name1");        Boolean val2 = (Boolean)myEnv.lookup("foo/bar/name2");        // The enterprise bean can also lookup using full           pathnames.        Integer val3 = (Integer)            initCtx.lookup("java:comp/env/name3");        Integer val4 = (Integer)            initCtx.lookup("java:comp/env/foo/name4");        ...     }  }

EJB.14.2.1.2 Declaration of Environment Entries

The bean provider must declare all the environment entries accessed from the enterprise bean's code. The environment entries are declared using the env-entry elements in the deployment descriptor.

Each env-entry element describes a single environment entry. The env-entry element consists of an optional description of the environment entry, the environment entry name relative to the java:comp/env context, the expected Java type of the environment entry value (i.e., the type of the object returned from the JNDI lookup method), and an optional environment entry value.

An environment entry is scoped to the session or entity bean whose declaration contains the env-entry element. This means that the environment entry is inaccessible from other enterprise beans at runtime, and that other enterprise beans may define env-entry elements with the same env-entry-name without causing a name conflict.

The environment entry values may be one of the following Java programming language types: String , Integer , Boolean , Double , Byte , Short , Long , and Float .

If the bean provider provides a value for an environment entry using the env- entry-value element, the value can be changed later by the application assembler or deployer. The value must be a string that is valid for the constructor of the specified type that takes a single String parameter.

The following example is the declaration of environment entries used by the EmployeeServiceBean whose code was illustrated in the previous subsection.

 <enterprise-beans>     <session>             ...        <ejb-name>EmployeeService</ejb-name>        <ejb-class>           com.wombat.empl.EmployeeServiceBean        </ejb-class>        ...        <env-entry>           <description>              The maximum number of tax exemptions              allowed to be set.           </description>           <env-entry-name>maxExemptions</env-entry-name>           <env-entry-type>java.lang.Integer</env-entry-type>           <env-entry-value>15</env-entry-value>        </env-entry>        <env-entry>           <description>              The minimum number of tax exemptions              allowed to be set.           </description>           <env-entry-name>minExemptions</env-entry-name>           <env-entry-type>java.lang.Integer</env-entry-type>           <env-entry-value>1</env-entry-value>        </env-entry>        <env-entry>           <env-entry-name>foo/name1</env-entry-name>           <env-entry-type>java.lang.String</env-entry-type>           <env-entry-value>value1</env-entry-value>        </env-entry>        <env-entry>           <env-entry-name>foo/bar/name2</env-entry-name>           <env-entry-type>java.lang.Boolean</env-entry-type>           <env-entry-value>true</env-entry-value>        </env-entry>        <env-entry>           <description>Some description.</description>           <env-entry-name>name3</env-entry-name>           <env-entry-type>java.lang.Integer</env-entry-type>        </env-entry>        <env-entry>           <env-entry-name>foo/name4</env-entry-name>           <env-entry-type>java.lang.Integer</env-entry-type>           <env-entry-value>10</env-entry-value>        </env-entry>        ...     </session>  </enterprise-beans>  ...

EJB.14.2.2 Application Assembler's Responsibility

The application assembler is allowed to modify the values of the environment entries set by the bean provider, and is allowed to set the values of those environment entries for which the bean provider has not specified any initial values.

EJB.14.2.3 Deployer's Responsibility

The deployer must ensure that the values of all the environment entries declared by an enterprise bean are set to meaningful values.

The deployer can modify the values of the environment entries that have been previously set by the bean provider and/or application assembler, and must set the values of those environment entries for which no value has been specified.

The description elements provided by the bean provider or application assembler help the deployer with this task.

EJB.14.2.4 Container Provider Responsibility

The container provider has the following responsibilities:

Provide a deployment tool that allows the deployer to set and modify the values of the enterprise bean's environment entries.
Implement the java:comp/env environment naming context, and provide it to the enterprise bean instances at runtime. The naming context must include all the environment entries declared by the bean provider, with their values supplied in the deployment descriptor or set by the deployer. The environment naming context must allow the deployer to create subcontexts if they are needed by an enterprise bean.
The container must ensure that the enterprise bean instances have only read access to their environment variables . The container must throw the javax.naming.OperationNotSupportedException from all the methods of the javax.naming.Context interface that modify the environment naming context and its subcontexts.