weblogic-cmp-jar.xml Deployment Descriptor Reference
The following sections describe the EJB 2.0 deployment descriptor elements found in the weblogic-cmp-jar.xml file, the WebLogic-specific XML document type definitions (DTD) file. Use these definitions to create the WebLogic-specific weblogic-cmp-jar.xml file that is part of your EJB deployment. Use this deployment descriptor file to specify container-managed-persistence (CMP) behavior.
For information on the EJB 1.1 deployment descriptor elements see Important Information for EJB 1.1 Users.
- 2.0 weblogic-cmp-jar.xml Deployment Descriptor File Structure
- 2.0 weblogic-cmp-jar.xml Deployment Descriptor Elements
2.0 weblogic-cmp-jar.xml Deployment Descriptor File Structure
The weblogic-cmp-jar.xml file defines deployment descriptors for a entity EJBs that uses WebLogic Server RDBMS-based persistence services. The EJB container uses a version of weblogic-cmp-jar.xml that is different from the XML shipped with WebLogic Server Version 6.x.
You can continue to use the earlier weblogic-cmp-jar.xml DTD for EJB 1.1 beans that you will deploy on the WebLogic Server Version 8.1. However, if you want to use any of the new CMP 2.0 features, use the new DTD described below.
The top-level element of the WebLogic Server 8.1 weblogic-cmp-jar.xml consists of a weblogic-rdbms-jar stanza:
description
weblogic-version
weblogic-rdbms-jar
weblogic-rdbms-bean
ejb-name
data-source-name
table-map
field-group
relationship-caching
weblogic-query
delay-database-insert-until
automatic-key-generation
check-exists-on-method
weblogic-rdbms-relation
relation-name
table-name
weblogic-relationship-role
create-default-dbms-tables
validate-db-schema-with
database-type
2.0 weblogic-cmp-jar.xml Deployment Descriptor Elements
- allow-readonly-create-and-remove
- automatic-key-generation
- caching-element
- caching-name
- check-exists-on-method
- cmp-field
- cmr-field
- column-map
- create-default-dbms-tables
- database-type
- data-source-name
- db-cascade-delete
- dbms-column
- dbms-column-type
- default-dbms-tables-ddl
- delay-database-insert-until
- description
- ejb-name
- enable-batch-operations
- field-group
- field-map
- foreign-key-column
- foreign-key-table
- generator-name
- generator-type
- group-name
- include-updates
- key-cache-size
- key-column
- lock-order
- max-elements
- method-name
- method-param
- method-params
- optimistic-column
- order-database-operations
- primary-key-table
- query-method
- relation-name
- relationship-caching
- relationship-role-map
- relationship-role-name
- serialize-byte-array-to-oracle-blob
- sql-select-distinct
- table-map
- table-name
- use-select-for-update
- validate-db-schema-with
- verify-columns
- verify-rows
- weblogic-ql
- weblogic-query
- weblogic-rdbms-bean
- weblogic-rdbms-jar
- weblogic-rdbms-relation
- weblogic-relationship-role
allow-readonly-create-and-remove
| Default value: | false |
| Requirements: | Optional |
| Parent elements: |
weblogic-rdbms-jar
compatibility |
Function
This element, introduced in WebLogic Server 8.1 SP02, is a backward compatibility flag. It is used to enable create and remove operations for an EJB that uses ReadOnly concurrency.
Prior to version 8.1 SP2, these operations were allowed, although they had no transactional meaning. They have been disallowed so that more efficient code can be generated for ReadOnly beans, and because using them is a bad practice.
Example
<compatibility>
<allow-readonly-create-and-remove>
true
</allow-readonly-create-and-remove>
</compatibility>
automatic-key-generation
| Default value: | n/a |
| Requirements: | Optional. |
| Parent elements: | weblogic-rdbms-bean |
Function
The automatic-key-generation element specifies the use of the Sequence/Key Generation feature.
Example
The XML stanza can contain the elements shown here:
<automatic-key-generation>
<generator-type>Oracle</generator-type>
<generator-name>test_sequence</generator-name>
<key-cache-size>10</key-cache-size>
</automatic-key-generation>
<automatic-key-generation>
<generator-type>SQL-SERVER</generator-type>
</automatic-key-generation>
<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
|
|
|
| Default value: | n/a |
| Requirements: | n/a |
| Parent elements: |
weblogic-rdbms-jar
weblogic-rdbms-bean relationship-caching |
Function
The caching-element descriptor specifies the container-managed relationship (cmr-field) for the related bean, 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 about group-name, see group-name.
As of WebLogic Server release 7.0 Service Pack 3, the EJB container now allows multiple caching-element sub-elements. The relevant DTD entry is this:
<!ELEMENT caching-element (
cmr-field,
group-name?,
caching-element*
)>
Previously, the DTD entry read this way:
<!ELEMENT caching-element (
cmr-field,
group-name?,
caching-element?
)>
For more information about relationship caching, see Relationship Caching.
Example
See relationship-caching:
caching-name
| Default value: | n/a |
| Requirements: | n/a |
| Parent elements: |
weblogic-rdbms-jar
weblogic-rdbms-bean relationship-caching |
Function
The caching-name element specifies the name of a relationship cache. For more information about relationship caching, see Relationship Caching.
Example
See relationship-caching:
check-exists-on-method
| Range of values: | True | False |
| Default value: | True |
| Requirements: | . |
| Parent elements: | weblogic-rdbms-bean |
Function
By default, the EJB container checks that a container-managed persistence (CMP) entity bean exists before any business method invoked on the bean completes. This means the container notifies an application as soon as any business method is invoked on a container-managed entity bean that has been removed
To specify that the EJB container wait for transaction completion to perform the existence check, set check-exists-on-method to False. This results in high performance and still provides a sufficient level of checking for most applications.
Example
The following example specifies that WebLogic Server notify the application that a business method has been invoked on a CMP entity bean that has been removed.
<check-exists-on-method>True</check-exists-on-method>
cmp-field
| Default value: | n/a |
| Requirements: | Field is case sensitive and must match the name of the field in the bean and must also have a cmp-entry entry in the ejb-jar.xml. |
| Parent elements: |
weblogic-rdbms-bean
field-map weblogic-rdbms-relation field-group |
Function
This name specifies the mapped field in the bean instance which should be populated with information from the database.
Example
See field-map.
cmr-field
| Default value: | n/a |
| Requirements: | The field referenced in cmr-field must have a matching cmr-field entry in the ejb-jar.xml. |
| Parent elements: | weblogic-rdbms-relation field-group |
Function
The cmr-field element specifies the name of a container-managed relationship field (cmr-field.)
Example
The XML stanza can contain the elements shown here:
<weblogic-rdbms-jar>
<weblogic-rdbms-relation>
<field-group>employee</field-group>
<cmp-field>employee stock purchases</cmp-field>
<cmr-field>stock options</cmr-field>
</weblogic-rdbms-relation>
</weblogic-rdbms-jar>
column-map
| Default value: | n/a |
| Requirements: | The key-column element is not specified, if the foreign-key-column refers to a remote bean. |
| Parent elements: |
weblogic-rdbms-bean
weblogic-relationship-role |
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 column belong are implicit from the context in which the column-map element appears in the deployment descriptor.
Example
The XML stanza can contain the elements shown here:
<weblogic-rdbms-jar>
<weblogic-rdbms-bean>
<column-map
<foreign-key-column>account-id</foreign-key-column>
<key-column>id</key-column>
</column-map>
</weblogic-rdbms-bean>
</weblogic-rdbms-jar>
compatibility
| Parent elements: | weblogic-rdbms-jar |
Function
The <compatibility> stanza, introduced in WebLogic Server 8.1 SP02, contains elements that specify compatibility flags for all of the cmp beans described in the descriptor file.
Example
<compatibility>
<serialize-byte-array-to-oracle-blob>
<allow-readonly-create-and-remove>
</compatibility>
create-default-dbms-tables
| Range of values: | Disabled | CreateOnly | DropAndCreate | DropAndCreateAlways |AlterOrCreate |
| Default value: | Disabled |
| Requirements: | Use this element only for convenience during the development and prototyping 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 most likely, will require a more precise schema definition. |
| Parent elements: | weblogic-rdbms-jar |
Function
The create-default-dbms-table element performs two functions:
- It determines whether or how WebLogic Server automatically creates a default table based on the descriptions in the deployment files and the bean class, when underlying table schema have changed.
- It determines whether or how WebLogic Server automatically creates an Oracle SEQUENCE.
Automatic Table Creation
The following table describes how WebLogic Server handles automatic table creation, based on the value of create-default-dbms-tables:
|
Setting
|
Results in this behavior with respect to automatic table creation |
|---|---|
| Disabled | The EJB container takes no action with respect to automatic table creation. This is the default value. |
| CreateOnly |
The EJB container automatically generates the table upon detecting changed schema. The container attempts to create the table based on information found in the deployment files and in the bean class. If table creation fails, a 'Table Not Found' error is thrown, and the user must create the table manually. |
| DropAndCreate |
The EJB container automatically generates the table upon detecting changed schema. The container drops and creates the table during deployment if columns have changed. The container does not save data. |
| DropAndCreateAlways | The EJB container automatically generates the table upon detecting changed schema.The container drops and creates the table during deployment whether or not columns have changed. The container does not save the data. |
| AlterOrCreate |
The EJB container automatically generates the table upon detecting changed schema.The container creates the table if it does not yet exist. If the table does exist, the container alters the table schema. Table data is saved.
Note: Do not choose this setting if a new column is specified as a primary key or if a column with null values is specified as the new primary key column. |
If TABLE CREATION fails, the server throws a Table Not Found error and the table must be created by hand.
Automatic Oracle SEQUENCE Generation
Note: Automatic Oracle SEQUENCE generation works only with servers running in development mode.
The following table describes how WebLogic Server handles automatic SEQUENCE generation, based on the value of create-default-dbms-tables:
|
Setting
|
Results in this behavior: |
|---|---|
| Disabled | The EJB container takes no action with respect to SEQUENCE generation. This is the default value. |
| CreateOnly | The EJB container creates a SEQUENCE, and constructs its name by appending "_WL" to the value of the generator-name element. |
| DropAndCreate | The EJB container creates a SEQUENCE, and constructs its name by appending "_WL" to the value of the generator-name element.If the SEQUENCE's increment value does not match the value of the key-cache-size element, the container alters the increment value to match the value of key-cache-size. |
| DropAndCreateAlways | The EJB container creates a SEQUENCE, and constructs its name by appending "_WL" to the value of the generator-name element.If the SEQUENCE's increment value does not match the value of the key-cache-size element, the container alters the increment value to match the value of key-cache-size. |
| AlterOrCreate | The EJB container creates a SEQUENCE, and constructs its name by appending "_WL" to the value of the generator-name element.If the SEQUENCE's increment value does not match the value of the key-cache-size element, the container alters the increment value to match the value of key-cache-size. |
For more information on automatic generation of an Oracle SEQUENCE, see Support for Oracle SEQUENCE.
Example
The following example specifies the create-default-dbms-tables element.
<create-default-dbms-tables>CreateOnly</create-default-dbms-tables>
database-type
| Range of values: | DB2| Informix| Oracle| SQLServer| Sybase| POINTBASE. |
| Parent elements: | weblogic-rdbms-jar |
Function
The database-type element specifies the database used as the underlying dbms.
Example
The following example specifies the underlying RDBMS.
<database-type>POINTBASE</database-type>
data-source-name
| Requirements: | Must be defined as a standard WebLogic Server JDBC data source for database connectivity. For more information on datasources, see Programming WebLogic JDBC". |
| Parent elements: | weblogic-rdbms-bean |
Function
The data-source-name that specifies the JDBC data source name to be used for all database connectivity for this bean.
Example
See table-name.
db-cascade-delete
| Requirements: |
If db-cascade-delete is specified in weblogic-cmp-rdbms-jar.xml, cascade-delete must be specified in ejb-jar.xml.Only supported for:
|
| 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
The db-cascade-delete element allows an application to take advantage of a database's built-in support for cascade delete, and possibly improve performance.
Note: If db-cascade-delete is not specified, it is important not to enable any of the database's cascade delete functionality, as this will produce incorrect results.
When db-cascade-delete is enabled, the underlying database must be set up for cascade deletes. For example, the following Oracle table definition will delete all of the emp rows if the owning dept is deleted in the database.
Figure 10-1 Oracle table setup for cascade delete
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>
<relationship-role-name>
<group-name> ....</group-name>
<relationship-role-map>...
....
</relationship-role-map>
<db-cascade-delete/>
</weblogic-relationship-role>
dbms-column
| Requirements: | dbms-column is case maintaining, although not all database are case sensitive. |
| Parent elements: |
weblogic-rdbms-bean
field-map |
Function
The name of the database column to which the field should be mapped.
Example
See field-map.
dbms-column-type
| Parent elements: |
weblogic-rdbms-bean
field-map |
Function
The dbms-column-type element maps the current field to a Blob or Clob in an Oracle database or a LongString or SybaseBinary in a Sybase database. This element can be one of the following:
- OracleBlob
- OracleCLob
- LongString
- SybaseBinary
Example
<field-map>
<cmp-field>photo</cmp-field>
<dbms-column>PICTURE</dbms-column>
<dbms_column-type>OracleBlob</dbms-column-type>
</field-map>
default-dbms-tables-ddl
| Parent elements: |
weblogic-rdbms-bean
weblogic-rdbms-relation |
Function
Specifies the DDL file name to which the EJB container writes the table creation scripts.
delay-database-insert-until
Function
Specifies when a new CMP bean is inserted into the database. The allowable values cause the following behavior:
- ejbCreate - perform database insert immediately after ejbCreate
- ejbPostCreate - perform insert immediately after ejbPostCreate
This element has an effect only when order-database-operations is False. By default, order-database-operations is true, which causes new beans to be inserted at the transaction commit time.
If order-database-operations is False, the default setting for delay-database-insert-until causes the bean to be inserted immediately after ejbPostCreate. This setting yields better performance than ejbCreate by avoiding an unnecessary store operation.
Delaying the database insert until after ejbPostCreate is required when a cmr-field is mapped to a foreign-key column that does not allow null values. In this case, the cmr-field must be set to a non-null value in ejbPostCreate before the bean is inserted into the database.
For maximum flexibility, avoid creating related beans in your ejbPostCreate method. If ejbPostCreate creates related beans, and database constraints prevent related beans from referring to a bean that has not yet been created, it is not possible to database insert until after the method completion.
Note: cmr-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
| Parent elements: |
weblogic-rdbms-jar
weblogic-rdbms-bean weblogic-query |
Function
The description element provides text that describes the parent element.
Example
<dscription>Contains a description of parent element</description>
ejb-name
| Requirements: | Must match the ejb-name of the cmp entity bean defined in the ejb-jar.xml. |
| Parent elements: | weblogic-rdbms-bean |
Function
The name that specifies an EJB as defined in the ejb-cmp-rdbms.xml. This name must match the ejb-name of a cmp entity bean contained in the ejb-jar.xml.
Example
See table-name.
enable-batch-operations
| Range of values: | True | False |
| Default value: | True |
| Parent elements: | weblogic-rdbms-bean |
| Deployment file: | weblogic-cmp-jar.xml |
Function
This element, introduced in WebLogic Server 8.1, controls whether or not the EJB container allows batch database operations, including batch inserts, batch updates and batch deletes.
If this element is set to True, the EJB delays database operations in a transaction until commit time.
Note: In WebLogic Server 8.1, this element replaces the functionality of the commit setting, available in WebLogic Server 7.0, for the delay-database-insert-until element.
Example
The following XML sample demonstrates use of the enable-batch-operations element:
<enable-batch-operations>True</enable-batch-operations>
field-group
| Default value: | A special group named default is used for finders and relationships that have no group specified. |
| Requirements: | The default group contains all of a bean's cmp-fields, but none of its cmr-fields. |
| Parent elements: | weblogic-rdbms-relation |
Function
The field-group element represents a subset of the cmp-fields and cmr-fields of a bean. Related fields in a bean can be put into groups that are faulted into memory together as a unit. A group can be associated with a finder or relationship, so that when a bean is loaded as the result of executing a finder or following a relationship, only the fields specified in the group are loaded.
A field may belong to multiple groups. In this case, the getXXX method for the field faults in the first group that contains the field.
Example
The XML stanza can contain the elements shown here:
<weblogic-rdbms-bean>
<ejb-name>XXXBean</ejb-name>
<field-group>
<group-name>medical-data</group-name>
<cmp-field>insurance</cmp-field>
<cmr-field>doctors</cmr-fields>
</field-group>
</weblogic-rdbms-bean>
field-map
| Default value: | n/a |
| Requirements: | Field mapped to the column in the database must correspond to a cmp field in the bean. |
| Parent elements: | weblogic-rdbms-bean |
Function
The name of the mapped field for a particular column in a database that corresponds to a cmp field in the bean instance.
Example
The XML stanza can contain the elements shown here:
<weblogic-rdbms-jar>
<weblogic-rdbms-bean>
<field-map>
<cmp-field>accountId</cmp-field>
<dbms-column>id</dbms-column>
</field-map>
<field-map>
<cmp-field>balance</cmp-field>
<dbms-column>bal</dbms-column>
</field-map>
<field-map>
<cmp-field>accountType</cmp-field>
<dbms-column>type</dbms-column>
</field-map>
</weblogic-rdbms-bean>
</weblogic-rdbms-jar>
foreign-key-column
| Requirements: | Must correspond to a column of a foreign key. |
| 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
| 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
generator-name
| Parent elements: |
weblogic-rdbms-bean
automatic-key-generation |
Function
The generator-name element is used to specify the name of the generator.
- If the generator-type element is Oracle, and WebLogic Server is running in development mode, then the EJB container constructs the Oracle SEQUENCE name by appending "_WL" to the generator-name as part of the container's automatic SEQUENCE generation feature.
For more information on automatic Oracle SEQUENCE generation, see Support for Oracle SEQUENCE.
- If the generator-type element is Oracle, and WebLogic Server is running in production mode, then the EJB container sets the name of the Oracle SEQUENCE to the value of generator-name.
- If the generator-type element is NamedSequenceTable, then the generator-name element would be the name of the SEQUENCE_TABLE to be used.
Example
generator-type
| Parent elements: |
weblogic-rdbms-bean
automatic-key-generation |
Function
The generator-type element specifies the key generation method to use. The options include:
- Oracle
- SQLServer
- NamedSequenceTable
In addition, generator type is used in conjunction with automatic Oracle SEQUENCE generation. See Support for Oracle SEQUENCE.
Example
group-name
| Parent elements: |
weblogic-rdbms-relation field-group
weblogic-rdbms-bean finder finder-query |
Function
The group-name element specifies the name of a field group.
Example
The XML stanza can contain the elements shown here:
<weblogic-rdbms-jar>
<weblogic-rdbms-relation>
<field-group>employee</field-group>
<cmp-field>employee stock purchases</cmp-field>
<cmr-field>stock options</cmr-field>
<group-name>financial data</group-name>
</weblogic-rdbms-relation>
</weblogic-rdbms-jar>
include-updates
| Range of values: | True | False |
| Default value: | True |
| Requirements: | The default value, which is False, provides the best performance. |
| Parent elements: |
weblogic-rdbms-bean
weblogic-query |
Function
The include-updates element specifies that 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.
The default value is False for beans that use optimistic concurrency. The default value is True for beans that use other concurrency types, such as database, or exclusive.
Example
The XML stanza can contain the elements shown here:
<include-updates>False</include-updates>
key-cache-size
| Default value: | 1 |
| Requirements: | Optional |
| Parent elements: |
weblogic-rdbms-bean
automatic-key-generation |
Function
The key-cache-size element 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.
Example
key-column
| Requirements: | Must correspond to a column of a primary key. |
| Parent elements: |
weblogic-rdbms-bean
column-map |
Function
The key-column element represents a column of a primary key in the database.
Example
See column-map.
lock-order
| Range of values: | All positive integers. |
| Default value: | 0 |
| Parent elements: | weblogic-rdbms-bean |
Function
Use this flag to specify the database locking order of an entity bean when a transaction involves multiple beans and exclusive concurrency. The bean with lowest number is locked first.
This flag should only be used to prevent a deadlock situation and, currently, only applies when a transaction performs cascade deletes.This flag is only used for cascade delete currently.
Example
The XML stanza can contain the elements shown here:
<lock-order>1</lock-order>
<!ELEMENT lock-order (PCDATA)>
max-elements
| Parent elements: |
weblogic-rdbms-bean
weblogic-query |
Function
max-elements specifies the maximum number of elements that should be returned by a multi-valued query. This element is similar to the maxRows feature in JDBC.
Example
The XML stanza can contain the elements shown here:
<max-elements>100</max-elements>
<!ELEMENT max-element (PCDATA)>
method-name
| Requirements: | The `*' character may not be used as a wildcard. |
| Parent elements: |
weblogic-rdbms-bean
query-method |
Function
The method-name element specifies the name of a finder or ejbSelect method.
Example
See weblogic-query.
method-param
| Parent elements: |
weblogic-rdbms-bean
method-params |
Function
The method-param element contains the fully qualified Java type name of a method parameter.
Example
The XML stanza can contain the elements shown here:
<method-param>java.lang.String</method-param>
method-params
| 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
| Requirements: | Although not all databases are case sensitive, this element is case maintaining. |
| Parent elements: |
weblogic-rdbms-bean
table-map |
| Deployment file: | weblogic-cmp-jar.xml |
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.
Example
The following sample XML shows the use of the optimistic-column element.
<optimistic-column>ROW_VERSION</optimistic-column>
where ROW_VERSION is the name of a database column that contains the value used for concurrency checking.
order-database-operations
| Range of values: | True | False |
| Default value: | True |
| Parent elements: | weblogic-rdbms-bean |
Function
This element, introduced in WebLogic Server 8.1, determines whether the EJB container delays all database operations in a transaction until commit time, automatically sorts the database dependency between the operations, and sends these operations to the database in such a way to avoid any database constraint errors.
If enable-batch-operations is set to True, the container automatically sets order-database-operations to True. To turn off order-database-operations, set both order-database-operations and enable-batch-operations to False.
See also enable-batch-operations and delay-database-insert-until.
Example
The following sample XML demonstrates the use of the order-database-operations element.
<order-database-operations>True</order-database-operations>
primary-key-table
| Requirements: | Although not all databases are case sensitive, this element is case maintaining. |
| 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.
Example
For examples, see relationship-role-map.
query-method
| Parent elements: | weblogic-rdbms-bean |
Function
The query-method element 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
| Requirements: | 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 |
| Parent elements: | weblogic-rdbms-relation |
Function
The relation-name element specifies the name of a relation.
Example
The XML stanza can contain the elements shown here:
<weblogic-rdbms-jar>
<weblogic-rdbms-relation>
<relation-name>stocks-holders</relation-name>
<table-name>stocks</table-name>
</weblogic-rdbms-relation>
</weblogic-rdbms-jar>
relationship-caching
| Parent elements: |
weblogic-rdbms-jar
weblogic-rdbms-bean |
Function
The relation-caching element specifies relationship caching. For more information about relationship caching, see Relationship Caching.
Example
The XML stanza can contain the elements shown here:
<relationship-caching>
<caching-name>cacheMoreBeans</caching-name>
<caching-element>
<cmr-field>accounts<</cmr-field>
<group-name>acct_group</group-name>
<caching-element>
<cmr-field>address</cmr-field>
<group-name>addr_group</group-name>
</caching-element>
</caching-element>
<caching-element>
<cmr-field>phone</cmr-field>
<group-name>phone_group</group-name>
</caching-element>
</relationship-caching>
relationship-role-map
| Requirements: |
|
| 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 1-1 or 1-m 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 1-1 or 1-m 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 may be omitted since the tables being used are implicit.
Example
Mapping a Bean on Foreign Key Side of a Relationship to Multiple Tables
The bean on the foreign-key side of a 1-1 relationship, Fk_Bean, is mapped to multiple tables. The table that holds the foreign-key columns must be specified by 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> must be specified above, 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 1-1 relationship, Pk_bean, is mapped to multiple tables, but the bean on the foreign-key side of the relationship, Fk_Bean, is mapped to one table, Fk_BeanTable. The foreign-key columns are named Fk_column_1 and Fk_column_2.
Pk_bean, is mapped to tables: Pk_BeanTable_1 with primary-key columns: Pk_table1_pkColumn_1 and Pk_table1_pkColumn_2 and Pk_BeanTable_2 with primary-key columns: Pk_table2_pkColumn_1 and Pk_table2_pkColumn_2.
<relationship-role-map>
<primary-key-table>Pk_BeanTable_1</primary-key-table>
<column-map>
<foreign-key-column>Fk_column_1</foreign-key-column>
<key-column>Pk_table1_pkColumn_1</key-column>
</column-map>
<column-map>
<foreign-key-column>Fk_column_2</foreign-key-column>
<key-column>Pk_table1_pkColumn_2</key-column>
</column-map>
</relationship-role-map>
relationship-role-name
| Requirements: | The name must match the ejb-relationship-role-name of an ejb-relationship-role in the associated ejb-jar.xml descriptor file. |
| Parent elements: |
weblogic-rdbms-relation
weblogic-relationship-role |
Function
The relationship-role-name element specifies the name of a relationship role.
Example
See the examples for weblogic-relationship-role
serialize-byte-array-to-oracle-blob
| Requirements: | Optional. |
| Parent elements: |
weblogic-rdbms-jar
compatibility |
Function
This element, introduced in WebLogic Server 8.1 SP02, is a compatibility flag. It is used to specify whether a cmp-field of type byte[] mapped to a OracleBlob should be serialized. By default, the value of the tag is false, which means that the container will persist the byte[] directly and not serialize it.
In versions prior to WebLogic Server 8.1 SP02, the default behavior was to serialize a cmp-field of type byte[] mapped to an OracleBlob. To revert to the old behavior, set the value of serialize-byte-array-to-oracle-blob to true.
Example
<compatibility>
<serialize-byte-array-to-oracle-blob>
true
</serialize-byte-array-to-oracle-blob>
</compatibility>
sql-select-distinct
Note: This element is deprecated. To achieve the same functionality, use the SELECT DISTINCT clause directly in finder queries
| Range of values: | True | False |
| Default value: | False |
| Requirements: | The Oracle database does not allow you to use a SELECT DISTINCT in conjunction 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 a transaction-isolation element set to the isolation-level sub element with a value of TransactionReadCommittedForUpdate. You specify the transaction-isolation element in the weblogic-ejb-jar.xml file. |
| Parent elements: | weblogic-query |
Function
The sql-select-distinct element controls whether the generated SQL SELECT statement will contain a a DISTINCT qualifier. Using the DISTINCT qualifier caused the database to return unique rows.
Example
The XML example contains the element shown here:
<sql-select-distinct>True</sql-select-distinct>
table-map
| Requirements: | Each table-map element must contain a mapping for the bean's primary key fields. |
| Parent elements: | weblogic-rdbms-bean |
Function
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 n DBMS tables, then specify n table-map elements for the bean, one for each n DBMS table.
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.
Example
The XML stanza can contain the elements shown here:
<table-map>
<table-nme>DeptTable</table-name>
<field-map>
<cmp-field>deptId1</cmp-field>
<dbms-column>t1_deptId1_column</dbms-column>
</field-map>
<field-map>
<cmp-field>deptId2</cmp-field>
<dbms-column>t1_deptId2_column</dbms-column>
</field-map>
<field-map>
<cmp-field>location</cmp-field>
<dbms-column>location_column</dbms-column>
</field-map>
<cmp-field>budget</cmp-field>
<dbms-column>budget</dbms-column>
</field-map>
<fieldmap
</table-map>
table-name
| Range of values: | Valid, fully qualified SQL name of the source table in the database. |
| Requirements: | table-name must be set in all cases. |
| Parent elements: |
weblogic-rdbms-bean
weblogic-rdbms-relation |
Function
The fully qualified SQL name of the table. The user defined for the data-source for this bean must have read and write privileges for this table, but does not necessarily need schema modification privileges.
Example
<weblogic-rdbms-jar>
<weblogic-rdbms-bean>
<ejb-name>containerManaged</ejb-name>
<data-source-name>examples-dataSource-demoPool</data-source-name>
<table-name>ejbAccounts</table-name>
</weblogic-rdbms-bean>
</weblogic-rdbms-jar>
use-select-for-update
| Range of values: | True | False |
| Default value: | False |
| Parent elements: | weblogic-rdbms-bean |
Function
Enforces pessimistic concurrency on a per-bean basis. Specifying True causes SELECT ... FOR UPDATE to be used whenever the bean is loaded from the database. This is different from the transaction isolation level of TransactionReadCommittedForUpdate in that this is set at the bean level rather than the transaction level.
Example
<weblogic-rdbms.jar>
<weblogic-rdbms-bean>
ejb-name>containerManaged</ejb-name>
<use-select-for-update>True</use-select-for-update>
</weblogic-rdbms-bean>
</weblogic-rdbms-jar>
validate-db-schema-with
| Range of values: | MetaData | TableQuery |
| Default value: | TableQuery |
| Parent elements: | weblogic-rdbms-jar |
Function
The validate-db-schema-with element specifies that container-managed persistence checks that beans have been mapped to a valid database schema during deployment.
If you specify MetaData WebLogic Server uses the JDBC metadata to validate the schema.
If you specify TableQuery, the default setting, WebLogic Server queries the tables directly to verify that they have the schema expected by CMP runtime.
Example
The XML stanza can contain the elements shown here:
<validate-db-schema-with>TableQuery</validate-db-schema-with>
verify-columns
| Range of values: | Read | Modified | Version | Timestamp |
| Default value: | none |
| Requirements: | table-name must be set in all cases. |
| Parent elements: |
weblogic-rdbms-bean
table-map |
Function
The verify-columns element specifies the columns in a table that you want WebLogic Server to check for validity when you use the optimistic concurrency strategy. WebLogic Server checks columns at the end of a transaction, before committing it to the database, to make sure that no other transaction has modified the data.
See Choosing a Concurrency Strategy for more information.
Example
<verify-columns>Modified</verify-columns>
verify-rows
| Range of values: | Read | Modified |
| Default value: | Modified |
| Requirements: | table-name must be set in all cases. |
| Parent elements: |
weblogic-rdbms-bean
table-map |
Function
The verify-rows element specifies the rows in a table that the EJB container should check when optimistic concurrency is used.
- Modified - only rows that are updated or deleted by a transaction are checked. This value ensures that two transactions do not update the same row concurrently, resulting in a lost update, but allows reads and updates of different transactions to be interleaved. This results in a level of consistency that falls between the ANSI READ_COMMITTED and REPEATABLE_READ levels of consistency.
- Read - specifies that any row that is read by the transaction should be checked. This includes both rows that are simply read and rows that are read and then updated or deleted by the transaction. Specifying a value of Read results in additional overhead since it generally increases the amount of optimistic checking the EJB container must perform. With the Read option, committed transactions read a set of rows that are guaranteed not to be modified by another transaction until after the transaction commits.This results in a high level of consistency which is very close to the ANSI definition of SERIALIZABLE consistency.
Note: If verify-rows is set to Read then the verify-columns element may not have a value of Modified, as this combination would result in the EJB container checking only the modified rows.
See Choosing a Concurrency Strategy for more information.
Example
<verify-rows>Modified</verify-rows>
weblogic-ql
| 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
| Parent elements: | weblogic-rdbms-bean |
Function
The weblogic-query element allows you to associate WebLogic specific attributes with a query, as necessary. For example, weblogic-query can be used to specify a query that contains a WebLogic specific extension to EJB-QL. Queries that do not take advantage of WebLogic extensions to EJB-QL should be specified in the ejb-jar.xml deployment descriptor.
Also, the weblogic-query element is used to associate a field-group with the query if the query retrieves an entity bean that should be pre-loaded into the cache by the query.
Example
The XML stanza can contain the elements shown here:
<weblogic-query>
<query-method>
<method-name>findBigAccounts</method-name>
<method-params>
<method-param>double</method-param>
</method-params>
<query-method>
<weblogic-ql>WHERE BALANCE>10000 ORDERBY NAME</weblogic-ql>
</weblogic-query>
weblogic-rdbms-bean
| Parent elements: | weblogic-rdbms-jar |
Function
The weblogic-rdbms-bean specifies an entity bean that is managed by the WebLogic RDBMS CMP persistence type.
Example
weblogic-rdbms-bean
ejb-name
data-source-name
table-map
field-group
relationship-caching
weblogic-query
dalay-database-insert-until
automatic-key-generation
check-exists-on-method
weblogic-rdbms-jar
Function
The weblogic-rdbms-jar element is the root level element of a WebLogic RDBMS CMP deployment descriptor. This element contains the deployment information for one or more entity beans and an optional set of relations.
Example
The XML structure of weblogic-rdbms-jar is:
weblogic-rdbms-jar
weblogic-rdbms-bean
weblogic-rdbms-relation
create-default-dbms-tables
validate-db-schema-with
database-type
weblogic-rdbms-relation
| Parent elements: | weblogic-rdbms-jar |
Function
The weblogic-rdbms-relation element represents a single relationship that is managed by the WebLogic CMP persistence type. deployment descriptor. WebLogic Server supports the following three relationship mappings:
- For one-to-one relationships, the mapping is from a foreign key in one bean to the primary key of the other bean.
- For one-to-many relationships, the mapping is also from a foreign key in one bean to the primary key of another bean.
- For many-to-many relationships, the mapping involves a join table. Each row in the join table contains two foreign keys that map to he primary keys of the entities involved in the relationship.
For more information on container managed relationships, see Using Container Managed Relationships.
Examples
See the sections that following for examples of how one-to-one, one-to-many, and many-to-many relationships are configured.
Defining a One-to-One Relationship
Figure 10-4 shows the weblogic-rdbms-bean stanza that defines a one-to-one relationship between the entities defined in Figure 10-2 and Figure 10-3. The weblogic-rdbms-relation stanza is in the weblogic-cmp-jar.xml file, after the weblogic-rdbms-bean stanzas.
<weblogic-rdbms-bean>
<ejb-name>CountryEJB</ejb-name>
<data-source-name>wlsd21-datasource</data-source-name>
<table-map>
<table-name>EXAMPLE07_COUNTRY</table-name>
<field-map>
<cmp-field>name</cmp-field>
<dbms-column>NAME</dbms-column>
</field-map>
<field-map>
<cmp-field>continent</cmp-field>
<dbms-column>CONTINENT</dbms-column>
</field-map>
</table-map>
</weblogic-rdbms-bean>
<weblogic-rdbms-bean>
<ejb-name>CapitalEJB</ejb-name>
<data-source-name>wlsd21-datasource</data-source-name>
<table-map>
<table-name>EXAMPLE07_CAPITAL</table-name>
<field-map>
<cmp-field>CAPITAL_NAME</cmp-field>
<dbms-column>NAME</dbms-column>
</field-map>
<field-map>
<cmp-field>continent</cmp-field>
<dbms-column>CONTINENT</dbms-column>
</field-map>
</table-map>
</weblogic-rdbms-bean>
Figure 10-4 <weblogic-rdbms-relation> Stanza for a One-to-One Relationship
<weblogic-rdbms-relation>
<relation-name>CountryCapitalRel</relation-name>
<weblogic-relationship-role>
<relationship-role-name>CountryRole</relationship-role-name>
<relationship-role-map>
<column-map>
<foreign-key-column>CAPITAL_NAME</foreign-key-column>
<key-column>NAME</key-column>
</column-map>
</relationship-role-map>
</weblogic-relationship-role>
</weblogic-rdbms-relation>
Note: CAPITAL_NAME is the column name for the foreign key in the Country table.
NAME is the column name for the primary key located in the Capital table
<relationship-role-name> contains the relation field specified in <cmr-field> in the <ejb-relationship-role> stanza in ejb-jar.xml.
Defining a One-to-Many Relationship
Figure 10-5 contains a sample <weblogic-rdbms-relation> stanza that defines a one-to-many relationship:
Figure 10-5 <weblogic-rdbms-relation> Stanza for a One-to-Many Relationship
<weblogic-rdbms-relation>
<relation-name>OwnerDogRel</relation-name>
<weblogic-relationship-role>
<relationship-role-name>DogRole</relationship-role-name>
<relationship-role-map>
<column-map>
<foreign-key-column>OWNER_NAME</foreign-<key-column>
<key-column>NAME</key-column>
</column-map>
<relationship-role-map>
</weblogic-relationship-role>
</weblogic-rdbms-relation>
Note: <relationship-role-name> contains the relation field specified in <cmr-field> in the <ejb-relationship-role> stanza in ejb-jar.xml.
<foreign-key-column> must specify the column in the table on the "many" side of the relationship.
Defining a Many-to-Many Relationship
A WebLogic Server many-to-many relationship involves the physical mapping of a join table. Each row in the join table contains two foreign keys that maps to the primary keys of the entities involved in the relationship.
The following example shows a many-to-many relationship between the FRIENDS bean and the EMPLOYEES bean.
Figure 10-6 <weblogic-rdbms-relation> Stanza for a Many-to-Many Relationship
<weblogic-rdbms-relation>
<relation-name>friends</relation-name>
<table-name>FRIENDS</table-name>
<weblogic-relationship-role>
<relationship-role-name>friend</relationship-role-name>
<relationship-role-map>
<column-map>
<foreign-key-column>first-friend-id</foreign-key-column>
<key-column>id</key-column>
</column-map
</relationship-role-map>
</weblogic-relationship-role>
<weblogic-relationship-role>
<relationship-role-name>second-friend</relationship-role-name>
<relationship-role-map>
<column-map>
<foreign-key-column>second-friend-id</foreign-key-column>
<key-column>id</key-column>
</column-map>
</relationship-role-map>
</weblogic-relationship-role>
</weblogic-rdbms-relation>
In Figure 10-5, the FRIENDS join table has two columns, called first-friend-id and second-friend-id. Each column contains a foreign key that designates a particular employee who is a friend of another employee. The primary key column (key-column) of the EMPLOYEES table is id. For this example, assume that the EMPLOYEES bean is mapped to a single table. If the EMPLOYEES bean is mapped to multiple tables, then the table containing the primary key column (key-column) must be specified in the relationship-role-map. For more information, see relationship-role-map.
weblogic-relationship-role
| Range of values: | Valid name |
| Parent elements: |
weblogic-rdbms-jar
weblogic-rdbms-relation |
Function
The weblogic-relationship-role element specifies the following DBMS schema information for an ejb-relationship-role specified in ejb-jar.xml:
- The relationship-role-map sub-element specifies the mapping between a foreign key and a primary key, for one side of a relationship. For a 1-1 or 1-n relationship, only the role on the foreign-key side of the relationship specifies a mapping. Both roles specify a mapping for a m-m relationship. For details and examples, see relationship-role-map.
- A group-name can be used to indicate the field-group to be loaded when the bean corresponding to the role is loaded as a result of traversing the relationship, i.e. calling a cmr getXXX method.
- The db-cascade-delete tag can to used to specify that cascade deletes use the built-in cascade delete facilities of the underlying DBMS. For more information, see db-cascade-delete.
Example
</weblogic-relationship-role>
<relationship-role-name>
<group-name> ....</group-name>
<relationship-role-map>...
....
</relationship-role-map>
<db-cascade-delete>>
</weblogic-relationship-role>
|
|
|