ResourcesNamingInjection.adoc

Resources, Naming, and Injection

This chapter describes how applications declare dependencies on external resources and configuration parameters, and how those items are represented in the Jakarta EE naming system and can be injected into application components. These requirements are based on annotations defined in the Java Metadata specification and features defined in the Java Naming and Directory Interface™ (JNDI) specification. The Resource annotation described here is defined in more detail in the Jakarta Annotations specification. The EJB annotation described here is defined in more detail in the Enterprise JavaBeans specification. The PersistenceUnit and PersistenceContext annotations described here are defined in more detail in the Jakarta Persistence specification. The Inject annotation described here is defined in the Dependency Injection for Java specification, and its usage in Jakarta EE applications is defined in the CDI specification.

Overview

The requirements defined in this chapter address the following two issues:

• The Application Assembler and Deployer should be able to customize the behavior of an application’s business logic without accessing the application’s source code. Typically this will involve specification of parameter values, connection to external resources, and so on. Deployment descriptors provide this capability

• Applications must be able to access resources and external information in their operational environment without knowledge of how the external information is named and organized in that environment. The JNDI naming context and Java language annotations provide this capability.

Chapter Organization

The following sections contain the Jakarta EE platform solutions to the above issues:

• JNDI Naming Context defines general rules for the use of the JNDI naming context and its interaction with Java language annotations that reference entries in the naming context.

• Responsibilities by Jakarta EE Role defines the general responsibilities for each of the Jakarta EE roles such as Application Component Provider, Application Assembler, Deployer, and Jakarta EE Product Provider.

• Simple Environment Entries defines the basic interfaces that specify and access the application component’s naming environment. The section illustrates the use of the application component’s naming environment for generic customization of the application component’s business logic.

• Jakarta Enterprise Beans References defines the interfaces for obtaining the business interface, no-interface view, or home interface of an enterprise bean using a Jakarta Enterprise Bean reference. A Jakarta Enterprise Bean reference is a special entry in the application component’s environment.

• Web Service References refers to the specification for web service references.

• Resource Manager Connection Factory References defines the interfaces for obtaining a resource manager connection factory using a resource manager connection factory reference. A resource manager connection factory reference is a special entry in the application component’s environment.

• Resource Environment References defines the interfaces for obtaining an administered object that is associated with a resource using a resource environment reference. A resource environment reference is a special entry in the application component’s environment.

• Message Destination References defines the interfaces for declaring and using message destination references.

• UserTransaction References describes the use by eligible application components of references to a UserTransaction object in the component’s environment to start, commit, and abort transactions.

• TransactionSynchronizationRegistry References describes the use by eligible application components of references to a TransactionSynchronizationRegistry object in the component’s environment.

• ORB References describes the use by eligible application components of references to a CORBA ORB object in the component’s environment.

• Persistence Unit References describes the use by eligible application components of references to an EntityManagerFactory object in the component’s environment.

• Persistence Context References describes the use by eligible application components of references to an EntityManager object in the component’s environment.

• Application Name and Module Name References describes the use by eligible application components of references to the names of the current application and module.

• Application Client Container Property describes the use by eligible application components of references to the application client container property.

• Validator and Validator Factory References describes the use by eligible application components of references to the Validator and ValidatorFactory objects in the component’s environment.

• Resource Definition and Configuration describes the use by eligible application components of metadata that may be used to define resources in the component’s environment.

• DataSource Resource Definition describes the use by eligible application components of references to DataSource resources in the component’s environment.

• Jakarta Messaging Connection Factory Resource Definition describes the use by eligible application components of references to Jakarta Messaging ConnectionFactory resources in the component’s environment.

• Jakarta Messaging Destination Definition describes the use by eligible application components of references to Jakarta Messaging Destination resources in the component’s environment.

• Mail Session Definition describes the use by eligible application components of references to Mail Session resources in the component’s environment.

• Connector Connection Factory Definition describes the use by eligible application components of references to Connector connection factory resources in the component’s environment.

• Connector Administered Object Definition describes the use by eligible application components of references to Connector administered object resources in the component’s environment.

• Default Data Source describes the use by eligible application components of references to the default DataSource in the component’s environment.

• Default Jakarta Messaging Connection Factory describes the use by eligible application components of references to the default Jakarta Messaging ConnectionFactory in the component’s environment.

• Default Jakarta Concurrency Objects describes the use by eligible application components of references to the default Jakarta Concurrency objects in the component’s environment.

• Managed Bean References describes the use by eligible application components of references to CDI Managed Beans.

• Bean Manager References describes the use by eligible application components of references to a BeanManager object in the component’s environment.

• Support for Dependency Injection describes support for the use of the Dependency Injection APIs.

Required Access to the JNDI Naming Environment

Jakarta EE application clients, enterprise beans, and web components are required to have access to a JNDI naming environment.^[1] The containers for these application component types are required to provide the naming environment support described here.

Annotations and deployment descriptors are the main vehicles for conveying access information to the Application Assembler and Deployer about application components’ requirements for customization of business logic and access to external information. The annotations described here are available for use by all application component types. The deployment descriptor entries described here are present in identical form in the deployment descriptor schemas for each of these application component types. See the corresponding specification of each application component type for the details.

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. Use of 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 Application Component’s Environment

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 make use of entries from the environment. The business methods may access the environment using the JNDI interfaces or lookup methods on component-specific context objects. Also, entries from the environment may be injected into the application component’s fields or methods. The Application Component Provider declares in the deployment descriptor, or via annotations, all the environment entries that the application component expects to be provided in its environment at runtime. For each environment entry, the Application Component Provider can also specify in the deployment descriptor, or via annotations, the JNDI name of another environment entry whose value should be used to initialize the environment entry being defined (“lookup” functionality).

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 deployment descriptor or via annotations. The Deployer can set and modify the values of the environment entries. As part of this process, the Deployer is allowed to override any “lookup” information associated with the application component.

4. The container injects entries from the environment into application component fields or methods as specified by the application component’s deployment descriptor or by annotations on the application component class.

5. The container also makes the environment naming context available to the application component instances at runtime. The application component’s instances may use the JNDI interfaces or component context lookup methods to obtain the values of the environment entries.

Application Component Environment Namespaces

The application component’s naming environment is composed of four logical namespaces, representing naming environments with different scopes. The four namespaces are:

• java:comp – Names in this namespace are per-component (for example, per enterprise bean). Except for components in a web module, each component gets its own java:comp namespace, not shared with any other component. Components in a web module do not have their own private component namespace. See note below.

• java:module – Names in this namespace are shared by all components in a module (for example, all enterprise beans in a single enterprise bean module, or all components in a web module).

• java:app – Names in this namespace are shared by all components in all modules in a single application, where “single application” means a single deployment unit, such as a single ear file, a single module deployed standalone, etc. For example, a war file and a Jakarta Enterprise Beans jar file in the same ear file would both have access to resources in the java:app namespace.

• java:global – Names in this namespace are shared by all applications deployed in an application server instance. Note that an application server instance may represent a single server, a cluster of servers, an administrative domain containing many servers, or even more. The scope of an application server instance is product-dependent, but it must be possible to deploy multiple applications to a single application server instance.

Note that in environments in which an application is deployed multiple times—such as, for example, in cloud environments, where multiple instances of the same application might be deployed on behalf of multiple tenants—the namespace for each application instance would be disjoint from the namespace of any other instance of that same application.

For historical reasons, the java:comp namespace is shared by all components in a web module. To preserve compatibility, this specification doesn’t change that. In a web module, java:comp refers to the same namespace as java:module. It is recommended that resources in a web module that are intended to be shared by more than one component be declared in the java:module/env namespace.

Note that an application client is a module with only a single component.

Note also that resource adapter (connector) modules may not define resources in any of the component namespaces, but may look up resources defined by other components. All the java: namespaces accessible in a resource adapter are the namespaces of the component that called the resource adapter (when called in the context of a component).

If multiple application components declare an environment entry in one of the shared namespaces, all attributes of that entry must be identical in each declaration. For example, if multiple components declare a resource reference with the same java:app name, the authentication and shareable attributes must be identical.

If all attributes of each declaration of a shared environment entry are not identical, this must be reported as a deployment error to the Deployer. The deployment tool may allow the Deployer to correct the error and continue deployment.

The default JNDI namespace for resource references and resource definitions must always be java:comp/env. Note that this applies to both the case where no name has been supplied so the rules for choosing a default name are used, and the case where a name has been supplied explicitly but the name does not specify a java: namespace. Since the java:comp namespace is not available in some contexts, use of that namespace in such a context should result in a deployment error. Likewise, the java:module namespace is not valid in some contexts; use of that namespace in such contexts should result in a deployment error. Environment entries may be declared in any one of the defined namespaces by explicitly including the namespace prefix before the name.

It is recommended but not required that environment entries be created in the env subcontext of the corresponding naming context. For example, entries shared within a module should be declared in the java:module/env context. Note that names that are not under the env subcontext may conflict with the current or future versions of this specification, with server-defined names, such as the names of applications or modules, or with server-defined resources. Names in the env subcontexts of any of the namespaces must only be created by an explicit declaration in an application or by an explicit action by an administrator; the application server must not predefine any names in the env subcontext of any of the namespaces, or in any subcontext of any such env context.

An environment entry declared in the application.xml descriptor must specify a JNDI name in the java:app or java:global namespace, for example: java:app/env/myString or java:global/someValue. The specification of a java:comp or java:module name for an environment entry declared in the application.xml descriptor must be reported as a deployment error to the Deployer.

A Jakarta EE product may impose security restrictions on access of resources in the shared namespaces. However, it must be possible to deploy applications that define resources in the shared namespaces that are usable by different entities at the given scope. For example, it must be possible to deploy an application that defines a resource, using various forms of metadata declaration, in the java:global namespace that is usable by a separate application.

Accessibility of Environment Entry Types

All objects defined in environment entries of any kind (either in deployment descriptors or through annotations) must be specified to be of a Java type that is accessible to the component. Accessibility of Java classes is specified in section Class Loading Requirements. If the object is of type java.lang.Class, the Class object must refer to a class that is accessible to the component. Note that in cases where the container may return an implementation subtype of the requested type, the implementation subtype might not be accessible to the component.

Sharing of Environment Entries

Each application component defines its own set of dependencies that must appear as entries in the application component’s environment. All instances of an application component within the same application instance within the same container share the same environment entries. Application component instances are not allowed to modify the environment at runtime.

In general, lookups of objects in the JNDI java: namespace are required to return a new instance of the requested object every time. Exceptions are allowed for the following:

• The container knows the object is immutable (for example, objects of type java.lang.String ), or knows that the application can’t change the state of the object.

• The object is defined to be a singleton, such that only one instance of the object may exist in the JVM.

• The name used for the lookup is defined to return an instance of the object that might be shared. The names java:comp/ORB, java:comp/ValidatorFactory, and java:comp/BeanManager are such names.

In these cases, a shared instance of the object may be returned. In all other cases, a new instance of the requested object must be returned on each lookup. Note that, in the case of resource adapter connection objects, it is the resource adapter’s ManagedConnectionFactory implementation that is responsible for satisfying this requirement.

Each injection of an object corresponds to a JNDI lookup. Whether a new instance of the requested object is injected, or whether a shared instance is injected, is determined by the rules described above.

Annotations and Injection

As described in the following sections, a field or method of certain container-managed component classes may be annotated to request that an entry from the application component’s environment be injected into the class. The specifications for the different containers indicate which classes are considered container-managed classes; not all classes of a given type are necessarily managed by the container.

Any of the types of resources described in this chapter may be injected. Injection may also be requested using entries in the deployment descriptor corresponding to each of these resource types. The field or method may have any access qualifier (public, private, etc.). For all classes except application client main classes, the fields or methods must not be static. Because application clients use the same lifecycle as Java SE applications, no instance of the application client main class is created by the application client container. Instead, the static main method is invoked. To support injection for the application client main class, the fields or methods annotated for injection must be static.

A field of a class may be the target of injection. The field must not be final. By default, the name of the field is combined with the fully qualified name of the class and used directly as the name in the application component’s naming context. For example, a field named myDatabase in the class MyApp in the package com.example would correspond to the JNDI name java:comp/env/com.example.MyApp/myDatabase. The annotation also allows the JNDI name to be specified explicitly. When a deployment descriptor entry is used to specify injection, the JNDI name and the field name are both specified explicitly. Note that, by default, the JNDI name is relative to the java:comp/env naming context.

Environment entries may also be injected into a class through methods that follow the naming conventions for JavaBeans properties. The annotation is applied to the set method for the property, which is the method that is called to inject the environment entry into the class. The JavaBeans property name (not the method name) is used as the default JNDI name. For example, a method named setMyDatabase in the same MyApp class would correspond to the same JNDI name java:comp/env/com.example.MyApp/myDatabase as the field myDatabase.

Each resource may only be injected into a single field or method of a given name in a given class. Requesting injection of the java:comp/env/com.example.MyApp/myDatabase resource into both the setMyDatabase method and the myDatabase field is an error. Note, however, that either the field or the method could request injection of a resource of a different (non-default) name. By explicitly specifying the JNDI name of a resource, a single resource may be injected into multiple fields or methods of multiple classes.

The specifications for the various application component types describe which classes may be annotated for injection, as summarized in Component classes supporting injection.

The component classes listed in Component classes supporting injection with support level “Standard” all support Jakarta EE resource injection, as well as PostConstruct and PreDestroy callbacks. In addition, if CDI is enabled—which it is by default—these classes also support CDI injection, as described in Support for Dependency Injection, and the use of interceptors.^[2] The component classes listed with support level “Limited” only support Jakarta EE field injection and the PostConstruct callback. Note that these are application client main classes, where field injection is into static fields.

The specifications for the various application component types also describe when injection occurs in the lifecycle of the component. Typically injection will occur after an instance of the class is constructed, but before any business methods are called. If the container fails to find a resource needed for injection, initialization of the class must fail, and the class must not be put into service.

Table 1. Component classes supporting injection

Spec	Classes supporting injection	Support level
Servlet	servlets servlet filters event listeners HTTP upgrade handlers	Standard Standard Standard Standard
Jakarta Server Pages	tag handlers tag library event listeners	Standard Standard
Jakarta Server Faces	managed classes [3]	Standard
Jakarta Web Services	service endpoints handlers	Standard Standard
Jakarta RESTful Web Services	Jakarta RESTful Web Services components [4]	Standard
WebSocket	endpoints	Standard
Jakarta Enterprise Beans	beans	Standard
Interceptor	interceptors [5]	Standard
Jakarta Persistence	attribute converters entity listeners	Standard Standard
Managed Beans	managed beans	Standard
CDI [6]	CDI-style managed beans [7] decorators [8]	Standard Standard
Jakarta EE platform	main class (static) login callback handler	Limited Standard

Annotations may also be applied to the class itself. These annotations declare an entry in the application component’s environment but do not cause the resource to be injected. Instead, the application component is expected to use JNDI or a component context lookup method to lookup the entry. When the annotation is applied to the class, the JNDI name and the environment entry type must be specified explicitly.

Resource annotations may appear on any of the classes listed above, or on any superclass of any class listed above. A resource annotation on any class in the inheritance hierarchy defines a resource needed by the application component. However, injection of resources follows the Java language overriding rules for visibility of fields and methods. A method definition that overrides a method on a superclass defines the resource, if any, to be injected into that method. An overriding method may request injection even though the superclass method does not request injection, it may request injection of a different resource than is requested by the superclass, or it may request no injection even though the superclass method requests injection.

