9 Creating TopLink Files for Deployment

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

This chapter includes the following sections:

Introduction to the TopLink Deployment File Creation
Creating Deployment Files for Java Applications
Creating Deployment Files for JavaServer Pages and Servlet Applications
Creating Deployment Files for Session Bean Applications
Creating Deployment Files for JPA Applications
Creating Deployment Files for CMP Applications
Creating Deployment Files for BMP Applications
Configuring the weblogic-ejb-jar.xml File for Oracle WebLogic Server
Configuring the orion-ejb-jar.xml File for OC4J

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

Section 9.1, "Introduction to the TopLink Deployment File Creation"
Chapter 8, "Integrating TopLink with an Application Server"
Chapter 10, "Packaging a TopLink Application"
Chapter 11, "Deploying a TopLink Application"
"Packaging and Deploying EclipseLink JPA Applications" section of EclipseLink Developer's Guide at http://wiki.eclipse.org/Packaging_and_Deploying_EclipseLink_JPA_Applications_%28ELUG%29.

9.1 Introduction to the TopLink Deployment File Creation

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

project.xml File
sessions.xml File
ejb-jar.xml File
JAVA-EE-CONTAINER-ejb-jar.xml File
toplink-ejb-jar.xml File

TopLink Workbench provides the ability to create deployment files from a TopLink Workbench project (see Section 116.3, "Exporting Project Information"). 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 TopLink Workbench.

Oracle recommends 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 EJB 3.0, 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.

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

This section describes the following:

XSD File Format
POJO Applications and Project Metadata
JPA Applications and Project Metadata
CMP Applications and Project Metadata
Creating the project.xml File with Oracle JDeveloper
Creating the project.xml File with TopLink Workbench
Creating project.xml Programatically

9.1.1.1 XSD File Format

The project.xml file XSD is toplink-object-persistence_11_1_1.xsd and it is located in the <TOPLINK_HOME>\xsds directory.

9.1.1.2 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 a TopLink project.TopLink Workbench provides a graphical tool to build and edit the project.xml file. For information on creating projects with TopLink Workbench, see Section 9.1.1.6, "Creating the project.xml File with TopLink Workbench".

9.1.1.3 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 session and project at run time.

Using EclipseLink JPA, you also have the option of specifying your metadata using 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" section of EclipseLink Developer's Guide at http://wiki.eclipse.org/Using_EclipseLink_JPA_Extensions_%28ELUG%29#What_You_May_Need_to_Know_About_EclipseLink_JPA_Overriding_Mechanisms.

9.1.1.4 CMP Applications and Project Metadata

For a CMP application, how you specify project metadata is dependent upon the Java EE application server you are deploying your application (see Section 9.1.5, "toplink-ejb-jar.xml File").

9.1.1.5 Creating the project.xml File with Oracle JDeveloper

In Oracle JDeveloper, TopLink mapping project information is maintained in the TopLink Map. For more information, see the Oracle JDeveloper online help.

9.1.1.6 Creating the project.xml File with TopLink Workbench

Because you must synchronize the project.xml file with the classes and data source associated with your application, Oracle recommends that you not modify this file manually. TopLink Workbench ensures proper synchronization, and is the best way to make changes to the project. Simply modify the project in TopLink 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 Section 116.3, "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.

9.1.1.7 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 toplink.jar;toplinkmw.jar;xmlparserv2.jar;ejb.jar;oracle.toplink.workbench.mappings.DeploymentXMLGenerator <MW_Project.mwp> <output file.xml>

Before you use either method, ensure that your classpath includes the <TOPLINK_HOME>\xsds directory.

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. For more information on what annotations are currently supported, see Oracle Fusion Middleware Enterprise JavaBeans Developer's Guide for Oracle Containers for Java EE

9.1.2 sessions.xml File

Each TopLink project belongs to a TopLink session. A session is the facade through which an application accesses TopLink functionality (for more information on sessions, see Part XXI, "TopLink Sessions"). Where you define a session differs depending on whether or not your application uses CMP.

