9
Packaging for Deployment

With your Oracle Application Server TopLink application built, you are ready to package and deploy the project to your enterprise. This chapter discusses:

• Introduction to Packaging and Deployment Concepts

• Creating OracleAS TopLink Deployment Files

• Packaging an OracleAS TopLink Application

• Hot Deployment of EJBs

This chapter discusses packaging and deployment from an OracleAS TopLink perspective. However, if you deploy your application to a J2EE container, you must configure elements of your application to enable OracleAS TopLink container support.

For more information, see also Appendix B, "Configuring OracleAS TopLink for J2EE Containers".

Introduction to Packaging and Deployment Concepts

This chapter introduces a basic approach to packaging that offers consistency across your projects, and the flexibility to work with projects of all kinds.

OracleAS TopLink Approach to Deployment

The OracleAS TopLink approach to deployment involves packaging application files into a single file, such as a Java archive (JAR) file, or an enterprise archive (EAR) file. This approach enables you to create clean and self-contained deployments that do not require significant file management.

After you create these files, you deploy the project.

OracleAS TopLink in an Enterprise Application

As an integral part of the enterprise application, OracleAS TopLink provides persistence and object-to-relational mapping functions. In most cases, the client does not interact with OracleAS TopLink directly; instead, clients access a client application that passes requests to OracleAS TopLink. As a result, there are two important steps to OracleAS TopLink deployment: make the packaged OracleAS TopLink application available; and add code to the client application to invoke OracleAS TopLink.

Road to Deployment

The goal of deployment is to provide the project to the client applications. Before you attempt to deploy an OracleAS TopLink application, complete the following:

1. Build the project elements, including beans, classes, and datasources.

2. Define the application mappings in the OracleAS TopLink Mapping Workbench.

3. Build the application deployment files. Use the OracleAS TopLink Mapping Workbench and the OracleAS TopLink Sessions Editor to create the files.

4. Package and deploy the application.

5. Add code to the client application to enable it to access the OracleAS TopLink application.

XML Versus Java Source Deployment

You can deploy the application mappings that you define in the OracleAS TopLink Mapping Workbench with your application as an XML file or as a compiled Java class. The OracleAS TopLink Mapping Workbench supports exporting for both of these formats.

The more traditional approach to deployment is to export Java source files from the OracleAS TopLink Mapping Workbench. It requires you to recompile the resulting Java files.

XML deployment files offer better flexibility both before and after deployment, and are easier to troubleshoot if a problem occurs. Because of this, in most cases, you should deploy your project using XML files rather than Java source files.

Creating OracleAS TopLink Deployment Files

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

• Create XML deployment files that require no compiling. 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.

• Create Java source files, which you compile and deploy outside of the OracleAS TopLink Mapping Workbench.

XML deployment is the preferred method of deployment, because XML files are easier to deploy and troubleshoot than compiled Java files.

This section discusses:

• XML Deployment Files

• Using Java Source Deployment Files

• Configuring Additional Files for CMP Deployment

XML Deployment Files

To deploy an OracleAS TopLink application, create a project file, in addition to one or more supporting files, as follows:

• If you deploy a non-EJB application, you require a session configuration file, known as the sessions.xml file.

• If you deploy EJBs to a J2EE container, you require the following entity bean deployment descriptors:
  • An ejb-jar.xml file that specifies standard EJB deployment properties

  • A J2EE container file that contains the properties specific to the J2EE container you use to deploy the application

  • A toplink-ejb-jar.xml that contains properties specific to OracleAS TopLink

Related beans share the same ejb-jar.xml file, J2EE container-specific file, and toplink-ejb-jar.xml file.

For more information, see "Container-Managed Persistence Applications".

Project.xml File

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

Because you must synchronize the project.xml file with the classes and database associated with your application, we recommend you not modify this file manually. The OracleAS TopLink Mapping Workbench ensures proper synchronization, and is the best way to make changes to the project. Simply modify the project in the OracleAS TopLink Mapping Workbench and redeploy the file project.xml file.