In addition, fields or methods that are not visible in or are hidden (as opposed to overridden) by a subclass may still request injection. This allows, for example, a private field to be the target of injection and that field to be used in the implementation of the superclass, even though the subclass has no visibility into that field and doesn’t know that the implementation of the superclass is using an injected resource. Note a declaration of a field in a subclass with the same name as a field in a superclass always causes the field in the superclass to be hidden.

In some cases a class may need to perform initialization of its own after all resources have been injected. To support this case, one method of the class may be annotated with the PostConstruct annotation (or, equivalently, specified using the post-construct entry of a deployment descriptor). This method will be called after all injections have occured and before the class is put into service. This method will be called even if the class doesn’t request any resources to be injected. Similarly, for classes whose lifecycle is managed by the container, the PreDestroy annotation (or, equivalently, the pre-destroy entry of a deployment descriptor) may be applied to one method that will be called when the class is taken out of service and will no longer be used by the container. Each class in a class hierarchy may have PostConstruct and PreDestroy methods. The order in which the methods are called matches the order of the class hierarchy with methods on a superclass being called before methods on a subclass.

The PostConstruct and PreDestroy annotations are specified by the Jakarta Annotations specification. All classes that support injection also support the PostConstruct annotation. All classes for which the container manages the full lifecycle of the object also support the PreDestroy annotation.

Starting with Java EE 7, CDI support is enabled by default. CDI bean-defining annotations and the beans.xml descriptor are used to determine which classes are CDI beans and eligible for injection into other objects. Similarly, the annotation metadata and the beans.xml descriptor are used by CDI to determine which interceptors are eligible to be applied. See the CDI specification and the Interceptors specification for the rules that determine which classes are CDI beans and the treatment of interceptors.

Annotations and Deployment Descriptors

Environment entries may be declared by use of annotations, without need for any deployment descriptor entries. Environment entries may also be declared by deployment descriptor entries. The same environment entry may be declared using both an annotation and a deployment descriptor entry. In this case, the information in the deployment descriptor entry may be used to override some of the information provided in the annotation. This approach may be used by an Application Assembler or Deployer to override information provided by the Application Component Developer. Applications should not use deployment descriptor entries to request injection of a resource into a field or method that has not been designed for injection.

The following list describes the rules for how a deployment descriptor entry may override a Resource annotation.

• The relevant deployment descriptor entry is located based on the JNDI name used with the annotation (either defaulted or provided explicitly).

• The type specified in the deployment descriptor must be assignable to the type of the field or property.

• The description, if specified, overrides the description element of the annotation.

• The injection target, if specified, defines additional injection points for the resource.

• The mapped-name element, if specified, overrides the mappedName element of the annotation.

• The res-sharing-scope element, if specified, overrides the shareable element of the annotation. In general, the Application Assembler or Deployer should not change this value as doing so is likely to break the application.

• The res-auth element, if specified, overrides the authenticationType element of the annotation. In general, the Application Assembler or Deployer should not change this value as doing so is likely to break the application.

• The lookup-name element, if specified, overrides the lookup element of the annotation.

It is an error to request injection of two resources into the same target. The behavior of an application that does so is undefined.

The rules for how a deployment descriptor entry may override an EJB annotation are included in the Jakarta Enterprise Beans specification. The rules for how a deployment descriptor entry may override a WebServiceRef annotation are included in the Web Services for Jakarta EE specification.

A PostConstruct method may be specified using either the PostConstruct annotation on the method or the post-construct deployment descriptor entry. Similarly, a PreDestroy method may be specified using either the PreDestroy annotation on the method or the pre-destroy deployment descriptor entry.

Other Naming Context Entries

In addition to environment entries declared by application components, other items will appear in the naming context, as specified by this and other specifications. Following are some of these entries. This is not an exhaustive list; consult the corresponding specification for details.

• All enterprise beans in an application are given entries in the shared namespaces. See the Jakarta Enterprise Beans specification for details.

• All web applications are given names in the shared namespaces. The names correspond to the complete URL of the web application. See the Servlet specification for details.

• Objects representing several container services are defined in the java:comp namespace. See, for example, UserTransaction References, TransactionSynchronizationRegistry References, and ORB References.

• Strings providing the current module name and application name are defined in the java:comp namespace. See Application Name and Module Name References.

Responsibilities by Jakarta EE Role

This section describes the responsibilities for each Jakarta EE role that apply to all uses of the Jakarta EE naming context. The sections that follow describe the responsibilities that are specific to the different types of objects that may be stored in the naming context.

Application Component Provider’s Responsibilities

The Application Component Provider may make use of three techniques for accessing and managing the naming context. First, the Application Component Provider may use Java language annotations to request injection of a resource from the naming context, or to declare elements that are needed in the naming context. Second, the component may use the JNDI APIs to access entries in the naming context. Third, deployment descriptor entries may be used to declare entries needed in the naming context, and to request injection of these entries into application components. Deployment descriptor entries may also be used to override information provided by annotations.

As part of the declaration of elements in the naming context, the Application Component Provider can specify the JNDI name of a resource to be looked up in the naming context to initialize the element being declared. The JNDI name in question may belong to any of the namespaces that compose the application component environment.

To ensure that it has access to the correct javax.naming.InitialContext implementation provided by the container, a portable application component must not specify the java.naming.factory.initial property, must not specify a URLContextFactory for the “java” scheme-id, and must not call the javax.naming.spi.NamingManager.setInitialContextFactoryBuilder method.

Application Assembler’s Responsibilities

The Application Assembler is allowed to modify the entries in the naming context set by the Application Component Provider, and is allowed to set the values of those entries for which the Application Component Provider has not specified any values. The Application Assembler may use the deployment descriptor to override settings made by the Application Component Provider in the source code using annotations.

Deployer’s Responsibilities

The Deployer must ensure that all the entries declared by an application component are created and properly initialized.

The Deployer can modify the entries that have been previously set by the Application Component Provider and/or Application Assembler, and must set the values of those entries for which a required value has not been specified. If an annotation contains the lookup element or a deployment descriptor entry includes the lookup-name element, the Deployer should bind it to the entry specified as the target of the lookup. Deployment should fail if the lookup element of an annotation or the lookup-name element in a deployment descriptor entry does not specify a name with an explicit java: namespace. The Deployer may also use product-specific resource mapping tools, deployment descriptors, rules, or capabilities to bind resource reference entries to resources in the target operational environment.

The description deployment descriptor elements and annotation elements provided by the Application Component Provider or Application Assembler help the Deployer with this task.

Jakarta EE Product Provider’s Responsibilities

The Jakarta EE Product Provider has the following responsibilities:

• Provide a deployment tool that allows the Deployer to set and modify the entries of the application component’s naming context.

• Implement the java:comp, java:module, java:app, and java:global environment naming contexts, and provide them to the application component instances at runtime. The naming context must include all the 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. Certain entries in the naming context may have to be initialized with the values of other entries, specifically when the “lookup” facility is used. In this case, it is an error if there are any circular dependencies between entries. Similarly, it is an error if looking up the specified JNDI name results in a resource whose type is not compatible with the entry being created. The deployment tool may allow the deployer to correct either of these classes of errors and continue the deployment.

• Ensure that, in the absence of any properties specified by the application, the javax.naming.InitialContext implementation meets the requirements described in this specification.

• Inject entries from the naming environment into the application component, as specified by the deployment descriptor or annotations on the application component classes.

• The container must ensure that the application component instances have only read access to their naming context. 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.

Simple Environment Entries

A simple environment entry is a configuration parameter used to customize an application component’s business logic. The environment entry values may be one of the following Java types: String, Character, Byte, Short, Integer, Long, Boolean, Double, Float, Class, and any subclass of Enum.

The following subsections describe the responsibilities of each Jakarta EE Role.

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 three sections, the first describing annotations for injecting environment entries, the second describing the API for accessing environment entries, and the third describing syntax for declaring the environment entries in a deployment descriptor.

Injection of Simple Environment Entries

A field or a method of an application component may be annotated with the Resource annotation. The name and type of the environment entry are as described above. Note that the container will unbox the environment entry as required to match it to a primitive type used for the injection field or method. The authenticationType and shareable elements of the Resource annotation must not be specified; simple environment entries are not shareable and do not require authentication.

The following code example illustrates how an application component uses annotations to declare environment entries.

// The maximum number of tax exemptions, configured by the Deployer.
@Resource int maxExemptions;
// The minimum number of tax exemptions, configured by the Deployer.
@Resource int minExemptions;

public void setTaxInfo(int numberOfExemptions,...)
       throws InvalidNumberOfExemptionsException {
  ...
  // Use the environment entries to
  // customize business logic.
  if (numberOfExemptions > maxExemptions ||
         numberOfExemptions < minExemptions)
    throw new InvalidNumberOfExemptionsException();
 ...
}

The following code example illustrates how an environment entry can be assigned a value by referring to another entry, potentially in a different namespace.

// an entry that gets its value from an application-wide entry
@Resource(lookup="java:app/env/timeout") int timeout;

Programming Interfaces for Accessing Simple Environment Entries

In addition to the injection based approach described above, an application component may access environment entries dynamically. 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 its direct or indirect subcontexts.

Environment entries have 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 (numberOfExemptions > 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");
  ...
}

Declaration of Simple 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 either annotations on the application component’s code, or 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, which by default is relative to the java:comp/env context, the expected Java programming language type of the environment entry value (the type of the object returned from the JNDI lookup method), and an optional environment entry value.

An environment entry is scoped to the application component whose declaration contains the env-entry element. This means that the environment entry is not accessible from other application components at runtime, and that other application components may define env-entry elements with the same env-entry-name without causing a name conflict.

If the Application Component 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, or in the case of Character, a single character.

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>
<env-entry>
  <env-entry-name>helperClass</env-entry-name>
  <env-entry-type>java.lang.Class</env-entry-type>
  <env-entry-value>com.acme.helper.Helper</env-entry-value>
</env-entry>
<env-entry>
  <env-entry-name>timeUnit</env-entry-name>
  <env-entry-type>java.util.concurrent.TimeUnit</env-entry-type>
  <env-entry-value>NANOSECONDS</env-entry-value>
</env-entry>
<env-entry>
  <env-entry-name>bar</env-entry-name>
  <env-entry-type>java.lang.Integer</env-entry-type>
  <lookup-name>java:app/env/appBar</lookup-name>
</env-entry>
...

Injection of environment entries may also be specified using the deployment descriptor, without need for Java language annotations. The following example is the declaration of environment entries corresponding to the earlier injection example.

...
<env-entry>
  <description>
     The maximum number of tax exemptions
     allowed to be set.
  </description>
  <env-entry-name>
     com.example.PayrollService/maxExemptions
  </env-entry-name>
  <env-entry-type>java.lang.Integer</env-entry-type>
  <env-entry-value>15</env-entry-value>
  <injection-target>
    <injection-target-class>
       com.example.PayrollService
    </injection-target-class>
    <injection-target-name>
       maxExemptions
    </injection-target-name>
  </injection-target>
</env-entry>
<env-entry>
  <description>
     The minimum number of tax exemptions
     allowed to be set.
  </description>
  <env-entry-name>
     com.example.PayrollService/minExemptions
  </env-entry-name>
  <env-entry-type>java.lang.Integer</env-entry-type>
  <env-entry-value>1</env-entry-value>
  <injection-target>
    <injection-target-class>
       com.example.PayrollService
    </injection-target-class>
    <injection-target-name>
       minExemptions
    </injection-target-name>
  </injection-target>
</env-entry>
...

It’s often convenient to declare a field or method as an injection target, but specify a default value in the code, as illustrated in the following example.

// The maximum number of tax exemptions, configured by the Deployer.
@Resource int maxExemptions = 4;        // defaults to 4

To support this case, the container must only inject a value for this resource if the deployer has specified a value to override the default value. The env-entry-value element in the deployment descriptor is optional when an injection target is specified. If the element is not specified, no value will be injected. In addition, if the element is not specified, the named resource is not initialized in the naming context; explicit lookups of the named resource will fail.

The deployment descriptor equivalent of the lookup element of the @Resource annotation is lookup-name. The following deployment descriptor fragment is equivalent to the earlier example that used lookup.

...
<env-entry>
  <env-entry-name>somePackage.SomeClass/timeout</env-entry-name>
  <env-entry-type>java.lang.Integer</env-entry-type>
  <injection-target>
    <injection-target-class>
       somePackage.SomeClass
    </injection-target-class>
    <injection-target-name>timeout</injection-target-name>
  </injection-target>
  <lookup-name>java:app/env/timeout</lookup-name>
</env-entry>
...

It is an error for both the env-entry-value and lookup-name elements to be specified for a given env-entry element. If either element exists, an eventual lookup element of the corresponding Resource annotation (if any) must be ignored. In other words, assignment of a value to an environment entry via a deployment descriptor, either directly ( env-entry-value ) or indirectly ( lookup-name ), overrides any assignments made via annotations.

Jakarta Enterprise Beans References

This section describes the programming and deployment descriptor interfaces that allow the Application Component Provider to refer to the homes of enterprise beans or to enterprise bean instances using “logical” names called Jakarta Enterprise Beans references. The Jakarta Enterprise Beans references are special entries in the application component’s naming environment. The Deployer binds the Jakarta Enterprise Beans reference to the enterprise bean’s business interface, no-interface view, or home interface in the target operational environment.

The deployment descriptor also allows the Application Assembler to link a Jakarta Enterprise Bean reference declared in one application component to an enterprise bean contained in an ejb-jar file in the same Jakarta EE application. The link is an instruction to the tools used by the Deployer describing the binding of the Jakarta Enterprise Beans reference to the business interface, no-interface view, or home interface of the specified target enterprise bean. The same linking can also be specified by the Application Component Provider using annotations in the source code of the component.

The requirements in this section only apply to Jakarta EE products that include a Jakarta Enterprise Beans container.

Application Component Provider’s Responsibilities

This subsection describes the Application Component Provider’s view and responsibilities with respect to Jakarta Enterprise Beans references. It does so in three sections, the first describing annotations for injecting Jakarta Enterprise Beans references, the second describing the API for accessing Jakarta Enterprise Beans references, and the third describing the syntax for declaring the Jakarta Enterprise Beans references in a deployment descriptor

Injection of Jakarta Enterprise Beans Entries

A field or a method of an application component may be annotated with the EJB annotation. The EJB annotation represents a reference to a Jakarta Enterprise Beans session bean or entity bean. The reference may be to a session bean’s business interface, to a session bean’s no-interface view, or to the local or remote home interface of a session bean or entity bean.

The following example illustrates how an application component uses the EJB annotation to reference an instance of an enterprise bean. The referenced bean is a stateful session bean. The enterprise bean reference will have the name java:comp/env/com.example.ExampleBean/myCart in the naming context, where ExampleBean is the name of the class of the referencing bean and com.acme.example is its package. The target of the reference is not named and must be resolved by the Deployer, unless there is only one session bean component within the application that exposes a client view type that matches the Jakarta Enterprise Bean reference.

package com.acme.example;

@Stateless public class ExampleBean implements Example {
  ...
  @EJB private ShoppingCart myCart;
  ...
}

The following example illustrates use of almost all elements of the EJB annotation.

@EJB(
  name = "ejb/shopping-cart",
  beanName = "cart1",
  beanInterface = ShoppingCart.class,
  description = "The shopping cart for this application"
)
private ShoppingCart myCart;