This section describes the following:

XSD File Format
POJO Applications and Session Metadata
JPA Applications and Session Metadata
CMP Applications and Session Metadata

9.1.2.1 XSD File Format

The sessions.xml file XSD is sessions_11_1_1.xsd and it is located in the <TOPLINK_HOME>\xsds directory.

When you use the XSD formatted sessions.xml file, the TopLink 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 Example 9-1 illustrates.

Example 9-1 Enhanced Validation Exceptions

Exception [TOPLINK-9010] (Oracle TopLink - 10g (10.0.3)(Build 040127Dev)): oracle.toplink.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'.

9.1.2.2 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 a TopLink session.TopLink provides graphical tools to build and edit the sessions.xml file. For information see Chapter 88, "Creating a Session".

9.1.2.3 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 TopLink session and project at run time.

9.1.2.4 CMP Applications and Session Metadata

For a CMP project, how you specify session metadata is dependent upon the Java EE application server to which you are deploying your application.

For OC4J, the session configuration is done in the orion-ejb-jar.xml file. You can specify the data-source, some common session options, and a session customizer class (see Table 9-3, "orion-ejb-jar.xml File persistence-manager Subentries for pm-properties"). In this case, you name the TopLink project XML file as toplink-ejb-jar.xml (see Section 9.1.1, "project.xml File")

Note:

If you are using EJB 3.0, you cannot use annotations to specify session configuration. You must provide a sessions.xml file, if one is applicable to your application type.

9.1.3 ejb-jar.xml File

Each EJB module contains one ejb-jar.xml file that describes all the EJB in the module.

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

If you build an EJB application, Oracle recommends that you use TopLink Workbench to build the ejb-jar.xml file. Because TopLink Workbench can both read and write the ejb-jar.xml file, you can use TopLink Workbench to maintain your ejb-jar.xml file in the following ways:

When you change the file manually outside of TopLink Workbench, reimport the ejb-jar.xml file into TopLink Workbench project to refresh the project.
When you change the TopLink Workbench project, TopLink Workbench updates the ejb-jar.xml file automatically when you save the project.

For more information about managing the ejb-jar.xml file in TopLink Workbench, see Section 19.7, "Working with the ejb-xml.File".

Note:

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

9.1.4 JAVA-EE-CONTAINER-ejb-jar.xml File

The contents of the JAVA-EE-CONTAINER-ejb-jar.xml file depend on the container to which you deploy your EJB. To create this file, use the tools that accompany your container.

In most cases, the JAVA-EE-CONTAINER-ejb-jar.xml file integrates with TopLink without revision. However, in some cases, you must make some TopLink-specific modifications.

Note:

If you are using EJB 3.0, you can use annotations to specify most of what you formerly specified in the JAVA-EE-CONTAINER-ejb-jar.xml file. To override annotations or specify options not supported by annotations, you can still provide a JAVA-EE-CONTAINER-ejb-jar.xml file in your EJB 3.0 application. For more information on what annotations are currently supported, see Oracle Fusion Middleware Enterprise JavaBeans Developer's Guide for Oracle Containers for Java EE.

For more information, see the following:

Section 9.1.4.1, "Oracle WebLogic Server and the weblogic-ejb-jar.xml File"
Section 9.1.4.2, "OC4J and the orion-ejb-jar.xml File"

9.1.4.1 Oracle WebLogic Server and the weblogic-ejb-jar.xml File

For more information on configuring the weblogic-ejb-jar.xml, see Section 9.8, "Configuring the weblogic-ejb-jar.xml File for Oracle WebLogic Server".

9.1.4.2 OC4J and the orion-ejb-jar.xml File

Table 9-1 summarizes the scenarios in which you may choose to modify the orion-ejb-jar.xml file.

Table 9-1 When to Modify the orion-ejb-jar.xml File

