The weblogic-cmp-rdbms-
jar.xml Deployment Descriptor

The following sections describe the EJB 2.0 deployment descriptor elements found in the weblogic-cmp-rdbms-jar.xml file, the weblogic-specific XML document type definitions (DTD) file. Use these definitions to create the WebLogic-specific weblogic-cmp-rdbms-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-rdbms-jar.xml Deployment Descriptor File Structure

The weblogic-cmp-rdbms-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-rdbms-jar.xml that is different from the XML shipped with WebLogic Server Version 6.x.

You can continue to use the earlier weblogic-cmp-rdbms-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-rdbms-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-rdbms-jar.xml Deployment Descriptor Elements

 

 

automatic-key-generation

Range of values: n/a
Default value: n/a
Requirements: Optional.
Parent elements: weblogic-rdbms-bean
Deployment file: weblogic-cmp-rdbms-jar.xml

 

 

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

Range of values: n/a
Default value: n/a
Requirements: n/a
Parent elements: weblogic-rdbms-jar
         weblogic-rdbms-bean
                   relationship-caching
Deployment file: weblogic-cmp-rdbms-jar.xml

 

 

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.

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? 



)>

 

 

Example

 

 

caching-name

Range of values: Valid name
Default value: n/a
Requirements: n/a
Parent elements: weblogic-rdbms-jar
         weblogic-rdbms-bean
                   relationship-caching
Deployment file: weblogic-cmp-rdbms-jar.xml

 

 

Function

The caching-name element specifies the name of a relationship cache.

 

 

Example

 

 

check-exists-on-method

Range of values: True | False
Default value: True
Requirements: .
Parent elements: weblogic-rdbms-bean
Deployment file: weblogic-cmp-rdbms-jar.xml

 

 

Function

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

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

 

 

Example

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


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

 

 

cmp-field

Range of values: Valid name
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
Deployment file: weblogic-cmp-rdbms-jar.xml

 

 

Function

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

 

 

Example

 

 

cmr-field

Range of values: Valid name
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
Deployment file: weblogic-cmp-rdbms-jar.xml

 

 

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

Range of values: n/a.
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
Deployment file: weblogic-cmp-rdbms-jar.xml

 

 

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>

 

 

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
Deployment file: weblogic-cmp-rdbms-jar.xml

 

 

Function

The create-default-dbms-table element enables or disables a feature that automatically creates a default table based on the descriptions in the deployment files and the bean class, when underlying table schema have changed.

When set to Disabled, this feature is turned off and the EJB container takes no action when table schema change.

When set to CreateOnly, DropAndCreate, DropAndCreateAlways or AlterOrCreate, this feature is turned on and the EJB container automatically generates the table upon detecting changed schema; the specific value for create-default-dbms-table determines whether and how, during deployment, the EJB container drops and recreates tables whose underlying schema has changed. This is described in the following bulleted sections:

  • When set to CreateOnly, 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.
  • When set to DropAndCreate, the container drops and creates the table during deployment if columns have changed. The container does not save data.
  • When set to DropAndCreateAlways, the container drops and creates the table during deployment whether or not columns have changed. The container does not save the data.
  • When set to AlterOrCreate, 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.

Warning: 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.

 

 

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.
Default value: NA
Requirements: NA.
Parent elements: weblogic-rdbms-jar
Deployment file: weblogic-cmp-rdbms-jar.xml

 

 

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

Range of values: Valid name of the data source used for all data base connectivity for this bean.
Default value: n/a
Requirements: Must be defined as a standard WebLogic Server JDBC data source for database connectivity.
Parent elements: weblogic-rdbms-bean
Deployment file: weblogic-cmp-rdbms-jar.xml

 

 

Function

The data-source-name that specifies the JDBC data source name to be used for all database connectivity for this bean.

 

 

Example

 

 

db-cascade-delete

Range of values:
Default value: n/a
Requirements: Only supported for Oracle database. Can only be specified for one-to-one or one-to-many relationships.
Parent elements: weblogic-rdbms-bean
         weblogic-relationship-role
Deployment file: weblogic-cmp-rdbms-jar.xml

 

 

Function

The db-cascade-delete element specifies whether the database cascade feature is turned on. If this element is not specified, WebLogic Server assumes that database cascade delete is not specified.

 

 

Example

 

 

dbms-column

Range of values: Valid name
Default value: n/a
Requirements: dbms-column is case maintaining, although not all database are case sensitive.
Parent elements: weblogic-rdbms-bean
         field-map
Deployment file: weblogic-cmp-rdbms-jar.xml

 

 

Function

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

 

 

Example

 

 

dbms-column-type

Range of values: Valid name
Default value: n/a
Requirements:
Parent elements: weblogic-rdbms-bean
         field-map
