Programming WebLogic Enterprise JavaBeans

      

weblogic-cmp-jar.xml Deployment Descriptor Reference

The following sections describe the EJB 2.1 elements in the weblogic-cmp-jar.xml file, the WebLogic-specific XML Schema-based (XSD) deployment descriptor 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.

In this release of WebLogic Server, weblogic-cmp-jar.xml is XML Schema-based (XSD). In prior releases, weblogic-cmp-jar.xml was Document Type Definition-based (DTD). For backward compatibility, this release of WebLogic Server supports XSD- or DTD-based EJB descriptors. In this release of WebLogic Server, the EJB container still supports all older DTD-based descriptors; you can deploy applications that use DTD-based descriptors in this release of WebLogic Server without modifying the descriptors.

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

For information on:

EJB 1.1 deployment descriptor elements, see Important Information for EJB 1.1 Users.

 

2.1 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 pre-9.0 releases of WebLogic Server.

You can continue to use the earlier weblogic-cmp-jar.xml DTD beans that you deploy to this release of WebLogic Server; likewise, you can continue to use the weblogic-cmp-jar.xml DTD that was supported in WebLogic Server 8.1. Though deployment descriptors are XSD-based beginning with WebLogic Server 9.0, for backward compatibility, WebLogic Server continues to support DTD-based descriptors. However, if you want to use any of the CMP 2.1 features, use the XSD described below.

Oracle recommends that you run DDConverter to convert EJB deployment descriptors from pre-9.0 releases of WebLogic Server to conform to the current release of WebLogic Server. DDConverter converts your DTD-based EJB deployment descriptors from pre-9.0 releases of WebLogic Server to XSD-based descriptors supported in this release.

Oracle recommends that you always convert descriptors when migrating applications to a new WebLogic Server release.

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

weblogic-rdbms-jar

    weblogic-rdbms-bean

        ejb-name

        data-source-jndi-name

        table-map

        field-group

        relationship-caching

        sql-shape

        weblogic-query

        delay-database-insert-until

        use-select-for-update

        lock-order

        instance-lock-order

        automatic-key-generation

        check-exists-on-method

        cluster-invalidation-disabled

    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

        serialize-byte-array-to-oracle-blob

        serialize-char-array-to-bytes

        allow-readonly-create-and-remove

        disable-string-trimming

 

2.1 weblogic-cmp-jar.xml Deployment Descriptor Elements

This list of the elements in weblogic-cmp-jar.xml includes all elements that are supported in WebLogic Server.

 

allow-readonly-create-and-remove

Table C-1 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 WebLogic Server 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

Table C-2 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 element for different primary key generation methods. For supported generation methods, see generator-type Listing C-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 C-2 automatic-key-generation With generator-type=SQL-SERVER 
<automatic-key-generation>

    <generator-type>SQL-SERVER</generator-type>

</automatic-key-generation>
Listing C-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

Table C-3 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.

caching-element can contain nested caching elements, as in the example shown in relationship-caching.

For information about relationship caching, see Relationship Caching.

 

Example

See relationship-caching:

 

caching-name

Table C-4 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

Table C-5 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>

 

cluster-invalidation-disabled

Table C-6 cluster-invalidation-disabled
Range of values: true | false
Default value: false
Parent elements: weblogic-rdbms-bean

 

Function

This flag, introduced in WebLogic Server 9.0, is used to disable or enable invalidation of an EJB that uses Optimistic or ReadOnly concurrency when the EJB is updated by a member of a cluster to which it is deployed. For more information, see Invalidation Options for Optimistic Concurrency in Clusters.

 

Example

<cluster-invalidation-disabled>true</cluster-invalidation-disabled>

 

cmp-field

Table C-7 cmp-field
Range of Values Valid name of field in the bean. Field must have matching cmp-entry in ejb-jar.xml. Field name is case-sensitive.
Default value: n/a
Parent elements: weblogic-rdbms-bean
field-map
and
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

Table C-8 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

Table C-9 column-map
Range of Values n/a
Default value: n/a
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.

 

Example

The following is an example of the column-map element:

You do not need to specify the key-column element if the foreign-key-column refers to a remote bean. 

<column-map>

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

    <key-column>id</key-column>

</column-map>

 

compatibility

Table C-10 compatibility
Range of values: n/a
Default value: n/a
Parent elements: weblogic-rdbms-jar

 

Function

The <compatibility> element, 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>

     <serialize-char-array-to-bytes>

     <allow-readonly-create-and-remove>

     <disable-string-trimming>

</compatibility>

 

create-default-dbms-table