As an alternative to beanName, a reference to an enterprise bean can use the global JNDI name for that enterprise bean, or any of the other names mandated by the Jakarta Enterprise Beans specifications, by means of the lookup annotation element. The following example uses a JNDI name in the application namespace.

@EJB(
  lookup="java:app/cartModule/ShoppingCart",
  description = "The shopping cart for this application"
)
private ShoppingCart myOtherCart;

If the ShoppingCart bean were instead written to the Jakarta Enterprise Beans 2.x client view, the Jakarta Enterprise Bean reference would be to the bean’s home interface. For example:

@EJB(
  name="ejb/shopping-cart",
  beanInterface=ShoppingCartHome.class,
  beanName="cart1",
  description="The shopping cart for this application"
)
private ShoppingCartHome myCartHome;

If the ShoppingCart bean were instead written to the no-interface client view and implemented by bean class ShoppingCartBean.class, the Jakarta Enterprise Bean reference would have type ShoppingCartBean.class. For example:

@EJB(
  name="ejb/shopping-cart",
  beanInterface=ShoppingCartBean.class,
  beanName="cart1",
  description="The shopping cart for this application"
)
private ShoppingCartBean myCart;

Programming Interfaces for Jakarta Enterprise Beans References

The Application Component Provider may use Jakarta Enterprise Beans references to locate the business interface, no-interface view, or home interface of an enterprise bean as follows.

• Assign an entry in the application component’s environment to the reference. (See subsection Declaration of Jakarta Enterprise Beans References for information on how Jakarta Enterprise Beans references are declared in the deployment descriptor.)

• This specification recommends, but does not require, that references to enterprise beans be organized in the ejb subcontext of the application component’s environment (that is, in the java:comp/env/ejb JNDI context). Note that enterprise bean references declared via annotations will not, by default, be in any subcontext.

• Look up the business interface, no-interface view, or home interface of the referenced enterprise bean in the application component’s environment using JNDI.

The following example illustrates how an application component uses a Jakarta Enterprise Bean reference to locate the home interface of an enterprise bean.

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

  // Look up the home interface of the EmployeeRecord
  // enterprise bean in the environment.
  Object result = initCtx.lookup("java:comp/env/ejb/EmplRecord");

  // Convert the result to the proper type.
  EmployeeRecordHome emplRecordHome = (EmployeeRecordHome)
         javax.rmi.PortableRemoteObject.narrow(result,
            EmployeeRecordHome.class);
 ...
}

In the example, the Application Component Provider assigned the environment entry ejb/EmplRecord as the Jakarta Enterprise Bean reference name to refer to the remote home interface of an enterprise bean.

Declaration of Jakarta Enterprise Beans References

Although the Jakarta Enterprise Bean 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 the Jakarta Enterprise Beans references using either annotations on the application component’s code or the ejb-ref or ejb-local-ref elements of the deployment descriptor. This allows the consumer of the application component’s JAR file (the Application Assembler or Deployer) to discover all the Jakarta Enterprise Beans references used by the application component. Deployment descriptor entries may also be used to specify injection of a Jakarta Enterprise Bean reference into an application component.

Each ejb-ref or ejb-local-ref element describes the interface requirements that the referencing application component has for the referenced enterprise bean. The ejb-ref element is used for referencing an enterprise bean that is accessed through its remote business interface or remote home and component interfaces. The ejb-local-ref element is used for referencing an enterprise bean that is accessed through its local business interface, no-interface view, or local home and component interfaces. The ejb-ref element contains a description element and the ejb-ref-name, ejb-ref-type, home, and remote elements. The ejb-local-ref element contains a description element and the ejb-ref-name, ejb-ref-type, local-home, and local elements

The ejb-ref-name element specifies the Jakarta Enterprise Bean reference name. Its value is the environment entry name used in the application component code. The optional ejb-ref-type element specifies the expected type of the enterprise bean. Its value must be either Entity or Session. The home and remote or local-home and local elements specify the expected Java programming language types of the referenced enterprise bean’s interface(s). If the reference is to a Jakarta Enterprise Beans 2.x remote client view interface, the home element is required. Likewise, if the reference is to a Jakarta Enterprise Beans 2.x local client view interface, the local-home element is required. The remote element of the ejb-ref element refers to either the business interface type or the component interface, depending on whether the reference is to a bean’s Jakarta Enterprise Beans 3.x or Jakarta Enterprise Beans 2.x remote client view. Likewise, the local element of the ejb-local-ref element refers to either the business interface type, bean class type, or the component interface type, depending on whether the reference is to a bean’s Jakarta Enterprise Beans 3.x local business interface, no-interface view, or Jakarta Enterprise Beans 2.x local client view respectively.

A Jakarta Enterprise Bean reference is scoped to the application component whose declaration contains the ejb-ref or ejb-local-ref element. This means that the Jakarta Enterprise Bean reference is not accessible from other application components at runtime and that other application components may define ejb-ref or ejb-local-ref elements with the same ejb-ref-name without causing a name conflict.

The lookup-name element specifies the JNDI name of an environment entry that provides a value for the reference.

The following example illustrates the declaration of Jakarta Enterprise Beans references in the deployment descriptor.

...
<ejb-ref>
  <description>
     This is a reference to the entity bean that
     encapsulates access to employee records.
  </description>
  <ejb-ref-name>ejb/EmplRecord</ejb-ref-name>
  <ejb-ref-type>Entity</ejb-ref-type>
  <home>com.wombat.empl.EmployeeRecordHome</home>
  <remote>com.wombat.empl.EmployeeRecord</remote>
</ejb-ref>

<ejb-ref>
  <ejb-ref-name>ejb/Payroll</ejb-ref-name>
  <ejb-ref-type>Entity</ejb-ref-type>
  <home>com.aardvark.payroll.PayrollHome</home>
  <remote>com.aardvark.payroll.Payroll</remote>
</ejb-ref>

<ejb-ref>
  <ejb-ref-name>ejb/PensionPlan</ejb-ref-name>
  <ejb-ref-type>Session</ejb-ref-type>
  <home>com.wombat.empl.PensionPlanHome</home>
  <remote>com.wombat.empl.PensionPlan</remote>
  <lookup-name>java:global/personnel/retirement/PensionPlan</lookup-name>
</ejb-ref>
...

Application Assembler’s Responsibilities

The Application Assembler can use the ejb-link element in the deployment descriptor to link a Jakarta Enterprise Beans reference to a target enterprise bean.

The Application Assembler specifies the link to an enterprise bean as follows:

• The Application Assembler uses the optional ejb-link element of the ejb-ref or ejb-local-ref element of the referencing application component. The value of the ejb-link element is the name of the target enterprise bean. This is the name as defined by the metadata annotation (or default) on the bean class or in the ejb-name element for the target enterprise bean. The target enterprise bean can be in any ejb-jar file or war file in the same Jakarta EE application as the referencing application component.

• Alternatively, to avoid the need to rename enterprise beans to have unique names within an entire Jakarta EE application, the Application Assembler may use either of the following two syntaxes in the ejb-link element of the referencing application component.

• The Application Assembler specifies the module name of the ejb-jar file or war file containing the referenced enterprise bean and appends the ejb-name of the target bean separated by “/”. The module name is the base name of the bundle with no filename extension, unless specified in the deployment descriptor.

• The Application Assembler specifies the path name of the ejb-jar file containing the referenced enterprise bean and appends the ejb-name of the target bean separated from the path name by “ # ”. The path name is relative to the referencing application component JAR file. In this manner, multiple beans with the same ejb-name may be uniquely identified when the Application Assembler cannot change _ejb-name_s.

• Alternatively to the use of ejb-link, the Application Assembler may use the lookup-name element to reference the target enterprise bean component by means of one of its JNDI names. It is an error for both ejb-link and lookup-name to appear inside an ejb-ref element.

• The Application Assembler must ensure that the target enterprise bean is type-compatible with the declared Jakarta Enterprise Beans reference. This means that the target enterprise bean must be of the type indicated in the ejb-ref-type element, if present, and that the business interface, no-interface view, or home and remote interfaces of the target enterprise bean must be Java type-compatible with the type declared in the Jakarta Enterprise Bean reference.

The following example illustrates the use of the ejb-link element in the deployment descriptor. The enterprise bean reference should be satisfied by the bean named EmployeeRecord. The EmployeeRecord enterprise bean may be packaged in the same module as the component making this reference, or it may be packaged in another module within the same Jakarta EE application as the component making this reference.

...
<ejb-ref>
  <description>
     This is a reference to the entity bean that
     encapsulates access to employee records. It
     has been linked to the entity bean named
     EmployeeRecord in this application.
  </description>
  <ejb-ref-name>ejb/EmplRecord</ejb-ref-name>
  <ejb-ref-type>Entity</ejb-ref-type>
  <home>com.wombat.empl.EmployeeRecordHome</home>
  <remote>com.wombat.empl.EmployeeRecord</remote>
  <ejb-link>EmployeeRecord</ejb-link>
</ejb-ref>
...

The following example illustrates using the ejb-link element to indicate an enterprise bean reference to the ProductEJB enterprise bean that is in the same Jakarta EE application unit but in a different ejb-jar file.

...
<ejb-ref>
  <description>
     This is a reference to the entity bean that
     encapsulates access to a product. It
     has been linked to the entity bean named
     ProductEJB in the product.jar file in this
     application.
  </description>
  <ejb-ref-name>ejb/Product</ejb-ref-name>
  <ejb-ref-type>Entity</ejb-ref-type>
  <home>com.acme.products.ProductHome</home>
  <remote>com.acme.products.Product</remote>
  <ejb-link>../products/product.jar#ProductEJB</ejb-link>
</ejb-ref>
...

The following example illustrates using the ejb-link element to indicate an enterprise bean reference to the ShoppingCart enterprise bean that is in the same Jakarta EE application unit but in a different ejb-jar file. The reference was originally declared in the application component’s code using an annotation. The Assembler provides only the link to the bean.

...
<ejb-ref>
  <ejb-ref-name>ShoppingService/myCart</ejb-ref-name>
  <ejb-link>../products/product.jar#ShoppingCart</ejb-link>
</ejb-ref>
...

The same effect can be obtained by using the lookup-name element instead, using an appropriate JNDI name for the target bean.

...
<ejb-ref>
  <ejb-ref-name>ShoppingService/myCart</ejb-ref-name>
  <lookup-name>java:app/products/ShoppingCart</lookup-name>
</ejb-ref>
...

Deployer’s Responsibilities

The Deployer is responsible for the following:

• The Deployer must ensure that all the declared Jakarta Enterprise Beans references are bound to the business interfaces, no-interface views, or home interfaces of enterprise beans 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 enterprise bean.

• The Deployer must ensure that the target enterprise bean is type-compatible with the types declared for the Jakarta Enterprise Bean reference. This means that the target enterprise bean must be of the type indicated in the ejb-ref-type element or specified via the EJB annotation, and that the business interface, no-interface view, or home and remote interfaces of the target enterprise bean must be Java type-compatible with the type declared in the Jakarta Enterprise Bean reference (if specified).

• If a Jakarta Enterprise Bean reference declaration includes the ejb-link element, the Deployer should bind the enterprise bean reference to the enterprise bean specified as the link’s target. If an EJB annotation includes the lookup element or the Jakarta Enterprise Beans reference declaration includes the lookup-name element, the Deployer should bind the enterprise bean reference to the enterprise bean specified as the target of the lookup. It is an error for a Jakarta Enterprise Bean reference declaration to include both an ejb-link and a lookup-name element.

The following example illustrates the use of the lookup-name element to bind an ejb-ref to a target enterprise bean in the operational environment. The reference was originally declared in the bean’s code using an annotation. The target enterprise bean has ejb-name ShoppingCart and is deployed in the stand-alone module products.jar.

...
<ejb-ref>
  <ejb-ref-name>ShoppingService/myCart</ejb-ref-name>
  <lookup-name>java:global/products/ShoppingCart</lookup-name>
</ejb-ref>
...

Jakarta EE Product Provider’s Responsibilities

The Jakarta 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 Jakarta EE Product Provider must be able to process the information supplied in class file annotations and in the ejb-ref and ejb-local-ref elements in the deployment descriptor.

At the minimum, the tools must be able to:

• Preserve the application assembly information in annotations or in the ejb-link elements by binding a Jakarta Enterprise Bean reference to the business interface, no-interface view, or home interface of the specified target enterprise bean.

• Inform the Deployer of any unresolved Jakarta Enterprise Beans references, and allow him or her to resolve a Jakarta Enterprise Bean reference by binding it to a specified compatible target enterprise bean.

Web Service References

A web service reference is similar to an Jakarta Enterprise Bean reference, but is used to reference a web service. Web service references are fully specified in the Web Service specification and the Jakarta Web Service specification.

Resource Manager Connection Factory References

A resource manager connection factory is an object that is used to create connections to a resource manager. For example, an object that implements the javax.sql.DataSource interface is a resource manager connection factory for java.sql.Connection objects that implement connections to a database management system.

This section describes the application component programming and deployment descriptor interfaces that allow the application component code to refer to resource factories using logical names called resource manager connection factory references. The resource manager connection factory references are special entries in the application component’s environment. The Deployer binds the resource manager connection factory references to the actual resource manager connection factories that exist in the target operational environment. Because these resource manager connection factories allow the Container to affect resource management, the connections acquired through the resource manager connection factory references are called managed resources (for example, these resource manager connection factories allow the Container to implement connection pooling and automatic enlistment of the connection with a transaction).

Resource manager connection factory objects accessed through the naming environment are only valid within the component instance that performed the lookup. See the individual component specifications for additional restrictions that may apply.

Application Component Provider’s Responsibilities

This subsection describes the Application Component Provider’s view of locating resource factories and defines his or her responsibilities. It does so in three sections, the first describing the annotations used to inject resource manager connection factory references, the second describing the API for accessing resource manager connection factory references, and the third describing the syntax for declaring the factory references in a deployment descriptor

Injection of Resource Manager Connection Factory References

A field or a method of an application component may be annotated with the Resource annotation. The name and type of the factory are as described above. The authenticationType and shareable elements of the Resource annotation may be used to control the type of authentication desired for the resource and the shareability of connection acquired from the factory, as described in the following sections.

The following code example illustrates how an application component uses annotations to declare resource manager connection factory references.

// The employee database.
@Resource javax.sql.DataSource employeeAppDB;

public void changePhoneNumber(...) {
  ...
  // Invoke factory to obtain a resource. The security
  // principal for the resource is not given, and
  // therefore it will be configured by the Deployer.
  java.sql.Connection con = employeeAppDB.getConnection();
  ...
}

It is possible to specify as part of the @Resource annotation the JNDI name of an entry to which the resource being defined will be bound.

// The customer database, looked up in the application environment.
@Resource(lookup="java:app/env/customerDB")
javax.sql.DataSource customerAppDB;

The data source object being looked up in the previous example may have been declared as follows.

@Resource(name="java:app/env/customerDB",
          type=javax.sql.DataSource.class)
public class AnApplicationClass {
  ...
}

From a practical standpoint, declaring a commonly used data source at the application level and referring to it using lookup from multiple components may simplify the task of deploying the application, since now the Deployer will have to perform a single binding operation for the application-level resource, instead of multiple ones. The task can be further simplified by using a data source resource definition, see DataSource Resource Definition. Of course, nothing prevents the Deployer from separately binding each data source reference if necessary.

Programming Interfaces for Resource Manager Connection Factory References

The Application Component Provider may use resource manager connection factory references to obtain connections to resources as follows.

