Packaging an OracleAS TopLink Application

The OracleAS TopLink approach to deployment includes packaging application files into a single file, such as a JAR file or an EAR file. Each of the deployment strategies discussed in this section use this approach. The nature of the application also influences the approach you take to deploying the project. This section illustrates deployment strategies for:

• Java Applications

• Java Server Pages and Servlets Applications

• Session Bean Applications

• Container-Managed Persistence Applications

• Bean-Managed Persistence Applications

Java Applications

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

Packaging the Java Application

You deploy Java applications simply by placing them on the classpath. To follow the standard OracleAS TopLink approach of encapsulating applications in an archive, deploy the application in a JAR file, as follows:

1. Place the sessions.xml and project.xml files in the root of the JAR.

2. Include all mapped classes and any required helper classes in the JAR.

3. Place the completed JAR on the classpath.

Deploying the Application to a Client

Build the JAR and place it on the classpath. Include the following Java code in your client application to access the OracleAS TopLink application from a client:

Session mysession = SessionManager.getManager().getSession("[SESSION-NAME]");

Java Server Pages and Servlets Applications

Many designers build OracleAS TopLink applications that use Java server pages (JSPs) and Java servlets. This type of design usually supports Web-based applications.

Packaging Applications with JSPs and Servlets

When you build an application to deploy to the Web, package the application components in separate archives based on function. You can then assemble the separate archive files in a single deployment archive file.

The final deployment archive is an EAR file. If your client application includes application XML files, store those files in the \meta-inf\ directory of the EAR. In addition, the EAR contains the following archive files:

A Domain JAR File

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

• sessions.xml

