Creating EclipseLink Files for Deployment (ELUG)

From Eclipsepedia

Jump to: navigation, search

Contents

Related Topics

This section includes EclipseLink information that you need when creating deployment files for various types of applications.

For more information on packaging and deployment, see the following:


Introduction to the EclipseLink Deployment File Creation

Depending on the type of application you are deploying, you may need to create any of the following deployment files:

Workbench provides the ability to create deployment files from a Workbench project. After you build a project, you have two options to create the deployment files:

  • Create XML deployment files that require no compiling.
  • Create Java source files, which you compile and deploy outside of Workbench.

We recommend XML deployment because XML files are easier to deploy and troubleshoot than compiled Java files. This approach gives you a very flexible configuration that enables you to make changes safely and easily. XML deployment files do not require third-party applications or compilers to deploy successfully.

Note: If you are using JPA, you can use annotations to specify most of what you formerly specified in deployment descriptors. Use deployment descriptors to override annotations or specify options not supported by annotations.


project.xml File

The project.xml file is the core of your application. It contains the descriptors and mappings you define and also includes any named queries or finders associated with your project.


XSD File Format

The project.xml file XSD is eclispelink-object-persistence_1_0.xsd and it is located in the <ECLIPSELINK_HOME>\xsds directory.

POJO Applications and Project Metadata

For a POJO application, you define your project metadata in a project.xml file.

The project.xml file provides a simple and flexible way to configure, modify, and troubleshoot the project metadata. Because of these attributes, the project.xml file is the preferred way to configure an EclipseLink project.Workbench provides a graphical tool to build and edit the project.xml file. For information on creating projects with Workbench, see Creating the project.xml File with Workbench.


JPA Applications and Project Metadata

For a JPA application, you can express project metadata using JPA annotations, persistence.xml, orm.xml, and EclipseLink JPA annotation and persistence.xml property extensions. The EclipseLink JPA persistence provider interprets all these sources of metadata to create an in-memory EclipseLink session and project at run time.

Using EclipseLink JPA, you also have the option of specifying your metadata using EclipseLink sessions.xml and project.xml while accessing your persistent classes using JPA and an EntityManager. For more information, see What You May Need to Know About EclipseLink JPA Overriding Mechanisms.

Creating the project.xml File with Workbench

Because you must synchronize the project.xml file with the classes and data source associated with your application, we recommend that you not modify this file manually. Workbench ensures proper synchronization, and is the best way to make changes to the project. Simply modify the project in Workbench and redeploy the project.xml file. Using this option reduces development time by eliminating the need to regenerate and recompile Java code each time the project changes.

See Exporting Project Information for detailed information on exporting the deployment XML information.


Note: You can name this file with a name other than project.xml; however, for clarity, this discussion assumes that the file has not been renamed.


Creating project.xml Programatically

Optionally, you can use the DeploymentXMLGenerator API to programatically generate the project.xml file in either of the following ways:

  • From an application, instantiate the DeploymentXMLGenerator and your java source. Call the following method:generate (<MW_Project.mwp>, <output file.xml>)
  • From the command line, use the following:
java -classpath eclipselink.jar;eclispelinkmw.jar;
org.eclipse.persistence.tools.workbench.mappings.DeploymentXMLGenerator <MW_Project.mwp> <output file.xml>

Before you use either method, ensure that your classpath includes the <ECLIPSELINK_HOME>\jlib\eclipselink.jar and <ECLIPSELINK_HOME>\utils\workbench\jlib\eclipselinkmw.jar directories.


Note: If you are using EJB 3.0, you can use annotations to specify most of what you formerly specified in the project.xml file. To override annotations or specify options not supported by annotations, you can still provide a project.xml file in your EJB 3.0 application.

sessions.xml File

Each EclipseLink project belongs to an EclipseLink session. A session is the facade through which an application accesses EclipseLink functionality (for more information on sessions, see EclipseLink Sessions).


XSD File Format

The sessions.xml file XSD is eclipse_persistence_sessions_1_0.xsd and it is located in the <ECLIPSELINK_HOME>\xsds directory as well as on the web at http://www.eclipse.org/eclipselink/xsds/eclipse_persistence_sessions_1_0.xsd.

When you use the XSD formatted sessions.xml file, the EclipseLink run time separates sessions.xml file validation from session instantiation. Separating XML file formatting problems from Session Manager session instantiation problems simplifies troubleshooting. Exceptions thrown during validation clearly indicate that the failure is due to an invalid sessions.xml file, as the following illustrates.


Enhanced Validation Exceptions

Exception [ECLIPSELINK-9010] (EclipseLink): org.eclipselink.exceptions.SessionLoaderException
Exception Description: A End tag does not match start tag 'session'. was thrown while parsing the XML file against the XML schema.
Internal Exception: oracle.xml.parser.v2.XMLParseException: End tag does not match start tag 'session'.