Table C-11 create-default-dbms-table
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:

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 recreates the table during deployment only if columns have changed. The container does not save data. You must ensure that the column type and cmp-field types are compatible. The EJB container does not attempt to ensure the column type and cmp-field types are compatible.
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.

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

See Automatic Table Creation (Development Only).

Automatic Oracle SEQUENCE Generation

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-specific-sql

Table C-12 database-specific-sql
Range of values:
Default value:
Requirements: database-type must be specified.
Parent elements: weblogic-rdbms-jar
weblogic-rdbms-bean
weblogic-query
sql-query

 

Function

The database-specific-sql element specifies a database-specific SQL statement.

 

Example

<database-specific-sql>

<database-type>SQLServer</database-type>

<sql>SELECT name, phone, location, testid FROM medrecappPharmacyBeanTable WHERE testid = ?1 AND SUBSTRING(testid, 1,5) = 'local' ORDER BY name</sql>

</database-specific-sql>

 

database-type

Table C-13 database-type
Range of values: DB2 | Informix | MySQL | Oracle | POINTBASE | SQLServer | SQLServer2000 | Sybase
Default value:
Parent elements: weblogic-rdbms-jar and weblogic-rdbms-jar
weblogic-rdbms-bean
weblogic-query
sql-query database-specific-sql

 

Function

The database-type element specifies the database used as the underlying WebLogic Server dbms or the dbms against which to execute a vendor-specific SQL statement. If you specify database-type in the weblogic-rdbms-jar element, the database you specify applies to the entire weblogic-rdbms-jar deployment descriptor file unless it is overridden in a database-specific-sql element by another database-type element.

 

Example

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

 

data-source-jndi-name

Table C-14 data-source-jndi-name
Range of values Valid WebLogic Server JDBC data source 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 data sources, see “Programming WebLogic JDBC.”

Prior to WebLogic Server 9.0, this element was data-source-name.

 

Example

See table-name.

 

db-cascade-delete

Table C-15 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:

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

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

Table C-16 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.

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

 

Example

See field-map.

 

dbms-column-type

Table C-17 dbms-column-type
Range of values: Blob | Clob | LongString | SybaseBinary
Default value:
Requirements To specify Blob or Clob in this element, also set dbms-default-value to Oracle or DB2.
Parent elements: weblogic-rdbms-bean
field-map

 

Function

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

 

Example

<field-map>

    <cmp-field>photo</cmp-field>

    <dbms-column>PICTURE</dbms-column>

    <dbms_column-type>OracleBlob</dbms-column-type>

</field-map>

 

dbms-default-value

Table C-18 dbms-default-value
Range of values: DB2 | Informix| MySQL | Oracle | POINTBASE | SQLServer | SQLServer2000 | Sybase
Default value:
Parent elements: weblogic-rdbms-bean
field-map

 

Function

Specifies the database used as the default underlying dbms. This value can be overridden by the database-type element.

 

Example

<dbms-default-value>Oracle</dbms-default-value>

 

default-dbms-tables-ddl

Table C-19 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

Table C-20 delay-database-insert-until
Range of values: ejbCreate | ejbPostCreate
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:

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 perform a database insert until after the method completion.

cmr-fields 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

Table C-21 description
Range of values: n/a
Default value: n/a
Parent elements: weblogic-rdbms-jar
weblogic-rdbms-bean
weblogic-query or weblogic-rdbms-jar
weblogic-rdbms-bean
sql-shape

 

Function

The description element provides text that describes the parent element.

 

Example

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

 

disable-string-trimming

Table C-22 disable-string-trimming
Range of values: True | False
Default value: False
Parent elements: compatibility

 

Function

This element, introduced in WebLogic Server 9.0, is a compatibility flag. It is used to specify whether a cmp-field of type string[] should be trimmed. Set this flag to True to disable string trimming. For more information on string trimming, see String-Valued CMP Field Trimming and Disabling String Trimming.

 

Example

<compatibility>

  <disable-string-trimming>True</disable-string-trimming>

</compatibility>

 

ejb-name

Table C-23 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.

 

ejb-ql-query

Table C-24 ejb-ql-query
Range of values:
Default value:
Parent elements: weblogic-rdbms-jar
weblogic-rdbms-bean
weblogic-query

 

Function

The ejb-ql-query element specifies an EJB-QL query. You should only specify EJB-QL queries that implement EJB finders or contain WebLogic-specific extensions in the weblogic-cmp-jar.xml deployment descriptor; specify queries that use only standard EJB-QL features in the ejb-jar.xml deployment descriptor.

 

Example