Deployment file: weblogic-cmp-rdbms-jar.xml

 

 

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

Range of values: Valid name
Default value: n/a
Requirements: n/a
Parent elements: weblogic-rdbms-bean
         weblogic-rdbms-relation
Deployment file: weblogic-cmp-rdbms-jar.xml

 

 

Function

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

 

 

 

 

delay-database-insert-until

Range of values: ejbCreate | ejbPostCreate | commit
Default value: ejbPostCreate
Requirements: Database insert is delayed until after ejbPostCreate 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. The cmr-fields may not be set during ejbCreate, before the primary key of the bean is known.
Parent elements: weblogic-rdbms-bean
Deployment file: weblogic-cmp-rdbms-jar.xml

 

 

Function

The delay-database-insert-until element specifies the precise time when a new bean that uses RDBMS CMP is inserted into the database.

It is advisable to delay the database insert until after the ejbPostCreate method modifies the persistent fields of the bean. This can yield better performance by avoiding an unnecessary store operation.

For maximum flexibility, you should avoid creating related beans in your ejbPostCreate method. This may make delaying the database insert impossible if database constraints prevent related beans from referring to a bean that has not yet been created.

 

 

Example

The following example specifies the delay-database-insert-until element. 


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

 

 

description

Range of values: n/a
Default value: n/a
Requirements: n/a
Parent elements: weblogic-rdbms-jar
         weblogic-rdbms-bean
                   weblogic-query
Deployment file: weblogic-cmp-rdbms-jar.xml

 

 

Function

The description element is used to provide text that describes the parent element.

 

 

Example

The following example specifies the description element. 


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

 

 

ejb-name

Range of values: Valid name of an EJB.
Default value: n/a
Requirements: Must match the ejb-name of the cmp entity bean defined in the ejb-jar.xml.
Parent elements: weblogic-rdbms-bean
Deployment file: weblogic-cmp-rdbms-jar.xml

 

 

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

 

 

enable-batch-operations

Range of values: True | False
Default value: True
Requirements: n/a
Parent elements: weblogic-rdbms-bean
Deployment file: weblogic-cmp-rdbms-jar.xml

 

 

Function

This element allows or disallows the EJB container to perform batch operations, including batch inserts, batch updates and batch deletes.

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

 

 

Example

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

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

 

 

field-group

Range of values: Valid name
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
Deployment file: weblogic-cmp-rdbms-jar.xml

 

 

Function

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

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

 

 

Example

The XML stanza can contain the elements shown here: 


<weblogic-rdbms-bean>



 <ejb-name>XXXBean</ejb-name>



 <field-group>


<group-name>medical-data</group-name>


<cmp-field>insurance</cmp-field>


<cmr-field>doctors</cmr-fields>



 </field-group>



</weblogic-rdbms-bean>

 

 

field-map

Range of values: Valid name
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
Deployment file: weblogic-cmp-rdbms-jar.xml

 

 

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

Range of values: Valid name
Default value: n/a
Requirements: Must correspond to a column of a foreign key.
Parent elements: weblogic-rdbms-bean
         column-map
Deployment file: weblogic-cmp-rdbms-jar.xml

 

 

Function

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

 

 

Example

 

 

foreign-key-table

Range of values: Valid name
Default value: n/a
Requirements: n/a
Parent elements: weblogic-rdbms-jar
         weblogic-rdbms-relation
                   weblogic-relationship-role
                             relationship-role-map
Deployment file: weblogic-cmp-rdbms-jar.xml

 

 

Function

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

 

 

Example

 

 

generator-name

Range of values: n/a
Default value: n/a
Requirements: Optional.
Parent elements: weblogic-rdbms-bean
         automatic-key-generation
Deployment file: weblogic-cmp-rdbms-jar.xml

 

 

Function

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

For example;

  • If the generator-type element is Oracle, then the generator-name element would be the name of the ORACLE_SEQUENCE to be used.
  • 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

Range of values: n/a
Default value: n/a
Requirements: Optional
Parent elements: weblogic-rdbms-bean
         automatic-key-generation
Deployment file: weblogic-cmp-rdbms-jar.xml

 

 

Function

The generator-type element specifies the key generation method to use. The options include:

  • Oracle
  • SQLServer
  • NamedSequenceTable

 

 

Example

 

 

group-name

Range of values: Valid name
Default value: n/a
Requirements: n/a
Parent elements: weblogic-rdbms-relation          field-group weblogic-rdbms-bean          finder                    finder-query
Deployment file: weblogic-cmp-rdbms-jar.xml

 

 

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
Deployment file: weblogic-cmp-rdbms-jar.xml

 

 

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

Range of values: n/a
Default value: 1
Requirements: Optional
Parent elements: weblogic-rdbms-bean
         automatic-key-generation
