J2EE.5.2 Java Naming and Directory Interface (JNDI) Naming Context


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

The container implements the application component's environment, and provides it to the application component instance as a JNDI naming context. The application component's environment is used as follows :

  1. The application component's business methods access the environment using the JNDI interfaces. The application component provider declares in the deployment descriptor all the environment entries that the application component expects to be provided in its environment at runtime.

  2. The container provides an implementation of the JNDI naming context that stores the application component environment. The container also provides the tools that allow the deployer to create and manage the environment of each application component.

  3. The deployer uses the tools provided by the container to initialize the environment entries that are declared in the application component's deploy-ment descriptor. The deployer can set and modify the values of the environment entries.

  4. The container makes the environment naming context available to the application component instances at runtime. The application component's instances use the JNDI interfaces to obtain the values of the environment entries.

Each application component defines its own set of environment entries. All instances of an application component within the same container share the same environment entries. Application component instances are not allowed to modify the environment at runtime.

Note

Terminology warning: The application component's "environment" should not be confused with the "environment properties" defined in the JNDI documentation. The JNDI environment properties are used to initialize and configure the JNDI naming context itself. The application component's environment is accessed through a JNDI naming context for direct use by the application component.


The following subsections describe the responsibilities of each J2EE role.

J2EE.5.2.1 Application Component Provider's Responsibilities

This section describes the application component provider's view of the application component's environment, and defines his or her responsibilities. It does so in two sections, the first describing API for accessing environment entries, and the second describing syntax for declaring the environment entries.

J2EE.5.2.1.1 Access to Application Component's Environment

An application component 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 naming environment via the InitialContext under the name java:comp/env . The application component'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 Java programming language type declared by the application component provider in the deployment descriptor.

The following code example illustrates how an application component accesses its environment entries.

 public void setTaxInfo(int numberOfExemptions, ...)         throws InvalidNumberOfExemptionsException {    ...     // Obtain the application component'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 > max.intValue()          numberOfExemptions < min.intValue())            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 application component 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");     ...  } 
J2EE.5.2.1.2 Declaration of Environment Entries

The application component provider must declare all the environment entries accessed from the application component'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 programming language 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.

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

If the application component provider provides a value for an environment entry, 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 application component whose code was illustrated in the previous subsection.

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

J2EE.5.2.2 Application Assembler's Responsibilities

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.

J2EE.5.2.3 Deployer's Responsibilities

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

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

J2EE.5.2.4 J2EE Product Provider's Responsibilities

The J2EE product provider has the following responsibilities:

  • Provide a deployment tool that allows the deployer to set and modify the values of the application component's environment entries.

  • Implement the java:comp/env environment naming context, and provide it to the application component instances at runtime. The naming context must include all the environment entries declared by the application component 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 application component.

  • The container must ensure that the application component 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.



Java 2 Platform, Enterprise Edition. Platform and Component Specifications
Java 2 Platform, Enterprise Edition: Platform and Component Specifications
ISBN: 0201704560
EAN: 2147483647
Year: 2000
Pages: 399

flylib.com © 2008-2017.
If you may any questions please contact us: flylib@qtcs.net