Skip navigation.
Downloads | Product Documentation | Support

Programming WebLogic Enterprise JavaBeans

# weblogic-cmp-jar.xml Deployment Descriptor Reference

The following sections describe the EJB 2.0 deployment descriptor elements found in the `weblogic-cmp-jar.xml` file, the WebLogic-specific XML document type definitions (DTD) file. Use these definitions to create the WebLogic-specific `weblogic-cmp-jar.xml` file that is part of your EJB deployment. Use this deployment descriptor file to specify container-managed-persistence (CMP) behavior.

For information on the EJB 1.1 deployment descriptor elements see Important Information for EJB 1.1 Users.

- 2.0 weblogic-cmp-jar.xml Deployment Descriptor File Structure
- Changes to weblogic-cmp-jar.xml in WebLogic Server 8.1
- 2.0 weblogic-cmp-jar.xml Deployment Descriptor Elements

# 2.0 weblogic-cmp-jar.xml Deployment Descriptor File Structure

The `weblogic-cmp-jar.xml` file defines deployment descriptors for entity EJBs that use WebLogic Server RDBMS-based persistence services. The EJB container uses a version of `weblogic-cmp-jar.xml` that is different from the XML shipped with WebLogic Server Version 6.x.

You can continue to use the earlier `weblogic-cmp-jar.xml` DTD for EJB 1.1 beans that you will deploy on the WebLogic Server Version 8.1. However, if you want to use any of the new CMP 2.0 features, you must use the new DTD described below.

The top-level element of the WebLogic Server 8.1 `weblogic-cmp-jar.xml` consists of a `weblogic-rdbms-jar` stanza:

>     description

>     weblogic-version

>     weblogic-rdbms-jar

>     	weblogic-rdbms-bean
>     		ejb-name
>     		data-source-name
>     		table-map
>     		field-group
>     		relationship-caching
>     		weblogic-query
>     		delay-database-insert-until
>     		automatic-key-generation
>     		check-exists-on-method

>     	weblogic-rdbms-relation
>     		relation-name
>     		table-name
>     		weblogic-relationship-role
>     	order-database-operations

>     	enable-batch-operations

>     	create-default-dbms-tables

>     	validate-db-schema-with

>     	database-type

>     	default-dbms-tables-ddl

>     	compatibility

# Changes to weblogic-cmp-jar.xml in WebLogic Server 8.1

These changes were made to `weblogic-cmp-jar.xml` in WebLogic Server 8.1:

- enable-batch-operations was added in WebLogic Server 8.1.
- instance-lock-order was added in WebLogic Server 8.1 SP01.
- order-database-operations was added in WebLogic Server 8.1.
- serialize-byte-array-to-oracle-blob was added in WebLogic Server SP02.
- verify-rows was added in WebLogic Server 8.1.

# 2.0 weblogic-cmp-jar.xml Deployment Descriptor Elements

This list of the elements in `weblogic-cmp-jar.xml` includes all elements that were supported in any service pack of WebLogic Server 8.1. The previous section, Changes to weblogic-cmp-jar.xml in WebLogic Server 8.1 lists elements that were new, changed, or deprecated in Weblogic Server 8.1, or a subsequent service pack.

- allow-readonly-create-and-remove
- automatic-key-generation
- caching-element
- caching-name
- check-exists-on-method
- cmp-field
- cmr-field
- column-map
- create-default-dbms-tables
- database-type
- data-source-name
- db-cascade-delete
- dbms-column
- dbms-column-type
- default-dbms-tables-ddl
- delay-database-insert-until
- description
- ejb-name
- enable-batch-operations
- field-group
- field-map
- foreign-key-column
- foreign-key-table
- generator-name
- generator-type
- group-name
- include-updates
- instance-lock-order
- key-cache-size
- key-column
- lock-order
- max-elements
- method-name
- method-param
- method-params
- optimistic-column
- order-database-operations
- primary-key-table
- query-method
- relation-name
- relationship-caching
- relationship-role-map
- relationship-role-name
- serialize-byte-array-to-oracle-blob
- sql-select-distinct
- table-map
- table-name
- use-select-for-update
- validate-db-schema-with
- verify-columns
- verify-rows
- weblogic-ql
- weblogic-query
- weblogic-rdbms-bean
- weblogic-rdbms-jar
- weblogic-rdbms-relation
- weblogic-relationship-role

# allow-readonly-create-and-remove

Range of Values: | `true | false`
Default value: | `false`
Parent elements: | `weblogic-rdbms-jar compatibility`

## Function

This element, introduced in WebLogic Server 8.1 SP02, is a backward compatibility flag. It is used to enable create and remove operations for an EJB that uses `ReadOnly` concurrency.

Prior to version 8.1 SP2, these operations were allowed, although they had no transactional meaning. They have been disallowed so that more efficient code can be generated for `ReadOnly` beans, and because using them is a bad practice.

## Example

>     <compatibility>
>          <allow-readonly-create-and-remove>
>          true
>          </allow-readonly-create-and-remove>
>     </compatibility>

# automatic-key-generation

Range of Values | n/a
Default value: | n/a
Parent elements: | `weblogic-rdbms-bean`

## Function

The `automatic-key-generation` element specifies how primary keys will be automatically generated. For more information about this feature, see Automatically Generating Primary Keys.

## Example

The following code samples show the `automatic-key-generation` stanza for different primary key generation methods. For supported generation methods, see generator-type

Listing B-1 automatic-key-generation With generator-type=Oracle

>     <automatic-key-generation>
>     	<generator-type>Oracle</generator-type>
>     	<generator-name>test_sequence</generator-name>
>     	<key-cache-size>10</key-cache-size>
>     </automatic-key-generation>

Listing B-2 automatic-key-generation With generator-type=SQL-SERVER

>     <automatic-key-generation>
>     	<generator-type>SQL-SERVER</generator-type>
>     </automatic-key-generation>

Listing B-3 automatic-key-generation With generator-type=NamedSequenceTable

>     <automatic-key-generation>
>     	<generator-type>NamedSequenceTable</generator-type>
>     	<generator-name>MY_SEQUENCE_TABLE_NAME</generator-name>
>     	<key-cache-size>100</key-cache-size>
>     </automatic-key-generation>

# caching-element

Range of Values | n/a
Default value: | n/a
Parent elements: | `weblogic-rdbms-jar weblogic-rdbms-bean relationship-caching`

## Function

Specifies the `cmr-field` and the `group-name` in the related bean. If `group-name` is not specified, the default `group-name` (load all fields) is used. For more information, see group-name.

The `caching-element` stanza can contain nested caching element stanzas, as in the example shown in relationship-caching.

For information about relationship caching, see Relationship Caching.

## Example

See relationship-caching:

# caching-name