CMP Type	Mapping Type	Action
Orion	Specified in `orion-ejb-jar.xml`	Deploy.
Orion	Default mappings	Edit the `orion-ejb-jar.xml` file to set `persistence-manager` attribute `name` to `orion`. Deploy.
Toplink	Specified in `toplink-ejb-jar.xml`	Deploy.
Toplink	Specified in `toplink-ejb-jar.xml` (custom persistence manager properties)	Edit the `orion-ejb-jar.xml` file to set `persistence-manager` attribute `name` to `toplink`. Edit additional `persistence-manager` subentries (see Section 9.9, "Configuring the orion-ejb-jar.xml File for OC4J"). Deploy.
Toplink	Default mappings (no `toplink-ejb-jar.xml`)	Deploy.

For more information on configuring the orion-ejb.jar.xml file, see Section 9.9, "Configuring the orion-ejb-jar.xml File for OC4J".

9.1.5 toplink-ejb-jar.xml File

The toplink-ejb-jar.xml file is used only in CMP projects. The TopLink runtime uses properties set in the JAVA-EE-CONTAINER-ejb-jar.xml file (see Section 9.1.4, "JAVA-EE-CONTAINER-ejb-jar.xml File") to locate the toplink-ejb-jar.xml file and read it in.

The purpose of toplink-ejb-jar.xml file depends on the type of application server you are using.

9.1.5.1 OC4J and the toplink-ejb-jar.xml File

When deploying a CMP application to OC4J, the toplink-ejb-jar.xml file is the name used for the project.xml file.

To create the toplink-ejb-jar.xml file in this case, simply rename your project.xml file. For more information, see Section 9.1.1, "project.xml File".

9.2 Creating Deployment Files for Java Applications

In a Java application, TopLink does not use a Java EE container for deployment. Instead, it relies on TopLink 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:

project.xml File
sessions.xml File

9.3 Creating Deployment Files for JavaServer Pages and Servlet Applications

Many designers build TopLink 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:

project.xml File
sessions.xml File

9.4 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 TopLink applications that wrap interaction with TopLink in session beans. Session beans execute all TopLink-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 1.n and 2.n Session Bean Applications
How to Create Deployment Files for EJB 3.0 Session Bean Applications

9.4.1 How to Create Deployment Files for EJB 1.n and 2.n Session Bean Applications

EJB 1.n and 2.n session bean applications require the following deployment files:

project.xml File
sessions.xml File

9.4.2 How to Create Deployment Files for EJB 3.0 Session Bean Applications