POJO Applications and Session Metadata

For a POJO application, you define your sessions in a sessions.xml file.

The sessions.xml file provides a simple and flexible way to configure, modify, and troubleshoot the application sessions. Because of these attributes, the sessions.xml file is the preferred way to configure an EclipseLink session.EclipseLink provides graphical toosl to build and edit the sessions.xml file. For information see Creating a Session.


JPA Applications and Session Metadata

For a JPA application, you can express session metadata using JPA annotations, persistence.xml, orm.xml, and EclipseLink JPA annotation and persistence.xml property extensions. The EclipseLink JPA persistence provider interprets all these sources of metadata to create an in-memory EclipseLink session and project at run time.

Using EclipseLink JPA, you also have the option of specifying your metadata using EclipseLink sessions.xml and project.xml while accessing your persistent classes using JPA and an EntityManager. For more information, see What You May Need to Know About EclipseLink JPA Overriding Mechanisms.

Creating Deployment Files for Java Applications

In a Java application, EclipseLink does not use a Java EE container for deployment. Instead, it relies on EclipseLink mechanisms to provide functionality and persistence. The key elements of this type of application are the lack of a Java EE container and the fact that you deploy the application by placing the application JAR file on the classpath.

Java applications require the following deployment files:


Creating Deployment Files for JavaServer Pages and Servlet Applications

Many designers build EclipseLink applications that use JavaServer Pages (JSP) and Java servlets. This type of design generally supports Web-based applications.

JSP and servlet applications require the following deployment files:


Creating Deployment Files for Session Bean Applications

Session beans generally model a process, operation, or service and as such, are not persistent. You can build EclipseLink applications that wrap interaction with EclipseLink in session beans. Session beans execute all EclipseLink-related operations on behalf of the client.

This type of design uses JTS and externally managed transactions, but does not incur the overhead associated with persistence applications. Session bean applications also scale and deploy easily.

This section describes the following:


How to Create Deployment Files for EJB 3.0 Session Bean Applications

We recommend using JPA annotations and persistence unit properties, or a special-case eclipselink.sessions-xml persistence unit property (see EclipseLink JPA Persistence Unit Properties for Database, Session, and Application Server) in your EJB 3.0 session bean application.

You may also choose to use the project.xml File and sessions.xml File.

For more information, see the following:

Creating Deployment Files for JPA Applications

See Packaging and Deploying EclipseLink JPA Applications for information on how to create deployment files for your JPA application.

Configuring the orion-ejb-jar.xml File for OC4J

To deploy a EclipseLink application to OC4J, modify the orion-ejb-jar.xml file. For more information, see How to Configure persistence-manager Entries.


How to Configure persistence-manager Entries

If you are using EclipseLink as your OC4J persistence manager, you can configure the persistence-manager subentry (see the orion-ejb-jar.xml File persistence-manager Entries table) in the orion-ejb-jar.xml file.

If you are not using EclipseLink as your OC4J persistence manager, do not modify the persistence-manager subentries.

OC4J does not support entity-deployment attribute pm-name. Use persistence-manager attribute name instead (see the orion-ejb-jar.xml File persistence-manager Entries table). When OC4J parses the orion-ejb.jar.xml file, if it finds a pm-name attribute, OC4J ignores its value and logs the following warning message:


Use of pm-name is unsupported and will be removed in a future release. 
Specify pm usage using  <persistence-manager> 'name' instead.


orion-ejb-jar.xml File persistence-manager Entries

Entry Description

name

The name of the persistence manager to use. Set this value to eclipselink.

If you set the name property to eclipselink, you may also configure pm-properties (see Configuring pm-properties).

class-name

Do not configure this attribute. If name is set to eclipselink, then class-name is set correctly by default.

descriptor

This property applies only when name is set to eclipselink.

If you export your EclipseLink mapping metadata to a deployment XML file, set this property to the name of the deployment XML file (default: toplink-ejb-jar.xml).

Do not set this property if you are using a EclipseLink project class instead of a mapping metadata file (see project-class in the orion-ejb-jar.xml File persistence-manager Subentries for pm-properties table).



Configuring pm-properties

When you select EclipseLink as the persistence manager (see name in the orion-ejb-jar.xml File persistence-manager Entries table), use the persistence-manager subentries for pm-properties (see the orion-ejb-jar.xml File persistence-manager Subentries for pm-properties table) to configure the EclipseLink session that the EclipseLink run time creates and uses internally.


Note: You can only configure a subset of session features using these properties and in most cases, default configuration applies. To configure all session features and to override defaults, you must use a customization class (see customization-class in the orion-ejb-jar.xml File persistence-manager Subentries for pm-properties table).