Range of Values | n/a
Default value: | n/a
Parent elements: | `weblogic-rdbms-jar weblogic-rdbms-bean relationship-caching`

## Function

The `caching-name` element specifies the name of a relationship cache. For more information about relationship caching, see Relationship Caching.

## Example

See relationship-caching:

# check-exists-on-method

Range of values: | `True | False`
Default value: | `True`
Parent elements: | `weblogic-rdbms-bean`

## Function

By default, the EJB container checks that a container-managed persistence (CMP) entity bean exists before any business method invoked on the bean completes. This means the container notifies an application as soon as any business method is invoked on a container-managed entity bean that has been removed.

To specify that the EJB container wait for transaction completion to perform the existence check, set `check-exists-on-method` to `False`. This results in high performance and still provides a sufficient level of checking for most applications.

## Example

The following example specifies that WebLogic Server notify the application that a business method has been invoked on a CMP entity bean that has been removed.

>     <check-exists-on-method>True</check-exists-on-method>

# cmp-field

Range of Values | Valid name of field in the bean. Field must have matching `cmp-entry` entry in `ejb-jar.xml`. Field name is case-sensitive.
Default value: | n/a
Parent elements: | `weblogic-rdbms-bean field-map weblogic-rdbms-relation field-group`

## Function

This name specifies the mapped field in the bean instance which should be populated with information from the database.

## Example

See field-map.

# cmr-field

Range of Values | Valid name of field in the bean. Field must have matching `cmr-field` entry in `ejb-jar.xml`.
Default value: | n/a
Parent elements: | `weblogic-rdbms-relation field-group` and relationship-caching caching-element

## Function

Specifies the name of a container-managed relationship field.

## Example

>     <cmr-field>stock options</cmr-field>

# column-map

Range of Values | n/a
Default value: | n/a
Requirements: |
Parent elements: | `<weblogic-rdbms-relation> <weblogic-relationship-role> <relationship-role-map>`

## Function

This element represents the mapping of a foreign key column in one table in the database to a corresponding primary key. The two columns may or may not be in the same table. The tables to which the columns belong are implicit from the context in which the `column-map` element appears in the deployment descriptor.

Note: The `key-column` element is not specified if the `foreign-key-column` refers to a remote bean.

## Example

The `XML` stanza can contain the elements shown here:

>     <column-map
>     	<foreign-key-column>account-id</foreign-key-column>
>     	<key-column>id</key-column>
>     </column-map>

# compatibility

Range of values: | n/a
Default value: | n/a
Parent elements: | `weblogic-rdbms-jar`

## Function

The `<compatibility>` stanza, introduced in WebLogic Server 8.1 SP02, contains elements that specify compatibility flags for all of the cmp beans described in the descriptor file.

## Example

>     <compatibility>
>          <serialize-byte-array-to-oracle-blob>
>          <allow-readonly-create-and-remove>
>     </compatibility>

# create-default-dbms-tables

Range of values: | `Disabled | CreateOnly | DropAndCreate | DropAndCreateAlways |AlterOrCreate`
Default value: | `Disabled`
Parent elements: | `weblogic-rdbms-jar`

## Function

The `create-default-dbms-table` element performs two functions:

- It determines whether or how WebLogic Server automatically creates a default table based on the descriptions in the deployment files and the bean class, when underlying table schema have changed.
- It determines whether or how WebLogic Server automatically creates an Oracle SEQUENCE.

Use this element only for convenience during development phases. This is because the table schema in the `DBMS CREATE` statement used are the EJB container's best approximation of the definition. A production environment typically requires more precise schema definition.

### Automatic Table Creation

The following table describes how WebLogic Server handles automatic table creation, based on the value of `create-default-dbms-tables`.