Oracle recommends using JPA annotations and persistence unit properties, or a special-case eclipselink.session-xml persistence unit property (see "EclipseLink JPA Persistence Unit Properties for Database, Session, and Application Server" table of EclipseLink Developer's Guide at http://wiki.eclipse.org/Using_EclipseLink_JPA_Extensions_%28ELUG%29#Using_EclipseLink_JPA_Extensions_for_Session.2C_Target_Database_and_Target_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:

"Java Persistence API Overview" section of EclipseLink Developer's Guide at http://wiki.eclipse.org/Introduction_to_Java_Persistence_API_%28ELUG%29
"Introduction to EclipseLink JPA" section of EclipseLink Developer's Guide at http://wiki.eclipse.org/Introduction_to_EclipseLink_JPA_%28ELUG%29
http://wiki.eclipse.org/EclipseLink/UserGuide/Developing_JPA_Projects_%28ELUG%29

9.5 Creating Deployment Files for JPA Applications

See "Packaging and Deploying EclipseLink JPA Applications" section of EclipseLink Developer's Guide at http://wiki.eclipse.org/Packaging_and_Deploying_EclipseLink_JPA_Applications_%28ELUG%29 for information on how to create deployment files for your JPA application.

9.6 Creating Deployment Files for CMP Applications

Many applications use the persistence mechanisms a Java EE container offers. TopLink provides full support for this type of application.

You can only use one persistence manager for all the entity beans with container-managed persistence in a JAR file.

CMP applications require the following deployment files:

ejb-jar.xml (see Section 9.1.3, "ejb-jar.xml File")
JAVA-EE-CONTAINER-ejb-jar.xml (see Section 9.1.4, "JAVA-EE-CONTAINER-ejb-jar.xml File")
toplink-ejb-jar.xml (see Section 9.1.5, "toplink-ejb-jar.xml File")

9.7 Creating Deployment Files for BMP Applications

If you choose to write your own persistence code with BMP, you can take advantage of the classes in oracle.toplink.ejb.bmp package. Whether or not you use these classes, BMP applications require the following deployment files:

project.xml (see Section 9.1.1, "project.xml File")
sessions.xml (see Section 9.1.2, "sessions.xml File")
ejb-jar.xml (see Section 9.1.3, "ejb-jar.xml File")

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

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

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

9.8.1 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 TopLink either does not support or does not require:

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

For more information about the TopLink concurrency strategy, see Section 119.26, "Configuring Locking Policy".
db-is-shared: Because TopLink does not make any assumptions about the exclusivity of database access, TopLink does not require this tag. TopLink addresses multiuser access issues through various locking and refreshing policies.
delay-updates-until-end-of-tx: TopLink always delays updates until the end of a transaction, and does not require this tag.
finders-load-bean: TopLink always loads the bean upon execution of the finder, and does not require this tag.
pool: 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 TopLink does not use a pooling strategy, TopLink ignores this tag.
is-modified-method-name: TopLink 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 TopLink project, TopLink ignores this tag.
cache: Because you define TopLink cache properties in TopLink Workbench, this tag is unnecessary.

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

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

If you are migrating an application from a previous release of OC4J, you can use the TopLink migration tool to automatically migrate persistence information from your orion-ejb-jar.xml file to a new toplink-ejb-jar.xml. For more information, see Section 8.4.2, "How to Migrate OC4J Orion CMP Persistence to OC4J TopLink Persistence".

9.9.1 How to Configure persistence-manager Entries

If you are using TopLink as your OC4J persistence manager, you can configure the persistence-manager subentry (see Table 9-2) in the orion-ejb-jar.xml file. For more information on the scenarios in which you would want to modify orion-ejb-jar.xml, see Section 9.1.4.2, "OC4J and the orion-ejb-jar.xml File".

If you are not using TopLink 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 Table 9-2). 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:

WARNING:

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

Table 9-2 orion-ejb-jar.xml File persistence-manager Entries

Entry Description

Entry	Description
`name`	The name of the persistence manager to use. Set this value to `toplink`. If you set the `name` property to `toplink`, you may also configure `pm-properties` (see Section 9.9.1.1, "Configuring pm-properties").
`class-name`	Do not configure this attribute. If `name` is set to `toplink`, then `class-name` is set correctly by default.
`descriptor`	This property applies only when `name` is set to `toplink`. If you export your TopLink 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 TopLink project class instead of a mapping metadata file (see `project-class` in Table 9-3).

name

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

If you set the name property to toplink, you may also configure pm-properties (see Section 9.9.1.1, "Configuring pm-properties").

class-name

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

descriptor

This property applies only when name is set to toplink.

If you export your TopLink 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 TopLink project class instead of a mapping metadata file (see project-class in Table 9-3).

9.9.1.1 Configuring pm-properties

When you select TopLink as the persistence manager (see name in Table 9-2), use the persistence-manager subentries for pm-properties (see Table 9-3) to configure the TopLink session that the TopLink runtime creates and uses internally for CMP projects. The persistence-manager subentries take the place of a sessions.xml file in a CMP project.

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 Table 9-3).

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