Deployment file: weblogic-cmp-rdbms-jar.xml

 

 

Function

The key-cache-size element specifies the optional size of the primary key cache available in the automatic primary key generation feature.

 

 

Example

 

 

key-column

Range of values: Valid name
Default value: n/a
Requirements: Must correspond to a column of a primary key.
Parent elements: weblogic-rdbms-bean
         column-map
Deployment file: weblogic-cmp-rdbms-jar.xml

 

 

Function

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

 

 

Example

 

 

lock-order

Range of values: All positive integers.
Default value: 0
Requirements: n/a
Parent elements: weblogic-rdbms-bean
Deployment file: weblogic-cmp-rdbms-jar.xml

 

 

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 applices when a transaction performs cascade deletes.This flag is only used for cascade delete currently.

 

 

Example

The XML stanza can contain the elements shown here: 


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


         <!ELEMENT lock-order  (PCDATA)>

 

 

max-elements

Range of values: n/a
Default value: n/a
Requirements: n/a
Parent elements: weblogic-rdbms-bean          weblogic-query
Deployment file: weblogic-cmp-rdbms-jar.xml

 

 

Function

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

 

 

Example

The XML stanza can contain the elements shown here: 


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


         <!ELEMENT max-element (PCDATA)>

 

 

method-name

Range of values: n/a
Default value: n/a
Requirements: The `*' character may not be used as a wildcard.
Parent elements: weblogic-rdbms-bean          query-method
Deployment file: weblogic-cmp-rdbms-jar.xml

 

 

Function

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

 

 

Example

 

 

method-param

Range of values: Valid name
Default value: n/a
Requirements: n/a
Parent elements: weblogic-rdbms-bean          method-params
Deployment file: weblogic-cmp-rdbms-jar.xml

 

 

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

Range of values: list of valid names
Default value: n/a
Requirements: n/a
Parent elements: weblogic-rdbms-bean          query-method
Deployment file: weblogic-cmp-rdbms-jar.xml

 

 

Function

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

 

 

Example

 

 

optimistic-column

Range of values: n/a
Default value: n/a
Requirements: Although not all databases are case sensitive, this element is case maintaining.
Parent elements: weblogic-rdbms-bean          table-map
Deployment file: weblogic-cmp-rdbms-jar.xml

 

 

Function

The optimistic-column element denotes a database column that contains a version or timestamp value used to implement optimistic concurrency.

 

 

Example

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

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

 

 

order-database-operations

Range of values: True | False
Default value: True
Requirements:
Parent elements: weblogic-rdbms-bean
Deployment file: weblogic-cmp-rdbms-jar.xml

 

 

Function

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.

 

 

Example

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

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

 

 

primary-key-table

Range of values: n/a
Default value: n/a
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
Deployment file: weblogic-cmp-rdbms-jar.xml

 

 

Function

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

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

 

 

Example

The following sample XML shows the use of the primary-key-table element.

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

 

 

query-method

Range of values: n/a
Default value: n/a
Requirements: n/a
Parent elements: weblogic-rdbms-bean
Deployment file: weblogic-cmp-rdbms-jar.xml

 

 

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

 

 

relation-name

Range of values: Valid name
Default value: n/a
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
Deployment file: weblogic-cmp-rdbms-jar.xml

 

 

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

Range of values: n/a
Default value: n/a
Requirements: n/a
Parent elements: weblogic-rdbms-jar
         weblogic-rdbms-bean
Deployment file: weblogic-cmp-rdbms-jar.xml

 

 

Function

The relation-caching element specifies relationship caching.

 

 

Example

The XML stanza can contain the elements shown here: 


<relationship-caching>



 <caching-name>cacheMoreBeans</caching-name>



 <caching-element>


<cmr-field>accounts<</cmr-field>


<group-name>acct_group</group-name>


<caching-element>


 <cmr-field>address</cmr-field>


 <group-name>addr_group</group-name>


</caching-element>



 </caching-element>


 <caching-element>


<cmr-field>phone</cmr-field>


<group-name>phone_group</group-name>



 </caching-element>



</relationship-caching>

 

 

relationship-role-map

Range of values: Valid name
Default value: n/a
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
Deployment file: weblogic-cmp-rdbms-jar.xml

 

 

Function

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

 

 

Example

The XML stanza can contain the elements shown here: 


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

 

 

relationship-role-name

Range of values: Valid name
Default value: n/a
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
Deployment file: weblogic-cmp-rdbms-jar.xml

 

 

Function

The relationship-role-name element specifies the name of a relationship role. The bean on the foreign-key side of the a one-to-one relationship called Fk_Bean, as shown in the following XML stanza, is mapped to multiple tables. The table that has the foreign-key columns must be specified in the foreign-key-table element.

 

 

Example

The XML stanza can contain the elements shown here: 


<weblogic-rdbms-jar>


 <weblogic-rdbms-relation>


  <weblogic-relationship-role>stockholder</weblogic- relationship-role>


   <relationship-role-name>stockholders</relationship- role-name>


 </weblogic-rdbms-relation>


</weblogic-rdbms-jar>

 

 

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
Deployment file: weblogic-cmp-rdbms-jar.xml

.

 

 

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

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
Deployment file: weblogic-cmp-rdbms-jar.xml

 

 

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.
Default value: n/a
Requirements: table-name must be set in all cases.
Parent elements: weblogic-rdbms-bean          weblogic-rdbms-relation
Deployment file: weblogic-cmp-rdbms-jar.xml

 

 

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

The XML stanza can contain the elements shown here: 


<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
Requirements: n/a
Parent elements: weblogic-rdbms-bean
Deployment file: weblogic-cmp-rdbms-jar.xml

 

 

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

The XML stanza can contain the elements shown here: 


<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
Requirements: n/a
Parent elements: weblogic-rdbms-jar
Deployment file: weblogic-cmp-rdbms-jar.xml

 

 

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
Deployment file: weblogic-cmp-rdbms-jar.xml

 

 

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.

 

 

Example

The XML stanza can contain the elements shown here: 


<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
Deployment file: weblogic-cmp-rdbms-jar.xml

 

 

Function

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

A value of Modified means that only rows that are updated or deleted by a transaction are checked. A value of 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 bemodified 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.

Specifying a value of Modified, on the other hand, ensures that two transactions do not update the same row concurrently, resulting in a lost update, but it 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.

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.

 

 

Example

The XML stanza can contain the elements shown here: 


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

 

 

weblogic-ql

Range of values: n/a
Default value: n/a
Requirements: n/a
Parent elements: weblogic-rdbms-bean          weblogic-query
Deployment file: weblogic-cmp-rdbms-jar.xml

 

 

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

 

 

weblogic-query

Range of values: n/a
Default value: n/a
Requirements: n/a
Parent elements: weblogic-rdbms-bean
Deployment file: weblogic-cmp-rdbms-jar.xml

 

 

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

Range of values: n/a
Default value: n/a
Requirements: n/a
Parent elements: weblogic-rdbms-jar
Deployment file: weblogic-cmp-rdbms-jar.xml

 

 

Function

The weblogic-rdbms-bean represents a single entity bean that is managed by the WebLogic RDBMS CMP persistence type.

 

 

Example

The XML structure of weblogic-rdbms-bean is: 


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

Range of values: n/a
Default value: n/a
Requirements: n/a
Parent elements: n/a
Deployment file: weblogic-cmp-rdbms-jar.xml

 

 

Function

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

 

 

Example

The XML structure of weblogic-rdbms-jar is: 


weblogic-rdbms-jar



 weblogic-rdbms-bean



 weblogic-rdbms-relation



 create-default-dbms-tables



 validate-db-schema-with



 database-type

 

 

weblogic-rdbms-relation

Range of values: n/a
Default value: n/a
Requirements: n/a
Parent elements: weblogic-rdbms-jar
Deployment file: weblogic-cmp-rdbms-jar.xml

 

 

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 tot he primary keys of the entities involved in the relation. for more information on one-to-one relationships, see Many-to-Many Relationships.

 

 

Example

The XML structure of a weblogic-rdbms-relation showing a one-to-one relationship follows: 


<weblogic-rdbms-relation>



 <relation-name>employee-manager</relation-name>



 <weblogic-relationship-role>


<relationship-role-name>employee


 </relationship-role-name>


<relationship-role-name>


 <<column-map>


  <foreign-key-column>manager-id


   </foreign-key-column>


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


 </column-map>


<relationship-role-name>



 </weblogic-relationship-role>



</weblogic-rdbms-relation>

 

 

weblogic-relationship-role

Range of values: Valid name
Default value: n/a
Requirements: The mapping of a role to a table is specified in the associated weblogic-rdbms-bean and ejb-relation elements.
Parent elements: weblogic-rdbms-jar
         weblogic-rdbms-relation
Deployment file: weblogic-cmp-rdbms-jar.xml

 

 

Function

The weblogic-relationship-role element is used to express a mapping from a foreign key to a primary key. Only one mapping is specified for one-to-one relationships when the relationship is local. However, with a many-to-many relationship, specify two mappings

Multiple column mappings are specified for a single role, it the key is complex. No column-map is specified if the role is just specifying a group-name.

 

 

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-relationship-role>stockholder </weblogic-relationship-role>


 </weblogic-rdbms-relation>


</weblogic-rdbms-jar>