Setting <create-default-dbms-tables> to this value | Results in this behavior with respect to automatic table creation
--- | ---
`Disabled` | The EJB container takes no action with respect to automatic table creation. This is the default value.
`CreateOnly` | The EJB container automatically generates the table upon detecting changed schema. The container attempts to create the table based on information found in the deployment files and in the bean class. If table creation fails, a '`Table Not Found'` error is thrown, and the user must create the table manually.
`DropAndCreate` | The EJB container automatically generates the table upon detecting changed schema. The container drops and creates the table during deployment if columns have changed. The container does not save data.
`DropAndCreateAlways` | The EJB container automatically generates the table upon detecting changed schema. The container drops and creates the table during deployment whether or not columns have changed. The container does not save the data.
`AlterOrCreate` | The EJB container automatically generates the table upon detecting changed schema. The container creates the table if it does not yet exist. If the table does exist, the container alters the table schema. Table data is saved. Note: Do not choose this setting if a new column is specified as a primary key or if a column with null values is specified as the new primary key column.

If `TABLE CREATION` fails, the server throws a `Table Not Found` error and the table must be created by hand.

See Automatic Table Creation (Development Only).

### Automatic Oracle SEQUENCE Generation

Note: Automatic Oracle SEQUENCE generation works only with servers running in development mode.

The following table describes how WebLogic Server handles automatic SEQUENCE generation, based on the value of `create-default-dbms-tables`.

Setting <create-default-dbms-tables> to this value | Results in this behavior:
--- | ---
`Disabled` | The EJB container takes no action with respect to SEQUENCE generation. This is the default value.
`CreateOnly` | The EJB container creates a SEQUENCE, and constructs its name by appending "_WL" to the value of the `generator-name` element.
`DropAndCreate` | The EJB container creates a SEQUENCE, and constructs its name by appending "_WL" to the value of the `generator-name` element. If the SEQUENCE's increment value does not match the value of the key-cache-size element, the container alters the increment value to match the value of key-cache-size.
`DropAndCreateAlways` | The EJB container creates a SEQUENCE, and constructs its name by appending "_WL" to the value of the `generator-name` element. If the SEQUENCE's increment value does not match the value of the key-cache-size element, the container alters the increment value to match the value of key-cache-size.
`AlterOrCreate` | The EJB container creates a SEQUENCE, and constructs its name by appending "_WL" to the value of the `generator-name` element. If the SEQUENCE's increment value does not match the value of the key-cache-size element, the container alters the increment value to match the value of key-cache-size.

For more information on automatic generation of an Oracle SEQUENCE, see Support for Oracle SEQUENCE.

## Example

The following example specifies the create-default-dbms-tables element.

>     <create-default-dbms-tables>CreateOnly</create-default-dbms-tables>

# database-type

Range of values: | `DB2 | Informix| Oracle | SQLServer | SQLServer2000| Sybase | POINTBASE.`
Default value: |
Parent elements: | `weblogic-rdbms-jar`

## Function

The `database-type` element specifies the database used as the underlying dbms.

## Example

>     <database-type>POINTBASE</database-type>

# data-source-name

Range of values | Valid WebLogic Server JDBC datasource name.
Default value | n/a
Parent elements: | `weblogic-rdbms-bean`

## Function

Specifies the JDBC data source name to be used for database connectivity for this bean. For more information on datasources, see Programming WebLogic JDBC.

## Example

See table-name.

# db-cascade-delete

Range of Values | n/a
Default | By default, database cascade delete is not used. The EJB container performs cascade deletes by issuing an individual SQL `DELETE`.
Parent elements: | `weblogic-rdbms-bean weblogic-relationship-role`

## Function

Allows an application to take advantage of a database's built-in support for cascade delete, and possibly improve performance. This functionality is supported only for:

- Oracle databases
- One-to-one or one-to-many relationships.

If `db-cascade-delete` is enabled in `weblogic-cmp-rdbms-jar.xml`, you must

- Enable `cascade-delete` in `ejb-jar.xml`
- Enable cascade delete in the database table definition.

Note: If `db-cascade-delete` is not specified, do not enable the database's cascade delete functionality, as this will produce incorrect results.

## Setting up Oracle for Cascade Delete

The following Oracle table definition will cause deletion all of the `emp` rows if the owning `dept` is deleted in the database.

>     CREATE TABLE dept
>     (deptno   NUMBER(2) CONSTRAINT pk_dept PRIMARY KEY,
>     dname    VARCHAR2(9) );

>     CREATE TABLE emp
>     (empno    NUMBER(4) PRIMARY KEY,
>     ename    VARCHAR2(10),
>     deptno   NUMBER(2)   CONSTRAINT fk_deptno
>     REFERENCES dept(deptno)
>     ON DELETE CASCADE );

## Example

>     </weblogic-relationship-role>
>         <db-cascade-delete/>
>     </weblogic-relationship-role>

# dbms-column

Range of values: | Valid database column.
Default value: | n/a
Parent elements: | `weblogic-rdbms-bean field-map`

## Function

The name of the database column to which the field should be mapped.

Note: `dbms-column` is case maintaining, although not all database are case sensitive.

## Example

See field-map.

# dbms-column-type

Range of values: | `OracleBlob | OracleClob | LongString | SybaseBinary`
Default value: |
Parent elements: | `weblogic-rdbms-bean field-map`

## Function

Specifies the type of the `cmp-field`. the current field to a Blob or Clob in an Oracle database or a LongString or SybaseBinary in a Sybase database.

- `OracleBlob`—maps the field to an Oracle Blob.
- `OracleClob`—maps the field to an Oracle Clob.
- `LongString`—tells the container to use `setCharacterStream` to write String data into the database. Some JDBC drivers have problems writing more than 4K of data using `setString`.
- `SybaseBinary`—tells the container to use `setBytes` to write bytes into the binary column, because `setBinaryStream` does not work with `SybaseXADriver`.

## Example

>     <field-map>
>     	<cmp-field>photo</cmp-field>
>     	<dbms-column>PICTURE</dbms-column>
>     	<dbms_column-type>OracleBlob</dbms-column-type>
>     </field-map>

# default-dbms-tables-ddl

Range of values: | Valid file name.
Default value: |
Parent elements: | `weblogic-rdbms-jar`

## Function

Specifies the `DDL` file name to which the EJB container writes the table creation scripts.

# delay-database-insert-until

Range of values: | `ejbCreate | ejbPostCreate` The `commit` option is removed in WebLogic Server 8.1
Default value: | `ejbPostCreate`
Requirements: |
Parent elements: | `weblogic-rdbms-bean`

## Function

Specifies when a new CMP bean is inserted into the database. The allowable values cause the following behavior:

- `ejbCreate` - perform database insert immediately after `ejbCreate.` This setting yields better performance than `ejbCreate` by avoiding an unnecessary store operation.
- `ejbPostCreate` - perform insert immediately after `ejbPostCreate.`

This element has an effect only when order-database-operations is `False`. By default, `order-database-operations` is `true`, which causes new beans to be inserted at the transaction commit time.

Delaying the database insert until after `ejbPostCreate` is required when a `cmr-field` is mapped to a `foreign-key` column that does not allow null values. In this case, the `cmr-field` must be set to a non-null value in `ejbPostCreate` before the bean is inserted into the database.

For maximum flexibility, avoid creating related beans in your `ejbPostCreate` method. If `ejbPostCreate` creates related beans, and database constraints prevent related beans from referring to a bean that has not yet been created, it is not possible to database insert until after the method completion.

Note: `cmr-field`s may not be set during `ejbCreate`, before the primary key of the bean is known.

## Example

>     <delay-database-insert-until>ejbPostCreate</delay-database-insert-until>

# description

Range of values: | n/a
Default value: | n/a
Parent elements: | `weblogic-rdbms-jar weblogic-rdbms-bean weblogic-query`

## Function

The `description` element provides text that describes the parent element.

## Example

>     <dscription>Contains a description of parent element</description>

# ejb-name

Range of values: | Must match the `ejb-name` of a cmp entity bean defined in the `ejb-jar.xml.`
Default value: | n/a
Parent elements: | `weblogic-rdbms-bean`

## Function

The name that specifies an EJB as defined in the `ejb-cmp-rdbms.xml`. This name must match the `ejb-name` of a cmp entity bean contained in the `ejb-jar.xml`.

## Example

See table-name.

# enable-batch-operations

Range of values: | `True | False`
Default value: | `True`
Parent elements: | `weblogic-rdbms-jar`

## Function

This element, introduced in WebLogic Server 8.1, controls whether or not the EJB container allows batch database operations, including batch inserts, batch updates and batch deletes.

If this element is set to `True`, the EJB delays database operations in a transaction until commit time.

Note: In WebLogic Server 8.1, this element replaces the functionality of the `commit` setting, available in WebLogic Server 7.0, for the delay-database-insert-until element.

## Example

The following XML sample demonstrates use of the `enable-batch-operations` element:

`<enable-batch-operations>True</enable-batch-operations>`

# field-group

Range of values: | n/a
Default value: | A special group named `default` is used for finders and relationships that have no `field-group` specified. The default group contains all of a bean's cmp-fields, but none of its cmr-fields.
Parent elements: | `weblogic-rdbms-relation`

## Function

The `field-group` element represents a subset of the cmp-fields and cmr-fields of a bean. Related fields in a bean can be put into groups that are faulted into memory together as a unit. A group can be associated with a finder or relationship, so that when a bean is loaded as the result of executing a finder or following a relationship, only the fields specified in the group are loaded.

A field may belong to multiple groups. In this case, the `getXXX` method for the field faults in the first group that contains the field.

## Example

The `XML` stanza can contain the elements shown here:

>     <weblogic-rdbms-bean>
>     	<ejb-name>XXXBean</ejb-name>
>     	<field-group>
>     		<group-name>medical-data</group-name>
>     		<cmp-field>insurance</cmp-field>
>     		<cmr-field>doctors</cmr-fields>
>     	</field-group>
>     </weblogic-rdbms-bean>

# field-map

Range of values: | n/a
Default value: | n/a
Parent elements: | `weblogic-rdbms-bean`

## Function

The `field-map` element represents a mapping between a particular column in a database and a `cmp-field` in the bean instance.

The optional `group-name` element specifies a field group that is to be loaded when the `getXXX` method for the `cmp-field` is called and the EJB container needs to read the value from the DBMS because it is not in memory. If `group-name` is omitted, the default group, which contains all `cmp-field`s, is used when the `cmp-field` is not explicitly listed in any field groups, otherwise a field group that contains the `cmp-field` is chosen. Thus, developers should specify a `group-name` if the `cmp-field` is listed in multiple field groups or the container will pick one of the groups arbitrarily.

The dbms-column-type element is optional.

## Example

The `XML` stanza can contain the elements shown here:

>     <field-map>
>     	<cmp-field>....</cmp-field>
>     	<dbms-column>...</dbms-column>
>     	<dbms-column-type>...</dbms-column-type>
>     	<group-name>...</group name>
>     </field-map>

# foreign-key-column

Range of values: | Valid foreign key database column name.
Default value: | n/a
Parent elements: | `weblogic-rdbms-bean column-map`

## Function

The `foreign-key-column` element represents a column of a foreign key in the database.

## Example

See column-map.

# foreign-key-table

Range of values: | Valid database table name.
Default value: | n/a
Parent elements: | `weblogic-rdbms-jar weblogic-rdbms-relation weblogic-relationship-role relationship-role-map`

## Function

The `foreign-key-table` element specifies the name of a DBMS table that contains a foreign key.

## Example

See relationship-role-map.

# generator-name

Range of values: |
Default value: |
Parent elements: | `weblogic-rdbms-bean automatic-key-generation`

## Function

The `generator-name` element is used to specify the name of the primary key generator.

- If the generator-type element is `Oracle`, and WebLogic Server is running in development mode, then the EJB container constructs the Oracle SEQUENCE name by appending "_WL" to the `generator-name` as part of the container's automatic SEQUENCE generation feature.

For more information on automatic Oracle SEQUENCE generation, see Support for Oracle SEQUENCE.

- If the `generator-type` element is `Oracle`, and WebLogic Server is running in production mode, then the EJB container sets the name of the Oracle SEQUENCE to the value of `generator-name`.
- If the `generator-type` element is `NamedSequenceTable`, then the `generator-name` element would be the name of the `SEQUENCE_TABLE` to be used.

## Example

See automatic-key-generation.

# generator-type

Range of values: | `Oracle | SQLServer | SQLServer2000 | NamedSequenceTable`
Default value: |
Parent elements: | `weblogic-rdbms-bean automatic-key-generation`

## Function

The `generator-type` element specifies the primary key generation method to use.

In addition, `generator-type` is used in conjunction with automatic Oracle SEQUENCE generation. See Support for Oracle SEQUENCE.

## Example

See automatic-key-generation.

# group-name

Range of values: | n/a
Default value: | `field-group` and `caching-element` and `weblogic-query` and `field-map` and `weblogic-relationship-role`
Parent elements: | `weblogic-rdbms-relation field-group`

## Function

Specifies the name of a field group.

## Example

See field-group.

# include-updates

Range of values: | `True | False`
Default value: | `False` for beans that use optimistic concurrency. `True` for beans that use other concurrency types.
Parent elements: | `weblogic-rdbms-bean weblogic-query`

## Function

Specifies whether updates made during the current transaction must be reflected in the result of a query. If this element is set to `True`, the container will flush all changes made by the current transaction to disk before executing the query. A value of `False` provides best performance.

## Example

>     <weblogic-query>
>     	<query-method>
>     	<method-name>findBigAccounts</method_name>
>     	<method-params>
>     		<method-param>double</method-param>
>     	</method-params>
>     	</query-method>
>     	<weblogic-ql>WHERE BALANCE>10000 ORDERBY NAME</weblogic-ql>
>     	<include-updates>True</include-updates>
>     </weblogic-query>

# instance-lock-order

Range of values: | `AccessOrder | ValueOrder`
Default value: | `AccessOrder`
Parent elements: | `weblogic-rdbms-bean`

## Function

Specifies a locking or processing order for instances of a particular EJB. This element can be used to prevent deadlocks in an application that would otherwise experience deadlocks. `instance-lock-order` is used whenever database operations (update, for example) that apply to multiple instances of the same EJB are performed by the container. It specifies an order for operations that can cause a database lock to be acquired for a bean instance.

For example, `instance-lock-order` could be used to specify the order in which the EJB container calls `ejbStore` for instances of a particular EJB that uses database concurrency; `ejbStore` may acquire an exclusive lock when a database update is done. `instance-lock-order` also controls the order in which beans using optimistic concurrency are locked when optimistic checking is performed.

- `AccessOrder`—The container will process beans so that locks are acquired (or upgraded) in the order in which the application originally accessed the beans during the transaction. This is the recommended value when all transactions in the system access instances of the bean, and ultimately rows in a database table, in the same order.
- `instance-lock-order`—`ValueOrder`-Beans are processed in order based on the value of their primary key. `ValueOrder` should be specified to avoid deadlocks when concurrent transactions access instances of the same EJB in different orders.

Note: The EJB's primary key class is not required to implement the `java.lang.Comparable` interface when `ValueOrder` is specified, although this will result in a total ordering. Beans are ordered partially using the hash code value of the primary key when the primary key does not implement `java.lang.Comparabl`e.

## Example

>     <instance-lock-order>ValueOrder</instance-lock-order>

# key-cache-size

Range of values: |
Default value: | 1
Parent elements: | `weblogic-rdbms-bean automatic-key-generation`

## Function

Specifies the optional size of the primary key cache available in the automatic primary key generation feature. In addition, the EJB container uses this value to calculate the increment value for an Oracle SEQUENCE when automatic SEQUENCE generation is enabled. See Support for Oracle SEQUENCE.

If generator-type is

- `Oracle`—`key-cache-size` must match the Oracle SEQUENCE INCREMENT value. If there is a mismatch between this value and the Oracle SEQUENCE INCREMENT value, then there will likely be duplicate key problems.
- `NamedSequenceTable`—`key-cache-size` specifies how many keys the container will fetch in a single DBMS call
- SQLServer—`key-cache-size` is ignored.

## Example

See automatic-key-generation.

# key-column

Range of values: | Valid primary key column name.
Default value: | n/a
Parent elements: | `weblogic-rdbms-bean column-map`

## Function

The `key-column` element represents a column of a primary key in the database.

## Example

See column-map.

# lock-order

Range of values: | All positive integers.
Default value: | 0
Parent elements: | `weblogic-rdbms-bean`

## Function

Use this flag to specify the database locking order of an entity bean when a transaction involves multiple beans and exclusive concurrency. The bean with lowest number is locked first.

This flag should only be used to prevent a deadlock situation and, currently, only applies when a transaction performs cascade deletes.This flag is only used for cascade delete currently.

## Example

The `XML` stanza can contain the elements shown here:

>     <lock-order>1</lock-order>
>          <!ELEMENT lock-order (PCDATA)>

# max-elements

Range of values: | n/a
Default value: | n/a/
Parent elements: | `weblogic-rdbms-bean weblogic-query`

## Function

`max-elements` specifies the maximum number of elements that should be returned by a multi-valued query. This element is similar to the `maxRows` feature in JDBC.

## Example

The `XML` stanza can contain the elements shown here:

>     <max-elements>100</max-elements>
>           <!ELEMENT max-element (PCDATA)>

# method-name

Range of values: | n/a
Default value: | n/a
Parent elements: | `weblogic-rdbms-bean query-method`

## Function

The `method-name` element specifies the name of a finder or `ejbSelect` method.

Note: The `*' character may not be used as a wildcard.

