T
his chapter describes how applications declare dependencies on external resources and configuration parameters, and how those items are represented in the Java 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 Common Annotations specification. The EJB annotation described here is defined in more detail in the Enterprise JavaBeans specification. ThePersistenceUnit and PersistenceContext annotations described here are defined in more detail in the Java Persistence specification. The Inject annotation
described here is defined in the Dependency Injection for Java specification, and its usage in Java EE applications is defined in the Contexts and Dependency Injection for the Java EE Platform specification.
EE.5.1
Overview
The requirements defined in this chapter address the following two issues:
• The Application Assembler and Deployer should be able to customize the be- havior of an application’s business logic without accessing the application’s source code. Typically this will involve specification of parameter values, con- nection to external resources, and so on. Deployment descriptors provide this capability
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.
EE.5.1.1 Chapter Organization
The following sections contain the Java EE platform solutions to the above issues: • Section EE.5.2, “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.
• Section EE.5.3, “Responsibilities by Java EE Role,” defines the general re- sponsibilities for each of the Java EE roles such as Application Component Provider, Application Assembler, Deployer, and Java EE Product Provider. • Section EE.5.4, “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. • Section EE.5.5, “Enterprise JavaBeans™ (EJB) References,” defines the in-
terfaces for obtaining the business interface, no-interface view, or home inter- face of an enterprise bean using an EJB reference. An EJB reference is a special entry in the application component’s environment.
• Section EE.5.6, “Web Service References,” refers to the specification for web service references.
• Section EE.5.7, “Resource Manager Connection Factory References,” defines the interfaces for obtaining a resource manager connection factory using a re- source manager connection factory reference. A resource manager connection factory reference is a special entry in the application component’s environ- ment.
• Section EE.5.8, “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 spe- cial entry in the application component’s environment.
• Section EE.5.9, “Message Destination References,” defines the interfaces for declaring and using message destination references.
• Section EE.5.10, “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.
• Section EE.5.11, “TransactionSynchronizationRegistry References,” de- scribes the use by eligible application components of references to a
TransactionSynchronizationRegistry object in the component’s environ- ment.
• Section EE.5.12, “ORB References,” describes the use by eligible application components of references to a CORBA ORB object in the component’s envi-
ronment.
• Section EE.5.13, “Persistence Unit References,” describes the use by eligible application components of references to an EntityManagerFactory object in the component’s environment.
• Section EE.5.14, “Persistence Context References,” describes the use by eli- gible application components of references to an EntityManager object in the
component’s environment.
• Section EE.5.15, “Application Name and Module Name References,” de- scribes the use by eligible application components of references to the names of the current application and module.
• Section EE.5.16, “Application Client Container Property,” describes the use by eligible application components of references to the application client con- tainer property.
• Section EE.5.17, “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.
• Section EE.5.18, “Resource Definition and Configuration,” describes the use by eligible application components of metadata that may be used to define re- sources in the component’s environment.
• Section EE.5.18.3, “DataSource Resource Definition,” describes the use by eligible application components of references to DataSource resources in the component’s environment.
• Section EE.5.18.4, “JMS Connection Factory Resource Definition,” describes the use by eligible application components of references to JMS
ConnectionFactory resources in the component’s environment.
• Section EE.5.18.5, “JMS Destination Definition,” describes the use by eligi- ble application components of references to JMS Destination resources in the component’s environment.
• Section EE.5.18.6, “Mail Session Definition,” describes the use by eligible application components of references to Mail Session resources in the com-
• Section EE.5.18.7, “Connector Connection Factory Definition,” describes the use by eligible application components of references to Connector connection factory resources in the component’s environment.
• Section EE.5.18.8, “Connector Administered Object Definition,” describes the use by eligible application components of references to Connector admin- istered object resources in the component’s environment.
• Section EE.5.19, “Default Data Source,” describes the use by eligible applica- tion components of references to the default DataSource in the component’s environment.
• Section EE.5.20, “Default JMS Connection Factory,” describes the use by eli- gible application components of references to the default JMS Connection- Factory in the component’s environment.
• Section EE.5.21, “Default Concurrency Utilities Objects,” describes the use by eligible application components of references to the default Concurrency Utilities objects in the component’s environment.
• Section EE.5.22, “Managed Bean References,” describes the use by eligible application components of references to Managed Beans.
• Section EE.5.23, “Bean Manager References,” describes the use by eligible application components of references to a BeanManager object in the compo- nent’s environment.
• Section EE.5.24, “Support for Dependency Injection,” describes support for the use of the Dependency Injection APIs.
EE.5.1.2 Required Access to the JNDI Naming Environment
Java EE application clients, enterprise beans, and web components are required to have access to a JNDI naming environment1. 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
1.Note that Java EE Managed Beans are required to have access to the
these application component types. See the corresponding specification of each application component type for the details.