See weblogic-query.

 

enable-batch-operations

Table C-25 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.

 

Example

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

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

 

enable-query-caching

Table C-26 enable-query-caching
Range of values: True | False
Default value: True
Parent elements: weblogic-rdbms-jar
weblogic-rdbms-bean
weblogic-query and weblogic-rdbms-jar
weblogic-rdbms-relation

 

Function

This element, introduced in WebLogic Server 9.0, controls whether read-only entity EJBs can be cached at the query level. Caching read-only entity EJBs at the query level improves performance because it enables the EJBs to be accessed in cache by any finder, thereby avoiding the need to access the database. If you set this value to True, you can specify the maximum number of queries to cache at the application or bean level. To specify the maximum number of queries to cache, set max-queries-in-cache in the weblogic-ejb-jar.xml deployment descriptor. For information, see max-queries-in-cache.

 

Example

The following XML sample demonstrates use of the enable-query-caching element:

<enable-query-caching>True</enable-query-caching>

 

field-group

Table C-27 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 field-group element 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

Table C-28 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-fields, 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 field-map element 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>

 

finders-return-nulls

Table C-29 finders-return-nulls
Range of values: True | False
Default value:
Parent elements: weblogic-rdbms-jar
compatibility
weblogic-query

 

Function

This element, introduced in WebLogic Server 9.0, is a compatibility flag. It is used to specify whether finders can return null results.

By default

 

Example

<compatibility>

  <finders-return-nulls>

  True

  </finders-return-value>

</compatibility>

 

foreign-key-column

Table C-30 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

Table C-31 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

Table C-32 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.

 

Example

See automatic-key-generation.

 

generator-type

Table C-33 generator-type
Range of values: Identity | Sequence | SequenceTable
Default value:
Parent elements: weblogic-rdbms-bean
automatic-key-generation

 

Function

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

You must set the database-type element when using automatic-key-generation.

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

The following databases are supported for each generator-type:

 

Example

See automatic-key-generation.

 

group-name

Table C-34 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

Table C-35 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

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>

    <ejb-ql-query>

        <weblogic-ql>WHERE BALANCE>10000 ORDER BY NAME</weblogic-ql>

    </ejb-ql-query>

    <include-updates>True</include-updates>

</weblogic-query>

 

instance-lock-order

Table C-36 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.

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

 

Example

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

 

key-cache-size

Table C-37 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:

 

Example

See automatic-key-generation.

 

key-column

Table C-38 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

Table C-39 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 the 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.

 

Example

An example of the lock-order element is: 

<lock-order>1</lock-order>

     <!ELEMENT lock-order (PCDATA)>

 

max-elements

Table C-40 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

An example of the max-elements element is shown here: 

<max-elements>100</max-elements>

      <!ELEMENT max-element (PCDATA)>

 

method-name

Table C-41 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.

The ‘*' character cannot be used as a wildcard.

 

Example

See weblogic-query.

 

method-param

Table C-42 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

Table C-43 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

Table C-44 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.

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

Table C-45 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 ejb-ql-query and delay-database-insert-until.

 

Example

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

 

pass-through-columns

Table C-46 pass-through-columns
Range of values: Any positive integer.
Default value:
Parent elements: weblogic-rdbms-bean sql-shape

 

Function

This element, introduced in WebLogic Server 9.0, specifies the number of aggregate columns that should be passed through to a SQL query result set without being mapped to anything.

 

Example

See sql-shape.

 

primary-key-table

Table C-47 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.

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

Table C-48 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

Table C-49 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

An example of the relationship-name element is 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

Table C-50 relationship-caching
Range of values: n/a
Default value: n/a
Parent elements: weblogic-rdbms-jar
weblogic-rdbms-bean

 

Function

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

 

Example

The relationship-caching element 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

Table C-51 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:

<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

Table C-52 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

Table C-53 serialize-byte-array-to-oracle-blob
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 compatibility flag. It is used to specify whether a cmp-field of type byte[] mapped to a Blob in an Oracle database 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 a Blob in an Oracle database. To revert to the old behavior, set the value of serialize-byte-array-to-oracle-blob to true.

 

Example

<compatibility>

  <serialize-byte-array-to-oracle-blob>

  true

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

</compatibility>

 

serialize-char-array-to-bytes

Table C-54 serialize-char-array-to-bytes
Range of values: True | False
Default value: False
Parent elements: weblogic-rdbms-jar
compatibility

 

Function

