5 Understanding Application Deployment
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.
For more information, see Chapter 6 "Entity Packaging" in the JPA Specification:
This chapter contains the following sections:
5.1 Integrating with an Application Server
This section describes concepts unique to application server integration, including the following:
5.1.1 Software Requirements
To run EclipseLink applications within a Java EE container, your system must meet the following software requirements:
An application server or Java EE container
A JDBC driver configured to connect with your local database system (for more information, see your database administration documentation);
Any of the following:
Any Java environment that is compatible with the Sun JDK 1.6 or later;
A command-line JVM executable (such as
5.1.2 Setting Security Permissions
By default, when you run applications in a JVM configured with a nondefault
java.lang.SecurityManager, the runtime environment executes certain internal functions by executing a
doPrivileged. This ensures that you do not need to grant many permissions to EclipseLink for it to perform its most common operations. You need only grant certain permissions depending on the types of optional features you use.
If you run EclipseLink-enabled applications in a JVM without a nondefault
SecurityManager, you do not need to set any permissions. For more information, see "Using Oracle TopLink with the Oracle Database" in Oracle Fusion Middleware Solutions Guide for Oracle TopLink. See also the Oracle Database Security Guide and the Oracle Label Security Administrator's Guide.
5.1.3 Migrating Applications to the EclipseLink Persistence Manager
You can configure an application server to use EclipseLink as the persistence manager. You can use only one persistence manager for all of the entities with container-managed persistence in a JAR file.
5.2 About the Persistence Unit
A persistence unit defines the details that are required when you acquire an entity manager. To package your EclipseLink JPA application, you must configure the persistence unit during the creation of the
persistence.xml file. Define each persistence unit in a
persistence-unit element in the
persistence.xml file to package your entities. Once you chose a packaging strategy, place the
persistence.xml file in the
META-INF directory of the archive of your choice. The following sections provide more detail on how to specify the persistence unit. For more information and examples, see "persistence.xml file" in the JPA Specification. For information on EclipseLink extensions to the persistence.xml file, see "Persistence Property Extensions Reference" in Oracle Fusion Middleware Java Persistence API (JPA) Extensions Reference for Oracle TopLink.
5.2.1 About 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
EmployeeService in an
For more information, see "name" in the JPA Specification.
5.2.2 About the Transaction Type, Persistence Provider and Data Source
If you are developing your application in a Java EE environment, accept the default transaction type: JTA, and for the persistence provider setting, set the persistence provider in a
provider element. Specify the data source in a
5.2.3 About 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
xml-mapping-metadata-complete element). If you use one mapping orm.xml file for your metadata, and place this file in a
META-INF 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 mapping-file elements in the
For more information, see "mapping-file, jar-file, class, exclude-unlisted-classes" in the JPA Specification
5.2.4 About Managed Classes
Typically, you put all of the entities and other managed classes in a single JAR file, along with the persistence.xml file in the
META-INF directory, and one or more mapping files (when you store metadata in XML).
At the time the 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, the EclipseLink persistence provider may obtain managed classes from any of the following sources. A managed class will be included if it is one of the following:
Local classes: the classes annotated with
@Embeddablein the deployment unit in which its
persistence.xmlfile was packaged. For more information, see "Entity" in the JPA Specification.
If you are deploying your application in the Java EE environment, the application server itself, not the EclipseLink persistence provider, will discover local classes. In the Java SE environment, you can use the
falseto enable this functionality—EclipseLink persistence provider will attempt to find local classes if you set this element to false. See "mapping-file, jar-file, class, exclude-unlisted-classes" in the JPA Specification.
Classes in mapping files: the classes that have mapping entries, such as entity (see "entity" in the JPA Specification), mapped-superclass or embeddable, in an XML mapping file. For more information, see "mapped-superclass" and "embeddable" in the JPA Specification.
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 class elements in the persistence.xml file.
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 class element in the
persitence.xmlfile. 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 @Entity 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
exclude-unlisted-classeselement of the
persistence.xmlfile—the use of the default setting of this element prevents local classes from being added to the persistence unit. For more information, see "mapping-file, jar-file, class, exclude-unlisted-classes" of the JPA Specification.
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.
Additional JAR files of managed classes: the annotated classes in a named JAR file listed in a jar-file element in the persistence.xml file. For more information, see "mapping-file, jar-file, class, exclude-unlisted-classes" in the JPA Specification.
You have to ensure that any JAR file listed in the jar-file 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.
Note that you must list the JAR file in the jar-file element relative to the parent of the JAR file in which the persistence.xml file is located. This matches what you would put in the classpath entry in the manifest file.
5.2.5 About Vendor Properties
The last section in the
persistence.xml file is the
properties section. The properties element gives you the chance to supply EclipseLink persistence provider-specific settings for the persistence unit. See "properties" in the JPA Specification. see also "Persistence Property Extensions Reference" in Oracle Fusion Middleware Java Persistence API (JPA) Extensions Reference for Oracle TopLink.
5.2.6 About 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.
To do this, add a classpath entry to the
META-INF/MANIFEST.MFfile in the JAR or WAR file. You can specify one or more directories or JAR files, separating them by spaces.
Place the JAR file in the library directory of the EAR file.
This will make the 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
libdirectory of the EAR file, although you may configure it to be any directory in the EAR file using the
library-directoryelement in the
5.2.7 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
persistence.xmlfile is not optional–you must create and place it in the
META-INFdirectory 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
persistence.xmlfile in the
WEB-INF/classes/META-INFdirectory. Since the WEB-INF/classes 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
persistence.xmlfile in its
META-INFdirectory and the managed classes for the persistence unit defined by the persistence.xml file. Use a persistence archive if you want to allow multiple components in different Java EE modules to share or access a persistence unit.
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
WEB-INF/libdirectory 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 "Persistence Unit Packaging" in the JPA Specification.
5.2.8 About the Persistence Unit Scope
You can define any number of persistence units in single
persistence.xml 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 "Persistence Unit Scope" in the JPA Specification.
5.3 Integrating Clustering
Most application servers include a clustering service that you can use with your TopLink application.
To use TopLink with an application server cluster, use this general procedure:
toplink.jarfile (and include it in the classpath) on each application server in the cluster to which you deploy TopLink applications.
Configure the cache consistency options appropriate for your application.
For more information, see Chapter 9, "Understanding Caching."
Configure the coordinated cache support for your application server, if available.
For more information, see Chapter 9, "Understanding Caching."
Configure clustering on each application server.
For more information, see your application server documentation.