This section describes the programming and deployment descriptor interfaces that allow the Application Component Provider to refer to administered objects that are associated with a resource (for example, a Connector CCI InteractionSpec
instance) by using “logical” names called resource environment references. The resource environment references are special entries in the application component’s environment. The Deployer binds the resource environment references to
administered objects in the target operational environment.
EE.5.8.1 Application Component Provider’s Responsibilities
This subsection describes the Application Component Provider’s view and responsibilities with respect to resource environment references.
EE.5.8.1.1 Injection of Resource Environment References
A field or a method of an application component may be annotated with the
Resource annotation to request injection of a resouce environment reference. The name and type of the resource environment reference are as described earlier. The
authenticationType and shareable elements of the Resource annotation must not be specified; resource environment entries are not shareable and do not require authentication. The use of the Resource annotation to declare a resource
environment reference differs from the use of the Resource annotation to declare other environment references only in that the type of a resource environment reference is not one of the Java language types used for other environment references.
EE.5.8.1.2 Resource Environment Reference Programming Interfaces The Application Component Provider may use resource environment references to locate administered objects that are associated with resources as follows.
• Assign an entry in the application component’s environment to the reference. (See subsection 5.8.1.3 for information on how resource environment referenc- es are declared in the deployment descriptor.)
• This specification recommends, but does not require, that all resource envi- ronment references be organized in the appropriate subcontext of the compo- nent’s environment for the resource type. Note that resource environment references declared via annotations will not, by default, appear in any subcon- text.
• Look up the administered object in the application component’s environment using JNDI.
EE.5.8.1.3 Declaration of Resource Environment References in Deployment Descriptor
Although the resource environment reference is an entry in the application component’s environment, the Application Component Provider must not use a
env-entry element to declare it. Instead, the Application Component Provider must
declare all references to administered objects associated with resources using either annotations on the application component’s code or the resource-env-ref elements
of the deployment descriptor. This allows the application component’s JAR file consumer to discover all the resource environment references used by the
application component. Deployment descriptor entries may also be used to specify injection of a resource environment reference into an application component.
Each resource-env-ref element describes the requirements that the referencing application component has for the referenced administered object. The resource-env-ref element contains optional description and resource- env-ref-type elements and the mandatory resource-env-ref-name element. The
resource-env-ref-type element is optional if an injection target is specified for this resource; in this case the resource-env-ref-type defaults to the type of the injection target.
The resource-env-ref-name element specifies the resource environment reference name. Its value is the environment entry name used in the application component code. The name of the resource environment reference is relative to the java:comp/env context. The resource-env-ref-type element specifies the expected type of the referenced object.
A resource environment reference is scoped to the application component whose declaration contains the resource-env-ref element. This means that the resource environment reference is not accessible to other application components at runtime, and that other application components may define resource-env-ref
elements with the same resource-env-ref-name without causing a name conflict. A resource environment reference may specify a lookup-name to link the reference being defined to another one via a JNDI name.
EE.5.8.2 Deployer’s Responsibilities
The Deployer is responsible for the following:
• The Deployer must ensure that all the declared resource environment referenc- es are bound to administered objects that exist in the operational environment. The Deployer may use, for example, the JNDI LinkRef mechanism to create a symbolic link to the actual JNDI name of the target object. The Deployer may override the linkage preferences of a resource environment reference that in- cludes a lookup annotation element or lookup-name deployment descriptor el- ement.
• The Deployer must ensure that the target object is type-compatible with the type declared for the resource environment reference. This means that the tar- get object must be of the type indicated in the Resource annotation or the resource-env-ref-type element.
EE.5.8.3 Java EE Product Provider’s Responsibilities
The Java EE Product Provider must provide the deployment tools that allow the Deployer to perform the tasks described in the previous subsection. The deployment tools provided by the Java EE Product Provider must be able to process the
information supplied in the class file annotations and the resource-env-ref
elements in the deployment descriptor.
At the minimum, the tools must be able to inform the Deployer of any unresolved resource environment references, and allow him or her to resolve a resource environment reference by binding it to a specified compatible target object in the environment.