10 Packaging a TopLink Application

How you package the components of your application depends on the type of application and how you plan to deploy it.

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

This chapter includes the following sections:

Note:

If you are using EJB 3.0, you may be using annotations instead of some deployment files. Include deployment descriptors to override annotations or specify options not supported by annotations.

For more information, see the following:

10.1 Packaging Java Applications

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

Example 10-1 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 TopLink files and domain objects required by the application, including the following:

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 Section 10.8, "Packaging with TopLink Metadata File Resource Paths".

10.2 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 Example 10-2 shows.

Example 10-2 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 TopLink dependencies include TopLink domain JAR (see Section 10.2.1, "How to Create the TopLink Domain JAR").

10.2.1 How to Create the TopLink Domain JAR

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

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 Section 10.8, "Packaging with TopLink Metadata File Resource Paths".

10.3 Packaging Session Bean Applications

The packaging strategy you choose depends on whether you are packaging an EJB 1.n or 2.n session bean application (see Section 10.3.1, "How to Package an EJB 1.n and 2.n Session Bean Application"), or an EJB 3.0 session bean application (see Section 10.3.2, "How to Package an EJB 3.0 Session Bean Application").

10.3.1 How to Package an EJB 1.n and 2.n Session Bean Application

For Java EE applications with session beans, it is common to package the application in an Enterprise Archive (EAR) file made up of various Java EE application component archives, as Example 10-3 shows.

Example 10-3 Packaging a Java EE Application with Session Beans

appname.ear
    META-INF
        application.xml
        orion-application.xml
    ejb_module_X.jar
        EJB classes - session and non-entity beans
        META-INF
            ejb-jar.xml
            orion-ejb-jar.xml - no persistence-manager subentries
    domain_module.jar
        Java classes that represent the object mapped
        project.xml
        session.xml
        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 TopLink dependencies include the following:

10.3.2 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 an EclipseLink JPA Application" section of EclipseLink Developer's Guide at http://wiki.eclipse.org/Packaging_and_Deploying_EclipseLink_JPA_Applications_%28ELUG%29#Packaging_an_EclipseLink_JPA_Application.

10.3.3 How to Create the TopLink Domain JAR

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

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 Section 10.8, "Packaging with TopLink Metadata File Resource Paths".

10.3.4 How to Create the EJB JAR

In this type of application, the EJB JAR contains session beans. Consequently, its orion-ejb-jar.xml file does not contain persistence-manager or pm-properties entries. These entries apply only to CMP applications.

10.4 Packaging JPA Applications

See "Packaging an EclipseLink JPA Application" section of EclipseLink Developer's Guide at http://wiki.eclipse.org/Packaging_and_Deploying_EclipseLink_JPA_Applications_%28ELUG%29#Packaging_an_EclipseLink_JPA_Application for information on how to package your JPA application.

10.5 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 Section 2.10.4.1, "To Package a POJO Application for Weaving".

10.6 Packaging CMP Applications

For Java EE applications that use CMP to persist entity beans, it is common to package the application in an Enterprise Archive (EAR) file made up of various Java EE application component archives, as Example 10-4 shows.

Example 10-4 Packaging a Java EE Application with Entity Beans with Container-Managed Persistence

appname.ear
    META-INF
        application.xml
        orion-application.xml
    cmp_ejb_module_1.jar
        EJB classes - cmp entity beans
        META-INF
            ejb-jar.xml
            orion-ejb-jar.xml - includes persistence-manager properties
            toplink-ejb-jar.xml
    ejb_module_X.jar
        EJB classes - non-entity beans
        META-INF
            ejb-jar.xml
            orion-ejb-jar.xml - no persistence-manager subentries
    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 TopLink dependencies include EJB JAR (see Section 10.3.4, "How to Create the EJB JAR").

10.6.1 How to Create the EJB JAR

In this type of application, the EJB JAR file specifically service both non-entity and entity EJB. It includes the following:

  • The home and remote, and all implementation code for all mapped beans in the application.

  • All mapped non-EJB classes from the Oracle JDeveloper or TopLink Workbench project

  • The home and remote, and all implementation code for any session beans included in the application.

  • Helper classes that contain TopLink amendment methods, and any other classes the application requires.

    For example, an instance of oracle.toplink.ejb.cmp.DeploymentCustomization (for more information, see customization-class in Table 9-3 in Section 9.9.1, "How to Configure persistence-manager Entries").

Store the following XML files in the EJB JAR \meta-inf directory:

Note:

If you do not use XML files for deployment, include your compiled oracle.toplink.sessions.Project file at the root of the EJB JAR (not in the \meta-inf directory).

You must persist all of the entity beans to the same data source. For a CMP application, TopLink does not support the session broker functionality (see Section 87.7, "Session Broker and Client Sessions").

10.7 Packaging BMP Applications

For Java EE applications that use BMP to persist entity beans, it is common to package the application in an Enterprise Archive (EAR) file made up of various Java EE application component archives, as Example 10-5 shows.

Example 10-5 Packaging a Java EE Application with Entity Beans with Bean-Managed Persistence

appname.ear
    META-INF
        application.xml
        orion-application.xml
    bmp_ejb_module_1.jar
        EJB classes - bmp entity beans
        META-INF
            ejb-jar.xml
            orion-ejb-jar.xml - includes persistence-manager properties
            toplink-ejb-jar.xml
    ejb_module_X.jar
        EJB classes - non-entity beans
        META-INF
            ejb-jar.xml
            orion-ejb-jar.xml - no persistence-manager subentries
    domain_module.jar
        Java classes that represent the object mapped
        project.xml
        session.xml
        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 TopLink dependencies include the following:

10.7.1 How to Create the TopLink Domain JAR

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

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 Section 10.8, "Packaging with TopLink Metadata File Resource Paths".

10.7.2 How to Create EJB JAR File

In this type of application, the EJB JAR file specifically services both session and entity beans. It includes the following:

  • The home and remote, and all implementation code for all mapped beans in the application.

  • All mapped non-EJB classes from the Oracle JDeveloper or TopLink Workbench project.

  • The home and remote, and all implementation code for any session beans included in the application.

  • Helper classes that contain TopLink amendment methods, and any other classes the application requires.

Store the following XML files in the EJB JAR \meta-inf directory:

Because the EJB JAR does not contain entity beans with container-managed persistence, its orion-ejb-jar.xml file must not contain persistence-manager or pm-properties entries.

For more information, see Section 9.9.1, "How to Configure persistence-manager Entries".

10.8 Packaging with TopLink 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 Section 90.3, "Acquiring a Session from the Session Manager".