This element, introduced in WebLogic Server 9.0, is a compatibility flag. It is used to specify whether a cmp-field of type char[] mapped to a byte should be serialized. By default, the value of the tag is False, which causes the EJB container to persist the char[] directly and not serialize it; If you want the EJB container to serialize the char[], set this value to True.

 

Example

<compatibility>

  <serialize-char-array-to-bytes>

  true

  </serialize-char-array-to-bytes>

</compatibility>

 

sql

Table C-55 sql
Range of values: Valid SQL.
Default value: n/a
Requirements: To use database-specific SQL, specify the database against which to execute the SQL in the in database-type element.
Parent elements: weblogic-rdbms-bean
weblogic-query
sql-query and weblogic-rdbms-bean
weblogic-query
sql-query database-specific-query

 

Function

The sql element contains a standard or database-specific SQL query. You should specify queries that use only standard EJB-QL language features in the ejb-jar.xml deployment descriptor. Specify queries that contain standard SQL, database-specific SQL, or WebLogic extensions to EJB-QL in the weblogic-cmp-jar.xml deployment descriptor.

 

Example

...

<weblogic-rdbms-bean>
<weblogic-query>
<sql-query>
<sql>SELECT date_prescribed, dosage, drug, id, frequency, instructions, pat_id, issuing_phys_id, record_id, refills_remaining FROM medrecappPrescription WHERE testid = ?1</sql>
</sql-query>
</weblogic-query>

...

</weblogic-rdbms-bean>

 

sql-query

Table C-56 sql-query
Range of values:
Default value: n/a
Requirements: To use database-specific SQL, specify the database against which to execute the SQL in database-type.
Parent elements: weblogic-rdbms-bean
weblogic-query

 

Function

The sql-query element allows you to specify standard and database-specific SQL queries. EJB-QL queries that do not take advantage of WebLogic extensions to EJB-QL should be specified in the ejb-jar.xml deployment descriptor.

Prior to WebLogic Server 9.0, only EJB-QL queries (with or without WebLogic extensions) were supported; in this release of WebLogic Server, SQL queries, EJB-QL queries (with or without WebLogic extensions), or a combination of the two are supported.

 

Example

<sql-query>
<sql-shape-name>...</sql-shape-name>
<sql>...</sql>
<database-specific-sql>...</database-specific-sql>
<database-type>...</database-type>
<sql>...</sql>
<unknown-primary-key-field>...</unknown-primary-key-field>
<cmp-field>...</cmp-field>
</sql-query>

 

sql-select-distinct

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

Table C-57 sql-select-distinct
Range of values: True | False
Default value: False
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 causes 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-distinct>

 

sql-shape

Table C-58 sql-shape
Range of values:
Default value:
Parent elements: weblogic-rdbms-jar
weblogic-rdbms-bean sql-query

 

Function

The sql-shape element describes the data that is returned by a SQL query. Specifying sql-shape is necessary because databases do not always provide this information. Usually the sql-shape element should simply specify the database tables and columns that are being returned. For more complex queries, sql-shape should also specify the relationships that are present in the data that is returned by the database, and whether there are aggregate columns that should be passed through (should not be mapped to anything).

 

Example

sql-shape

description

sql-shape-name

table

pass-through-columns

ejb-relation-name

 

sql-shape-name

Table C-59 sql-shape-name
Range of values:
Default value:
Parent elements: weblogic-rdbms-jar
weblogic-rdbms-bean
weblogic-query
sql-query sql-shape

 

Function

The sql-shape-name element can be used to associate a sql-shape with multiple queries. If you have multiple queries that use the same sql-shape, you can define the shape once and use it multiple times by referencing sql-shape-name.

 

Example

See sql-shape.

 

table-map

Table C-60 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 specify a table-map element for each of 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 table-map element can contain the elements shown here: 

<table-map>

    <table-name>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>        

    <trigger-updates-optimistic-column>False

    </trigger-updates-optimistic-column>

    <version-column-initial-value>0</version-column-initial-value>

</table-map>

 

table-name

Table C-61 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-jndi-name>examples-dataSource-demoPool</data-source-jndi-name>

        <table-name>ejbAccounts</table-name>

     </weblogic-rdbms-bean>

</weblogic-rdbms-jar>

 

trigger-updates-optimistic-column

Table C-62 trigger-updates-optimistic-column
Range of values: True | False.
Default value: False
Parent elements: weblogic-rdbms-bean
table-map

 

Function

The trigger-updates-optimistic-column element, introduced in WebLogic Server 9.0, indicates whether you want the EJB container to automatically update the database column value specified in optimistic-column that is used for concurrency checking. By default, the value of trigger-updates-optimistic-column is False, and the EJB container automatically updates the database column specified in optimistic-column whenever it sends SQL UPDATE statements to JDBC. If you have legacy applications that use database triggers to update the version values whenever the legacy application updates a database row and you do not want the EJB container to automatically update version values, set the value of this element to True.