• Assign an entry in the application component’s naming environment to the resource manager connection factory reference. (See subsection Declaration of Resource Manager Connection Factory References in Deployment Descriptor for information on how resource manager connection factory references are declared in the deployment descriptor.)

• This specification recommends, but does not require, that all resource manager connection factory references be organized in the subcontexts of the application component’s environment, using a different subcontext for each resource manager type. For example, all JDBC™ DataSource references should be declared in the java:comp/env/jdbc subcontext, all Jakarta Messaging connection factories in the java:comp/env/jms subcontext, all Jakarta Mail connection factories in the java:comp/env/mail subcontext, and all URL connection factories in the java:comp/env/url subcontext. Note that resource manager connection factory references declared via annotations will not, by default, appear in any subcontext.

• Look up the resource manager connection factory object in the application component’s environment using the JNDI interface.

• Invoke the appropriate method on the resource manager connection factory object to obtain a connection to the resource. The factory method is specific to the resource type. It is possible to obtain multiple connections by calling the factory object multiple times.

The Application Component Provider can control the shareability of the connections acquired from the resource manager connection factory. By default, connections to a resource manager are shareable across other application components in the application that use the same resource in the same transaction context. The Application Component Provider can specify that connections obtained from a resource manager connection factory reference are not shareable by specifying the value of the shareable annotation element to false or the res-sharing-scope deployment descriptor element to be Unshareable. The sharing of connections to a resource manager allows the container to optimize the use of connections and enables the container’s use of local transaction optimizations.

The Application Component Provider has two choices with respect to dealing with associating a principal with the resource manager access:

• Allow the Deployer to set up principal mapping or resource manager sign on information. In this case, the application component code invokes a resource manager connection factory method that has no security-related parameters.

• Sign on to the resource from the application component code. In this case, the application component invokes the appropriate resource manager connection factory method that takes the sign on information as method parameters.

The Application Component Provider uses the authenticationType annotation element or the res-auth deployment descriptor element to indicate which of the two resource authentication approaches is used.

We expect that the first form (that is letting the Deployer set up the resource sign on information) will be the approach used by most application components.

The following code sample illustrates obtaining a JDBC connection.

public void changePhoneNumber(...) {
  ...
  // obtain the initial JNDI context
  Context initCtx = new InitialContext();

  // perform JNDI lookup to obtain resource manager
  // connection factory
  javax.sql.DataSource ds = (javax.sql.DataSource)
     initCtx.lookup("java:comp/env/jdbc/EmployeeAppDB");

  // Invoke factory to obtain a resource. The security
  // principal for the resource is not given, and
  // therefore it will be configured by the Deployer.
  java.sql.Connection con = ds.getConnection();
  ...
}

Declaration of Resource Manager Connection Factory References in Deployment Descriptor

Although a resource manager connection factory reference is an entry in the application component’s environment, the Application Component Provider must not use an env-entry element to declare it.

Instead, the Application Component Provider must declare all the resource manager connection factory references using either annotations on the application component’s code or in the deployment descriptor using the resource-ref elements. This allows the consumer of the application component’s JAR file (the Application Assembler or Deployer) to discover all the resource manager connection factory references used by an application component. Deployment descriptor entries may also be used to specify injection of a resource manager connection factory reference into an application component.

Each resource-ref element describes a single resource manager connection factory reference. The resource-ref element consists of the description element, the mandatory res-ref-name element, and the optional res-sharing-scope, res-type, and res-auth elements. The res-ref-name element contains the name of the environment entry used in the application component’s code. The name of the environment entry is relative to the java:comp/env context (for example, the name should be jdbc/EmployeeAppDB rather than java:comp/env/jdbc/EmployeeAppDB ). The res-type element contains the Java programming language type of the resource manager connection factory that the application component code expects. The res-type element is optional if an injection target is specified for this resource; in this case the res-type defaults to the type of the injection target. The res-auth element indicates whether the application component code performs resource sign on programmatically, or whether the container signs on to the resource based on the principal mapping information supplied by the Deployer. The Application Component Provider indicates the sign on responsibility by setting the value of the res-auth element to Application or Container. If not specified, the default is Container. The res-sharing-scope element indicates whether connections to the resource manager obtained through the given resource manager connection factory reference can be shared or whether connections are unshareable. The value of the res-sharing-scope element is Shareable or Unshareable. If the res-sharing-scope element is not specified, connections are assumed to be shareable.

A resource manager connection factory reference is scoped to the application component whose declaration contains the resource-ref element. This means that the resource manager connection factory reference is not accessible from other application components at runtime, and that other application components may define resource-ref elements with the same res-ref-name without causing a name conflict.

The type declaration allows the Deployer to identify the type of the resource manager connection factory.

Note that the indicated type is the Java programming language type of the resource manager connection factory, not the type of the connection.

The following example is the declaration of the resource reference used by the application component illustrated in the previous subsection.

...
<resource-ref>
  <description>
     A data source for the database in which
     the EmployeeService enterprise bean will
     record a log of all transactions.
  </description>
  <res-ref-name>jdbc/EmployeeAppDB</res-ref-name>
  <res-type>javax.sql.DataSource</res-type>
  <res-auth>Container</res-auth>
  <res-sharing-scope>Shareable</res-sharing-scope>
</resource-ref>
...

The following example modifies the previous one by linking the resource reference being defined to another one, using a well-known JNDI name for the latter.

...
<resource-ref>
  <res-ref-name>jdbc/EmployeeAppDB</res-ref-name>
  <res-type>javax.sql.DataSource</res-type>
  <res-auth>Container</res-auth>
  <res-sharing-scope>Shareable</res-sharing-scope>
  <lookup-name>java:app/env/TheEmployeeDB</lookup-name>
</resource-ref>
...

Standard Resource Manager Connection Factory Types

The Application Component Provider must use the javax.sql.DataSource resource manager connection factory type for obtaining JDBC API connections.

The Application Component Provider must use the jakarta.jms.ConnectionFactory, the jakarta.jms.QueueConnectionFactory, or the jakarta.jms.TopicConnectionFactory for obtaining Jakarta Messaging connections.

The Application Component Provider must use the jakarta.mail.Session resource manager connection factory type for obtaining Jakarta Mail API connections.

The Application Component Provider must use the java.net.URL resource manager connection factory type for obtaining URL connections.

It is recommended that the Application Component Provider name JDBC API data sources in the java:comp/env/jdbc subcontext, all Jakarta Messaging connection factories in the java:comp/env/jms subcontext, all Jakarta Mail API connection factories in the java:comp/env/mail subcontext, and all URL connection factories in the java:comp/env/url subcontext. Note that resource manager connection factory references declared via annotations will not, by default, appear in any subcontext.

The Jakarta EE Connector Architecture allows an application component to use the annotation or API described in this section to obtain resource objects that provide access to additional back-end systems.

Deployer’s Responsibilities

The Deployer uses deployment tools to bind the resource manager connection factory references to the actual resource factories configured in the target operational environment.

The Deployer must perform the following tasks for each resource manager connection factory reference declared in the deployment descriptor:

• Bind the resource manager connection factory reference to a resource manager connection factory that exists 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 resource manager connection factory. The resource manager connection factory type must be compatible with the type declared in the source code or in the res-type element. If the resource manager connection factory references includes a lookup annotation element or a lookup-name deployment descriptor element, the Deployer may choose whether to honor it and have the corresponding lookup be performed, or override it with a binding of his or her own choosing.

• Provide any additional configuration information that the resource manager needs for opening and managing the resource. The configuration mechanism is resource manager specific, and is beyond the scope of this specification.

• If the value of the Resource annotation authenticationType element is AuthenticationType.CONTAINER or the deployment descriptor’s res-auth element is Container, the Deployer is responsible for configuring the sign on information for the resource manager. This is performed in a manner specific to the container and resource manager; it is beyond the scope of this specification.

For example, if principals must be mapped from the security domain and principal realm used at the application component level to the security domain and principal realm of the resource manager, the Deployer or System Administrator must define the mapping. The mapping is performed in a manner specific to the container and resource manager; it is beyond the scope of this specification.

Jakarta EE Product Provider’s Responsibilities

The Jakarta EE Product Provider is responsible for the following:

• Provide the deployment tools that allow the Deployer to perform the tasks described in the previous subsection.

• Provide the implementation of the resource manager connection factory classes that are required by this specification.

• If the Application Component Provider sets the authenticationType element of the Resource annotation to AuthenticationType.APPLICATION or the res-auth of a resource reference to Application, the container must allow the application component to perform explicit programmatic sign on using the resource manager’s API.

• If the Application Component Provider sets the shareable element of the Resource annotation to false or sets the res-sharing-scope of a resource manager connection factory reference to Unshareable, the container must not attempt to share the connections obtained from the resource manager connection factory reference.^[9]

• The container must provide tools that allow the Deployer to set up resource sign on information for the resource manager references whose authenticationType is set to AuthenticationType.CONTAINER or whose res-auth element is set to Container. The minimum requirement is that the Deployer must be able to specify the username/password information for each resource manager connection factory reference declared by the application component, and the container must be able to use the username/password combination for user authentication when obtaining a connection by invoking the resource manager connection factory.

Although not required by this specification, we expect that containers will support some form of a single sign on mechanism that spans the application server and the resource managers. The container will allow the Deployer to set up the resources such that the principal can be propagated (directly or through principal mapping) to a resource manager, if required by the application.

While not required by this specification, most Jakarta EE products will provide the following features:

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

• A mechanism to pool resources for the application components and otherwise manage the use of resources by the container. The pooling must be transparent to the application components.

System Administrator’s Responsibilities

The System Administrator is typically responsible for the following:

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

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

Resource Environment References

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.

Application Component Provider’s Responsibilities

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

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.

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 Declaration of Resource Environment References in Deployment Descriptor for information on how resource environment references are declared in the deployment descriptor.)

• This specification recommends, but does not require, that all resource environment references be organized in the appropriate subcontext of the component’s environment for the resource type. Note that resource environment references declared via annotations will not, by default, appear in any subcontext.

• Look up the administered object in the application component’s environment using JNDI.

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.

Deployer’s Responsibilities

The Deployer is responsible for the following:

• The Deployer must ensure that all the declared resource environment references 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 includes a lookup annotation element or lookup-name deployment descriptor element.

• The Deployer must ensure that the target object is type-compatible with the type declared for the resource environment reference. This means that the target object must be of the type indicated in the Resource annotation or the resource-env-ref-type element.

Jakarta EE Product Provider’s Responsibilities

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

Message Destination References

This section describes the programming and deployment descriptor interfaces that allow the Application Component Provider to refer to message destination objects by using “logical” names called message destination references. Message destination references are special entries in the application component’s environment. The Deployer binds the message destination references to administered message destinations in the target operational environment.

The requirements in this section only apply to Jakarta EE products that include support for Jakarta Messaging.

Application Component Provider’s Responsibilities

This subsection describes the Application Component Provider’s view and responsibilities with respect to message destination references.

Injection of Message Destination References

A field or a method of an application component may be annotated with the Resource annotation to request injection of a message destination 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; message destination references are not shareable and do not require authentication.

Note that when using the Resource annotation to declare a message destination reference it is not possible to link the reference to other references to the same message destination or to specify whether the message destination is used to produce or consume messages. The deployment descriptor entries described later do provide a way to associate many message destination references with a single message destination and to specify whether each message destination reference is used to produce, consume, or both produce and consume messages, so that the entire message flow of an application may be specified. The Application Assembler may use these message destination links to link together message destination references that have been declared using the Resource annotation. A message destination reference declared via the Resource annotation is assumed to be used to both produce and consume messages; this default may be overridden using a deployment descriptor entry.

The following example illustrates how an application component uses the Resource annotation to request injection of a message destination reference.

@Resource jakarta.jms.Queue stockQueue;

The following example illustrates how a message destination reference can be linked to another one by specifying its JNDI name, perhaps in a different namespace, as a value for the lookup element.

@Resource(lookup="java:app/env/TheOrderQueue")
jakarta.jms.Queue orderQueue;

Message Destination Reference Programming Interfaces

The Application Component Provider may use message destination references to locate message destinations, as follows.

• Assign an entry in the application component’s environment to the reference. (See subsection Declaration of Message Destination References in Deployment Descriptor for information on how message destination references are declared in the deployment descriptor.)

• This specification recommends, but does not require, that all message destination references be organized in the appropriate subcontext of the component’s environment for the resource type (for example, in the java:comp/env/jms JNDI context for Jakarta Messaging Destinations). Note that message destination references declared via annotations will not, by default, appear in any subcontext.

• Look up the administered object in the application component’s environment using JNDI.

The following example illustrates how an application component uses a message destination reference to locate a Jakarta Messaging Destination.

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

// Look up the Jakarta Messaging StockQueue in the environment.
Object result = initCtx.lookup("java:comp/env/jms/StockQueue");

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

In the example, the Application Component Provider assigned the environment entry jms/StockQueue as the message destination reference name to refer to a Jakarta Messaging queue.

Declaration of Message Destination References in Deployment Descriptor

Although the message destination 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 should declare all references to message destinations using either the Resource annotation in the application component’s code or the message-destination-ref elements of the deployment descriptor. This allows the application component’s JAR file consumer to discover all the message destination references used by the application component. Deployment descriptor entries may also be used to specify injection of a message destination reference into an application component.

Each message-destination-ref element describes the requirements that the referencing application component has for the referenced destination. The message-destination-ref element contains optional description, message-destination-type, and message-destination-usage elements and the mandatory message-destination-ref-name element.

The message-destination-ref-name element specifies the message destination reference name. Its value is the environment entry name used in the application component code. By default, the name of the message destination reference is relative to the java:comp/env context (for example, the name should be jms/StockQueue rather than java:comp/env/jms/StockQueue ). The message-destination-type element specifies the expected type of the referenced destination. For example, in the case of a Jakarta Messaging Destination, its value might be jakarta.jms.Queue. The message-destination-type element is optional if an injection target is specified for this message destination reference; in this case the message-destination-type defaults to the type of the injection target. The message-destination-usage element specifies whether messages are consumed from the message destination, produced for the destination, or both. If not specified, messages are assumed to be both consumed and produced.

A message destination reference is scoped to the application component whose declaration contains the message-destination-ref element. This means that the message destination reference is not accessible to other application components at runtime, and that other application components may define message-destination-ref elements with the same message-destination-ref-name without causing a name conflict.

The following example illustrates the declaration of message destination references in the deployment descriptor.

...
<message-destination-ref>
  <description>
     This is a reference to a Jakarta Messaging queue used in the
     processing of Stock info
  </description>
  <message-destination-ref-name>
     jms/StockInfo
  </message-destination-ref-name>
  <message-destination-type>
     jakarta.jms.Queue
  </message-destination-type>
  <message-destination-usage>
     Produces
  </message-destination-usage>
</message-destination-ref>
...

Application Assembler’s Responsibilities

By means of linking message consumers and producers to one or more common logical destinations specified in the enterprise bean deployment descriptor, the Application Assembler can specify the flow of messages within an application. The Application Assembler uses the message-destination element, the message-destination-link element of the message-destination-ref element, and the message-destination-link element of an ejb-jar’s message-driven element to link message destination references to a common logical destination.

The Application Assembler specifies the link between message consumers and producers as follows:

• The Application Assembler uses the message-destination element to specify a logical message destination within the application. The message-destination element defines a message-destination-name, which is used for the purpose of linking.