orion-ejb-jar.xml File persistence-manager Subentries for pm-properties

Entry Description

session-name

Unique name for this EclipseLink-persisted EJB deployment JAR file. Must be unique among all EclipseLink-persisted deployed JAR files in this application server instance.

When the EclipseLink run time internally creates a EclipseLink session for this EclipseLink-persisted deployed JAR file, the EclipseLink session manager stores the session instance under this session-name. For more information about the session manager, see Acquiring and Using Sessions at Run Time).

If you do not specify a name, the EclipseLink runtime will generate a unique name.

project-class

If you export your EclipseLink mapping metadata to a Java class (that extends org.eclipse.persistence.sessions.Project), set this property to the name of the class, fully qualified by its package name. Be sure to include the class file in the deployable JAR file.

Do not set this property if you are using a mapping metadata file (see descriptor in the orion-ejb-jar.xml File persistence-manager Entries table).

customization-class

Optional Java class (that implements org.eclipse.persistence.ejb.cmp.DeploymentCustomization) used to allow deployment customization of EclipseLink mapping and run-time configuration. At deployment time, the EclipseLink run time creates a new instance of this class and invokes its methods beforeLoginCustomization (before the EclipseLink run time logs into the session) and afterLoginCustomization (after the EclipseLink runtime logs into the session), passing in the EclipseLink session as a parameter.

Use your implementation of the beforeLoginCustomization method to configure session attributes not supported by the pm-properties including: cache coordination (see also Configuring cache-synchronization Properties), parameterized SQL, native SQL, batch writing/batch size, byte-array/string binding, EIS login, event listeners, table qualifier, and sequencing. For more information about session configuration, see Configuring a Session.

The class must be fully qualified by its package name and included in the deployment JAR file.

db-platform-class

Optional EclipseLink database platform class (instance of org.eclipse.persistence.platform.database or org.eclipse.persistence.platform.database.oracle) containing EclipseLink support specific to a particular database.

Set this value to the database platform class that corresponds to the database that your application uses. The class must be fully qualified by its package name.

remote-relationships

Optional flag to allow relationships between remote objects. Valid values are:

  • true: All relationships will be maintained through the remote interfaces of the entity beans
  • false: Disables this feature.

cache-synchronization

See Configuring cache-synchronization Properties.

default-mapping

See Configuring default-mapping Properties.


Configuring cache-synchronization Properties

When you select EclipseLink as the persistence manager (see name in the orion-ejb-jar.xml File persistence-manager Entries table), use the pm-properties subentry for cache-synchronization (see the orion-ejb-jar.xml File pm-properties Subentries for cache-synchronization table table) to configure EclipseLink cache coordination features of the session that the EclipseLink run time uses internally for CMP projects. For more information about EclipseLink cache coordination, see Cache Coordination.

When this subentry is present, you must use a customization class (see customization-class in the orion-ejb-jar.xml File persistence-manager Subentries for pm-properties table) to complete cache coordination configuration. For more information about EclipseLink cache coordination configuration, see Configuring a Coordinated Cache.

orion-ejb-jar.xml File pm-properties Subentries for cache-synchronization

Entry Description

mode

An indicator of whether or not cache coordination updates should be propagated to other servers synchronously or asynchronously. Valid values are as follows:

  • asynchronous (default)
  • synchronous

server-url

For a JMS coordinated cache: assuming that you are using the Oracle Containers for J2EE (OC4J) JNDI naming service and that all the hosts in your coordinated cache can communicate using OC4J proprietary RMI protocol ORMI, use a URL like:

ormi://<JMS-host-IP>:<JMS-host-port>

where JMS-host-IP is the IP address of the host on which the JMS service provider is running and JMS-host-port is the port on which the JMS service provider is listening for JMS requests.
For an RMI or CORBA coordinated cache: assuming that you are using the OC4J JNDI naming service and that all the hosts in your coordinated cache can communicate using OC4J proprietary RMI protocol ORMI on OC4J default port 23791, use a URL like:

ormi://<session-host-IP>:23791

where session-host-IP is the IP address of the host on which this session is deployed.

server-user

Optional username required to log in to the JNDI naming service.


Configuring default-mapping Properties

When you select EclipseLink as the persistence manager (see name in the orion-ejb-jar.xml File persistence-manager Entries table), use the pm-properties subentry for default-mapping (see the the following table table) to configure the EclipseLink default mapping and automatic table generation feature.

For more information about EclipseLink automatic table generation, see Creating Database Tables Automatically.


orion-ejb-jar.xml File pm-properties Subentries for default-mapping

Entry Description

db-table-gen