## Example

See weblogic-query.

# method-param

Range of values: | n/a
Default value: | n/a
Parent elements: | `weblogic-rdbms-bean method-params`

## Function

The `method-param` element contains the fully qualified Java type name of a method parameter.

## Example

>     <method-param>java.lang.String</method-param>

# method-params

Range of values: | n/a
Default value: | n/a
Parent elements: | `weblogic-rdbms-bean query-method`

## Function

The `method-params` element contains an ordered list of the fully-qualified Java type names of the method parameters.

## Example

See weblogic-query.

# optimistic-column

Range of values: | Valid database column name.
Default value: | n/a
Parent elements: | `weblogic-rdbms-bean table-map`

## Function

The `optimistic-column` element denotes a database column that contains a version or timestamp value used to implement optimistic concurrency. For more information on optimistic concurrency, see Choosing a Concurrency Strategy.

Note: Although not all databases are case sensitive, this element is case maintaining.

## Example

The following sample XML shows the use of the `optimistic-column` element.

`<optimistic-column>ROW_VERSION</optimistic-column>`

where `ROW_VERSION` is the name of a database column that contains the value used for concurrency checking.

# order-database-operations

Range of values: | `True | False`
Default value: | `True`
Parent elements: | `weblogic-rdbms-jar`

## Function