To redeploy a project.xml file, shut down and restart your OracleAS TopLink application.

Note: Because the sessions.xml file includes the name of the project file, you can save the project file with a name other than project.xml; however, for clarity, this discussion assumes that the file has not been renamed.

In addition to generating the deployment XML from the OracleAS TopLink Mapping Workbench, you can use either of the following methods and use the DeploymentXMLGenerator API:

Note: Before you use either method, ensure your the class path includes he <ORACLE_HOME>\toplink\config directory.

• From an application, instantiate the DeploymentXMLGenerator and your java source. Call the following method:

  generate (<MW_Project.mwp>, <output file.xml>)
  
  

• From a command line, use:

  java -classpath toplink.jar;toplinkmw.jar;xmlparserv2.jar;ejb.jar;. 
  oracle.toplink.workbench.external.api.DeploymentXMLGenerator <MW_
  Project.mwp> <output file.xml>
  
  

Sessions.xml File

The sessions.xml file provides a simple and flexible way to configure, modify, and troubleshoot the application database sessions. Because of these attributes, the sessions.xml file is the preferred way to configure an OracleAS TopLink session.

The OracleAS TopLink Sessions Editor is a graphical tool to build and edit the sessions.xml file, but you can also use a text editor.

For more information about the OracleAS TopLink Sessions Editor, see "Understanding the OracleAS TopLink Sessions Editor" in the Oracle Application Server TopLink Mapping Workbench User's Guide.

For more information, see "Configuring Sessions with the sessions.xml File".

Configuring the toplink-ejb-jar.xml File with the IBM WebSphere Server 4.0

The toplink-ejb-jar.xml file specifies all OracleAS TopLink-related information for an EJB entity bean deployment to a J2EE container. It includes several elements you use to configure the application.

The OracleAS TopLink deployment descriptor is included in the EJB JAR in the same META-INF directory as the ejb-jar.xml.

session

The session element contains settings for the entire project. The toplink-ejb-jar.xml file must include a session section, which includes the following XML elements:

• name: A session name (unique among all deployed JARs) that is used as a key for the deployed OracleAS TopLink project (or the JAR that contains the project).

• project-xml: Specifies the name of the XML file that contains the OracleAS TopLink project metadata. Specify the fully qualified file name, including the .xml extension.

• The project deployment XML file can be stored either in the deployable JAR file at the root directory or on the file system.

  Note: If you wish, use a project-class element rather than a project-xml tag. With the project-class element, specify the fully-qualified name of the OracleAS TopLink project class. Include this class in the deployable JAR file. You can generate the project class either with the OracleAS TopLink Mapping Workbench or write it manually.

• session-type: The session type must always be set to server-session.

• platform-class: The platform class controls the format of the SQL generated and other database specific behavior.

• uses-external-connection-pool and uses-external-transaction-controller: For OracleAS TopLink to participate in WebSphere JTS transactions set both of these to TRUE.

• external-transaction-controller-class: This is the OracleAS TopLink server-specific JTS controller class required when using external transaction control. For WebSphere 4.0, use oracle.toplink.jts.was.JTSExternalTransactionController_4_0.

• enable-logging: When set to TRUE, OracleAS TopLink prints logging information for several of its operations. This is very useful for debugging.

• logging-options: Options for different levels of OracleAS TopLink logging.

For more information about the toplink-was-ejb-jar_904.dtd, see <ORACLE_HOME>\toplink\config\dtds.

Configuring the toplink-ejb-jar.xml File with the BEA WebLogic Server

The toplink-ejb-jar.xml file specifies all OracleAS TopLink-related information for an EJB entity bean deployment to a J2EE container. It includes several elements you use to configure the application.

The OracleAS TopLink deployment descriptor is included in the EJB JAR in the same META-INF directory as the ejb-jar.xml.

session

The session element contains settings for the entire project. The toplink-ejb-jar.xml file must include a session section, which may include the following XML elements:

• name: Specifies the name of the session. Assign a unique session name to all projects deployed in a given server. This tag is mandatory.

• project-class: Specifies the name of the class that contains the OracleAS TopLink project metadata. Specify the fully qualified Java class name, but do not include the .class or .java extension.

  Use this tag (and not the project-xml tag) if you deploy your projects using exported and compiled Java code.

• project-xml: Specifies the name of the XML file that contains the OracleAS TopLink project metadata. Specify the fully qualified file name, including the .xml extension.

  Use this tag (and not the project-class tag) if you deploy your project using an exported XML file.

• login: Specifies the login parameters for the session. This element includes the sub elements listed in Table 9-1.

  Table 9-1 login Elements

  Element	Description
  connection-pool	Identifies a JDBC pool for the current OracleAS TopLink project. The name of the pool must correspond to a JDBC connection pool specified in the WebLogic administration console. Specify a connection-pool or a datasource and non-jts-datasource to deploy entity beans.
  datasource	Identifies JTA datasource for the current project. Use datasource in conjunction with non-jts-datasource. This provides an alternative to using a connection-pool. Use datasource to map to a JTA datasource, and non-jts-datasource to map to a non-JTS datasource. For more information about datasources, see "J2EE Integration" and the J2EE container documentation.
  non-jts-datasource	Identifies the read only datasource for the current project. Use non-jts-datasource in conjunction with datasource. This provides an alternative to using a connection-pool. For more information about datasources, see "J2EE Integration" and the J2EE container documentation.
  should-bind-all-parameters (optional)	Indicates whether all queries use parameter binding. Valid values are TRUE or FALSE. Default is FALSE.
  uses-byte-array-binding (optional)	Indicates whether byte arrays are bound. Valid values are TRUE or FALSE. Default is FALSE.
  uses-string-binding (optional)	Indicates whether strings are bound. Valid values are TRUE or FALSE. Default is FALSE.

• cache-synchronization (optional): This element indicates that changes made to one OracleAS TopLink cache in a cluster are automatically propagated to all other server caches. You can also include the optional sub elements listed in Table 9-2.

  Table 9-2 Optional cache-synchronization Elements

  Element	Description
  is-asynchronous	Specifies whether synchronization should NOT wait until all sessions have been synchronized before returning. Valid values are TRUE or FALSE. Default is TRUE.
  should-remove-connection-on-error	Specifies whether a synchronization connection is removed from the session if a communication error occurs. Valid values are TRUE or FALSE. Default is TRUE.

• use-remote-relationships (optional): OracleAS TopLink enables you to define relationships between beans in terms of their remote interfaces. This is especially useful when you port EJB 1.1 applications to EJB 2.0. When you enable this option, OracleAS TopLink defines all relationships in the JAR using remote interfaces. Valid values are TRUE or FALSE. Default is FALSE.

  Note: If you enable this option, your application is no longer strictly EJB 2.0 compliant, and your container may require some custom configuration. For example, when you deploy, run the weblogic.ejbc tool with the -nocompliance flag set.

• customization-class (optional): specifies the fully qualified name of a DeploymentCustomization class.

Using Java Source Deployment Files

Although XML deployment is the preferred deployment method, you can also deploy your OracleAS TopLink project as Java source files. To deploy a project as Java source files, create your project, and export the Java source files from the OracleAS TopLink Mapping Workbench. After you generate the files, compile them with an integrated development environment (IDE). This more traditional deployment method results in OracleAS TopLink applications with the following characteristics:

• They generally load more quickly than an XML-deployed project the first time they are loaded. They do not offer performance benefits after load time.

• Modifying session characteristics is a multi-step process that involves modifying the project in the OracleAS TopLink Mapping Workbench, recompiling the source files in an IDE, and redeploying the project.

In addition to generating the Java Source from the OracleAS TopLink Mapping Workbench, you can use either of the following methods and use the JavaSourceGenerator API:

