Java EE application resource declarations

You can configure your Java™ Enterprise Edition (Java EE) applications to declare dependencies on external resources and configuration parameters. These resources might be injected into the application code, or might be accessed by the application through the Java Naming and Directory Interface (JNDI).

Resource references allow an application to define and use logical names that you can bind to resources when the application is deployed.

The following resource types can be declared by Java EE applications: simple environment entries, Enterprise JavaBeans (EJB) references, web service references, resource manager connection factory references, resource environment references, message destination references, persistence unit references, and persistence context references.

Simple Environment Entries

You can define configuration parameters in your Java EE applications to customize business logic using simple environment entries. As described in the Java EE 6 application, simple environment entry values might be one of the following Java types: String, Character, Bye, Short, Integer, Long, Boolean, Double, Float, Class, and any subclass of Enum.

Note: The Java type, Class, and any subclass of Enum are new in Java EE 6.

The application provider must declare all of the simple environment entries accessed from the application code. The simple environment entries are declared using either annotations (javax.annotation.Resource) in the application code, or using env-entry elements in the XML deployment descriptor.

In the following example from an application, annotations declare environment entries:

// Retry interval in milliseconds
@Resource long retryInterval = 3000;

In the previous example, the field default value is 3000. You can use an env-entry-value, which you define in the XML deployment descriptor to change this value.

In the following example, an application declares a simple environment entry of type Class, and defines the Class to be injected using an env-entry-value element in the XML deployment descriptor.

@Resource(name=TraceFormatter) Class<?> traceFormatter; 

<env-entry>
    <env-entry-name>TraceFormatter</env-entry-name>
    <env-entry-value>com.sample.trace.StdOutTraceFormatter</env-entry-value>
</env-entry>

In the previous example, the field value is set to the com.sample.trace.StdOutTraceFormatter Class object.

In the following example, an application which declares a simple environment entry called validationMode as a subclass of Enum in the com.sample.Order class, and configures the Enum value of CALLBACK to inject using elements in the XML deployment descriptor.

<env-entry>
    <env-entry-name>JPAValidation</env-entry-name>
    <env-entry-type>javax.persistence.ValidationMode</env-entry-type>
    <env-entry-value>CALLBACK</env-entry-value>
    <injection-target>
        <injection-target-class>com.sample.Order</injection-target-class>
        <injection-target-name>validationMode</injection-target-name>
    </injection-target>
</env-entry>

In the previous example, the validationMode field is set to the CALLBACK Enum value. Use the same approach when you use annotations and XML code to declare simple environment entries; for example:

@Resource (name=JPAValidation) 
javax.persistence.ValidationMode validationMode;

<env-entry>
    <env-entry-name>JPAValidation</env-entry-name>
    <env-entry-value>CALLBACK</env-entry-value>
</env-entry>
Note: The simple environment entry support of the Java type, Class, and any subclass of Enum is new for Java EE 6. Previously, you might have developed your applications to declare these types as application resources using the resource-env-ref element in the XML deployment descriptor or using the javax.annotation.Resource annotation. For applications that were using these Java types with the javax.annotation.Resource annotation, the com.ibm.websphere.ejbcontainer.EE5Compatibility system property must be enabled. Without the EE5Compatibility system property, the binding-name element of the resource-env-ref element in the ibm-ejb-jar-bnd.xml file is ignored, since the data type is now treated as a simple environment entry and not a resource environment reference.
Note: The <lookup-name> deployment descriptor element and the lookup annotation attribute are new in Java EE 6. They specify the JNDI name of a referenced EJB or resource, relative to the java:comp/env naming context. If either is used in a simple environment entry, you cannot use an <env-entry-value> in the same <env-entry>.

Enterprise JavaBeans (EJB) References

As described in the Java EE 6 specification, you can develop your Java EE applications to declare references to enterprise bean homes or enterprise bean instances using logical names called EJB references.

When an application declares a reference to an EJB, the EJB that you reference will be resolved with one of the following techniques.

  • Specify an EJB binding in the ibm-ejb-jar-bnd.xml file or ibm-web-bnd.xml file
  • Specify an <ejb-link> element in ejb-jar.xml file or web.xml file
  • Specify a beanName attribute on the javax.ejb.EJB annotation
  • Specify a <lookup-name> element in ejb-jar.xml file or web.xml file
  • Specify a lookup attribute on the javax.ejb.EJB annotation
  • Locate an enterprise bean that implements the interface declared as the type of the EJB reference (referred to as AutoLink).