This element, introduced in WebLogic Server 8.1, determines whether the EJB container delays all database operations in a transaction until commit time, automatically sorts the database dependency between the operations, and sends these operations to the database in such a way to avoid any database constraint errors.

If enable-batch-operations is set to `True`, the container automatically sets `order-database-operations` to `True`. To turn off `order-database-operations`, set both `order-database-operations` and `enable-batch-operations` to `False`.

See also enable-batch-operations and delay-database-insert-until.

## Example

The following sample XML demonstrates the use of the `order-database-operations` element.

`<order-database-operations>True</order-database-operations>`

# primary-key-table

Range of values: | Valid database table name.
Default value: | n/a
Parent elements: | `weblogic-rdbms-jar weblogic-rdbms-relation weblogic-relationship-role relationship-role-map`

## Function

The `primary-key-table` element specifies the name of a DBMS table that contains a primary key. For more information about primary keys, see Using Primary Keys.

Note: Although not all databases are case sensitive, this element is case maintaining.

## Example

For examples, see relationship-role-map and Mapping a Bean on Primary Key Side of a Relationship to Multiple Tables.

# query-method

Range of values: | n/a
Default value: | n/a
Parent elements: | `weblogic-rdbms-bean`

## Function

Specifies the method that is associated with a `weblogic-query`. It also uses the same format as the `ejb-jar.xml` descriptor.

## Example

See weblogic-query.

# relation-name

Range of values: | Must match the `ejb-relation-name` of an`ejb-relation` in the associated `ejb-jar.xml` deployment descriptor file. The `ejb-relation-name` is optional, but is required for each relationship defined in the associated `ejb-jar.xml` deployment descriptor file
Default value: | n/a
Parent elements: | `weblogic-rdbms-relation`

## Function

The `relation-name` element specifies the name of a relation.

For more information about container-managed relationships, see Using Container-Managed Relationships (CMRs).

## Example

The `XML` stanza can contain the elements shown here:

>     <weblogic-rdbms-jar>
>     	<weblogic-rdbms-relation>
>     		<relation-name>stocks-holders</relation-name>
>     			<table-name>stocks</table-name>
>     	</weblogic-rdbms-relation>
>     </weblogic-rdbms-jar>

# relationship-caching

Range of values: | n/a
Default value: | n/a
Parent elements: | `weblogic-rdbms-jar weblogic-rdbms-bean`

## Function

The `relation-caching` element specifies relationship caching. For more information about relationship caching, see Relationship Caching.

## Example

The `XML` stanza can contain the elements shown here:

>     <relationship-caching>
>     	<caching-name>cacheMoreBeans</caching-name>
>     	<caching-element>
>     		<cmr-field>accounts<</cmr-field>
>     		<group-name>acct_group</group-name>
>     		<caching-element>
>     			<cmr-field>address</cmr-field>
>     			<group-name>addr_group</group-name>
>     		</caching-element>
>     	</caching-element>
>     	<caching-element>
>     		<cmr-field>phone</cmr-field>
>     		<group-name>phone_group</group-name>
>     	</caching-element>
>     </relationship-caching>

# relationship-role-map

Range of values: | n/a
Default value: | n/a
Parent elements: | `weblogic-rdbms-relation weblogic-relationship-role`

## Function

The `relationship-role-map` element specifies foreign key column to key column mapping for beans involved in a relationship.

A CMP bean that is involved in a relationship may be mapped to multiple DBMS tables (see the table-map element for more details). If the bean on the foreign key side of a one-to-one or one-to-many relationship is mapped to multiple tables, then the name of the table containing the foreign-key columns must be specified using the `foreign-key-table` element.

Conversely, if the bean on the primary key side of a one-to-one or one-to-many relationship or a bean participating in a m-n relationship is mapped to multiple tables, then the name of the table containing the primary key must be specified using the `primary-key-table` element.

If neither of the beans in a relationship is mapped to multiple tables, then the `foreign-key-table` and `primary-key-table` elements can be omitted because the tables being used are implicit.

For more information about container-managed relationships, see Using Container-Managed Relationships (CMRs).

## Example

### Mapping a Bean on Foreign Key Side of a Relationship to Multiple Tables

The bean on the foreign-key side of a one-to-one relationship, `Fk_Bean`, is mapped to multiple tables. The table that holds the foreign key columns must be specified in the `foreign-key-table` element.

