Difference between revisions of "EclipseLink/UserGuide/Packaging an Application"

Latest revision as of 11:21, 18 July 2012

For the latest EclipseLink documentation, please see http://www.eclipse.org/eclipselink/documentation/

This section describes EclipseLink-specific details applicable to the common packaging strategies used for various types of applications.

For more information, see the following:

• Integrating EclipseLink with an Application Server
• Creating EclipseLink Files for Deployment
• Deploying a EclipseLink Application

Packaging Java Applications

For non-Java EE Java applications, it is common to package the application in a single JAR file, as this example shows.

Packaging a non-Java EE Java Application

 domain_module.jar
     Java classes that represent the objects mapped
     project.xml
     session.xml
     META-INF
         Manifest.mf

This JAR contains the EclipseLink files and domain objects required by the application, including the following:

• sessions.xml File;
• project.xml File (or the compiled Project class file if you are not using XML files for deployment);
• The mapped classes required by the application, in a fully-resolved directory structure.

When you create the JAR file, the JAR building utility automatically creates a directory structure within the JAR. Ensure that the sessions.xml file and the project.xml file (or project class file) appear at the root of the JAR file. Ensure that the class directory structure starts at the root of the JAR.

If you do not store the project.xml or sessions.xml files at the root of the JAR file, see Packaging with EclipseLink Metadata File Resource Paths.

Packaging JavaServer Pages and Servlet Applications

For simple Java EE applications without EJB, it is common to package the application in an Enterprise Archive (EAR) file made up of various Java EE application component archives, as this example shows.

Packaging a Java EE JSP or Servlet Application Without EJB

 appname.ear
     META-INF
         application.xml
         orion-application.xml
     domain_module.jar
         Java classes that represent the object mapped
         project.xml
         session.xm
         META-INF
             Manifest.mf
     web_module.war
         html pages, JSP’s, etc.
         META-INF
             web.xml
             orion-web.xml
         classes
             servlet classes
         lib
     client_module.jar
         Client classes
         META-INF
             application-client.xml
             orion-application-client.xml

The component archives with EclipseLink dependencies include EclipseLink domain JAR (see How to Create the EclipseLink Domain JAR).

How to Create the EclipseLink Domain JAR

The domain JAR contains the EclipseLink files and domain objects required by the application, including the following:

• sessions.xml File;
• project.xml File (or the compiled Project class file, if you are not using XML files for deployment);
• The mapped classes required by the application, in a fully resolved directory structure.

When you create the JAR file, the JAR building utility automatically creates a directory structure within the JAR. Ensure that the sessions.xml file and the project.xml file (or project.class file) appear at the root of the JAR file. Also ensure that the class directory structure starts at the root of the JAR.

If you do not store the project.xml or sessions.xml files at the root of the JAR file, see Packaging with EclipseLink Metadata File Resource Paths.

Packaging Session Bean Applications

This section contains information on How to Package an EJB 3.0 Session Bean Application.

How to Package an EJB 3.0 Session Bean Application

For information on how to package an EJB 3.0 session bean application, see Packaging a EclipseLink JPA Application.

How to Create the EclipseLink Domain JAR

The domain JAR contains the EclipseLink files and domain objects required by the application, including the following:

• sessions.xml (see sessions.xml File);
• project.xml (see project.xml File) (or the compiled Project.class file if you are not using XML files for deployment);
• The mapped classes required by the application, in a fully-resolved directory structure.

When you create the JAR file, the JAR building utility automatically creates a directory structure within the JAR. Ensure that the sessions.xml file and the project.xml file (or project.class file) appear at the root of the JAR file. Also ensure that the class directory structure starts at the root of the JAR.

If you do not store the project.xml or sessions.xml files at the root of the JAR file, see Packaging with EclipseLink Metadata File Resource Paths.

Packaging JPA Applications

See Packaging a EclipseLink JPA Application for information on how to package your JPA application.

Packaging a POJO Application for Weaving

To package a POJO application for weaving, you create a JAR that contains a sessions.xml file and a persistence.xml file.

For more information on weaving, see To Package a POJO Application for Weaving.

Packaging with EclipseLink Metadata File Resource Paths

If you do not store the project.xml or sessions.xml files at the root of the JAR file, then you must provide the full resource path to the files when accessing them. Ensure that you use "/" in resources paths, not "\". Using "\" will not work in Java.

For example, in the jar element, reference the project.xml and sessions.xml files as follows:

<jar>/myapp/ordersys/persist/sessions.xml
<jar>/myapp/ordersys/persist/project.xml

In the sessions.xml file, reference the project.xml as follows:

myapp/ordersys/persist/project.xml

To acquire the session, use the following:

 SessionManager.getManager().getSession(
     new XMLSessionConfigLoader("myapp/ordersys/persist/sessions.xml"),
     "OrdersysSession",
     getClass().getClassLoader()
 );

For more information about acquiring sessions at run time, see Acquiring a Session from the Session Manager.

Packaging Directories with a Dot (.)

When packaging applications, avoid using a dot (.) in a directory in a WAR file as this may cause deployment to fail. For example, if your WAR includes:

WEB-INF/classes/.foo/jsp_servlet/bar.jspx

deployment may fail during persistence unit processing because the application could not find a class named .foo.jsp_servlet.bar.jspx.

Copyright Statement