View source for Packaging and Deploying EclipseLink JPA Applications (ELUG)

[[Image:Elug draft icon.png]] '''For the latest EclipseLink documentation, please see http://www.eclipse.org/eclipselink/documentation/ '''

----

<div style="float:right;border:1px solid #000000;padding:5px">__TOC__
[[Special:Whatlinkshere/Packaging and Deploying EclipseLink JPA Applications (ELUG)|Related Topics]]</div>


==Packaging an EclipseLink JPA Application==
Packaging means assembling all parts of the application in a way that can be correctly interpreted and used by the infrastructure when the application is deployed into an application server or run in a stand-alone JVM.

Once you chose a packaging strategy, place the <tt>persistence.xml</tt> file in the <tt>META-INF</tt> directory of the archive of your choice.

In a Java EE environment, the most efficient way to package your application is to use a tool, such as JDeveloper or Eclipse. Using OC4J, it is possible to skip the packaging step and deploy from your working directories using expanded deployment.

To package your EclipseLink JPA application, you need to configure the [[Developing%20Applications%20Using%20EclipseLink%20JPA%20(ELUG)#Persistence Unit|persistence unit]] during the creation of the [[Introduction%20to%20Java%20Persistence%20API%20(ELUG)#persistence.xml File|<tt>persistence.xml</tt> file]]. Define each persistence unit in a <tt>persistence-unit</tt> element in the <tt>persistence.xml</tt> file.

For more information, see the following:
* Chapter 6 "Entity Packaging" of the [http://jcp.org/en/jsr/detail?id=220 JPA Specification]
* [[Packaging%20a%20EclipseLink%20Application%20(ELUG)|Packaging an EclipseLink Application]]


===How to Specify the Persistence Unit Name===
If you are developing your application in a Java EE environment, ensure that the persistence unit name is unique within each module. For example, you can define only one persistence unit with the name <tt>"EmployeeService"</tt> in an <tt>emp_ejb.jar</tt> file. The following example shows how to define the name of the persistence unit:
<source lang="xml">
 <persistence-unit name="EmployeeService">
</source>

For more information, see Section 6.2.1.1 "name" of the [http://jcp.org/en/jsr/detail?id=220 JPA Specification].


===How to Specify the Transaction Type, Persistence Provider and Data Source===
If you are developing your application in a Java EE environment, accept the default transaction type (see Section 6.2.1.2 "transaction-type" of the [http://jcp.org/en/jsr/detail?id=220 JPA Specification])–JTA (see [[Introduction%20to%20Java%20Persistence%20API%20(ELUG)#JTA Transaction Management|JTA Transaction Management]]), and for the persistence provider setting, set the persistence provider in a <tt>provider</tt> element (see Section 6.2.1.2 "provider" of the [http://jcp.org/en/jsr/detail?id=220 JPA Specification]). Specify the data source in a <tt>jta-data-source</tt> element, as the following example shows:
<source lang="xml">
 <persistence-unit name="EmployeeService">
     <jta-data-source>jdbc/EmployeeServiceDS</jta-data-source>
 </persistence-unit>
</source>
Typically, you would use the JNDI access to the data source. Make this data source available by configuring it in a server-specific configuration file or management console.

For more information, see the following sections of the [http://jcp.org/en/jsr/detail?id=220 JPA Specification]:
* Section 6.2.1.2 "transaction-type"
* Section 6.2.1.4 "provider"
* Section 6.2.1.5 "jta-data-source, non-jta-data-source"

===How to Specify Mapping Files===
Apply the metadata to the persistence unit. This metadata is a union of all the mapping files and the annotations (if there is no <tt>xml-mapping-metadata-complete</tt> element). If you use one mapping [[Introduction%20to%20Java%20Persistence%20API%20(ELUG)#Metadata Annotations and ORM.xml File|<tt>orm.xml</tt> file]]) for your metadata, and place this file in a <tt>META-INF</tt> directory on the classpath, then you do not need to explicitly list it, because the EclipseLink persistence provider will automatically search for this file and use it. If you named your mapping files differently or placed them in a different location, then you must list them in the <tt>mapping-file</tt> elements in the <tt>persistence.xml</tt> file, as the following example shows:
<source lang="xml">
 <persistence-unit name="EmployeeService">
     <jta-data-source>jdbc/EmployeeServiceDS</jta-data-source>
     <mapping-file>META-INF/employee_service_queries.xml</mapping-file>
 </persistence-unit>
</source>

Note that the <tt>orm.xml</tt> file is not listed in the previous example, because the persistence provider finds it by default.

For more information, see the following:
* Section 6.2.1.6 "mapping-file, jar-file, class, exclude-unlisted-classes" of the [http://jcp.org/en/jsr/detail?id=220 JPA Specification]


===How to Specify Managed Classes===
Typically, you put all of the entities and other managed classes in a single JAR file, along with the <tt>persistence.xml</tt> file in the <tt>META-INF</tt> directory, and one or more mapping files (when you use XML mapping).

At the time EclipseLink persistence provider processes the persistence unit, it determines which set of entities, mapped superclasses, and embedded objects each particular persistence unit will manage.

At deployment time, EclipseLink persistence provider may obtain managed classes from any of the four sources. A managed class will be included if it is one of the following:

* Local classes: the classes annotated with <tt>@Entity</tt> (see Section 8.1 "Entity" of the [http://jcp.org/en/jsr/detail?id=220 JPA Specification]), [[Introduction%20to%20EclipseLink%20JPA%20(ELUG)#@MappedSuperclass|<tt>@MappedSuperclass</tt>]] or [[Introduction%20to%20EclipseLink%20JPA%20(ELUG)#@Embeddable|<tt>@Embeddable</tt>]] in the deployment unit in which its <tt>persistence.xml</tt> file was packaged.<br />
{| class="Note oac_no_warn" width="80%" border="1" frame="hsides" rules="groups" cellpadding="3" frame="hsides" rules="groups"
| align="left" |
'''Note:''' If you are deploying your application in the Java EE environment, not EclipseLink persistence provider, but the application server itself will discover local classes. In the Java SE environment, you can use the <tt>exclude-unlisted-classes</tt> element (see Section 6.2.1.6 "mapping-file, jar-file, class, exclude-unlisted-classes" of the [http://jcp.org/en/jsr/detail?id=220 JPA Specification]) to enable this functionality–EclipseLink persistence provider will attempt to find local classes if you set this element to <tt>false</tt>.
|}<br />
* Classes in mapping files: the classes that have mapping entries, such as <tt>entity</tt> (see Section 10.1.2.10 "entity" of the [http://jcp.org/en/jsr/detail?id=220 JPA Specification]), <tt>mapped-superclass</tt> (see Section 10.1.2.11 "mapped-superclass" of the [http://jcp.org/en/jsr/detail?id=220 JPA Specification]) or <tt>embeddable</tt> (see Section 10.1.2.12 "embeddable" of the [http://jcp.org/en/jsr/detail?id=220 JPA Specification]), in an XML mapping file.<br>If these classes are in the deployed component archive, then they will already be on the classpath. If they are not, you must explicitly include them in the classpath.
* Explicitly listed classes: the classes that are listed as <tt>class</tt> elements in the <tt>persistence.xml</tt> file.<br>Consider listing classes explicitly if one of the following applies:
** there are additional classes that are not local to the deployment unit JAR. For example, there is an embedded object class in a different JAR that you want to use in an entity in your persistence unit. You would list the fully qualified class in the <tt>class</tt> element in the <tt>persitence.xml</tt> file. You would also need to ensure that the JAR or directory that contains the class is on the classpath of the deployed component (by adding it to the manifest classpath of the deployment JAR, for example);
** you want to exclude one or more classes that may be annotated as an entity. Even though the class may be annotated with the <tt>@Entity</tt> annotation, you do not want it treated as an entity in this particular deployed context. For example, you may want to use this entity as a transfer object and it needs to be part of the deployment unit. In this case, in the Java EE environment, you have to use the <tt>exclude-unlisted-classes</tt> element (see Section 6.2.1.6 "mapping-file, jar-file, class, exclude-unlisted-classes" of the [http://jcp.org/en/jsr/detail?id=220 JPA Specification]) of the <tt>persistence.xml</tt> file–the use of the default setting of this element prevents local classes from being added to the persistence unit;
** you plan to run your application in the Java SE environment, and you list your classes explicitly because that is the only portable way to do so in Java SE (see [[#How to Perform an Application Bootstrapping|How to Perform an Application Bootstrapping]]).
* Additional JAR files of managed classes: the annotated classes in a named JAR file listed in a <tt>jar-file</tt> element (see Section 6.2.1.6 "mapping-file, jar-file, class, exclude-unlisted-classes" of the [http://jcp.org/en/jsr/detail?id=220 JPA Specification]) in the <tt>persistence.xml</tt> file.<br>You have to ensure that any JAR file listed in the <tt>jar-file</tt> element is on the classpath of the deployment unit. Do so by manually adding the JAR file to the manifest classpath of the deployment unit.<br>Note that you must list the JAR file in the <tt>jar-file</tt> element relative to the parent of the JAR file in which the <tt>persistence.xml</tt> file is located. This matches what you would put in the classpath entry in the manifest file. The following example shows the structure of the <tt>emp.ear</tt> EAR file: 
 emp.ear
     emp-ejb.jar
         META-INF/persistence.xml
     employee/emp-classes.jar
         examples/model/Empoyee.class

The following example shows the contents of the <tt>persistence.xml</tt> file, with the <tt>jar-file</tt> element containing "employee/emp-classes.jar" to reference the <tt>emp-classes.jar</tt> in the <tt>employee</tt> directory in the EAR file: 
<source lang="xml">
 <persitence-unit name="EmployeeService">
     <jta-data-source>jdbc/EmployeeServiceDS</jta-data-source>
     <jar-file>employee/emp-classes.jar</jar-file>
 </persitence-unit>
</source>

You may choose to use any one or a combination of these mechanisms to include your managed classes in the persistence unit.

For more information, see [[#How to Deploy an Application to Generic Java EE 5 Application Servers|How to Deploy an Application to Generic Java EE 5 Application Servers]].


===How to Add Vendor Properties===
The last section in the <tt>persistence.xml</tt> file is the properties section. The <tt>properties</tt> element (see Section 6.2.1.7 "properties" of the [http://jcp.org/en/jsr/detail?id=220 JPA Specification]) gives you the chance to supply EclipseLink persistence provider-specific settings for the persistence unit.

This example shows how to add EclipseLink-specific properties.

<span id="Example 22-1"></span>
'''''Using EclipseLink Persistence Provider Properties'''''
<source lang="xml">
 <persitence-unit name="EmployeeService">
     ...
     <properties>
         <property name="eclipselink.logging.level" value="FINE"/>
 
         <property name="eclipselink.cache.size.default" value="500"/>
     </properties>
 </persitence-unit>
</source>

For more information, see the following:
* [[Using%20EclipseLink%20JPA%20Extensions%20(ELUG)#What You May Need to Know About Using EclipseLink JPA Persistence Unit Properties|What You May Need to Know About Using EclipseLink JPA Persistence Unit Properties]]
* [[Using%20EclipseLink%20JPA%20Extensions%20(ELUG)|Using EclipseLink JPA Extensions]]

===How to Set Up the Deployment Classpath===
To be accessible to the EJB JAR, WAR, or EAR file, a class or a JAR file must be on the deployment classpath. You can achieve this in one of the following ways:
* Put the JAR file in the manifest classpath of the EJB JAR or WAR file. Do this by adding a classpath entry to the <tt>META-INF/MANIFEST.MF</tt> file in the JAR or WAR file. You may specify one or more directories or JAR files, separating them by spaces. The following example shows how the manifest file classpath entry adds the <tt>employee/emp-classes.jar</tt> file and the <tt>employee/classes</tt> directory to the classpath of the JAR file that contains the manifest file: 
 Class-Path: employee/emp-classes.jar employee/classes
* Place the JAR file in the library directory of the EAR file–this will make this JAR file available on the application classpath and accessible by all of the modules deployed within the EAR file. By default, this would be the <tt>lib</tt> directory of the EAR file, although you may configure it to be any directory in the EAR file using the <tt>library-directory</tt> element in the <tt>application.xml</tt> deployment descriptor. The following example shows the <tt>application.xml</tt> file: 
 <application ...>
     ...
     <library-directory>myDir/jars</library-directory>
 </application>

===What You May Need to Know About Persistence Unit Packaging Options===
Java EE allows for persistence support in a variety of packaging configurations. You can deploy your application to the following module types:
* EJB modules: you can package your entities in an EJB JAR. When defining a persistence unit in an EJB JAR, the <tt>persistence.xml</tt> file is not optional–you must create and place it in the <tt>META-INF</tt> directory of the JAR alongside the deployment descriptor, if it exists.
* Web modules: you can use WAR file to package your entities. In this case, place the <tt>persistence.xml</tt> file in the <tt>WEB-INF/classes/META-INF</tt> directory. Since the <tt>WEB-INF/classes</tt> directory is automatically on the classpath of the WAR, specify the mapping file relative to that directory.
* Persistence archives: a persistence archive is a JAR that contains a <tt>persistence.xml</tt> file in its <tt>META-INF</tt> directory and the managed classes for the persistence unit defined by the <tt>persistence.xml</tt> file. Use a persistence archive if you want to allow multiple components in different Java EE modules to share or access a persistence unit. The following example shows how to package entities in a persistence archive: 
 emp.ear
     emp-persitence.jar
         META-INF/persistence.xml
         META-INF/orm.xml
         examples/model/Employee.class
         examples/model/Phone.class
         examples/model/Address.class
         examples/model/Department.class
         examples/model/Project.class

Once you created a persistence archive, you can place it in either the root or the application library directory of the EAR. Alternatively, you can place the persistence archive in the <tt>WEB-INF/lib</tt> directory of a WAR. This will make the persistence unit accessible only to the classes inside the WAR, but it enables the decoupling of the definition of the persistence unit from the web archive itself.

For more information, see Section 6.2 "Persistence Unit Packaging" of the [http://jcp.org/en/jsr/detail?id=220 JPA Specification].


===What You May Need to Know About the Persistence Unit Scope===
You can define any number of persistence units in single <tt>persistence.xml</tt> file. The following are the rules for using defined and packaged persistence units:
* Persistence units are accessible only within the scope of their definition.
* Persistence units names must be unique within their scope.

For more information, see Section 6.2.2 "Persistence Unit Scope" of the [http://jcp.org/en/jsr/detail?id=220 JPA Specification].


===How to Perform an Application Bootstrapping===
Outside of a container, use the <tt>createEntityManagerFactory</tt> method of the <tt>javax.persistence.Persistence</tt> class to create an entity manager factory. This method accepts a <tt>Map</tt> of properties and the name of the persistence unit. The properties that you pass to this method are combined with those that you already specified in the <tt>persistence.xml</tt> file. They may be additional properties or they may override the value of a property that you specified previously.


{| class="Note oac_no_warn" width="80%" border="1" frame="hsides" rules="groups" cellpadding="3" frame="hsides" rules="groups"
| align="left" |
'''Note:''' This is a convenient way to set properties obtained from a program input, such as the command line.
|}


This example shows how to take the user name and password properties from the command line and pass them to the EclipseLink persistence provider when creating the <tt>EntityManagerFactory</tt>.

<span id="Example 22-2"></span>
''''' Using Command-Line Persistence Properties'''''
<source lang="java">
 public class EmployeeService {
 
     public static void main (String[] args) {
         Map props = new HashMap();
         props.put("eclipselink.jdbc.user", args[0]);
         props.put("eclipselink.jdbc.password", args[1]);
         EntityManagerFactory emf = Persistence.createEntityManagerFactory("EmployeeService", props);
         ...
         emf.close();
     }
 }
</source>

For more information, see the following:
* Section 7.2 "Bootstrapping in Java SE Environments" of the [http://jcp.org/en/jsr/detail?id=220 JPA Specification]
* [[Introduction%20to%20Java%20Persistence%20API%20(ELUG)#Application-Managed Entity Manager|Application-Managed Entity Manager]]

<span id="Deploying an EclipseLink JPA Application"></span>


==Deploying an EclipseLink JPA Application==

Deployment is the process of getting the application into an execution environment and running it.

For more information, see the following:
* [[#Packaging a EclipseLink JPA Application|Packaging an EclipseLink JPA Application]]
* [[#How to Specify Managed Classes|How to Specify Managed Classes]]
* [[Creating%20EclipseLink%20Files%20for%20Deployment%20(ELUG)|Creating EclipseLink Files for Deployment]]
* [[Deploying%20a%20EclipseLink%20Application%20(ELUG)|Deploying an EclipseLink Application]]
* Chapter 7 "Container and Provider Contracts for Deployment and Bootstrapping" of the [http://jcp.org/en/jsr/detail?id=220 JPA Specification]


===How to Deploy an Application to OC4J===
After packaging, you deploy your EclipseLink JPA application to OC4J to execute it and make it available to end users.

You can deploy from a Java EE development tool such as [[EclipseLink/Examples/JPA#Integrating_EclipseLink_JPA_with_an_IDE|JDeveloper]] or [[EclipseLink/Examples/JPA/OC4J_Web_Tutorial|Eclipse]].

===How to Deploy an Application to Generic Java EE 5 Application Servers===
Each persistence unit deployed into a Java EE container consists of a single <tt>persistence.xml</tt> file, any number of mapping files, and any number of class files.


{| class="Note oac_no_warn" width="80%" border="1" frame="hsides" rules="groups" cellpadding="3" frame="hsides" rules="groups"
| align="left" |
'''Note:''' If you are deploying to JBoss 4.2 server, refer to [[Integrating%20EclipseLink%20with%20an%20Application%20Server%20(ELUG)#How to Configure JPA Application Deployment to JBoss 4.2 Application Server|How to Configure JPA Application Deployment to JBoss 4.2 Application Server]].
|}





----
''[[EclipseLink User's Guide Copyright Statement|Copyright Statement]]''


[[Category: EclipseLink User's Guide]]
[[Category: Release 1]]
[[Category: Task]]
[[Category: JPA]]