`Fk_Bean` is mapped to two tables: `Fk_BeanTable_1` and `Fk_BeanTable_2`. The foreign key columns for the relationship are located in table `Fk_BeanTable_2`. The foreign key columns are named `Fk_column_1` and `Fk_column_2`. The bean on the primary key side, `Pk_Bean`, is mapped to a single table with primary key columns `Pk_table_pkColumn_1` and `Pk_table_pkColumn_2`:

>     <relationship-role-map
>     	<foreign-key-table>Fk_BeanTable_2</foreign-key-table>
>     	<column-map>
>     		<foreign-key-column>Fk_column_1</foreign-key-column>
>     		<key-column>Pk_table_pkColumn_1</key-column>
>     	</column-map>
>     	<column-map>
>     		<foreign-key-column>Fk_column_2</foreign-key-column>
>     		<key-column>Pk_table_pkColumn_2</key-column>
>     	</column-map>
>     </relationship-role-map>

The `foreign-key-table` element must be specified so that the container can know which table contains the foreign key columns.

### Mapping a Bean on Primary Key Side of a Relationship to Multiple Tables

The bean on the primary key side of a one-to-one relationship, `Pk_bean`, is mapped to multiple tables, but the bean on the foreign key side of the relationship, `Fk_Bean`, is mapped to one table, `Fk_BeanTable`. The foreign key columns are named `Fk_column_1` and `Fk_column_2`.

`Pk_bean` is mapped to tables:

- `Pk_BeanTable_1` with primary key columns `Pk_table1_pkColumn_1` and `Pk_table1_pkColumn_2` and
- `Pk_BeanTable_2` with primary key columns `Pk_table2_pkColumn_1` and `Pk_table2_pkColumn_2`.

`<relationship-role-map>
<primary-key-table>Pk_BeanTable_1</primary-key-table>
<column-map>
<foreign-key-column>Fk_column_1</foreign-key-column>
<key-column>Pk_table1_pkColumn_1</key-column>
</column-map>
<column-map>
<foreign-key-column>Fk_column_2</foreign-key-column>
<key-column>Pk_table1_pkColumn_2</key-column>
</column-map>
</relationship-role-map>`

# relationship-role-name

Range of values: | Must match the `ejb-relationship-role-name` of an `ejb-relationship-role` in the associated `ejb-jar.xml`.
Default value: | n/a
Parent elements: | `weblogic-rdbms-relation weblogic-relationship-role`

## Function

The `relationship-role-name` element specifies the name of a relationship role.

For more information about container-managed relationships, see Using Container-Managed Relationships (CMRs).

## Example

See the examples for weblogic-relationship-role.

# serialize-byte-array-to-oracle-blob

Range of values: | n/a
Default value: | false
Parent elements: | `weblogic-rdbms-jar compatibility`

## Function

This element, introduced in WebLogic Server 8.1 SP02, is a compatibility flag. It is used to specify whether a cmp-field of type `byte[]` mapped to a OracleBlob should be serialized. By default, the value of the tag is `false`, which means that the container will persist the `byte[]` directly and not serialize it.

In versions prior to WebLogic Server 8.1 SP02, the default behavior was to serialize a cmp-field of type byte[] mapped to an OracleBlob. To revert to the old behavior, set the value of s`erialize-byte-array-to-oracle-blob` to true.

## Example

>     <compatibility>
>       <serialize-byte-array-to-oracle-blob>
>       true
>       </serialize-byte-array-to-oracle-blob>
>     </compatibility>

# sql-select-distinct

Note: This element is deprecated. To achieve the same functionality, use the `SELECT DISTINCT` clause directly in finder queries

Range of values: | `True | False`
Default value: | `False`
Requirements: |
Parent elements: | `weblogic-query`

.

## Function

The `sql-select-distinct` element controls whether the generated SQL SELECT statement will contain a a DISTINCT qualifier. Using the DISTINCT qualifier caused the database to return unique rows.

Oracle database does not allow use of a `SELECT DISTINCT` with a `FOR UPDATE` clause. Therefore, you cannot use the `sql-select-distinct` element if any bean in the calling chain has a method with `isolation-level` of `TransactionReadCommittedForUpdate`. You specify the `transaction-isolation` element in the `weblogic-ejb-jar.xml`.

## Example

The `XML` example contains the element shown here:

`<sql-select-distinct>True</sql-select-dist`inct>

# table-map

Range of values: |
Default value: |
Requirements: | Each `table-map` element must contain a mapping for the bean's primary key fields.
Parent elements: | `weblogic-rdbms-bean`

## Function

A CMP bean can be mapped to one or more DBMS tables. The `table-map` element specifies a mapping between the cmp-fields of a bean and the columns of a table for all of the `cmp-fields` mapped to that table. If you map a CMP bean to multiple DBMS tables, then you must specify a `table-map` element for each the tables.

When you map a CMP bean to multiple tables, each table contains a row that maps to a particular bean instance. Consequently, all tables will contain the same number of rows at any point in time. In addition, each table contains the same set of homogeneous primary key values. Therefore, each table must have the same number of primary key columns and corresponding primary key columns in different tables must have the same type, although they may have different names.

Each `table-map` element must specify a mapping from the primary key column(s) for a particular table to the primary key field(s) of the bean. You can only map non-primary key fields to a single table.

For information about using the verify-rows, verify-columns, and optimistic-column elements, see Check Data for Validity with Optimistic Concurrency

## Example

The `XML` stanza can contain the elements shown here:

>     <table-map>
>     	<table-nme>DeptTable</table-name>
>     	<field-map>
>     		<cmp-field>deptId1</cmp-field>
>     		<dbms-column>t1_deptId1_column</dbms-column>
>     	</field-map>
>     	<field-map>
>     		<cmp-field>deptId2</cmp-field>
>     		<dbms-column>t1_deptId2_column</dbms-column>
>     	</field-map>
>     	<field-map>
>     		<cmp-field>location</cmp-field>
>     		<dbms-column>location_column</dbms-column>
>     	</field-map>
>     		<cmp-field>budget</cmp-field>
>     		<dbms-column>budget</dbms-column>
>     	</field-map>
>     	<verify-rows>Read</verify-rows>
>     	<verify-columns>Version</verify-columns>
>     	<optimistic-column>ROW_VERSION</optimistic-column>
>     </table-map>

# table-name

Range of values: | Valid, fully qualified SQL name of the source table in the database.
Default value: |
Requirements: | `table-name` must be set in all cases.
Parent elements: | `weblogic-rdbms-bean weblogic-rdbms-relation`

## Function

The fully qualified SQL name of the table. The user defined for the`data-source` for this bean must have read and write privileges for this table, but does not necessarily need schema modification privileges.

## Example