If you set trigger-updates-optimistic-column to True, also ensure that your database triggers initialize the version column in the database when the bean is created.

 

Example

See table-map.

 

unknown-primary-key-field

Table C-63 unknown-primary-key-field
Range of values: A valid datatype.
Default value: n/a
Parent elements: weblogic-rdbms-bean

 

Function

The unknown-primary-key-field element allows you to specify which of your cmp fields should be used as the primary key when the primary key is not specified in the ejb-jar.xml descriptor. The specified primary key field must be mapped to a database column using the field-map element. If the specified primary key field was not declared as a cmp field in the ejb-jar.xml descriptor, automatic key generation must be enabled and the primary key type will be java.lang.Long.

 

Example

See weblogic-rdbms-bean.

 

use-select-for-update

Table C-64 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.

When using a pessimistic locking strategy (for example, HOLDLOCK) with Sybase JConnect drivers, specify SELECT_OPENS_CURSOR=true to generate a cursor when the query contains a FOR UPDATE clause.

 

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

Table C-65 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

An example of the validate-db-schema-with element is shown here: 

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

 

verify-columns

Table C-66 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

Table C-67 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.

If verify-rows is set to Read then the verify-columns element cannot 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>

 

version-column-initial-value

Table C-68 version-column-initial-value
Range of values: 0 or any positive integer
Default value: n/a
Parent elements: weblogic-rdbms-bean
table-map

 

Function

The version-column-initial-value element, introduced in WebLogic Server 9.0, specifies the initial value of the version column used to implement optimistic concurrency. The version column is the database column you specify in the optimistic-column element. For more information, see optimistic-column.

 

Example

See table-map.

 

weblogic-ql

Table C-69 weblogic-ql
Range of values:
Default value:
Parent elements: weblogic-rdbms-bean
weblogic-query

 

Function

The weblogic-ql 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

Table C-70 weblogic-query
Range of values: n/a
Default value: mA
Parent elements: weblogic-rdbms-bean

 

Function

The weblogic-query element allows you to specify queries that use standard or database-specific SQL or WebLogic-specific extensions to EJB-QL. Queries that do not take advantage of SQL or WebLogic extensions to EJB-QL should be specified in the ejb-jar.xml deployment descriptor.

The weblogic-query element is also 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 weblogic-query element 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>

   <ejb-ql-query>

      <weblogic-ql>WHERE BALANCE>10000 ORDER BY NAME

      </weblogic-ql>

      <group-name>...</group-name>

      <caching-name>...</caching-name>

   </ejb-ql-query>

   <sql-query>

      <sql-shape>...</sql-shape>

      <sql>SELECT date_prescribed, dosage, drug, id, frequency, instructions, pat_id, issuing_phys_id, record_id, refills_remaining FROM medrecappPrescription WHERE testid = ?1</sql>

      <database-specific-sql>

         <database-type>SQLServer</database-type>

         <sql>SELECT name, phone, location, testid FROM medrecappPharmacyBeanTable WHERE testid = ?1 AND SUBSTRING(testid, 1,5) = 'local' ORDER BY name</sql>

      </database-specific-sql>

   </sql-query>

   <max-elements>...</max-elements>

   <include-updates>...</include-updates>

   <sql-select-distinct>...</sql-select-distinct>

</weblogic-query>

 

weblogic-rdbms-bean

Table C-71 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-jndi-name

    unkonown-primary-key-field

    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

Table C-72 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 more information on container managed relationships, see Using Container-Managed Relationships (CMRs).

 

Examples

See the following sections 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 element that defines a one-to-one relationship between the entities defined in Listing 8-1 and Listing 8-2. The weblogic-rdbms-relation element is in the weblogic-cmp-jar.xml file, after the weblogic-rdbms-bean elements. Listing 8-1 Bean 1

<weblogic-rdbms-bean>
<ejb-name>CountryEJB</ejb-name>
<data-source-jndi-name>wlsd21-datasource</data-source-jndi-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-jndi-name>wlsd21-datasource</data-source-jndi-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> Element 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>

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

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

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

Defining a One-to-Many Relationship

Listing 8-4 contains a sample <weblogic-rdbms-relation> element that defines a one-to-many relationship: Listing 8-4 <weblogic-rdbms-relation> Element 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>

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

Note: <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> Element 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

Table C-73 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:

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>