Configuring an Environment Reference to a Persistence Context

The simplest way to acquire an entity manager is by using the @PersistenceContext annotation (see "Acquiring an EntityManager").

However, to acquire an entity manager in a class that does not support annotations and injection, namely helper classes, you must first define a persistence-context-ref in the appropriate deployment descriptor file.

To create an environment reference to a persistence context, do the following:

1. Define a logical name for the persistence context.

   Define a <persistence-context-ref> element in the appropriate client deployment descriptor (see "Where do you Configure an EJB Environment Reference?") and configure the following subelements:

   • <persistence-context-ref-name>: a logical name for the persistence context.

   • <persistence-unit-name>: the name of the persistence unit associated with this persistence context.

     You must define a persistence unit of this name in a persistence.xml file.

     For more information, see the following:

     • "What is the persistence.xml File?"

     • "Configuring the persistence.xml File"

   Example 19-18 shows a <persistence-context-ref> element for a persistence context in a web.xml file.

   It is a best practice to start the reference name with persistence, but it is not required. In the bean code, the lookup of this reference (see "Acquiring an Entity Manager in a Helper Class") is always prefaced by java:comp/env (for example, java:comp/env/persistence/InventoryAppMgr).

   Example 19-20 web.xml For a Persistence Context

   ...
       <servlet>
           <servlet-name>webTierEntryPoint</servlet-name>
           <servlet-class>com.sun.j2ee.blueprints.waf.controller.web.MainServlet</servlet-class>
           <init-param>
               <param-name>default_locale</param-name>
               <param-value>en_US</param-value>
           </init-param>
           <persistence-context-ref>
               <description>
                   Persistence context for the inventory management application.
               </description>
               <persistence-context-ref-name>
                   persistence/InventoryAppMgr
               </persistence-context-ref-name>
               <persistence-unit-name>
                   InventoryManagement <!-- Defined in persistenc.xml -->
               </persistence-unit-name>
           </persistence-context-ref>
       </servlet>
   ...
   

For information on looking up and using an entity manager, see "Acquiring an Entity Manager in a Helper Class".