• The Application Assembler uses the message-destination-link element of the message-destination-ref element of an application component that produces messages to link it to the target destination. The value of the message-destination-link element is the name of the target destination, as defined in the message-destination-name element of the message-destination element. The message-destination element can be in any module in the same Jakarta EE application as the referencing component. The Application Assembler uses the message-destination-usage element of the message-destination-ref element to indicate that the referencing application component produces messages to the referenced destination.

• If the consumer of messages from the common destination is a message-driven bean, the Application Assembler uses the message-destination-link element of the message-driven element to reference the logical destination. If the Application Assembler links a message-driven bean to its source destination, he or she should use the message-destination-type element of the message-driven element to specify the expected destination type. Otherwise, the Application Assembler uses the message-destination-link element of the message-destination-ref element of the application component that consumes messages to link to the common destination. In the latter case, the Application Assembler uses the message-destination-usage element of the message-destination-ref element to indicate that the application component consumes messages from the referenced destination.

• To avoid the need to rename message destinations to have unique names within an entire Jakarta EE application, the Application Assembler may use the following syntax in the message-destination-link element of the referencing application component. The Application Assembler specifies the path name of the JAR file containing the referenced message destination and appends the message-destination-name of the target destination separated from the path name by #. The path name is relative to the referencing application component JAR file. In this manner, multiple destinations with the same message-destination-name may be uniquely identified.

• When linking message destinations, the Application Assembler must ensure that the consumers and producers for the destination require a message destination of the same or compatible type, as determined by the messaging system.

Deployer’s Responsibilities

The Deployer is responsible for the following:

• The Deployer must ensure that all the declared message destination references 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 message destination reference that includes a lookup-name element.

• The Deployer must ensure that the target object is type-compatible with the type declared for the message destination reference. This means that the target object must be of the type indicated in the message-destination-type element.

• The Deployer must observe the message destination links specified by the Application Assembler.

Jakarta EE Product Provider’s Responsibilities

The Jakarta 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 Jakarta EE Product Provider must be able to process the information supplied in the message-destination-ref elements in the deployment descriptor.

At the minimum, the tools must be able to inform the Deployer of any unresolved message destination references, and allow him or her to resolve a message destination reference by binding it to a specified compatible target object in the environment.

UserTransaction References

Certain Jakarta EE application component types are allowed to use the Jakarta Transactions UserTransaction interface to start, commit, and abort transactions. Such application components can find an appropriate object implementing the UserTransaction interface by looking up the JNDI name java:comp/UserTransaction or by requesting injection of a UserTransaction object using the Resource annotation. The authenticationType and shareable elements of the Resource annotation must not be specified. The container is only required to provide the java:comp/UserTransaction name, or inject a UserTransaction object, for those components that can validly make use of it. Any such reference to a UserTransaction object is only valid within the component instance that performed the lookup. See the individual component definitions for further information.

The following example illustrates how an application component acquires and uses a UserTransaction object via injection.

@Resource UserTransaction tx;
public void updateData(...) {
  ...
  // Start a transaction.
  tx.begin();
  ...
  // Perform transactional operations on data.
  ...
  // Commit the transaction.
  tx.commit();
  ...
}

The following example illustrates how an application component acquires and uses a UserTransaction object using a JNDI lookup.

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

  // Look up the UserTransaction object.
  UserTransaction tx = (UserTransaction)initCtx.lookup(
                                 "java:comp/UserTransaction");

  // Start a transaction.
  tx.begin();
  ...
  // Perform transactional operations on data.
  ...
  // Commit the transaction.
  tx.commit();
  ...
}

A UserTransaction object reference may also be declared in a deployment descriptor in the same way as a resource environment reference. Such a deployment descriptor entry may be used to specify injection of a UserTransaction object.

The requirements in this section only apply to Jakarta EE products that include support for Jakarta Transactions.

Application Component Provider’s Responsibilities

The Application Component Provider is responsible for requesting injection of a UserTransaction object using a Resource annotation, or using the defined name to look up the UserTransaction object.

Only some application component types are required to be able to access a UserTransaction object; see Jakarta EE Technologies in this specification and the Jakarta Enterprise Beans specification for details.

Jakarta EE Product Provider’s Responsibilities

The Jakarta EE Product Provider is responsible for providing an appropriate UserTransaction object as required by this specification.

TransactionSynchronizationRegistry References

The Jakarta Transactions TransactionSynchronizationRegistry interface may be used by system level components such as persistence managers that may be packaged with enterprise bean or web application components. Such components can find an appropriate object implementing the TransactionSynchronizationRegistry interface by looking up the JNDI name java:comp/TransactionSynchronizationRegistry or by requesting injection of a TransactionSynchronizationRegistry object using the Resource annotation. The authenticationType and shareable elements of the Resource annotation must not be specified. The container is only required to provide the java:comp/TransactionSynchronizationRegistry name, or inject a TransactionSynchronizationRegistry object, for those components that can validly make use of it. Any such reference to a TransactionSynchronizationRegistry object is only valid within the component instance that performed the lookup. See the individual component definitions for further information.

A TransactionSynchronizationRegistry object reference may also be declared in a deployment descriptor in the same way as a resource environment reference. Such a deployment descriptor entry may be used to specify injection of a TransactionSynchronizationRegistry object.

The requirements in this section only apply to Jakarta EE products that include support for Jakarta Transactions.

Application Component Provider’s Responsibilities

The Application Component Provider is responsible for requesting injection of a TransactionSynchronizationRegistry object using a Resource annotation, or using the defined name to look up the TransactionSynchronizationRegistry object.

Only some application component types are required to be able to access a TransactionSynchronizationRegistry object; see Jakarta EE Technologies in this specification for details.

Jakarta EE Product Provider’s Responsibilities

The Jakarta EE Product Provider is responsible for providing an appropriate TransactionSynchronizationRegistry object as required by this specification.

ORB References (optional)

Note	Support for CORBA as an application service is optional.

Some Jakarta EE applications will need to make use of the CORBA ORB to perform certain operations. Such applications can find an appropriate object implementing the ORB interface by looking up the JNDI name java:comp/ORB or by requesting injection of an ORB object. The container is required to provide the java:comp/ORB name for all components. Any such reference to a ORB object is only valid within the component instance that performed the lookup.

The following example illustrates how an application component acquires and uses an ORB object via injection.

@Resource ORB orb;
public void method(...) {
  ...
  // Get the POA to use when creating object references.
  POA rootPOA = (POA)orb.resolve_initial_references("RootPOA");
  ...
}

The following example illustrates how an application component acquires and uses an ORB object using a JNDI lookup.

public void method(...) {
  ...
  // Obtain the default initial JNDI context.
  Context initCtx = new InitialContext();
  // Look up the ORB object.
  ORB orb = (ORB)initCtx.lookup("java:comp/ORB");
  // Get the POA to use when creating object references.
  POA rootPOA = (POA)orb.resolve_initial_references("RootPOA");
  ...
}

An ORB object reference may also be declared in a deployment descriptor in the same way as a resource manager connection factory reference. Such a deployment descriptor entry may be used to specify injection of an ORB object.

The ORB instance available under the JNDI name java:comp/ORB may always be a shared instance. By default, the ORB instance injected into a component or declared via a deployment descriptor entry may also be a shared instance. However, the application may set the shareable element of the Resource annotation to false , or may set the res-sharing-scope element in the deployment descriptor to Unshareable , to request a non-shared ORB instance.

Application Component Provider’s Responsibilities

The Application Component Provider is responsible for requesting injection of the ORB object using the Resource annotation, or using the defined name to look up the ORB object. If the shareable element of the Resource annotation is set to false , the ORB object injected will not be the shared instance used by other components in the application but instead will be a private ORB instance used only by this component.

Jakarta EE Product Provider’s Responsibilities

The Jakarta EE Product Provider is responsible for providing an appropriate ORB object as required by this specification.

Persistence Unit References

This section describes the metadata annotations and deployment descriptor elements that allow the application component code to refer to the entity manager factory for a persistence unit using a logical name called a persistence unit reference. Persistence unit references are special entries in the application component’s environment. The Deployer binds the persistence unit references to entity manager factories that are configured in accordance with the persistence.xml specification for the persistence unit, as described in the Jakarta Persistence specification.

The requirements in this section only apply to Jakarta EE products that include support for the Jakarta Persistence API.

Application Component Provider’s Responsibilities

This subsection describes the Application Component Provider’s view of locating the entity manager factory for a persistence unit and defines his or her responsibilities. The first subsection describes annotations for injecting references to an entity manager factory for a persistence unit; the second describes the API for accessing an entity manager factory using a persistence unit reference; and the third describes syntax for declaring persistence unit references in a deployment descriptor.

Injection of Persistence Unit References

A field or a method of an application component may be annotated with the PersistenceUnit annotation. The name element specifies the name under which the entity manager factory for the referenced persistence unit may be located in the JNDI naming context. The optional unitName element specifies the name of the persistence unit as declared in the persistence.xml file that defines the persistence unit.

The following code example illustrates how an application component uses annotations to declare persistence unit references.

@PersistenceUnit
EntityManagerFactory emf;

@PersistenceUnit(unitName="InventoryManagement")
EntityManagerFactory inventoryEMF;

Programming Interfaces for Persistence Unit References

The Application Component Provider must use persistence unit references to obtain references to entity manager factories as follows.

• Assign an entry in the application component’s environment to the persistence unit reference. (See subsection Declaration of Persistence Unit References in Deployment Descriptor for information on how persistence unit references are declared in the deployment descriptor.) It is recommended that the Application Component Provider organize all persistence unit references in the java:comp/env/persistence subcontext of the component’s environment.

• Lookup the entity manager factory for the persistence unit in the application component’s environment using JNDI.

• Invoke the appropriate method on the entity manager factory to obtain an entity manager instance.

The following code sample illustrates obtaining an entity manager factory.

@PersistenceUnit(name="persistence/InventoryAppDB")
@Stateless
public class InventoryManagerBean implements InventoryManager {
  EJBContext ejbContext;
  ...
  public void updateInventory(...) {
    ...
    // obtain the initial JNDI context
    Context initCtx = new InitialContext();

    // perform JNDI lookup to obtain entity manager factory
    EntityManagerFactory = (EntityManagerFactory)
       initCtx.lookup(
          "java:comp/env/persistence/InventoryAppDB");

    // use factory to obtain application-managed entity manager
    EntityManager em = emf.createEntityManager();
    ...
  }
}

Declaration of Persistence Unit References in Deployment Descriptor

Although a persistence unit reference is an entry in the application component’s environment, the Application Component Provider must not use an env-entry element to declare it.

Instead, if metadata annotations are not used, the Application Component Provider must declare all the persistence unit references in the deployment descriptor using the persistence-unit-ref elements. This allows the Application Assembler or Deployer to discover all the persistence unit references used by an application component. Deployment descriptor entries may also be used to specify injection of a persistence unit reference into an application component.

Each persistence-unit-ref element describes a single entity manager factory reference for the persistence unit. The persistence-unit-ref element consists of the optional description and persistence-unit-name elements, and the mandatory persistence-unit-ref-name element.

The persistence-unit-ref-name element contains the name of the environment entry used in the application component’s code. The name of the environment entry is relative to the java:comp/env context (e.g., the name should be persistence/InventoryAppDB rather than java:comp/env/persistence/InventoryAppDB ). The persistence-unit-name element is the name of the persistence unit, as specified in the persistence.xml file for the persistence unit.

The following example is the declaration of a persistence unit reference used by the InventoryManager enterprise bean illustrated in the previous subsection.

...
  <persistence-unit-ref>
    <description>
       Persistence unit for the inventory management
       application.
    </description>
    <persistence-unit-ref-name>
       persistence/InventoryAppDB
    </persistence-unit-ref-name>
    <persistence-unit-name>
       InventoryManagement
    </persistence-unit-name>
  </persistence-unit-ref>
...

Application Assembler’s Responsibilities

The Application Assembler can use the persistence-unit-name element in the deployment descriptor to disambiguate a reference to a persistence unit. The Application Assembler (or Application Component Provider) may use the following syntax in the persistence-unit-name element of the referencing application component to avoid the need to rename persistence units to have unique names within a Jakarta EE application. The Application Assembler specifies the path name of the root of the persistence.xml file for the referenced persistence unit and appends the name of the persistence unit separated from the path name by #. The path name is relative to the referencing application component jar file. In this manner, multiple persistence units with the same persistence unit name may be uniquely identified when the Application Assembler cannot change persistence unit names.

For example,

...
  <persistence-unit-ref>
    <description>
       Persistence unit for the inventory management
       application.
    </description>
    <persistence-unit-ref-name>
       persistence/InventoryAppDB
    </persistence-unit-ref-name>
    <persistence-unit-name>
       ../lib/inventory.jar#InventoryManagement
    </persistence-unit-name>
  </persistence-unit-ref>
...

The Application Assembler uses the persistence-unit-name element to link the persistence unit name InventoryManagement declared in the InventoryManagerBean to the persistence unit named InventoryManagement defined in inventory.jar .

The following rules apply to how a deployment descriptor entry may override a PersistenceUnit annotation:

• The relevant deployment descriptor entry is located based on the JNDI name used with the annotation (either defaulted or provided explicitly).

• The persistence-unit-name overrides the unitName element of the annotation. The Application Assembler or Deployer should exercise caution in changing this value, if specified, as doing so is likely to break the application.

• The injection target, if specified, must name exactly the annotated field or property method.

Deployer’s Responsibility

The Deployer uses deployment tools to bind a persistence unit reference to the actual entity manager factory configured for the persistence unit in the target operational environment.

The Deployer must perform the following tasks for each persistence unit reference declared in the metadata annotations or deployment descriptor:

• Bind the persistence unit reference to an entity manager factory configured for the persistence unit that exists 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 entity manager factory.

• If the persistence unit name is specified, the Deployer should bind the persistence unit reference to the entity manager factory for the persistence unit specified as the target.

• Provide any additional configuration information that the entity manager factory needs for managing the persistence unit, as described in the Jakarta Persistence specification.

Jakarta EE Product Provider’s Responsibility

The Jakarta EE Product Provider is responsible for the following:

• Provide the deployment tools that allow the Deployer to perform the tasks described in the previous subsection.

• Provide the implementation of the entity manager factory classes for the persistence units that are configured with the container. The implementation of the entity manager factory classes may be provided by the container directly or by the container in conjunction with a third-party persistence provider, as described in the Jakarta Persistence specification.

System Administrator’s Responsibility

The System Administrator is typically responsible for the following:

• Add, remove, and configure entity manager factories in the server environment.

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

Persistence Context References

This section describes the metadata annotations and deployment descriptor elements that allow the application component code to refer to a container-managed entity manager of a specified persistence context type using a logical name called a persistence context reference. Persistence context references are special entries in the application component’s environment. The Deployer binds the persistence context references to container-managed entity managers for persistence contexts of the specified type and configured in accordance with their persistence unit, as described in the Jakarta Persistence specification.

The requirements in this section only apply to Jakarta EE products that include support for the Jakarta Persistence API.

Application Component Provider’s Responsibilities

This subsection describes the Application Component Provider’s view of locating container-managed entity managers and defines his or her responsibilities. The first subsection describes annotations for injecting references to container-managed entity managers; the second describes the API for accessing references to container-managed entity managers; and the third describes syntax for declaring these references in a deployment descriptor.

Injection of Persistence Context References