Note: Before you use either method, ensure your the class path includes he <ORACLE_HOME>\toplink\config directory.

• From an application, instantiate the JavaSourceGenerator and your java source. Call the method:

  generate (<MW_Project.mwp>, <output file.xml>)
  
  

• From a command line, use:

  java -classpath toplink.jar;toplinkmw.jar;xmlparserv2.jar;ejb.jar;. 
  oracle.toplink.workbench.external.api.JavaSourceGenerator  <MW_Project.mwp> 
  <output file.xml>
  
  

XML Files for Java Deployment

As with an XML deployment, a Java source deployment requires the sessions.xml file (for non-EJB applications) or EJB deployment descriptor files (for EJB projects). Build these files the same way you do for an XML deployment, and deploy it with your project.

For more information, see "Sessions.xml File", and "Configuring the toplink-ejb-jar.xml File with the BEA WebLogic Server".

Configuring Additional Files for CMP Deployment

If you deploy your application to a J2EE container that implements Container-managed Persistence (CMP), you may have to configure additional files to support the deployment. This section discusses:

• Configuring the ejb-jar.xml File

• Configuring the [J2EE-Container]-ejb-jar.xml

Configuring the ejb-jar.xml File

There is one ejb-jar.xml file for every JAR, although you can specify multiple beans in a single ejb-jar.xml file. The EJB specification you use determines the contents of this file.

Most IDEs provide facilities to create the ejb-jar.xml file. For more information about generating this file, see your IDE documentation.

If you build an EJB 2.0 application, the OracleAS TopLink Mapping Workbench can build the ejb-jar.xml file for you. Because the OracleAS TopLink Mapping Workbench can both read and write the ejb-jar.xml, you can either drive changes in the ejb-jar.xml file using the OracleAS TopLink Mapping Workbench:

• When you change the file manually outside of the OracleAS TopLink Mapping Workbench, re import the ejb-jar.xml file into the OracleAS TopLink Mapping Workbench project to refresh the project.

• When you change the OracleAS TopLink Mapping Workbench project, OracleAS TopLink Mapping Workbench updates the ejb-jar.xml file automatically when you save the project.

For more information about managing the ejb-jar.xml file in the OracleAS TopLink Mapping Workbench, see the Oracle Application Server TopLink Mapping Workbench User's Guide.

Configuring the [J2EE-Container]-ejb-jar.xml

The contents of the [J2EE-Container]-ejb-jar.xml file depends on the container to which you deploy your beans. To create this file, use the tools that accompany your container.

In most cases, the [J2EE-Container]-ejb-jar.xml file integrates with OracleAS TopLink without revision. However, when you deploy to a WebLogic Server container, modify the weblogic-ejb-jar.xml. The topics in this section explore the required modifications.

Configuring the [J2EE-Container]-ejb-jar.xml File for BEA WebLogic

To deploy to a BEA WebLogic Server, modify the webLogic-ejb-jar.xml file. Within that file, each bean must have a persistence-descriptor entry with subentries, as follows:

• Configure the persistence-descriptor entry with subentries that indicate OracleAS TopLink is available and should be used:
  • If you deploy to WebLogic 6.1 (Service Pack 4), include a persistence-type element and a persistence-use element. Both elements require a type-identifier and a type-version tag. Table 9-3 lists the options for the type-identifier tag, and Table 9-4 lists the options for the type-version tag.

  • If you deploy to WebLogic 7.0 or 8.1, include a persistence-use element with a type-identifier and a type-version tag. Table 9-3 lists the options for the type-identifier tag, and Table 9-4 lists the options for the type-version tag.

• If you use WebLogic 6.1, add the element type-storage to the persistence-type element, and set it to META-INF\toplink-ejb-jar.xml.

• If you use WebLogic 7.0 or 8.1, add the element type-storage to the persistence-use element, and set it to META-INF\toplink-ejb-jar.xml.

