C weblogic-cmp-jar.xml Deployment Descriptor Reference
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. Note:
If you are using metadata annotations in your EJB 3.x implementation, refer to EJB Metadata Annotations Reference in Developing Enterprise JavaBeans for Oracle WebLogic Server.The WebLogic Server weblogic-cmp-jar.xml
file is XML Schema-based (XSD). In pre-9.0 releases of WebLogic Server, weblogic-cmp-jar.xml
was Document Type Definition-based (DTD). For backward compatibility, WebLogic Server still supports XSD- or DTD-based EJB descriptors; you can deploy applications that use DTD-based descriptors in 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:
-
XML Schema Definitions and the namespace declaration required in
weblogic-cmp-jar.xml
, as well as Document Type Definitions and DOCTYPE headers, see Deployment Descriptor Schema and Document Type Definitions Reference. -
the
weblogic-ejb-jar.xml
file, see weblogic-ejb-jar.xml Deployment Descriptor Reference.
EJB 1.1 deployment descriptor elements, see Important Information for EJB 1.1 Users.
This appendix includes the following topics:
- 2.1 weblogic-cmp-jar.xml Deployment Descriptor File Structure
- 2.1 weblogic-cmp-jar.xml Deployment Descriptor Elements
- allow-readonly-create-and-remove
- automatic-key-generation
- caching-element
- caching-name
- check-exists-on-method
- cluster-invalidation-disabled
- cmp-field
- cmr-field
- column-map
- compatibility
- create-default-dbms-table
- database-specific-sql
- database-type
- data-source-jndi-name
- db-cascade-delete
- dbms-column
- dbms-column-type
- dbms-default-value
- default-dbms-tables-ddl
- delay-database-insert-until
- description
- disable-string-trimming
- ejb-name
- ejb-ql-query
- enable-batch-operations
- enable-query-caching
- field-group
- field-map
- finders-return-nulls
- 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
- pass-through-columns
- primary-key-table
- query-method
- relation-name
- relationship-caching
- relationship-role-map
- relationship-role-name
- serialize-byte-array-to-oracle-blob
- serialize-char-array-to-bytes
- sql
- sql-query
- sql-select-distinct
- sql-shape
- sql-shape-name
- table-map
- table-name
- trigger-updates-optimistic-column
- unknown-primary-key-field
- use-select-for-update
- validate-db-schema-with
- verify-columns
- verify-rows
- version-column-initial-value
- weblogic-ql
- weblogic-query
- weblogic-rdbms-bean
- weblogic-rdbms-jar
- weblogic-rdbms-relation
- weblogic-relationship-role
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, you must 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.
Note:
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
Parent topic: weblogic-cmp-jar.xml Deployment Descriptor Reference
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.
Parent topic: weblogic-cmp-jar.xml Deployment Descriptor Reference
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.
Parent topic: allow-readonly-create-and-remove
Example
<compatibility> <allow-readonly-create-and-remove> true </allow-readonly-create-and-remove> </compatibility>
Parent topic: allow-readonly-create-and-remove
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.
Parent topic: automatic-key-generation
Example
The following code samples show the automatic-key-generation
element for different primary key generation methods. For supported generation methods, see generator-type.
Example 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>
Example C-2 automatic-key-generation With generator-type=SQL-SERVER
<automatic-key-generation> <generator-type>SQL-SERVER</generator-type> </automatic-key-generation>
Example 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>
Parent topic: 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.
caching-element
can contain nested caching elements, as in the example shown in relationship-caching.
For information about relationship caching, see Relationship Caching.
Parent topic: caching-element
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.
Parent topic: caching-name
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.
Parent topic: check-exists-on-method
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>
Parent topic: check-exists-on-method
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.
Parent topic: cluster-invalidation-disabled
Example
<cluster-invalidation-disabled>true</cluster-invalidation-disabled>
Parent topic: cluster-invalidation-disabled
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.
Parent topic: cmp-field
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
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.
Parent topic: column-map
Example
The following is an example of the column-map
element:
Note:
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>
Parent topic: column-map
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.
Parent topic: compatibility
Example
<compatibility> <serialize-byte-array-to-oracle-blob>...</serialize-byte-array-to-oracle-blob> <serialize-char-array-to-bytes>...</serialize-char-array-to-bytes> <allow-readonly-create-and-remove>...</allow-readonly-create-and-remove> <disable-string-trimming>...</disable-string-trimming> </compatibility>
Parent topic: compatibility
create-default-dbms-table
Range of values: Disabled | CreateOnly | DropAndCreate | DropAndCreateAlways | AlterOrCreate
Default value: Disabled
Parent elements:
weblogic-rdbms-jar
Parent topic: weblogic-cmp-jar.xml Deployment Descriptor Reference
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 database 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.
Parent topic: create-default-dbms-table
Automatic Table Creation
The following table describes how WebLogic Server handles automatic table creation, based on the value of create-default-dbms-tables
.
Table C-1 Automatic Table Creation
Setting <create-default-dbms-tables> to this value... | Results in this behavior with respect to automatic table creation... |
---|---|
|
The EJB container takes no action with respect to automatic table creation. This is the default value. |
|
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 ' |
|
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. |
|
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. |
|
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 manually.
Parent topic: create-default-dbms-table
Automatic Oracle Database SEQUENCE Generation
Note:
Automatic Oracle database 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
.
Table C-2 Automatic Oracle Database SEQUENCE Generation
Setting <create-default-dbms-tables> to this value... | Results in this behavior... |
---|---|
|
The EJB container takes no action with respect to SEQUENCE generation. This is the default value. |
|
The EJB container creates a |
|
The EJB container creates a If the |
|
The EJB container creates a SEQUENCE, and constructs its name by appending "_WL" to the value of the If the |
|
The EJB container creates a If the |
For more information on automatic generation of an Oracle database SEQUENCE, see Support for Oracle Database SEQUENCE.
Parent topic: create-default-dbms-table
Example
The following example specifies the create-default-dbms-tables
element.
<create-default-dbms-tables>CreateOnly</create-default-dbms-tables>
Parent topic: create-default-dbms-table
database-specific-sql
Range of values: n/a
Default value: n/a
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.
Parent topic: database-specific-sql
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>
Parent topic: database-specific-sql
database-type
Range of values: DB2 | Informix | MySQL | Oracle | SQLServer | SQLServer2000 | Sybase
Default value: n/a
Parent elements:
weblogic-rdbms-jar
and
weblogic-rdbms-jar weblogic-rdbms-bean weblogic-quer 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.
Parent topic: database-type
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 Developing JDBC Applications for Oracle WebLogic Server.
Note:
Prior to WebLogic Server 9.0, this element was data-source-name.
Parent topic: data-source-jndi-name
db-cascade-delete
Range of values: n/a
Default value: 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
Parent topic: weblogic-cmp-jar.xml Deployment Descriptor Reference
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
inejb-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.
Parent topic: db-cascade-delete
Setting up Oracle Database for Cascade Delete
The following Oracle database 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 );
Parent topic: db-cascade-delete
Example
<weblogic-relationship-role> <db-cascade-delete/> </weblogic-relationship-role>
Parent topic: db-cascade-delete
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.
Parent topic: dbms-column
dbms-column-type
Range of values: Blob | Clob | LongString | SybaseBinary
Default value: n/a
Requirements: To specify Blob
or Clob
in this element, you must also set dbms-default-value
to Oracle
or DB2
databases.
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.
-
Blob
—maps the field to an Oracle or DB2 database Blob. -
Clob
—maps the field to an Oracle or DB2 database Clob. -
LongString
—tells the container to usesetCharacterStream
to write String data into the database. Some JDBC drivers have problems writing more than 4K of data usingsetString
. -
SybaseBinary
—tells the container to usesetBytes
to write bytes into the binary column, becausesetBinaryStream
does not work withSybaseXADriver
.
Parent topic: dbms-column-type
Example
<field-map> <cmp-field>photo</cmp-field> <dbms-column>PICTURE</dbms-column> <dbms_column-type>OracleBlob</dbms-column-type> </field-map>
Parent topic: dbms-column-type
dbms-default-value
Range of values: DB2 | Informix| MySQL | Oracle | 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.
Parent topic: dbms-default-value
default-dbms-tables-ddl
Range of values: Valid file name
Default value:
Parent elements:
weblogic-rdbms-jar
Parent topic: weblogic-cmp-jar.xml Deployment Descriptor Reference
Function
Specifies the DDL
file name to which the EJB container writes the table creation scripts.
Parent topic: default-dbms-tables-ddl
delay-database-insert-until
Range of values: ejbCreate | ejbPostCreate
Default value: ejbPostCreate
Requirememts:
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 afterejbCreate.
This setting yields better performance thanejbCreate
by avoiding an unnecessary store operation. -
ejbPostCreate
- perform insert immediately afterejbPostCreate.
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.
Note:
cmr-field
s may not be set during ejbCreate
, before the primary key of the bean is known.
Parent topic: delay-database-insert-until
Example
<delay-database-insert-until>ejbPostCreate</delay-database-insert-until>
Parent topic: delay-database-insert-until
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.
Parent topic: description
Example
<description>Contains a description of parent element</description>
Parent topic: description
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.
Parent topic: disable-string-trimming
Example
<compatibility> <disable-string-trimming>True</disable-string-trimming> </compatibility>
Parent topic: disable-string-trimming
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
.
Parent topic: ejb-name
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.
Parent topic: ejb-ql-query
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.
Parent topic: enable-batch-operations
Example
The following XML sample demonstrates use of the enable-batch-operations
element:
<enable-batch-operations>True</enable-batch-operations>
Parent topic: enable-batch-operations
enable-query-caching
Range of values: True | False
Default value: True
Parent elements:
weblogic-rdbms-jar weblogic-rdbms-bean weblogic-query
or
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.
Parent topic: enable-query-caching
Example
The following XML sample demonstrates use of the enable-query-caching
element:
<enable-query-caching>True</enable-query-caching>
Parent topic: enable-query-caching
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-field
s and cmr-field
s 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.
Parent topic: field-group
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>
Parent topic: field-group
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.
Parent topic: field-map
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>
Parent topic: field-map
finders-return-nulls
Range of values: True | False
Default value: n/a
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
Parent topic: finders-return-nulls
Example
<compatibility>
<finders-return-nulls>True</finders-return-value>
</compatibility>
Parent topic: finders-return-nulls
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.
Parent topic: foreign-key-column
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.
Parent topic: foreign-key-table
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 isOracle
, and WebLogic Server is running in development mode, then the EJB container constructs the Oracle database SEQUENCE name by appending "_WL" to thegenerator-name
as part of the container's automatic SEQUENCE generation feature.For more information on automatic Oracle database SEQUENCE generation, see Support for Oracle Database SEQUENCE.
-
If the
generator-type
element isOracle
, and WebLogic Server is running in production mode, then the EJB container sets the name of the Oracle database SEQUENCE to the value ofgenerator-name
. -
If the
generator-type
element isNamedSequenceTable
, then thegenerator-name
element would be the name of theSEQUENCE_TABLE
to be used.
Parent topic: generator-name
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.
Note:
You must set the database-type element when using automatic-key-generation.
In addition, generator-type
is used in conjunction with automatic Oracle database SEQUENCE generation. See Support for Oracle Database SEQUENCE.
The following databases are supported for each generator-type
:
-
Identity
: Oracle databases are not supported. -
Sequence
: Oracle, DB2, and Informix (version 9.2 and greater) databases are supported. -
SequenceTable
: All databases are supported.
Parent topic: generator-type
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
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.
Parent topic: include-updates
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>
Parent topic: include-updates
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. -
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 whenValueOrder
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 implementjava.lang.Comparabl
e.
Parent topic: 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 database SEQUENCE when automatic SEQUENCE generation is enabled. See Support for Oracle Database SEQUENCE.
If generator-type
is:
-
Oracle
—key-cache-size
must match the Oracle database SEQUENCE INCREMENT value. If there is a mismatch between this value and the Oracle database 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.
Parent topic: key-cache-size
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.
Parent topic: key-column
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.
Parent topic: lock-order
Example
An example of the lock-order
element is:
<lock-order>1</lock-order> <!ELEMENT lock-order (PCDATA)>
Parent topic: lock-order
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.
Parent topic: max-elements
Example
An example of the max-elements
element is shown here:
<max-elements>100</max-elements> <!ELEMENT max-element (PCDATA)>
Parent topic: max-elements
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 cannot be used as a wildcard.
Parent topic: method-name
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.
Parent topic: 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.
Parent topic: method-params
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.
Parent topic: optimistic-column
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.
Parent topic: optimistic-column
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
.
Parent topic: order-database-operations
Example
<order-database-operations>True</order-database-operations>
Parent topic: order-database-operations
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.
Parent topic: pass-through-columns
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.
Parent topic: primary-key-table
Example
For examples, see relationship-role-map and Mapping a Bean on Primary Key Side of a Relationship to Multiple Tables.
Parent topic: primary-key-table
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.
Parent topic: query-method
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).
Parent topic: relation-name
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>
Parent topic: relation-name
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.
Parent topic: 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>
Parent topic: relationship-caching
relationship-role-map
Range of values: n/a
Default value: n/a
Parent elements:
weblogic-rdbms-relation weblogic-relationship-role
- Function
- Example
- Mapping a Bean on Foreign Key Side of a Relationship to Multiple Tables
- Mapping a Bean on Primary Key Side of a Relationship to Multiple Tables
Parent topic: weblogic-cmp-jar.xml Deployment Descriptor Reference
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).
Parent topic: relationship-role-map
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.
Parent topic: relationship-role-map
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 columnsPk_table1_pkColumn_1
andPk_table1_pkColumn_2
and -
Pk_BeanTable_2
with primary key columnsPk_table2_pkColumn_1
andPk_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>
Parent topic: 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).
Parent topic: relationship-role-name
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.
Parent topic: serialize-byte-array-to-oracle-blob
Example
<compatibility> <serialize-byte-array-to-oracle-blob>true</serialize-byte-array-to-oracle-blob> </compatibility>
Parent topic: serialize-byte-array-to-oracle-blob
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
.
Parent topic: serialize-char-array-to-bytes
Example
<compatibility> <serialize-char-array-to-bytes>true</serialize-char-array-to-bytes> </compatibility>
Parent topic: serialize-char-array-to-bytes
sql
Range of values: Valid SQL
Default value: n/a
Requirements: To use database-specific SQL, you must 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.
Parent topic: sql
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>
Parent topic: sql
sql-query
Range of values:
Default value: n/a
Requirements: To use database-specific SQL, you must 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.
Parent topic: sql-query
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>
Parent topic: sql-query
sql-select-distinct
Range of values: True | False
Default value: False
Parent elements:
weblogic-query
Note:
This element is deprecated in this release of WebLogic Server. To achieve the same functionality, use the SELECT DISTINCT
clause directly in finder queries.
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
.
Parent topic: sql-select-distinct
Example
The XML
example contains the element shown here:
<sql-select-distinct>True</sql-select-distinct>
Parent topic: sql-select-distinct
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).
Parent topic: sql-shape
Example
sql-shape description sql-shape-name table pass-through-columns ejb-relation-name
Parent topic: sql-shape
sql-shape-name
Range of values: n/a
Default value: n/a
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
.
Parent topic: sql-shape-name
table-map
Range of values: n/a
Default value: n/a
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-field
s 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 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.
Parent topic: table-map
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>
Parent topic: 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.
Parent topic: table-name
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>
Parent topic: table-name
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
.
Note:
If you set trigger-updates-optimistic-column to True, you must also ensure that your database triggers initialize the version column in the database when the bean is created.
Parent topic: trigger-updates-optimistic-column
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
.
Parent topic: unknown-primary-key-field
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.
Note:
When using a pessimistic locking strategy (for example, HOLDLOCK
) with Sybase JConnect drivers, you must specify SELECT_OPENS_CURSOR=true
to generate a cursor when the query contains a FOR UPDATE
clause.
Parent topic: use-select-for-update
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>
Parent topic: use-select-for-update
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.
Parent topic: validate-db-schema-with
Example
An example of the validate-db-schema-with
element is shown here:
<validate-db-schema-with>TableQuery</validate-db-schema-with>
Parent topic: 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.
Parent topic: 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 ANSIREAD_COMMITTED
andREPEATABLE_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 ofRead
results in additional overhead since it generally increases the amount of optimistic checking the EJB container must perform. With theRead
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 ofSERIALIZABLE
consistency.Note:
If
verify-rows
is set toRead
then theverify-columns e
lement cannot have a value ofModified
, as this combination would result in the EJB container checking only the modified rows.
See Choosing a Concurrency Strategy for more information.
Parent topic: verify-rows
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.
Parent topic: version-column-initial-value
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.
Parent topic: weblogic-ql
weblogic-query
Range of values: n/a
Default value: n/a
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.
Parent topic: weblogic-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>
Parent topic: 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.
Parent topic: weblogic-rdbms-bean
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
Parent topic: weblogic-rdbms-bean
weblogic-rdbms-jar
This section describes and provides an example of the weblogic-rdbms-jar
element.
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.
Parent topic: weblogic-rdbms-jar
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
Parent topic: weblogic-rdbms-jar
weblogic-rdbms-relation
Range of values: n/a
Default value: n/a
Parent elements:
weblogic-rdbms-jar
- Function
- Examples
- Defining a One-to-One Relationship
- Defining a One-to-Many Relationship
- Defining a Many-to-Many Relationship
Parent topic: weblogic-cmp-jar.xml Deployment Descriptor Reference
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 the primary keys of the entities involved in the relationship.
For more information on container managed relationships, see Using Container-Managed Relationships (CMRs).
Parent topic: weblogic-rdbms-relation
Examples
See the following sections for examples of how one-to-one, one-to-many, and many-to-many relationships are configured.
Parent topic: weblogic-rdbms-relation
Defining a One-to-One Relationship
Example C-6 shows the weblogic-rdbms-bean
element that defines a one-to-one relationship between the entities defined in Example C-4 and Example C-5. The weblogic-rdbms-relation
element is in the weblogic-cmp-jar.xml
file, after the weblogic-rdbms-bean
elements.
Note:
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
> element in ejb-jar.xml.
Example C-4 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>
Example C-5 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>
Example C-6 <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>
Parent topic: weblogic-rdbms-relation
Defining a One-to-Many Relationship
Example C-7 contains a sample <weblogic-rdbms-relation>
element that defines a one-to-many relationship:
Note:
<relationship-role-name> contains the relation field specified in <cmr-field
> in the <ejb-relationship-role
> element in ejb-jar.xml.
<foreign-key-column> must specify the column in the table on the "many" side of the relationship.
Example C-7 <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>
Parent topic: weblogic-rdbms-relation
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.
Example C-8 <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 Example C-7, 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.
Parent topic: weblogic-rdbms-relation
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 thefield-group
to be loaded when the bean corresponding to the role is loaded as a result of traversing the relationship, i.e. calling a cmrgetXXX
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).
Parent topic: weblogic-relationship-role
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>
Parent topic: weblogic-relationship-role