Configuring Default Mappings

You can configure OC4J to automatically generate all required mappings at deployment time (see "Using Deployment XML"). To use this feature, you must:

Omit all container-managed relationship configuration (see "Configuring an EJB 2.1 CMP Entity Bean Container-Managed Persistence Field").
Ensure that no toplink-ejb-jar.xml is present in the EJB module (see "What is the toplink-ejb-jar.xml File?").

You can use this feature in conjunction with automatic database table creation (see "Configuring Automatic Database Table Creation").

Using Deployment XML

To configure default mapping, configure the orion-ejb-jar.xml file element pm-properties subelement default-mapping as Table 14-4 shows.

Table 14-4 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" on page 6-6.
`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" on page 6-6.

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