>     <weblogic-rdbms-jar>
>          <weblogic-rdbms-bean>
>             <ejb-name>containerManaged</ejb-name>
>             <data-source-name>examples-dataSource-demoPool</data-source-name>
>             <table-name>ejbAccounts</table-name>
>          </weblogic-rdbms-bean>
>     </weblogic-rdbms-jar>

# use-select-for-update

Range of values: | True | False
Default value: | False
Parent elements: | `weblogic-rdbms-bean`

## Function

Enforces pessimistic concurrency on a per-bean basis. Specifying `True` causes `SELECT ... FOR UPDATE` to be used whenever the bean is loaded from the database. This is different from the transaction isolation level of `TransactionReadCommittedForUpdate` in that this is set at the bean level rather than the transaction level.

## Example

>     <weblogic-rdbms.jar>
>          <weblogic-rdbms-bean>
>               ejb-name>containerManaged</ejb-name>
>               <use-select-for-update>True</use-select-for-update>
>          </weblogic-rdbms-bean>
>     </weblogic-rdbms-jar>

# validate-db-schema-with

Range of values: | `MetaData | TableQuery`
Default value: | `TableQuery`
Parent elements: | `weblogic-rdbms-jar`

## Function

The `validate-db-schema-with` element specifies that container-managed persistence checks that beans have been mapped to a valid database schema during deployment.

If you specify `MetaData` WebLogic Server uses the JDBC metadata to validate the schema.

If you specify `TableQuery`, the default setting, WebLogic Server queries the tables directly to verify that they have the schema expected by CMP runtime.

## Example

The `XML` stanza can contain the elements shown here:

>     <validate-db-schema-with>TableQuery</validate-db-schema-with>

# verify-columns

Range of values: | `Read | Modified | Version | Timestamp`
Default value: | `none`
Requirements: | `table-name` must be set in all cases.
Parent elements: | `weblogic-rdbms-bean table-map`

## Function

The `verify-columns` element specifies the columns in a table that you want WebLogic Server to check for validity when you use the `optimistic` concurrency strategy. WebLogic Server checks columns at the end of a transaction, before committing it to the database, to make sure that no other transaction has modified the data.

See Choosing a Concurrency Strategy for more information.

## Example

>     <verify-columns>Modified</verify-columns>

# verify-rows

Range of values: | `Read | Modified`
Default value: | `Modified`
Requirements: | `table-name` must be set in all cases.
Parent elements: | `weblogic-rdbms-bean table-map`

## Function

The `verify-rows` element specifies the rows in a table that the EJB container should check when optimistic concurrency is used.

- `Modified`— only rows that are updated or deleted by a transaction are checked. This value ensures that two transactions do not update the same row concurrently, resulting in a lost update, but allows reads and updates of different transactions to be interleaved. This results in a level of consistency that falls between the ANSI `READ_COMMITTED` and `REPEATABLE_READ` levels of consistency.
- `Read`—specifies that any row that is read by the transaction should be checked. This includes both rows that are simply read and rows that are read and then updated or deleted by the transaction. Specifying a value of `Read` results in additional overhead since it generally increases the amount of optimistic checking the EJB container must perform. With the `Read` option, committed transactions read a set of rows that are guaranteed not to be modified by another transaction until after the transaction commits.This results in a high level of consistency which is very close to the ANSI definition of `SERIALIZABLE` consistency.

Note: If `verify-rows` is set to `Read` then the `verify-columns` element may not have a value of `Modified`, as this combination would result in the EJB container checking only the modified rows.

See Choosing a Concurrency Strategy for more information.

## Example

>     <verify-rows>Modified</verify-rows>

# weblogic-ql

Range of values: |
Default value: |
Parent elements: | `weblogic-rdbms-bean weblogic-query`

## Function

The `weblogic-q`l element specifies a query that contains a WebLogic specific extension to the ejb-ql language. You should specify queries that only use standard EJB-QL language features in the `ejb-jar.xml` deployment descriptor.

## Example

See weblogic-query.

# weblogic-query

Range of values: | n/a
Default value: | mA
Parent elements: | `weblogic-rdbms-bean`

## Function

The `weblogic-query` element allows you to associate WebLogic specific attributes with a query, as necessary. For example, `weblogic-query` can be used to specify a query that contains a WebLogic specific extension to EJB-QL. Queries that do not take advantage of WebLogic extensions to EJB-QL should be specified in the `ejb-jar.xml` deployment descriptor.

Also, the `weblogic-query` element is used to associate a `field-group` with the query if the query retrieves an entity bean that should be pre-loaded into the cache by the query.

## Example

The `XML` stanza can contain the elements shown here:

>     <weblogic-query>
>        <description>...</description>
>        <query-method>
>           <method-name>findBigAccounts</method-name>
>              <method-params>
>                 <method-param>double</method-param>
>              </method-params>
>        <query-method>
>        <weblogic-ql>WHERE BALANCE>10000 ORDERBY NAME
>        </weblogic-ql>
>        <group-name>...</group-name>
>        <caching-name>...</caching-name>
>        <max-elements>...</max-elements>
>        <include-updates>...</include-updates>
>        <sql-select-distinct>...</sql-select-distinct>
>     </weblogic-query>

# weblogic-rdbms-bean

Range of values: | n/a
Default value: | n/a
Parent elements: | `weblogic-rdbms-jar`

## Function

The `weblogic-rdbms-bean` specifies an entity bean that is managed by the WebLogic RDBMS CMP persistence type.

## Example

>     weblogic-rdbms-bean
>     	ejb-name
>     	data-source-name
>     		table-map
>     	field-group
>     	relationship-caching
>     	weblogic-query
>     	dalay-database-insert-until
>     	automatic-key-generation
>     	check-exists-on-method

# weblogic-rdbms-jar

## Function

The `weblogic-rdbms-jar` element is the root level element of a WebLogic RDBMS CMP deployment descriptor. This element contains the deployment information for one or more entity beans and an optional set of relations.

## Example

The `XML` structure of `weblogic-rdbms-jar` is:

>     weblogic-rdbms-jar
>     	weblogic-rdbms-bean
>     	weblogic-rdbms-relation
>     	create-default-dbms-tables
>     	validate-db-schema-with
>     	database-type

# weblogic-rdbms-relation

Range of values: | n/a
Default value: | n/a
Parent elements: | `weblogic-rdbms-jar`

## Function

The `weblogic-rdbms-relation` element represents a single relationship that is managed by the WebLogic CMP persistence type. deployment descriptor. WebLogic Server supports the following three relationship mappings:

- For one-to-one relationships, the mapping is from a foreign key in one bean to the primary key of the other bean.
- For one-to-many relationships, the mapping is also from a foreign key in one bean to the primary key of another bean.
- For many-to-many relationships, the mapping involves a join table. Each row in the join table contains two foreign keys that map to he primary keys of the entities involved in the relationship.