Entry	Description
`session-name`	Unique name for this TopLink-persisted EJB deployment JAR file. Must be unique among all TopLink-persisted deployed JAR files in this application server instance. When the TopLink run time internally creates a TopLink session for this TopLink-persisted deployed JAR file, the TopLink session manager stores the session instance under this `session-name`. For more information about the session manager, see Chapter 90, "Acquiring and Using Sessions at Run Time"). If you do not specify a name, the TopLink runtime will generate a unique name.
`project-class`	If you export your TopLink mapping metadata to a Java class (that extends `oracle.toplink.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 Table 9-2).
`customization-class`	Optional Java class (that implements `oracle.toplink.ejb.cmp.DeploymentCustomization`) used to allow deployment customization of TopLink mapping and run-time configuration. At deployment time, the TopLink run time creates a new instance of this class and invokes its methods `beforeLoginCustomization` (before the TopLink run time logs into the session) and `afterLoginCustomization` (after the TopLink runtime logs into the session), passing in the TopLink 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 Section 9.9.1.2, "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 Chapter 89, "Configuring a Session". The class must be fully qualified by its package name and included in the deployment JAR file.
`db-platform-class`	Optional TopLink database platform class (instance of `oracle.toplink.platform.database` or `oracle.toplink.platform.database.oracle`) containing TopLink 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 Section 9.9.1.2, "Configuring cache-synchronization Properties".
`default-mapping`	See Section 9.9.1.3, "Configuring default-mapping Properties".

9.9.1.2 Configuring cache-synchronization Properties

When you select TopLink as the persistence manager (see name in Table 9-2), use the pm-properties subentry for cache-synchronization (see Table 9-4) to configure TopLink cache coordination features of the session that the TopLink runtime uses internally for CMP projects. For more information about TopLink cache coordination, see Section 102.3, "Cache Coordination".

When this subentry is present, you must use a customization class (see customization-class in Table 9-3) to complete cache coordination configuration. For more information about TopLink cache coordination configuration, see Chapter 103, "Configuring a Coordinated Cache".

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

Entry Description

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 OC4J JNDI naming service and that all the hosts in your coordinated cache can communicate using OC4J proprietary RMI protocol ORMI, use a URL similar to the following: 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 similar to the following: 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 user name required to log in to the JNDI naming service.

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 OC4J JNDI naming service and that all the hosts in your coordinated cache can communicate using OC4J proprietary RMI protocol ORMI, use a URL similar to the following:

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 similar to the following:

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 user name required to log in to the JNDI naming service.

9.9.1.3 Configuring default-mapping Properties

When you select TopLink as the persistence manager (see name in Table 9-2), use the pm-properties subentry for default-mapping (see Table 9-5) to configure the TopLink default mapping and automatic table generation feature.

For more information about TopLink default mappings, see Section 17.2.3.4, "Default Mapping in EJB 2.n CMP Projects Using OC4J at Run Time".

For more information about TopLink automatic table generation, see Section 6.4, "Creating Database Tables Automatically".

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

Entry Description

Entry	Description
`db-table-gen`	Optional element that determines what TopLink will do to prepare the database tables that are being mapped to. Valid values are: `Create` (default): This value tells TopLink to create the mapped tables during the deployment. If the tables already exist, TopLink will log an appropriate warning messages (such as "Table already existed...") and keeps processing the deployment. `DropAndCreate`: This value tells TopLink 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, TopLink 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 TopLink 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 TopLink system property `toplink.defaultmapping.dbTableGenSetting`. For example: `-Dtoplink.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, TopLink 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 Section 6.4, "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 TopLink 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_EMPLOYEE`. 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`, TopLink 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 TopLink system property `toplink.defaultmapping.useExtendedTableNames`. For example: `-Dtoplink.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, TopLink retrieves the setting from the `orion-ejb-jar.xml` file.

db-table-gen

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

Create (default): This value tells TopLink to create the mapped tables during the deployment. If the tables already exist, TopLink will log an appropriate warning messages (such as "Table already existed...") and keeps processing the deployment.
DropAndCreate: This value tells TopLink 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, TopLink 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 TopLink 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 TopLink system property toplink.defaultmapping.dbTableGenSetting. For example: -Dtoplink.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, TopLink 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 Section 6.4, "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 TopLink 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_EMPLOYEE.

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, TopLink 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 TopLink system property toplink.defaultmapping.useExtendedTableNames. For example: -Dtoplink.defaultmapping.useExtendedTableNames="true".