Optional element that determines what EclipseLink will do to prepare the database tables that are being mapped to. Valid values are:

  • Create (default): This value tells EclipseLink to create the mapped tables during the deployment. If the tables already exist, EclipseLink will log an appropriate warning messages (such as "Table already existed...") and keeps processing the deployment.
  • DropAndCreate: This value tells EclipseLink to drop tables before creating them during deployment. If a table does not initially exist, the drop operation will cause anSQLException to be thrown through the driver. However, EclipseLink handles the exception (logs and ignores it) and moves on to process the table creation operation. The deployment fails only if both drop and create operations fail.
  • UseExisting: This value tells EclipseLink to perform no table manipulation. If the tables do not exist, deployment still goes through without error.

If no orion-ejb-jar.xml file is defined in your EAR file, the OC4J container generates one during deployment. In this case, to specify a value for db-table-gen, use the EclipseLink system property eclipselink.defaultmapping.dbTableGenSetting. For example: -Declipselink.defaultmapping.dbTableGenSetting="DropAndCreate".

The orion-ejb-jar.xml property overrides the system property. If both the orion-ejb-jar.xml property and the system property are present, EclipseLink retrieves the setting from the orion-ejb-jar.xml file.

This setting overrides autocreate-tables and autodelete-tables configuration at the application (EAR) or system level. For more information, see Creating Database Tables Automatically.

extended-table-names

An element used if the generated table names are not long enough to be unique. Values are restricted to true or false (default). When set to true, the EclipseLink run time will ensure that generated tables names are unique.

In default mapping, each entity is mapped to one table. The only exception is in many-to-many mappings where there is one extra relation table involved in the source and target entities.

When extended-table-names is set to false (the default), a simple table naming algorithm is used as follows: table names are defined as TL_<bean_name>. For example, if the bean name is Employee, the associated table name would be TL_EaMPLOYEE.

However, if the same entity is defined in multiple JAR files in an application, or across multiple applications, table-naming collision is inevitable.

To address this problem, set extended-table-names to true. When set to true, EclipseLink uses an alternative table-naming algorithm as follows: table names are defined as <bean_name>_<jar_name>_<app_name>. This algorithm uses the combination of bean, JAR, and EAR names to form a table name unique across the application. For example, given a bean named Employee, which is in Test.jar, which is in Demo.ear (and the application name is "Demo"), then the corresponding table name will be EMPLOYEE_TEST_DEMO.

If there is no orion-ejb-jar.xml file defined in the EAR file, the OC4J container generates one during deployment. In this case, to specify a value for extended-table-names, use the EclipseLink system property eclipselink.defaultmapping.useExtendedTableNames. For example: -Declipselink.defaultmapping.useExtendedTableNames="true".

The orion-ejb-jar.xml property overrides the system property. If both the orion-ejb-jar.xml property and the system property are present, EclipseLink retrieves the setting from the orion-ejb-jar.xml file.

Configuring the weblogic-ejb-jar.xml File for WebLogic Server

Before you deploy a EclipseLink application to a WebLogic Server, you must modify the weblogic-ejb-jar.xml file.

Avoid the weblogic-ejb-jar.xml tags that EclipseLink either does not support or does not require (see What You May Need to Know About Unsupported weblogic-ejb-jar.xml File Tags).


What You May Need to Know About Unsupported weblogic-ejb-jar.xml File Tags

The weblogic-ejb-jar.xml file includes the following tags that EclipseLink either does not support or does not require:

  • concurrency-strategy: This tag specifies how WebLogic manages concurrent users for a given bean. Because EclipseLink manages concurrent access internally, it does not require this tag.
    For more information about the EclipseLink concurrency strategy, see Configuring Locking Policy.
  • db-is-shared: Because EclipseLink does not make any assumptions about the exclusivity of database access, EclipseLink does not require this tag. EclipseLink addresses multiuser access issues through various locking and refreshing policies.
  • delay-updates-until-end-of-tx: EclipseLink always delays updates until the end of a transaction, and does not require this tag.
  • finders-load-bean: EclipseLink always loads the bean upon execution of the finder, and does not require this tag.
  • pool: EclipseLink does not use a pooling strategy for entity beans. This avoids object-identity problems that can occur due to pooling.
  • lifecycle: This element manages beans that follow a pooling strategy. Because EclipseLink does not use a pooling strategy, EclipseLink ignores this tag.
  • is-modified-method-name: EclipseLink does not require a bean developer-defined method to detect changes in the object state.
  • isolation-level: Because isolation level settings for the cache or database transactions are specified in the EclipseLink project, EclipseLink ignores this tag.
  • cache: Because you define EclipseLink cache properties in Workbench, this tag is unnecessary.



Copyright Statement