For more information on container managed relationships, see Using Container-Managed Relationships (CMRs).

## Examples

See the sections that following for examples of how one-to-one, one-to-many, and many-to-many relationships are configured.

### Defining a One-to-One Relationship

Listing 8-3 shows the `weblogic-rdbms-bean` stanza that defines a one-to-one relationship between the entities defined in Listing 8-1 and Listing 8-2. The `weblogic-rdbms-relation` stanza is in the `weblogic-cmp-jar.xml` file, after the `weblogic-rdbms-bean` stanzas.

Listing 8-1 Bean 1

`<weblogic-rdbms-bean>
` `<ejb-name>CountryEJB</ejb-name>
` `<data-source-name>wlsd21-datasource</data-source-name>
` `<table-map>
` `<table-name>EXAMPLE07_COUNTRY</table-name>
` `<field-map>
` `<cmp-field>name</cmp-field>
` `<dbms-column>NAME</dbms-column>
` `</field-map>
` `<field-map>
` `<cmp-field>continent</cmp-field>
` `<dbms-column>CONTINENT</dbms-column>
` `</field-map>
` `</table-map>
</weblogic-rdbms-bean>`

Listing 8-2 Bean 2

>     <weblogic-rdbms-bean>
>        <ejb-name>CapitalEJB</ejb-name>
>        <data-source-name>wlsd21-datasource</data-source-name>
>           <table-map>
>           <table-name>EXAMPLE07_CAPITAL</table-name>
>           <field-map>
>              <cmp-field>CAPITAL_NAME</cmp-field>
>              <dbms-column>NAME</dbms-column>
>           </field-map>
>           <field-map>
>              <cmp-field>continent</cmp-field>
>              <dbms-column>CONTINENT</dbms-column>
>           </field-map>
>        </table-map>
>     </weblogic-rdbms-bean>

Listing 8-3 <weblogic-rdbms-relation> Stanza for a One-to-One Relationship

>     <weblogic-rdbms-relation>
>        <relation-name>CountryCapitalRel</relation-name>
>        <weblogic-relationship-role>
>           <relationship-role-name>CountryRole</relationship-role-name>
>           <relationship-role-map>
>               <column-map>
>                  <foreign-key-column>CAPITAL_NAME</foreign-key-column>
>                  <key-column>NAME</key-column>
>               </column-map>
>           </relationship-role-map>
>        </weblogic-relationship-role>
>     </weblogic-rdbms-relation>

Note: `CAPITAL_NAME` is the column name for the foreign key in the Country table.

`NAME` is the column name for the primary key located in the Capital table

<relationship-role-name> contains the relation field specified in <`cmr-field`> in the <`ejb-relationship-role`> stanza in `ejb-jar.xml.`

### Defining a One-to-Many Relationship

Listing 8-4 contains a sample <weblogic-rdbms-relation> stanza that defines a one-to-many relationship:

Listing 8-4 <weblogic-rdbms-relation> Stanza for a One-to-Many Relationship

>     <weblogic-rdbms-relation>
>        <relation-name>OwnerDogRel</relation-name>
>        <weblogic-relationship-role>
>           <relationship-role-name>DogRole</relationship-role-name>
>           <relationship-role-map>
>              <column-map>
>                 <foreign-key-column>OWNER_NAME</foreign-<key-column>
>                 <key-column>NAME</key-column>
>              </column-map>
>           <relationship-role-map>
>        </weblogic-relationship-role>
>     </weblogic-rdbms-relation>

Note: <relationship-role-name> contains the relation field specified in <`cmr-field`> in the <`ejb-relationship-role`> stanza in `ejb-jar.xml.`

<foreign-key-column> must specify the column in the table on the "many" side of the relationship.

### Defining a Many-to-Many Relationship

A WebLogic Server many-to-many relationship involves the physical mapping of a join table. Each row in the join table contains two foreign keys that maps to the primary keys of the entities involved in the relationship.

The following example shows a many-to-many relationship between the `FRIENDS` bean and the `EMPLOYEES` bean.

Listing 8-5 <weblogic-rdbms-relation> Stanza for a Many-to-Many Relationship

>     <weblogic-rdbms-relation>
>        <relation-name>friends</relation-name>
>        <table-name>FRIENDS</table-name>
>        <weblogic-relationship-role>
>           <relationship-role-name>friend</relationship-role-name>
>           <relationship-role-map>
>              <column-map>
>                 <foreign-key-column>first-friend-id</foreign-key-column>
>                 <key-column>id</key-column>
>              </column-map
>           </relationship-role-map>
>        </weblogic-relationship-role>
>        <weblogic-relationship-role>
>           <relationship-role-name>second-friend</relationship-role-name>
>              <relationship-role-map>
>                 <column-map>
>                    <foreign-key-column>second-friend-id</foreign-key-column>
>                    <key-column>id</key-column>
>              </column-map>
>           </relationship-role-map>
>        </weblogic-relationship-role>
>     </weblogic-rdbms-relation>

In Figure 8-4, the `FRIENDS` join table has two columns, called `first-friend-id` and `second-friend-id.` Each column contains a foreign key that designates a particular employee who is a friend of another employee. The primary key column (`key-column`) of the `EMPLOYEES` table is `id`. For this example, assume that the `EMPLOYEES` bean is mapped to a single table. If the `EMPLOYEES` bean is mapped to multiple tables, then the table containing the primary key column (`key-column`) must be specified in the `relationship-role-map`. For more information, see relationship-role-map.

# weblogic-relationship-role

Range of values: | n/a
Default value: | n/a
Parent elements: | `weblogic-rdbms-jar weblogic-rdbms-relation`

## Function

The `weblogic-relationship-role` element specifies the following DBMS schema information for an `ejb-relationship-role` specified in `ejb-jar.xml`:

- The `relationship-role-map` sub-element specifies the mapping between a foreign key and a primary key, for one side of a relationship. For a 1-1 or 1-n relationship, only the role on the foreign-key side of the relationship specifies a mapping. Both roles specify a mapping for a m-m relationship. For details and examples, see relationship-role-map.
- A `group-name` can be used to indicate the field-group to be loaded when the bean corresponding to the role is loaded as a result of traversing the relationship, i.e. calling a cmr `getXXX` method.
- The `db-cascade-delete` tag can to used to specify that cascade deletes use the built-in cascade delete facilities of the underlying DBMS. For more information, see db-cascade-delete.

For more information about container-managed relationships, see Using Container-Managed Relationships (CMRs).

## Example

>     <weblogic-relationship-role>
>         <relationship-role-name>...</relationship-role-name>
>         <group-name> ....</group-name>
>         <relationship-role-map>...
>            ....
>         </relationship-role-map>
>         <db-cascade-delete/>
>     </weblogic-relationship-role>