• Set the enable-call-by-reference element to TRUE to enable Call by Reference:

  <weblogic-enterprise-bean>
      <ejb-name>AccountBean</ejb-name>
      ...
          <enable-call-by-reference>True</enable-call-by-reference>
      ...
  </weblogic-enterprise-bean>
  
  

  Table 9-3 WebLogic type-identifier Settings

  EJB Version	XML Elements
  1.1	<type-identifier>TopLink_CMP_1_1</type-identifier>
  2.0	<type-identifier>TopLink_CMP_2_0</type-identifier>

  Table 9-4 WebLogic type-version Settings

  WebLogic Version	XML Elements
  6.1	<type-version>4.0</type-version>
  7.0	<type-version>4.5</type-version>
  8.1	<type-version>9.0.4</type-version>

  Note: Although deprecated, the type-version setting of version 3.5 also functions correctly with WebLogic 6.1 (Service Pack 4) under EJB 1.1.

Unsupported weblogic-ejb-jar.xml File Tags

The weblogic-ejb-jar.xml file includes several tags that OracleAS TopLink either does not support or does not require:

• concurrency-strategy: This tag specifies how WebLogic manages concurrent users for a given bean. Because OracleAS TopLink manages concurrent access internally, it does not require this element.

  For more information about OracleAS TopLink concurrency strategy, see "Locking Policy".

• db-is-shared: Because OracleAS TopLink does not make any assumptions about the exclusivity of database access, OracleAS TopLink does not require this tag. OracleAS TopLink addresses multi-user access issues through various locking and refreshing policies.

• delay-updates-until-end-of-tx: OracleAS TopLink always delays updates until the end of a transaction, and does not require this tag.

• finders-load-bean: OracleAS TopLink always loads the bean upon execution of the finder, and does not require this tag.

• pool: OracleAS TopLink 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 OracleAS TopLink does not use a pooling strategy, OracleAS TopLink ignores this tag.

• is-modified-method-name: OracleAS TopLink does not require a bean developer-defined method to detect changes in object state.

• isolation-level: Because isolation level settings for the cache or database transactions are specified in the OracleAS TopLink project, OracleAS TopLink ignores this tag.

• cache: Because you define OracleAS TopLink cache properties in the OracleAS TopLink Mapping Workbench, this tag is necessary.

Packaging an OracleAS TopLink Application

The OracleAS TopLink approach to deployment involves 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 class path.

Packaging the Java Application

You deploy Java applications simply by placing them on the class path. 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 class path.

Deploying the Application to a Client

Build the JAR and place it on the class path. 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 generally 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 generally empty except for the header and two carriage returns.

Example 9-1 illustrates how to add a class path 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 generally 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 generally empty except for the header and two carriage returns.

Example 9-1 illustrates how to add a class path 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 generally empty except for the header and two carriage returns.

Example 9-1 illustrates how to add a class path 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: Oracle Application Server Containers for J2EE 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 the 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, attempt to determine which stage causes the problem. Common problems include:

• Bean classes that do not conform with the EJB specification

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

• 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 pre-configure 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's 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, "Error Codes and Messages" 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 developers 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 the 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.

Hot Deployment of EJBs

Many J2EE containers support hot deployment, a feature that enables you to deploy EJBs on a running server. Hot deployment allows you to:

• Deploy newly-developed EJBs to a running production system

• Remove (undeploy) deployed EJBs from a running server

• Modify (redeploy) the behavior of deployed EJBs by updating the bean class definition

When you take advantage of hot deployment, consider the following:

• You must deploy all related beans (all beans that share a common OracleAS TopLink project) within the same EJB JAR file. Because OracleAS TopLink views deployment on a project level, deploy all the project beans (rather than just a portion of them) to maintain consistency across the project.

• When you redeploy a bean, you automatically reset its OracleAS TopLink project. This flushes all object caches and rolls back any active object transactions associated with the project.

The client receives deployment exceptions when attempting to access undeployed or re-deployed bean instances. The client application must catch and handle the exceptions.

For more information about hot deployment, see the J2EE container documentation.