2.4.6 Resource reference names

In Java EE 6 and later, apart from the names using java:comp/env, you can specify the fully qualified JNDI name in the resource reference name. By specifying the fully qualified JNDI name in the resource reference name, you can define the resource reference shared by all the components in one application (Enterprise Beans, servlets, JSPs, filters, and resource adapters) and the resource reference shared by all the components in the EJB-JAR or Web application.

Also, you can look up the other resource references with the fully qualified JNDI name by specifying the <lookup-name> tag in the DD (web.xml), or the lookup attribute of the @Resource and @EJB annotations.

This subsection describes the specification of the fully qualified JNDI name for the resource reference name, and the look up of the other resource references.

Note
If the registration of the Portable Global JNDI names is controlled by specifying false in the ejbserver.jndi.global.enabled parameter, do not specify a name beginning with java: in the resource reference name.
Organization of this subsection
(1) Specifying the fully qualified JNDI name for the resource reference name
(2) Looking up the other resource references

(1) Specifying the fully qualified JNDI name for the resource reference name

With Application Server, if you specify a name beginning with java: in the resource reference name when the registration of the Portable Global JNDI name is enabled, the fully qualified JNDI name is determined to have been specified and the specified name is handled as the JNDI name as is.

If the registration of the Portable Global JNDI name is disabled, or if you specify a name beginning with a string other than java:, the name is handled as a name beginning with java:comp/env or as an optional name of the resource adapter.

The following table describes the resource reference types for which you can specify the fully qualified JNDI name as the resource reference name in the DD (web.xml).

Table 2-16 Resource reference types for which you can specify the fully qualified JNDI name (DD)

No.Resource reference typesTags specifying the resource reference name
1Environment entry<env-entry> - <env-entry-name>
2Resource reference<resource-ref> - <res-ref-name>
3Resource environment variable reference<resource-env-ref> - <resource-env-ref-name>
4Remote EJB reference<ejb-ref> - <ejb-ref-name>
5Local EJB reference<ejb-local-ref> - <ejb-local-ref-name>
6Persistence context reference<persistence-context-ref> - <persistence-context-ref-name>
7Persistence unit reference<persistence-unit-ref> - <persistence-unit-ref-name>

The following table describes the resource reference annotations for which you can specify the fully qualified JNDI name in the name attribute.

Table 2-17 Resource reference types for which you can specify the fully qualified JNDI name (Annotations)

No.Resource reference typesAnnotations specifying the resource reference name
1Environment entryname attribute of @Resource
2Resource reference
3Resource environment variable reference
4Remote EJB referencename attribute of @EJB
5Local EJB reference
6Persistence context referencename attribute of @PersistenceContext
7Persistence unit referencename attribute of @PersistenceUnit

If you specify the fully qualified JNDI name in the resource reference name when the registration of the Portable Global JNDI name is enabled, depending on the combination of whether the specified name space, and standard application name and standard module name violate the naming rules, KDJE47730-E is output when the application is starting and the application fails to start.

The following table describes the specified name space of the fully qualified JNDI name and whether the application can be started. Note that even if you specify a name that begins with java:, but without a specifiable name space, KDJE47730-E is output when the application is starting and the application fails to start.

Table 2-18 Specified name space of the fully qualified JNDI name and can the application be started

PreconditionsSpecified name space
Standard application name of the application defining the resource referenceStandard module name of the EJB-JAR or Web application defining the resource referencejava:compjava:modulejava:appjava:global
Invalid value or duplication--YNNY
NormalInvalid value or duplicationYNYY
NormalYYYY
Legend:
Y: The application can be started.
N: The application cannot be started.
--: Not applicable.

With Application Server, there are no constraints on the sub-context name when you specify the resource reference name for the fully qualified JNDI name. However, if a context or object is already registered with the same name, KDJE47721-W is output when the application is starting and the application fails to start.

Note that even when you define the Portable Global JNDI name in the resource reference name, that resource reference cannot be looked up from the J2EE server or EJB client application of another process. If you look up a resource reference on another process in which the Portable Global JNDI name is defined, the NameNotFoundException exception occurs.

(2) Looking up the other resource references

With Application Server, by specifying the <lookup-name> tag in web.xml, or the lookup attribute in the @Resource and @EJB annotations, in addition to specifying the resource references that have been registered using the names beginning with java:comp/env, you can look up the resources shared by the EJB-JAR or Web applications and the resources shared by an application through the DI functionality and resource references.

For example, the DI functionality can also be executed for the environment entry defined in the java:app name space in web.xml within a Web application from the EJB in the EJB-JAR that is a separate module.

You can use the resource adapter name and the EJB optional name in the names that can be looked up from the resource references.

The following table describes the names that can be looked up from the resource references.

Table 2-19 Names that can be looked up from the resource references

Lookup source resource referenceName that can be looked up
AnnotationDD (web.xml)
lookup attribute of @Resource #1<env-entry> - <lookup-name> #2Environment entry name (fully qualified JNDI name)
<resource-ref> - <lookup-name> #1Resource reference name (fully qualified JNDI name)
Optional name of the resource adapter
<resource-env-ref> - <lookup-name> #1Resource environment variable reference name (fully qualified JNDI name)
lookup attribute of @EJB<ejb-ref> - <lookup-name>EJB remote reference name (fully qualified JNDI name)
Portable Global JNDI name of the EJB remote object
Optional name of the EJB remote object
<ejb-local-ref> - <lookup-name>Local EJB reference name (fully qualified JNDI name)
Portable Global JNDI name of the local EJB object
Optional name of the local EJB object
#1
According to the Java EE specifications, if the data type in the injection destination or the data type set in the <resource-ref-type> tag and <resource-env-ref-type> tag of web.xml is one of the following types, the settings in the lookup attribute of the @Resource annotation or the <lookup-name> tag are ignored (the operation is the same as when the settings are not specified):
org.omg.CORBA.ORB
org.omg.CORBA_2_3.ORB
javax.ejb.EJBContext
javax.ejb.SessionContext
javax.ejb.TimerService
javax.transaction.UserTransaction
javax.validation.Validator
javax.validation.ValidatorFactory
javax.enterprise.inject.spi.BeanManager
#2
According to the Java EE specifications, if a value is set in the <env-entry-value> tag, the settings in the lookup attribute of the @Resource annotation or the <lookup-name> tag are ignored (the operation is the same as when the settings are not specified).

Note that if the <linked-to> tag, <linked-queue> tag, or <linked-adminobject> tag is specified in the property file, and the mappedName attribute is specified in the @Resource annotation, the settings in the lookup attribute of the @Resource annotation and the <lookup-name> tag in web.xml are ignored.

Note
Do not set the lookup destination resource reference as the lookup source and do not set a circular reference. If you define the resource references so that they form a circular reference, an infinite recursive call occurs when you look up from an application or when you execute the DI functionality, the java.lang.StackOverflowError exception occurs, and the application does not return a response.
An example of a circular reference is as follows:
<env-entry>
<env-entry-name>java:app/env/sample1</env-entry>
<lookup-name>java:app/env/sample2</env-entry>
</env-entry>
<env-entry>
<env-entry-name>java:app/env/sample2</env-entry>
<lookup-name>java:app/env/sample1</env-entry>
</env-entry>
For this definition, if you look up java:app/env/sample1 from the application, an infinite recursive call occurs, and the java.lang.StackOverflowError exception is thrown.