A field or a method of an application component may be annotated with the PersistenceContext annotation. The name element specifies the name under which a container-managed entity manager for the referenced persistence unit may be located in the JNDI naming context. The optional unitName element specifies the name of the persistence unit as declared in the persistence.xml file that defines the persistence unit. The optional type element specifies whether a transaction-scoped or extended persistence context is to be used. If the type is not specified, a transaction-scoped persistence context will be used. References to container-managed entity managers with extended persistence contexts can only be injected into stateful session beans. The optional synchronization element specifies whether the persistence context is always automatically synchronized with the current transaction or whether it must be explicitly joined to the transaction. If the synchronization element is not specified, the persistence context will be automatically synchronized. The optional properties element specifies configuration properties to be passed to the persistence provider when the entity manager is created.

The following code example illustrates how an application component uses annotations to declare persistence context references.

@PersistenceContext(type=EXTENDED)
EntityManager em;

Programming Interfaces for Persistence Context References

The Application Component Provider may use a persistence context reference to obtain a reference to a container-managed entity manager configured for a persistence unit as follows:

• Assign an entry in the application component’s environment to the persistence context reference. (See subsection Declaration of Persistence Context References in Deployment Descriptor for information on how persistence context references are declared in the deployment descriptor.) It is recommended that the Application Component Provider organize all persistence context references in the java:comp/env/persistence subcontext of the component’s environment.

• Lookup the container-managed entity manager for the persistence unit in the application component’s environment using the JNDI API.

The following code sample illustrates obtaining an entity manager for a persistence context.

@PersistenceContext(name="persistence/InventoryAppMgr")
@Stateless
public class InventoryManagerBean implements InventoryManager {

  public void updateInventory(...) {
    ...

    // obtain the initial JNDI context
    Context initCtx = new InitialContext();

    // JNDI lookup to obtain container-managed entity manager
    EntityManager = (EntityManager)
       initCtx.lookup(
          "java:comp/env/persistence/InventoryAppMgr");
    ...
  }
}

Declaration of Persistence Context References in Deployment Descriptor

Although a persistence context reference is an entry in the application component’s environment, the Application Component Provider must not use an env-entry element to declare it.

Instead, if metadata annotations are not used, the Application Component Provider must declare all the persistence context references in the deployment descriptor using the persistence-context-ref elements. This allows the Application Assembler or Deployer to discover all the persistence context references used by an application component. Deployment descriptor entries may also be used to specify injection of a persistence context reference into a bean.

Each persistence-context-ref element describes a single container-managed entity manager reference. The persistence-context-ref element consists of the optional description, persistence-unit-name, persistence-context-type, persistence-context-synchronization, and persistence-property elements, and the mandatory persistence-context-ref-name element.

The persistence-context-ref-name element contains the name of the environment entry used in the application component’s code. The name of the environment entry is relative to the java:comp/env context (e.g., the name should be persistence/InventoryAppMgr rather than java:comp/env/persistence/InventoryAppMgr ). The persistence-unit-name element is the name of the persistence unit, as specified in the persistence.xml file for the persistence unit. The persistence-context-type element specifies whether a transaction-scoped or extended persistence context is to be used. Its value is either Transaction or Extended. If the persistence context type is not specified, a transaction-scoped persistence context will be used. The optional persistence-context-synchronization element specifies whether the persistence context is automatically synchronized with the current transaction. Its value is either Synchronized or Unsynchronized. If the persistence context synchronization is not specified, the persistence context will be automatically synchronized. The optional persistence-property elements specify configuration properties that are passed to the persistence provider when the entity manager is created.

The following example is the declaration of a persistence context reference used by the InventoryManager enterprise bean illustrated in the previous subsection.

...
  <persistence-context-ref>
    <description>
       Persistence context for the inventory management
       application.
    </description>
    <persistence-context-ref-name>
       persistence/InventoryAppDB
    </persistence-context-ref-name>
    <persistence-unit-name>
       InventoryManagement
    </persistence-unit-name>
  </persistence-context-ref>
...

Application Assembler’s Responsibilities

The Application Assembler can use the persistence-unit-name element in the deployment descriptor to specify a reference to a persistence unit using the syntax described in Application Assembler’s Responsibilities. In this manner, multiple persistence units with the same persistence unit name may be uniquely identified when the persistence unit names cannot be changed.

For example,

...
  <persistence-context-ref>
    <description>
       Persistence context for the inventory management
       application.
    </description>
    <persistence-context-ref-name>
       persistence/InventoryAppDB
    </persistence-context-ref-name>
    <persistence-unit-name>
       ../lib/inventory.jar#InventoryManagement
    </persistence-unit-name>
  </persistence-context-ref>
...

The Application Assembler uses the persistence-unit-name element to link the persistence unit name InventoryManagement declared in the InventoryManagerBean to the persistence unit named InventoryManagement defined in inventory.jar .

The following rules apply to how a deployment descriptor entry may override a PersistenceContext annotation:

• The relevant deployment descriptor entry is located based on the JNDI name used with the annotation (either defaulted or provided explicitly).

• The persistence-unit-name overrides the unitName element of the annotation. The Application Assembler or Deployer should exercise caution in changing this value, if specified, as doing so is likely to break the application.

• The persistence-context-type, if specified, overrides the type element of the annotation. In general, the Application Assembler or Deployer should never change the value of this element, as doing so is likely to break the application.

• The persistence-context-synchronization, if specified, overrides the synchronization element of the annotation. In general, the Application Assembler or Deployer should never change the value of this element, as doing so is likely to break the application.

• Any persistence-property elements are added to those specified by the PersistenceContext annotation. If the name of a specified property is the same as one specified by the PersistenceContext annotation, the value specified in the annotation is overridden.

• The injection target, if specified, must name exactly the annotated field or property method.

Deployer’s Responsibility

The Deployer uses deployment tools to bind a persistence context reference to the container-managed entity manager for the persistence context of the specified type and configured for the persistence unit in the target operational environment.

The Deployer must perform the following tasks for each persistence context reference declared in the metadata annotations or deployment descriptor:

• Bind the persistence context reference to a container-managed entity manager for a persistence context of the specified type and configured for the persistence unit as specified in the persistence.xml file for the persistence unit that exists 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 entity manager.

• If the persistence unit name is specified, the Deployer should bind the persistence context reference to an entity manager for the persistence unit specified as the target.

• Provide any additional configuration information that the entity manager factory needs for creating such an entity manager and for managing the persistence unit, as described in the Jakarta Persistence specification.

Jakarta EE Product Provider’s Responsibility

The Jakarta EE Product Provider is responsible for the following:

• Provide the deployment tools that allow the Deployer to perform the tasks described in the previous subsection.

• Provide the implementation of the entity manager classes for the persistence units that are configured with the container. This implementation may be provided by the container directory or by the container in conjunction with a third-party persistence provider, as described in the Jakarta Persistence specification.

System Administrator’s Responsibility

The System Administrator is typically responsible for the following:

• Add, remove, and configure entity manager factories in the server environment.

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

Application Name and Module Name References

A component may access the name of the current application using the pre-defined JNDI name java:app/AppName. A component may access the name of the current module using the pre-defined JNDI name java:module/ModuleName. Both of these names are represented by String objects.

Application Component Provider’s Responsibilities

The Application Component Provider is responsible for requesting injection of the application name or module name using a Resource annotation on a String method or field, or using the defined name to look up the application name or module name.

Jakarta EE Product Provider’s Responsibilities

The Jakarta EE Product Provider is responsible for providing the correct application name and module name String objects as required by this specification.

Application Client Container Property

An application may determine whether it is executing in a Jakarta EE application client container by using the pre-defined JNDI name java:comp/InAppClientContainer. This property is represented by a Boolean object. If the application is running in a Jakarta EE application client container, the value of this property is true. If the application is running in a Jakarta EE web or enterprise bean container, the value of this property is false.

Application Component Provider’s Responsibilities

The Application Component Provider is responsible for requesting injection of the application client container property using a Resource annotation on a Boolean or boolean method or field, or using the defined name to look up the application client container property.

Jakarta EE Product Provider’s Responsibilities

The Jakarta EE Product Provider is responsible for providing the correct application client container property as required by this specification.

Validator and Validator Factory References

This section describes the metadata annotations and deployment descriptor entries that allow an application to obtain instances of the Validation Validator and ValidatorFactory types.

Applications that need to use those interfaces can find appropriate objects by looking up the name java:comp/Validator for Validator and java:comp/ValidatorFactory for ValidatorFactory, or by requesting the injection of an object of the appropriate type via the Resource annotation. The authenticationType and shareable elements of the Resource annotation must not be specified.

@Resource ValidatorFactory validatorFactory;

@Resource Validator validator;

For Validator objects, the default validation context is used. This means that all such Validators will be equivalent to those obtained by first acquiring a ValidatorFactory and then invoking the getValidator method on it with no arguments.

In other words, the following two code snippets are equivalent:

// obtaining a Validator directly
Context initCtx = new InitialContext();
Validator validator = (Validator)initCtx.lookup(
                            "java:comp/Validator");

// obtaining a Validator from a ValidatorFactory
Context initCtx = new InitialContext();
Validator validator =
       ((ValidatorFactory) initCtx.lookup(
                             "java:comp/ValidatorFactory"))
       .getValidator();

A Validator or ValidatorFactory object reference may also be declared in a deployment descriptor in the same way as a resource environment reference.

In order to customize the returned ValidatorFactory, a Jakarta Enterprise Beans, web or application client module may specify a Validation XML deployment descriptor, as described in the Validation specification.

A validation deployment descriptor only affects ValidatorFactory instances in that module.

There is no per-application validation deployment descriptor.

Application Component Provider’s Responsibilities

The Application Component Provider is responsible for requesting injection of a Validator or of a ValidatorFactory using a Resource annotation, or using the defined names to look up a Validator or ValidatorFactory instance.

The Application Component Provider may customize the ValidatorFactory and (indirectly) Validator instances by including a Validation deployment descriptor inside a specific module of the application.

Jakarta EE Product Provider’s Responsibilities

The Jakarta EE Product Provider must make a default ValidatorFactory available at java:comp/ValidatorFactory. The default ValidatorFactory available at java:comp/ValidatorFactory must support use of CDI if CDI is enabled for the module. In particular, all of the classes specified by the jakarta.validation.BootstrapConfiguration interface must be created as non-contextual objects using CDI, as described in Support for Dependency Injection. These objects must be used to configure the default ValidatorFactory available at java:comp/ValidatorFactory in accordance with the bootstrapping APIs described by the Validation specification.

The default ValidatorFactory is a single instance per module; each lookup of java:comp/ValidatorFactory returns the same instance.

The default Validator is created by the default ValidatoryFactory using the getValidator method. Each lookup of java:comp/Validator returns a new Validator instance.

Resource Definition and Configuration

In addition to referencing resources as defined in this chapter, an application may specify the definition and configuration of resources that it requires in its operational environment.

Each application has a set of “physical” resources and services that it depends on (database storage, queueing, mail, etc.) and which need to be made available to it when it is deployed. Such resources may be scoped to the application instance or may be shareable. An application may define a dependency upon such resources in its environment by means of resource definition metadata.

The specification of resource definition metadata provides information that can be used at the application’s deployment to provision and configure the required resource. Further, resource definitions allow an application to be deployed into a Jakarta EE environment with more minimal administrative configuration.

Resources may be defined in any of the JNDI namespaces described in Application Component Environment Namespaces. For example, a resource may be defined:

in the java:comp namespace, for use by a single component;

• in the java:module namespace, for use by all components in a module;

• in the java:app namespace, for use by all components in an application;

• in the java:global namespace, for use by all applications.

The following annotations (and corresponding XML deployment descriptor elements) define resources: AdministeredObjectDefinition, ConnectionFactoryDefinition, ContextServiceDefinition, DataSourceDefinition, JMSConnectionFactoryDefinition, JMSDestinationDefinition, MailSessionDefinition, ManagedExecutorDefinition, ManagedScheduledExecutorDefinition, and ManagedThreadFactoryDefinition.

Once defined, a resource may be referenced by a component using the lookup element of the Resource annotation or the lookup-name element of the resource-ref deployment descriptor element in order to bind the logical reference to the resource as referenced in the application code to the resource defined in the environment.

The specificity of the resource definition elements as provided by the Application Component Provider may vary according to the needs of the application. For example:

• An application may require an instance of a resource, but its needs may be general in that while it requires a resource with certain properties, it does not require a particular instance of the resource. It may expect the resource to be provisioned and configured for it by the Deployer or System Administrator.

• An application may require a particular instance of a resource (with specific configuration properties) that already exists. For example, the resource may previously have been created and configured by the Deployer or System Administrator.

The values specified for required annotation elements (and corresponding XML deployment descriptor elements) must be observed when the application is deployed. Changing a value that has been specified for some optional elements (e.g., transactional ) may cause the application to work incorrectly. Changing a value that has been specified for an optional element related to quality of service (e.g., pool size, idle time, etc.) may affect the performance of the application.

The following default values used in the DataSourceDefinition, JMSConnectionFactoryDefinition, JMSDestinationDefinition, MailSessionDefinition, and ConnectionFactoryDefinition annotations indicate that an element value is optional and has not been set:

• integer-valued elements: -1

• string-valued elements: “”

• array-valued elements: {}

Guidelines

The following guidelines should be observed with regard to the specification of values for resource definition elements.

• In general, the Application Component Provider or Assembler should specify values for elements which, if changed, would cause the application to break—for example, JNDI name, isolation level. If multiple resource definitions are specified for a given resource, they must be consistent.

• The Jakarta EE Product Provider may choose suitable server-specific default values for optional elements for which values have not been specified.

Requirements Common to All Resource Definition Types

The following requirements apply to the resource definitions described in Sections DataSource Resource Definition through Connector Administered Object Definition.

When an Application Component Provider or Application Assembler specifies connectivity information to a “physical” resource through a resource definition annotation or deployment descriptor element, it is assumed that the physical resource exists. The automatic provisioning of resources may be supported by an implementation of this specification, but support for this functionality is not required. If automatic provisioning of resources is not supported, it is the Deployer’s responsibility (possibly in conjunction with the System Administrator) to insure that the physical resource is provisioned for use by the application.

JNDI Name

The Deployer and Jakarta EE Product Provider must not alter the specified JNDI name. The requested resource must be made available in JNDI under the specified name.

Resource Address

If the Application Component Provider or Application Assembler has specified an address for a resource (server name, port, etc.), a resource at the specified location should already exist. If it does not, and if the automatic provisioning of resources is not supported, it is the Deployer’s responsibility (possibly in conjunction with the System Administrator) to insure that the resource is provisioned for use by the application.^[10]

If the resource has not been otherwise provisioned and if automatic provisioning of resources is supported, the Jakarta EE Product Provider is responsible for provisioning the resource. If the requested resource cannot be made available or created, the application must fail to deploy.

Quality of Service Elements

Quality of service elements may be altered by the Deployer. The Jakarta EE Product Provider is permitted to impose restrictions upon quality of service elements in accordance with its implementation limits and quality of service guarantees. If quality of service values that have been specified do not meet these restrictions, the Product Provider must not reject the deployment (but must instead use appropriate values).

Properties

All resource definition annotations and XML elements support the use of property elements (elements named “properties” or “property”). A Jakarta EE Product Provider is permitted to reject a deployment if a property that it recognizes has a value that it does not support. A Jakarta EE Product Provider must not reject a deployment on the basis of a property that it does not recognize.

DataSource Resource Definition

An application may define a DataSource resource. A DataSource resource is used to access a database using a JDBC driver.