• project.xml (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.

A Web Archive (WAR) File

The WAR file contains the Web application files, including:

• JSPs and Servlets that provide the dynamic content for the client application

• Static HTML content for the client application

• Additional client application resources, such as images

To complete the WAR file, modify the manifest.mf file (located in the \meta-inf directory) to include a reference to the domain JAR file. The standard manifest is usually empty except for the header and two carriage returns.

Example 9-1 illustrates how to add a classpath attribute.

Example 9-1 Modified manifest.mf File

Manifest-Version: 1.0
Created-By: 1.3.1 (Sun Microsystems Inc.)
// Add the following line
Class-Path: [Domain-Archive-Name].jar
// Two carriage returns to complete the file
[CR]
[CR]

Deploying the Application to a Client

After you build the WAR and JAR files, build them into an EAR file for deployment. To deploy the EAR to your JSP servlet server, copy the EAR to a well-known directory. You may also need to use server-specific deployment tools. For more information, see the server documentation.

Include the following Java code in your client application to access the OracleAS TopLink application from a client:

Session s = SessionManager.getManager().getSession("[SESSION-NAME]",[classloader]);

In most cases, [classloader] represents the class loader from the current thread context, specified as follows:

    Thread.current().getContextClassLoader()

However, if your J2EE container does not support using this class loader, you can substitute the class loader from the current class, as follows:

    this.getClass().getLoader()

Note: Oracle Application Server Containers for J2EE supports the use of the class loader from the current thread.

Session Bean Applications

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

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

Packaging Applications with Session Beans

When you build an application to deploy to the Web, package the application components in separate archives based on function. You can then assemble the separate archive files in a single deployment archive file.

The final deployment archive is an EAR file. If your client application includes application XML files, store those files in the \meta-inf\ directory of the EAR. In addition, the EAR contains the following archive files.

A Domain JAR File

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

• sessions.xml file

• project.xml file (or the compiled project.class file if you are not using XML files for deployment)

• 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.

An EJB JAR File

The EJB JAR file specifically services the session beans in the application. It includes:

• The session bean home and remote for all session beans in the application

• Bean implementation code for all session beans in the application

• Any helper classes, such as amendment classes, required by the application

• Vendor-specific elements for the session beans

• The ejb-jar.xml file, stored in the \meta-inf\ directory of the JAR

In addition, modify the manifest.MF file, found in the \meta-inf\ directory, to include a reference to the domain JAR. The standard manifest is usually empty except for the header and two carriage returns.

Example 9-1 illustrates how to add a classpath attribute.

A WAR File

The WAR file contains the Web application files, including:

• JSPs and Servlets that provide the dynamic content for the client application

• Static HTML content for the client application

• Additional client application resources, such as images

In addition, modify the manifest.MF file, found in the \meta-inf\ directory, to include a reference to the domain JAR. The standard manifest is usually empty except for the header and two carriage returns.

Example 9-1 illustrates how to add a classpath attribute.

Deploying the Application to a Client

After you build the WAR and JAR files, build them into an EAR file for deployment. To deploy the EAR to your J2EE server, copy the EAR to a well-known directory. You may also need to use server-specific deployment tools. For more information, see the server documentation.

Include the following Java code in your client application to access the OracleAS TopLink application from a client:

Sessions = SessionManager.getManager().getSession("[SESSION-NAME]",[classloader]);

In most cases, [classloader] represents the class loader from the current thread context, specified as follows:

    Thread.current().getContextClassLoader()

However, if your J2EE container does not support using this class loader, you can substitute the class loader from the current class, as follows:

    this.getClass().getLoader()

Note: OC4J supports the use of the class loader from the current thread.

Container-Managed Persistence Applications

Many applications leverage the persistence mechanisms a J2EE container offers. OracleAS TopLink provides full support for this type of application.

The final deployment archive is an EAR file. If your client application includes application XML files, store those files in the \meta-inf\ directory of the EAR. In addition, the EAR contains the following archive files:

An EJB JAR file

The EJB JAR file specifically services the EJB entity beans in the application. It includes:

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

• All mapped non-EJB classes from OracleAS TopLink Mapping Workbench project

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

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

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

• ejb-jar.xml file

• [VENDOR-SPECIFIC]-ejb-jar.xml file

• toplink-ejb-jar.xml file

• project.xml file

  
  

  Note: If you do not use XML files for deployment, you do not have a project.xml file to include in the \meta-inf\ directory. Instead, include the compiled project.class file in the appropriate directory structure in the EJB JAR.

  
  

A WAR File

The WAR file contains the Web application files, including:

• JSPs and Servlets that provide the dynamic content for the client application

• Static HTML content for the client application

• Additional client application resources, such as images

General Deployment

After you build the WAR and JAR files, build them into an EAR file for deployment. To deploy the EAR to your J2EE server, copy the EAR to a well-known directory. You may also need to use server-specific deployment tools. For more information, see the server documentation.

Deploying the Application to BEA WebLogic Server

OracleAS TopLink CMP support includes integration for BEA WebLogic Server. To enable OracleAS TopLink CMP for WebLogic entity beans, use the WebLogic EJB Compiler (ejbc) to compile the EJB JAR, as follows:

• Run ejbc from the command line. Include the EJB JAR file as a command line argument. ejbc creates an EJB JAR that contains the original classes, as well as all required generated classes and files.

When you run ejbc:

• It performs a partial EJB conformance check on the beans and their associated interfaces.

• It builds the internal BEA WebLogic classes that manage security and transactions, as well as the RMI stubs and skeletons that enable client access to the beans.

• OracleAS TopLink builds concrete bean subclasses and EJB finder method implementations.

For more information about running ejbc, see the BEA WebLogic documentation.

Troubleshooting ejbc

When you start ejbc, it processes the data in a series of stages. If errors occur while running ejbc, determine which stage causes the problem. Common problems include:

• Bean classes that do not conform to the EJB specification

• Classes missing from the classpath (all domain classes, required OracleAS TopLink classes, and all required BEA WebLogic classes must be on the classpath)

• Java compiler (javac) problems, often caused by using an incorrect version of the JDK

• A failure when generating the RMI stubs and skeletons (a failure of rmic)

  
  

  Tip: Use a command script (for example, a batch or ant script) to run ejbc. This enables you to preconfigure all the required variables for the command line and helps to prevent typing errors. Sample build scripts are available with the OracleAS TopLink Application Server Examples for BEA WebLogic. For more information, see the OracleAS TopLink Examples at <ORACLE_HOME>\toplink\doc\examples.htm.

  
  

Deploying the Application to IBM WebSphere 4.x Server

OracleAS TopLink CMP support includes an integration for IBM WebSphere 4.x Server. Use the following procedure to deploy your application to WebSphere:

1. Use the OracleAS TopLink Deploy Tool for WebSphere to compile the EJB JAR file.

   For more information, see "Deploy Tool for WebSphere Server".

2. Start the WebSphere Administration Server.

3. Start the Administrator Console and deploy the compiled JAR.

   For more information about deploying the JAR, see the IBM WebSphere documentation.

   
   

   Note: When you deploy an application that contains an entity bean, set up a datasource and associate it with the bean. For more information about how to create and associate datasources, see the IBM WebSphere documentation.

   
   

It is not necessary to deploy the EJB JAR in WSAD, because deployment is carried out using the Deploy Tool (see "Deploy Tool for WebSphere Server").

Starting the Entity Bean

You can start the bean in either the WebSphere Application Server or in WSAD.

To start the bean in IBM WebSphere Application Server:

1. Select the application that contains the entity beans.

2. Right click and choose Start.

   A message dialog appears if the bean starts successfully. If an error occurs, consult Appendix C, "Troubleshooting", for troubleshooting information.

To start the bean in WSAD:

1. In WSAD, right click the EJB project and choose Run on Server.

2. To view the status of the process, open the Console tab of the Server view.

Bean-Managed Persistence Applications

OracleAS TopLink enables you to leverage bean-managed persistence in their OracleAS TopLink applications. The OracleAS TopLink base class for the BMP entity beans implements the methods required for the EJB specification.

For more information about OracleAS TopLink BMP support, see "Overview of Bean-Managed Persistence".

The final deployment archive is an EAR file. If your client application includes application XML files, store those files in the \meta-inf\ directory of the EAR. In addition, the EAR contains the following archive files

An EJB JAR file

The EJB JAR file specifically services the EJB entity beans in the application. It includes:

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

• All mapped non-EJB classes from OracleAS TopLink Mapping Workbench project

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

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

Store the following XML files as follows:

• The ejb-jar.xml file in the \meta-inf\ directory

• The sessions.xml and the project.xml files in the root directory

  
  

  Note: If you do not use XML files for deployment, you do not have a project.xml file to include in the \meta-inf\ directory. Instead, include the compiled project.class file in the appropriate directory structure in the EJB JAR.

  
  

A WAR File

The WAR file contains the Web application files, including:

• JSPs and Servlets that provide the dynamic content for the client application

• Static HTML content for the client application

• Additional client application resources, such as images

Deploying the Application

After you build the WAR and JAR files, build them into an EAR file for deployment. To deploy the EAR to your J2EE server, copy the EAR to a well-known directory. You may also need to use server-specific deployment tools. For more information, see the server documentation.