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

To deploy a TopLink application to OC4J 10g Release 3 (10.1.3) or later, modify the orion-ejb-jar.xml file as follows:

Configuring 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 "Migrating OC4J Orion Persistence to OC4J TopLink Persistence".

Configuring persistence-manager Entries

If you are using TopLink as your OC4J persistence manager, the default persistence manager in 10g Release 3 (10.1.3), you can configure the persistence-manager subentry (see Table 8-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 "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 10g Release 3 (10.1.3) and later do not support entity-deployment attribute pm-name. Use persistence-manager attribute name instead (see Table 8-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 8-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 "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 8-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 "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 8-3).

Configuring pm-properties

When you select TopLink as the persistence manager (see name in Table 8-2), use the persistence-manager subentries for pm-properties (see Table 8-3) to configure the TopLink session that the TopLink run time 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 8-3).

Table 8-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 "Acquiring and Using Sessions at Run Time"). If you do not specify a name, the TopLink run time 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 8-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 "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 "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. This flag may be used as a way to migrate from TopLink EJB 1.1 entities (when relationships were created between remote entities). Using this flag does not comply with EJB 2.0. Valid values are: `true`: All relationships will be maintained through the remote interfaces of the entities `false`: Disables this feature.
`cache-synchronization`	See "Configuring cache-synchronization Properties".
`default-mapping`	See "Configuring default-mapping Properties".

Configuring cache-synchronization Properties

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

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

Table 8-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: `asynchronous` (default) `synchronous`
`server-url`	For a JMS coordinated cache: assuming that you are using the Oracle Application Server Containers for J2EE (OC4J) JNDI naming service and that all the hosts in your coordinated cache can communicate using OC4J proprietary RMI protocol ORMI, use a URL like: 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 like: 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 username 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:

asynchronous (default)
synchronous

server-url

For a JMS coordinated cache: assuming that you are using the Oracle Application Server Containers for J2EE (OC4J) JNDI naming service and that all the hosts in your coordinated cache can communicate using OC4J proprietary RMI protocol ORMI, use a URL like:

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 like:

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

Configuring default-mapping Properties

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

For more information about TopLink default mappings, see "Default Mapping in EJB 2.0 or 3.0 CMP Projects Using OC4J at Run Time".

For more information about TopLink automatic table generation, see "Automatic Database Table Creation".

Table 8-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 "Automatic Database Table Creation".
`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 "Automatic Database Table Creation".

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