The DataSource resource may be defined in any of the JNDI namespaces described in Application Component Environment Namespaces.

A DataSource resource may be defined in a web module, enterprise bean module, application client module, or application deployment descriptor using the data-source element.

For example:

...
<data-source>
  <description>Sample DataSource definition</description>
  <name>java:app/MyDataSource</name>
  <class-name>com.example.MyDataSource</class-name>
  <server-name>myserver.com</server-name>
  <port-number>6689</port-number>
  <database-name>myDatabase</database-name>
  <user>lance</user>
  <password>secret</password>
  <property>
    <name>Property1</name>
    <value>10</value>
  </property>
  <property>
    <name>Property2</name>
    <value>20</value>
  </property>
  <login-timeout>0</login-timeout>
  <transactional>false</transactional>
  <isolation-level>TRANSACTION_READ_COMMITTED</isolation-level>
  <initial-pool-size>0</initial-pool-size>
  <max-pool-size>30</max-pool-size>
  <min-pool-size>20</min-pool-size>
  <max-idle-time>0</max-idle-time>
  <max-statements>50</max-statements>
</data-source>
...

A DataSource resource may also be defined using the DataSourceDefinition annotation on a container-managed class, such as a servlet or enterprise bean class.

For example:

  @DataSourceDefinition(
     name="java:app/MyDataSource",
     className="com.example.MyDataSource",
     portNumber=6689,
     serverName="myserver.com",
     user="lance",
     password="secret")

(Of course, we do not recommend including passwords to production systems in the code, but it’s often useful while testing. Passwords, or other parts of the DataSource definition, can be overridden by a deployment descriptor when the application is deployed.)

Once defined, a DataSource resource may be referenced by a component using the resource-ref deployment descriptor element or the Resource annotation. For example, the above DataSource could be referenced as follows:

  @Stateless
  public class MySessionBean {
    @Resource(lookup = "java:app/MyDataSource")
    DataSource myDB;
    ...
  }

The following DataSourceDefinition annotation elements (and corresponding XML deployment descriptor elements) are considered to specify an address for a DataSource resource: serverName, portNumber, databaseName, url.

The following DataSourceDefinition annotation elements (and corresponding XML deployment descriptor elements) are considered to be quality of service elements: loginTimeout, initialPoolSize, maxPoolSize, minPoolSize, maxIdleTime, maxStatements.

Application Component Provider’s Responsibilities

The Application Component Provider is responsible for the definition of a DataSource resource using a DataSourceDefinition annotation or the data-source deployment descriptor element.

If the database has been previously provisioned for the application (e.g., by administrative action), it is the responsibility of the Application Component Provider to specify the class name of the data source implementation class and the server and port at which the database is to be accessed.

A URL should not be specified in conjunction with address elements such as server name and port. If it is, the precedence order is undefined and implementation specific.

Deployer’s Responsibilities

Requirements common to all resource definition types are described in Requirements Common to All Resource Definition Types. The following additional requirements apply:

• If specified, user name and password should be used as specified.

• The transactional specification and isolation level must be used as specified.

Jakarta EE Product Provider’s Responsibilities

Requirements common to all resource definition types are described in Requirements Common to All Resource Definition Types. The following additional requirements apply:

• If a class name is specified, a resource with the specified implementation class (or a subclass) must be provided. If the class name is specified as XADataSource, an XA datasource must be provided.

• If an isolation level is specified, the Product Provider must satisfy the request or provide a higher level of isolation. If the request cannot be satisfied, the Product Provider must reject the deployment.

Jakarta Messaging Connection Factory Resource Definition

An application may define a Jakarta Messaging ConnectionFactory resource.

The Jakarta Messaging ConnectionFactory resource may be defined in any of the JNDI namespaces described in Application Component Environment Namespaces.

A Jakarta Messaging ConnectionFactory resource may be defined in a web module, enterprise bean module, application client module, or application deployment descriptor using the jms-connection-factory element.

For example:

...
<jms-connection-factory>
  <description>
     Sample Jakarta Messaging ConnectionFactory definition
  </description>
  <name>java:app/MyJMSCF</name>
  <interface-name>
     jakarta.jms.QueueConnectionFactory
  </interface-name>
  <resource-adapter>myJMSRA</resource-adapter>
  <user>scott</user>
  <password>secret</password>
  <client-id>MyId</client-id>
  <property>
    <name>Property1</name>
    <value>10</value>
   </property>
   <property>
     <name>Property2</name>
     <value>20</value>
   </property>
   <transactional>false</transactional>
   <max-pool-size>30</max-pool-size>
   <min-pool-size>20</min-pool-size>
</jms-connection-factory>
...

A Jakarta Messaging ConnectionFactory resource may also be defined using the JMSConnectionFactoryDefinition annotation on a container-managed class, such as a servlet or enterprise bean class.

For example:

  @JMSConnectionFactoryDefinition(
     name="java:app/MyJMSCF",
     interfaceName="jakarta.jms.QueueConnectionFactory",
     resourceAdapter="myJMSRA")

(As with the DataSource definition, we do not recommend including passwords to production systems in the code, but it’s often useful while testing. Passwords, or other parts of the JMSConnectionFactoryDefinition annotation, can be overridden by a deployment descriptor when the application is deployed.)

Once defined, a Jakarta Messaging ConnectionFactory resource may be referenced by a component using the resource-ref deployment descriptor element or the Resource annotation. For example, the above Jakarta Messaging ConnectionFactory could be referenced as follows:

  @Stateless_
  public class MySessionBean {
    @Resource(lookup = "java:app/MyJMSCF")
    ConnectionFactory myCF;
    ...
  }

The following JMSConnectionFactoryDefinition annotation elements (and corresponding XML deployment descriptor elements) are considered to specify an address for a Jakarta Messaging ConnectionFactory resource: resourceAdapter.

The following JMSConnectionFactoryDefinition annotation elements (and corresponding XML deployment descriptor elements) are considered to be quality of service elements: maxPoolSize, minPoolSize.

Application Component Provider’s Responsibilities

The Application Component Provider is responsible for the definition of a Jakarta Messaging ConnectionFactory using a JMSConnectionFactoryDefinition annotation or the jms-connection-factory deployment descriptor element.

Deployer’s Responsibilities

Requirements common to all resource definition types are described in Requirements Common to All Resource Definition Types. The following additional requirements apply:

• A resource of the specified interface type (or of the default interface type, if not specified) must be provided.

• If specified, user name and password should be used as specified.

• The transactional specification must be used as specified.

• If specified, the client id should be used as specified.

Jakarta EE Product Provider’s Responsibilities

Requirements common to all resource definition types are described in Requirements Common to All Resource Definition Types.

Jakarta Messaging Destination Definition

An application may define a Jakarta Messaging Destination resource. A Jakarta Messaging Destination resource is a Jakarta Messaging Queue or Topic.

The Jakarta Messaging Destination resource may be defined in any of the JNDI namespaces described in Application Component Environment Namespaces.

A Jakarta Messaging Destination resource may be defined in a web module, enterprise bean module, application client module, or application deployment descriptor using the jms-destination element.

For example:

...
<jms-destination>
  <description>Sample Jakarta Messaging Destination definition</description>
  <name>java:app/MyJMSDestination</name>
  <interface-name>jakarta.jms.Queue</interface-name>
  <resource-adapter>myJMSRA</resource-adapter>
  <destination-name>myQueue1</destination-name>
  <property>
    <name>Property1</name>
    <value>10</value>
  </property>
  <property>
    <name>Property2</name>
    <value>20</value>
  </property>
</jms-destination>
...

A Jakarta Messaging Destination resource may also be defined using the JMSDestinationDefinition annotation on a container-managed class, such as a servlet or enterprise bean class.

For example:

  @JMSDestinationDefinition(
     name="java:app/MyJMSQueue",
     interfaceName="jakarta.jms.Queue",
     destinationName="myQueue1")

The JMSDestinationDefinition annotation can be overridden by a deployment descriptor when the application is deployed.

Once defined, a Jakarta Messaging Destination resource may be referenced by a component using either the resource-env-ref or message-destination-ref deployment descriptor element or the Resource annotation. For example, the above Destination could be referenced as follows:

  @Stateless
  public class MySessionBean {
    @Resource(lookup = "java:app/MyJMSQueue")
    Queue myQueue;
    ...
  }

The following JMSDestinationDefinition annotation elements (and corresponding XML deployment descriptor elements) are considered to specify an address for a Jakarta Messaging Destination resource: resourceAdapter, destinationName.

Application Component Provider’s Responsibilities

The Application Component Provider is responsible for the definition of a Jakarta Messaging Destination using a JMSDestinationDefinition annotation or the jms-destination deployment descriptor element.

Deployer’s Responsibilities

Requirements common to all resource definition types are described in Requirements Common to All Resource Definition Types. The following additional requirements apply:

A resource of the specified interface type must be provided.

Jakarta EE Product Provider’s Responsibilities

Requirements common to all resource definition types are described in Requirements Common to All Resource Definition Types.

Mail Session Definition

An application may define a Mail Session resource.

The Mail Session resource may be defined in any of the JNDI namespaces described in Application Component Environment Namespaces.

A Mail Session resource may be defined in a web module, enterprise bean module, application client module, or application deployment descriptor using the mail-session element.

For example:

...
<mail-session>
  <description>Sample Mail Session definition</description>
  <name>java:app/mail/MySession</name>
  <store-protocol>imap</store-protocol>
  <transport-protocol>smtp</transport-protocol>
  <host>somewhere.myco.com</host>
  <user>linda</user>
  <password>secret</password>
  <from>some.body@myco.com</from>
  <property>
    <name>mail.smtp.starttls.enable</name>
    <value>true</value>
  </property>
  <property>
    <name>mail.imap.connectiontimeout</name>
    <value>500</value>
  </property>
</mail-session>
...

A Mail Session resource may also be defined using the MailSessionDefinition annotation on a container-managed class, such as a servlet or enterprise bean class.

For example:

  @MailSessionDefinition(_
       name="java:app/mail/MySession",
       host="somewhere.myco.com",
       from="some.body@myco.com")

The MailSessionDefinition annotation can be overridden by a deployment descriptor when the application is deployed.

Once defined, a Mail Session resource may be referenced by a component using the resource-ref deployment descriptor element or the Resource annotation. For example, the above Destination could be referenced as follows:

  @Stateless
  public class MySessionBean {
    @Resource(lookup = "java:app/mail/MySession")
    Session myMailSession;
    ...
  }

The following MailSessionDefinition annotation elements (and corresponding XML deployment descriptor elements) are considered to specify an address for a Mail Session resource: host.

Application Component Provider’s Responsibilities

The Application Component Provider is responsible for the definition of a Mail Session using a MailSessionDefinition annotation or the mail-session deployment descriptor element.

If a mail server resource has been previously provisioned for the application (e.g., by administrative action), it is the responsibility of the Application Component Provider to specify the mail server host name.

Deployer’s Responsibilities

Requirements common to all resource definition types are described in Requirements Common to All Resource Definition Types. The following additional requirements apply:

• If store protocol, store protocol class, transport protocol, or transport protocol class has been specified, a resource with the specified property or properties should be provided.

• If specified, the user name and password should be used as specified.

• If specified, the from address should be used as specified.

Jakarta EE Product Provider’s Responsibilities

Requirements common to all resource definition types are described in Requirements Common to All Resource Definition Types.

Connector Connection Factory Definition

An application may define Connector connection factory resources.

The resource may be defined in any of the JNDI namespaces described in Application Component Environment Namespaces.

A Connector connection factory resource may be defined in a web module, enterprise bean module, or application deployment descriptor using the connection-factory element.

For example:

...
<connection-factory>
  <description>Sample Connector resource definition</description>
  <name>java:app/myConnectionFactory</name>
  <interface-name>
     com.eis.ConnectionFactory
   </interface-name>
   <resource-adapter>MyEISRA</resource-adapter>
   <max-pool-size>20</max-pool-size>
   <min-pool-size>10</min-pool-size>
   <transaction-support>XATransaction</transaction-support>
   <property>
     <name>Property1</name>
     <value>prop1val</value>
   </property>
   <property>
     <name>Property2</name>
     <value>prop2val</value>
   </property>
</connection-factory>
...

A Connector connection factory resource may also be defined using the ConnectionFactoryDefinition annotation on a container-managed class, such as a servlet or enterprise bean class.

For example:

  @ConnectionFactoryDefinition(
       name="java:app/myConnectionFactory",
       interfaceName="com.eis.ConnectionFactory",
       resourceAdapter="MyESRA")

The ConnectionFactoryDefinition annotation can be overridden by a deployment descriptor when the application is deployed.

Once defined, a Connector connection factory resource may be referenced by a component using the resource-ref deployment descriptor element or the Resource annotation. For example, the above Connector connection factory resource could be referenced as follows:

  @Stateless
  public class MySessionBean {
    @Resource(lookup = "java:app/myConnectionFactory")
    ConnectionFactory myCF;
    ...
  }

Application Component Provider’s Responsibilities

The Application Component Provider is responsible for the definition of a Connector connection factory resource using a ConnectionFactoryDefinition annotation or the connection-factory deployment descriptor element.

Deployer’s Responsibilities

Requirements common to all resource definition types are described in Requirements Common to All Resource Definition Types. The following additional requirements apply:

• A resource of the specified type must be provided.

Jakarta EE Product Provider’s Responsibilities

Requirements common to all resource definition types are described in Requirements Common to All Resource Definition Types.

Connector Administered Object Definition

An application may define a Connector administered object resource. The administered object resource may be defined in any of the JNDI namespaces described in Application Component Environment Namespaces.

An administered object resource may be defined in a web module, enterprise bean module, or application deployment descriptor using the administered-object element. Properties that are specified are used in the configuration of the administered object, as described in the Connector specification.

For example:

...
<administered-object>
  <description>Sample Admin Object definition</description>
  <name>java:app/MyAdminObject</name>
  <class-name>com.extraServices.AdminObject</class-name>
  <resource-adapter>myESRA</resource-adapter>
  <property>
    <name>Property1</name>
    <value>10</value>
  </property>
  <property>
    <name>Property2</name>
    <value>20</value>
  </property>
</administered-object>
...

An administered object resource may also be defined using the AdministeredObjectDefinition annotation on a container-managed class, such as a servlet or enterprise bean class.

For example:

@AdministeredObjectDefinition(
    name="java:app/myAdminObject",
    className="com.extraServices.AdminObject",
    resourceAdapter="myESRA")

The AdministeredObjectDefinition annotation can be overridden by a deployment descriptor when the application is deployed.

Once defined, an administered object resource may be referenced by a component using the resource-env-ref deployment descriptor element or the Resource annotation. For example, the above administered object resource could be referenced as follows:

  @Stateless public class MySessionBean {
    @Resource(lookup="java:app/myAdminObject")
    AdminObject myAdminObject;
    ...
  }

Application Component Provider’s Responsibilities

The Application Component Provider is responsible for the definition of an administered object resource using an AdministeredObjectDefinition annotation or the administered-object deployment descriptor element.

Deployer’s Responsibilities

Requirements common to all resource definition types are described in Requirements Common to All Resource Definition Types. The following additional requirements apply:

If a class name is specified, an administered object resource of the specified class (or a subclass) must be provided.

Jakarta EE Product Provider’s Responsibilities

Requirements common to all resource definition types are described in Requirements Common to All Resource Definition Types.

Concurrency Resource Definitions