The EJB container attempts to resolve the EJB reference using the previous techniques in the order they are listed.

Note: If <lookup-name> or lookup is used in an EJB reference, you cannot use <ejb-link> or beanName in the same EJB reference.
Note: All of the following EJB reference examples assume the SampleCart bean has only a single interface. If the SampleCart bean had multiple interfaces, then add the following suffix to the end of the binding, <ejb-link> element, or beanName attribute : !com.sample.Cart.

In the following example, an application declares an EJB reference using an annotation, and provides a binding for resolution.

@EJB(name="Cart")
Cart shoppingCart;

<ejb-ref name="Cart" binding-name="java:app/SampleEJB/SampleCart"/>

In the following example, an application declares an EJB reference using an annotation, and provides an ejb-link element for resolution.

@EJB(name="Cart")
Cart shoppingCart;

<ejb-local-ref>
    <ejb-ref-name>Cart</ejb-ref-name>
    <ejb-link>SampleEJB/SampleCart</ejb-link>
</ejb-local-ref>

In the following example, an application declares an EJB reference using an annotation, and provides a lookup attribute for resolution, from the source bean com.sample.SourceBean.

@EJB(name="Cart" lookup="java:app/SampleEJB/SampleCart")
Cart shoppingCart;

The application could alternatively declare the EJB reference using the <lookup-name> element in the XML deployment descriptor, as in the following example.

<ejb-local-ref>
    <ejb-ref-name>Cart</ejb-ref-name>
    <lookup-name>java:app/SampleEJB/SampleCart</lookup-name>
    <injection-target>
    <injection-target-class>com.sample.SourceBean</injection-target-class>
    <injection-target-name>ShoppingCart</injection-target-name>
    </injection-target>
</ejb-local-ref>

In the following example, an application declares an EJB reference using an annotation, and provides a beanName attribute for resolution.

@EJB(name="Cart" beanName="SampleEJB/SampleCart")
Cart shoppingCart;

Resource Environment References

As described in the Java EE 6 specification, you can develop applications to declare references to administered objects that are associated with a resource, such as a Connecter CCI InteractionSpec instance, or other object types managed by the EJB container, including javax.transaction.UserTransaction, javax.ejb.EJBContext, javax.ejb.TimerServcie, org.omg.CORBA.ORB, javax.validation.Validator, javax.validation.ValidatorFactory, or javax.enterprise.inject.spi.BeanManager.

When an application declares a reference to an administered object, you must provide a binding to the administered object when the application is deployed. You can provide the binding using the administrative console when you deploy the application, or you can add the binding to the WebSphere® binding XML file, ibm-ejb-jar-bnd.xml or ibm-web-bnd.xml.

In the following example, an application declares a resource environment reference, and provides a binding to the resource:

@Resource(name="jms/ResponseQueue")
Queue responseQueue;

<session name="StatelessSampleBean">
    <resource-env-ref name="jms/ResponseQueue" binding-name="Jetstream/jms/ResponseQueue"/>
</session>

The application could alternatively declare the resource environment reference using the lookup attribute, and not require a binding, as in the following example:

@Resource(name="jms/ResponseQueue", lookup="Jetstream/jms/ResponseQueue")
Queue responseQueue;

<resource-env-ref>
    <resource-env-ref-name>jms/ResponseBean</resource-env-ref-name>
    <resource-env-ref-type>javax.jms.Queue</resource-env-ref-type>
</resource-env-ref>

When an application declares a reference to a container managed object type, a binding is not used. The container provides the correct instance of the referenced object. In the following example, an application declares a resource environment reference to a container-managed object:

@Resource
javax.validation.Validator validator;

Resource References to Resource References

A new lookup field on the @Resource annotation is added with Java EE 6. You can now declare a resource reference to a resource reference as shown in the following example:
@Resource(name="java:global/env/jdbc/ds1ref",
              lookup="java:global/env/jdbc/ds1",
              authenticationType=Resource.AuthenticationType.APPLICATION,
              shareable=false)
    DataSource ds1ref;
@Resource(name="java:global/env/jdbc/ds1refref",
              lookup="java:global/env/jdbc/ds1ref",
              authenticationType=Resource.AuthenticationType.APPLICATION,
              shareable=true)
    DataSource ds1refref;
The lookup uses the innermost nesting of references, which in this case is "java:global/env/jdbc/ds1ref".