An application may define ContextService, ManagedExecutorService, ManagedScheduledExecutorService, and ManagedThreadFactory resources. These resources are used to manage and perform context-aware asynchronous tasks.

These resources may be defined in any of the JNDI namespaces described in Application Component Environment Namespaces unless a non-empty list of qualifiers is specified, in which case java:global is not permitted.

These resources may be defined in a web module or application deployment descriptor using the context-service, managed-executor, managed-scheduled-executor, or managed-thread-factory element.

For example:

...
<context-service>
  <name>java:app/concurrent/MyContext</name>
  <cleared>Transaction</cleared>
  <propagated>Application</propagated>
  <propagated>Security</propagated>
  <unchanged>Remaining</unchanged>
</context-service>

<managed-executor>
  <name>java:app/concurrent/MaxAsync5</name>
  <context-service-ref>java:app/concurrent/MyContext</context-service-ref>
  <max-async>5</max-async>
</managed-executor>
...

Concurrency resources may also be defined using the following resource definition annotations: ContextServiceDefinition, ManagedExecutorDefinition, ManagedScheduledExecutorDefinition, ManagedThreadFactoryDefinition. These annotations must reside on a container-managed class, such as a Servlet, CDI bean, Jakarta REST resource, etc.

If any of these annotations specifies one or more qualifiers, then the class on which the annotation resides must also be a CDI managed bean.

For example:

  @ContextServiceDefinition(
     name = "java:app/concurrent/AppContextOnly",
     cleared = { TRANSACTION, SECURITY },
     propagated = APPLICATION,
     unchanged = ALL_REMAINING)

  @ManagedExecutorDefinition(
     name = "java:app/concurrent/MaxAsync10",
     context = "java:app/concurrent/AppContextOnly",
     qualifiers = MaxAsync10.class,
     maxAsync = 10)

Once defined, Concurrency resources may be referenced by a component using the resource-ref deployment descriptor element or the Resource annotation. For example, the above ManagedExecutorService could be referenced as follows:

  @Stateless
  public class MySessionBean {
    @Resource(lookup = "java:app/concurrent/MaxAsync10")
    ManagedExecutorService maxAsync10Executor;
    ...
  }

Alternatively, if qualifiers are included, the resource can be injected into CDI beans. For example:

  @ApplicationScoped
  public class MyBean {
    @Inject
    @MaxAsync10
    ManagedExecutorService maxAsync10Executor;
    ...
  }

Application Component Provider’s Responsibilities

For each row in the table, the Application Component Provider is responsible for the definition of the named resource using the corresponding annotation and the corresponding deployment descriptor element.

Name of the resource	Corresponding annotation name	corresponding deployment descriptor element
ContextService	ContextServiceDefinition	context-service
ManagedExecutorService	ManagedExecutorDefinition	managed-executor
ManagedScheduledExecutorService	ManagedScheduledExecutorDefinition	managed-scheduled-executor
ManagedThreadFactory	ManagedThreadFactoryDefinition	managed-thread-factory

If a qualifier class or class name is specified, a qualifier with the specified class must be provided by the application.

Deployer’s Responsibilities

Requirements common to all resource definition types are described in Requirements Common to All Resource Definition Types.

Jakarta EE Product Provider’s Responsibilities

Requirements common to all resource definition types are described in Requirements Common to All Resource Definition Types.

Default Data Source

The Jakarta EE Platform requires that a Jakarta EE Product Provider provide a database in the operational environment (see Database). The Jakarta EE Product Provider must also provide a preconfigured, default data source for use by the application in accessing this database.

The Jakarta EE Product Provider must make the default data source accessible to the application under the JNDI name java:comp/DefaultDataSource.

The Application Component Provider or Application Assembler may explicitly bind a DataSource resource reference to the default data source using the lookup element of the Resource annotation or the lookup-name element of the resource-ref deployment descriptor element. For example,

@Resource(lookup="java:comp/DefaultDataSource")
DataSource myDS;

In the absence of such a binding, or an equivalent product-specific binding, the mapping of the reference will default to the product’s default data source.

For example, the following will map to a preconfigured data source for the product’s default database:

@Resource
DataSource myDS;

Jakarta EE Product Provider’s Responsibilities

The Jakarta EE Product Provider must provide a database in the operational environment. The Jakarta EE Product Provider must also provide a preconfigured, default data source for use by the application in accessing this database under the JNDI name java:comp/DefaultDataSource.

If a DataSource resource reference is not mapped to a specific data source by the Application Component Provider, Application Assembler, or Deployer, it must be mapped by the Jakarta EE Product Provider to a preconfigured data source for the Jakarta EE Product Provider’s default database.

Default Jakarta Messaging Connection Factory

The Jakarta EE Platform requires that a Jakarta EE Product Provider provide a Jakarta Messaging provider in the operational environment (see Jakarta™ Message Service (Jakarta Messaging)). The Jakarta EE Product Provider must also provide a preconfigured, Jakarta Messaging ConnectionFactory for use by the application in accessing this Jakarta Messaging provider.

The Jakarta EE Product Provider must make the default Jakarta Messaging connection factory accessible to the application under the JNDI name java:comp/DefaultJMSConnectionFactory.

The Application Component Provider or Application Assembler may explicitly bind a Jakarta Messaging ConnectionFactory resource reference to the default connection factory using the lookup element of the Resource annotation or the lookup-name element of the resource-ref deployment descriptor element. For example,

@Resource(name="myJMSCF",
          lookup="java:comp/DefaultJMSConnectionFactory")
ConnectionFactory myJMScf;

In the absence of such a binding, or an equivalent product-specific binding, the mapping of the reference will default to a Jakarta Messaging connection factory for the product’s Jakarta Messaging provider.

For example, the following will map to a preconfigured connection factory for the product’s default Jakarta Messaging provider:

@Resource(name="myJMSCF")
ConnectionFactory myJMScf;

Jakarta EE Product Provider’s Responsibilities

The Jakarta EE Product Provider must provide a Jakarta Messaging provider in the operational environment. The Jakarta EE Product Provider must also provide a preconfigured, default Jakarta Messaging connection factory for use by the application in accessing this provider under the JNDI name java:comp/DefaultJMSConnectionFactory.

If a Jakarta Messaging ConnectionFactory resource reference is not mapped to a specific Jakarta Messaging connection factory by the Application Component Provider, Application Assembler, or Deployer, it must be mapped by the Jakarta EE Product Provider to a preconfigured Jakarta Messaging connection factory for the Jakarta EE Product Provider’s default Jakarta Messaging provider.

Default Jakarta Concurrency Objects

The Jakarta EE Platform requires that a Jakarta EE Product Provider provide a preconfigured default managed executor service, a preconfigured default managed scheduled executor service, a preconfigured default managed thread factory, and a preconfigured default context service for use by the application.

The Jakarta EE Product Provider must make the default Jakarta Concurrency objects accessible to the application under the following JNDI names:

• java:comp/DefaultManagedExecutorService for the preconfigured managed executor service

• java:comp/DefaultManagedScheduledExecutorService for the preconfigured managed scheduled executor service

• java:comp/DefaultManagedThreadFactory for the preconfigured managed thread factory

• java:comp/DefaultContextService for the preconfigured context service

The Application Component Provider or Application Assembler may explicitly bind a resource reference to a default Jakarta Concurrency object using the lookup element of the Resource annotation or the lookup-name element of the resource-ref deployment descriptor element. For example,

@Resource(name="myManagedExecutorService",
          lookup="java:comp/DefaultManagedExecutorService")
ManagedExecutorService myManagedExecutorService;

In the absence of such a binding, or an equivalent product-specific binding, the mapping of the reference will default to the product’s default managed executor service.

For example, the following will map to a preconfigured default managed executor service for the product:

@Resource(name="myManagedExecutorService")
ManagedExecutorService myManagedExecutorService;

Jakarta EE Product Provider’s Responsibilities

The Jakarta EE Product Provider must provide the following:

• a preconfigured, default managed executor service for use by the application in accessing this service under the JNDI name java:comp/DefaultManagedExecutorService ;

• a preconfigured, default managed scheduled executor service for use by the application in accessing this service under the JNDI name java:comp/DefaultManagedScheduledExecutorService ;

• a preconfigured, default managed thread factory for use by the application in accessing this factory under the JNDI name java:comp/DefaultManagedThreadFactory ;

• a preconfigured, default context service for use by the application in accessing this service under the JNDI name java:comp/DefaultContextService.

If a Jakarta Concurrency object resource environment reference is not mapped to a specific configured object by the Application Component Provider, Application Assembler, or Deployer, it must be mapped by the Jakarta EE Product Provider to a preconfigured Jakarta Concurrency object for the Jakarta EE Product Provider.

CDI Managed Bean References

This section describes the metadata annotations and deployment descriptor entries that allow an application to obtain instances of a CDI Managed Bean.

An instance of a named CDI Managed Bean can be obtained by looking up its name in JNDI using the same naming scheme used for Jakarta Enterprise Beans components:

java:app/<module-name>/<bean-name>

java:module/<bean-name>

The latter will only work within the module the CDI Managed Bean is declared in.

Each such lookup must return a new instance.

Alternatively, the Resource annotation can be used to request the injection of a CDI Managed Bean given either its type or its name. If a name is specified using the lookup element then the type of the resource can be any of the types that the CDI Managed Bean class implements, including any of its interfaces. If no name is specified, the type must be the CDI Managed Bean class itself. (Note that the name element of the Resource annotation serves an entirely different purpose than the lookup element, consistently with other uses of Resource in this specification.) The authenticationType and shareable elements of the Resource annotation must not be specified.

For example, given a ShoppingCartBean bean named “cart” defined in the same module as the client code and implementing the ShoppingCart interface, a client may use any of the following methods to obtain an instance of the bean class:

@Resource ShoppingCartBean cart;

@Resource(lookup="java:module/cart") ShoppingCart cart;

ShoppingCart cart = (ShoppingCart) context.lookup("java:module/cart");

References to managed beans can be declared in the deployment descriptor using the resource-ref element. The res-type element must contain a type that the managed bean implements. The lookup-name must be present and refer to a managed bean by name. The res-sharing-scope and res-auth elements may be omitted; if present, they must have the values Shareable and Container respectively, so as to match the default values of the corresponding elements of the Resource annotation.

The following example shows how to declare references to the shopping cart bean of the previous example, this time using descriptors. (To make the example somewhat more realistic, one should add an injection-target child element to resource-ref.)

...
<resource-ref>
  <res-ref-name>bean/cart</ref-ref-name>
  <ref-type>com.acme.ShoppingCart</ref-type>
  <lookup-name>java:module/cart</lookup-name>
</resource-ref>
...

Application Component Provider’s Responsibilities

The Application Component Provider is responsible for requesting injection of a CDI Managed Bean or for looking it up in JNDI using an appropriate name.

Jakarta EE Product Provider’s Responsibilities

The Jakarta EE Product Provider is responsible for providing appropriate instances of the requested CDI Managed Bean class as required by this specification.

Bean Manager References

This section describes the metadata annotations and deployment descriptor entries that allow an application to obtain instances of the CDI BeanManager type.

Typically, only portable extensions using the CDI SPI need to access a BeanManager. Application code may occasionally require access to that interface; in that case, the application should either look up a BeanManager instance in JNDI under the name java:comp/BeanManager, or request the injection of an object of type jakarta.enterprise.inject.spi.BeanManager via the Resource annotation. If the latter, the authenticationType and shareable elements of the Resource annotation must not be specified.

@Resource BeanManager manager;

Per the CDI specification, a bean can also request the injection of a BeanManager using the Inject annotation.

@Inject BeanManager manager;

A BeanManager object reference may also be declared in a deployment descriptor in the same way as a resource environment reference.

Application Component Provider’s Responsibilities

The Application Component Provider is responsible for requesting injection of a BeanManager instance using a Resource annotation, or using the defined name to look up an instance in JNDI.

Jakarta EE Product Provider’s Responsibilities

The Jakarta EE Product Provider is responsible for providing appropriate BeanManager instances as required by this specification.

Support for Dependency Injection

In Jakarta EE, support for dependency injection annotations as specified in the Dependency Injection for Java specification is mediated by CDI. Containers must support injection points annotated with the jakarta.inject.Inject annotation only to the extent dictated by CDI.

Per the CDI specification, dependency injection is supported on managed beans. There are currently three ways for a class to become a managed bean:

1. Being a Jakarta Enterprise Beans session bean component.

2. Satisfying the conditions described in the CDI specification.

Classes that satisfy at least one of these conditions will be eligible for full dependency injection support as described in the CDI specification.

Component classes listed in Component classes supporting injection that satisfy the third condition above, but neither the first nor the second condition, can also be used as CDI managed beans if they are annotated with a CDI bean-defining annotation or contained in a bean archive for which CDI is enabled. However, if they are used as CDI managed beans (e.g., injected into other managed classes), the instances that are managed by CDI may not be the instances that are managed by the Jakarta EE container.

Therefore, to make injection support more uniform across all Jakarta EE component types, Jakarta EE containers are required to support field, method, and constructor injection using the jakarta.inject.Inject annotation into all component classes listed in Component classes supporting injection as having the “Standard” level of injection support, as well as the use of interceptors for these classes. Such injection must be performed in the same logical phase as resource injection of fields and methods annotated with the Resource annotation. In particular, dependency injection must precede the invocation of any methods annotated with the PostConstruct annotation. In supporting such injection points, the container must behave as if it carried out the following steps, involving the use of the CDI SPI. Note that using these steps causes the container to create a non-contextual instance, which is not managed by CDI but rather by the Jakarta EE container.

1. Obtain a BeanManager instance.

2. Create an AnnotatedType instance for the component into which injection is to occur.

3. Create an InjectionTarget instance for the annotated type.

4. Create a CreationalContext, passing in null to the BeanManager createCreationalContext method.

5. Instantiate the component by calling the InjectionTarget produce method.

6. Inject the component instance by calling the InjectionTarget inject method on the instance.

7. Invoke the PostConstruct callback, if any, by calling the InjectionTarget postConstruct method on the instance.

When such a non-contextual instance is to be destroyed, the container should behave as if it carried out the following steps.

1. Invoke the PreDestroy callback, if any, by calling the InjectionTarget preDestroy method on the instance.

2. Invoke the InjectionTarget dispose method on the instance.

3. Invoke the CreationalContext release method to destroy any dependent objects of the instance.

Containers may optimize the steps above, e.g., by avoiding calls to the actual CDI SPI and relying on container-specific interfaces instead, as long as the outcome is the same.

---

---

1. Note that CDI Managed Beans are required to have access to the JNDI naming environment of their calling component.

2. Note that the use of interceptors defined by means of the Interceptors annotation is supported in the absence of CDI for Jakarta™ Enterprise Beans and Jakarta™ Managed Bean components.

3. See the Jakarta™ Server Faces specification section Jakarta™ Server Faces Managed Classes and Jakarta™ Annotations” for a list of these managed classes.

4. Resource and CDI injection is supported only in Jakarta™ RESTful Web Services components managed by CDI.

5. Interceptors cannot be bound to other interceptors.

6. See the CDI specification for requirements related to resource injection in CDI managed beans.

7. We use this term to refer to classes that become managed beans per the rules in the CDI specification, thus excluding managed beans declared using Jakarta™ Enterprise Beans session beans, which would be managed bean even in the absence of CDI.

8. Interceptors cannot be bound to decorators.

9. Connections obtained from the same resource manager connection factory through a different resource manager connection factory reference may be shareable.

10. Note that the Deployer is not prohibited from overriding the resource address.