bea.com | products | dev2dev | support | askBEA

Download Docs | Site Map | Glossary
Search

Programming WebLogic Enterprise JavaBeans

weblogic-cmp-rdbms-
jar.xml Document Type Definitions

The chapter describes both the EJB 1.1and 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.

The following sections provide a complete reference of both versions of the WebLogic-specific XML including the DOCTYPE header information. Use these deployment descriptor elements to specify container-managed-persistence (CMP).

- EJB Deployment Descriptors

- DOCTYPE Header Information

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

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

- 1.1 weblogic-cmp-rdbms-jar.xml Deployment Descriptor File Structure

- 1.1 weblogic-cmp-rdbms-jar.xml Deployment Descriptor Elements

EJB Deployment Descriptors

The EJB deployment descriptors provide structural and application assembly information for an enterprise bean. You specify this information by specifying values for the deployment descriptors in three EJB XML DTD files. These files are:

- ejb-jar.xml

- weblogic-ejb-jar.xml

- weblogic-cmp-rdbms-jar.xml

You package these three XML files with the EJB and other classes into a deployable EJB component, usually a JAR file, called ejb.jar.

The ejb-jar.xml file is based on the deployment descriptors found in Sun Microsystems's ejb.jar.xml file. The other two XML files are weblogic-specific files that are based on the deployment descriptors found in weblogic-ejb-jar.xml and weblogic-cmp-rdbms-jar.xml.

DOCTYPE Header Information

When editing or creating XML deployment files, it is critical to include the correct DOCTYPE header for each deployment file. In particular, using an incorrect PUBLIC element within the DOCTYPE header can result in parser errors that may be difficult to diagnose. The correct text for the PUBLIC element for each XML deployment file is as follows.

The correct text for the PUBLIC element for the WebLogic Server-specific weblogic-cmp-rdbms-jar.xml files are as follows.

XML File | PUBLIC Element String
--- | ---
weblogic-cmp-rdbms -jar.xml | '-// BEA Systems, Inc.//DTD WebLogic 7.0.0 EJB RDBMS Persistence//EN' 'http://www.bea.com/servers/wls700/dtd/weblogic-rdbms20-persistence-700.dtd'
weblogic-cmp-rdbms -jar.xml | '-// BEA Systems, Inc.//DTD WebLogic 6.0.0 EJB RDBMS Persistence//EN' 'http://www.bea.com/servers/wls600/dtd/weblogic-rdbms20-persistence-600.dtd'

The correct text for the PUBLIC elements for the Sun Microsystem-specific ejb-jar files are as follows.

XML File | PUBLIC Element String
--- | ---
ejb-jar.xml | '-//Sun Microsystems, Inc.//DTD Enterprise JavaBeans 2.0//EN' 'http://java.sun.com/dtd/ejb-jar_2_0.dtd'
ejb-jar.xml | '-//Sun Microsystems, Inc.//DTD Enterprise JavaBeans 1.1//EN' 'http://www.java.sun.com/j2ee/dtds/ejb-jar_1_1.dtd'

For example, the entire DOCTYPE header for a weblogic-cmp-rdbms-jar.xml file is as follows:

>     <!DOCTYPE weblogic-cmp-rdbms-jar PUBLIC
>     '-//BEA Systems, Inc.//DTD WebLogic 7.0.0 EJB RDBMS Persistence//EN' 'http://www.bea.com/servers/wls700/dtd/weblogic-rdbms20-persistence-700.dtd '>

XML files with incorrect header information may yield error messages similar to the following, when used with a utility that parses the XML (such as ejbc):

>     SAXException: This document may not have the identifier `identifier_name'

identifier_name generally includes the invalid text from the PUBLIC element.

Document Type Definitions (DTDs) for Validation

The contents and arrangement of elements in your XML files must conform to the Document Type Definition (DTD) for each file you use. WebLogic Server utilities ignore the DTDs embedded within the DOCTYPE header of XML deployment files, and instead use the DTD locations that were installed along with the server. However, the DOCTYPE header information must include a valid URL syntax in order to avoid parser errors.

Note: Most browsers do not display the contents of files having the .dtd extension. To view the DTD file contents in your browser, save the links as text files and view them with a text editor.

weblogic-cmp-rdbms-jar.xml

The following links provide the public DTD locations for the weblogic-cmp-rdbms-jar.xml deployment files used with WebLogic Server:

- For weblogic-cmp-rdbms-jar.xml 2.0 DTD:

  http://www.bea.com/servers/wls700/dtd/weblogic-rdbms20-
  persistence-700.dtd contains the DTD that defines container-managed persistence properties for entity EJBs. This DTD is changed from WebLogic Server Version 6.0, and you must still include a weblogic-cmp-rdbms-jar.xml file for entity EJBs using WebLogic Server RDBMS-based persistence.

  Use the existing DTD file located at:

  http://www.bea.com/servers/wls700/dtd/weblogic-rdbms-
  persistence-700.dtd

  http://www.bea.com/servers/wls600/dtd/weblogic-rdbms20-
  persistence-600.dtd contains the DTD that defines container-managed persistence properties for entity EJBs. This DTD is changed from WebLogic Server Version 5.1, and you must still include a weblogic-cmp-rdbms-jar.xml file for entity EJBs using WebLogic Server RDBMS-based persistence.

  Use the existing DTD file located at:

  http://www.bea.com/servers/wls600/dtd/weblogic-rdbms-
  persistence-600.dtd

ejb-jar.xml

The following links provide the public DTD locations for the ejb-jar.xml deployment files used with WebLogic Server:

- For ejb-jar.xml 2.0 DTD:

  http://www.java.sun.com/dtd/ejb-jar_2_0.dtd contains the DTD for the standard ejb-jar.xml deployment file, required for all EJBs. This DTD is maintained as part of the JavaSoft EJB 2.0 specification; refer to the JavaSoft specification for information about the elements used in ejb-jar.dtd.

- For ejb-jar.xml 1.1 DTD:

  ejb-jar.dtd contains the DTD for the standard ejb-jar.xml deployment file, required for all EJBs. This DTD is maintained as part of the JavaSoft EJB 1.1 specification; refer to the JavaSoft specification for information about the elements used in ejb-jar.dtd.

Note: Refer to the appropriate JavaSoft EJB specification for a description of the ejb-jar.xml deployment descriptors.

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 7.0. However, if you want to use any of the new CMP 2.0 features, you must use the new DTD described below.

The top-level element of the WebLogic Server 7.0 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

- 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

- description

- delay-database-insert-until

- ejb-name

- enable-tuned-updates

- field-group

- field-map

- foreign-key-column

- foreign-key-table

- generator-name

- generator-type

- group-name

- include-updates

- key-cache-size

- key-column

- max-elements

- method-name

- method-param

- method-params

- optimistic-column

- primary-key-table

- query-method

- relation-name

- relationship-caching

- relationship-role-map

- relationship-role-name

- sql-select-distinct

- table-map

- table-name

- use-select-for-update

- validate-db-schema-with

- verify-columns

- weblogic-ql

- weblogic-query

- weblogic-rdbms-bean

- weblogic-rdbms-jar

- weblogic-rdbms-relation

- weblogic-relationship-role

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

caching-element 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.

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

Example

See relationship-caching:

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

See relationship-caching:

check-exists-on-method

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

Function

By default, the EJB container waits for a transaction to complete to check that a container-managed persistence (CMP) entity bean exists. This results in high performance and still provides a sufficient level of checking for most applications.

To specify that the EJB container check that bean exists before any business method invoked on the bean completes, set check-exists-on-method to True. 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.

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

See field-map.

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: | True | False.
Default value: | False
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 will be the 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 turns on or off a feature that automatically creates a default table based on the descriptions in the deployment files and the bean class. When set to False, this feature is turned off and table will not automatically be generated. When set to True, this feature is turned on and the table is automatically created. If TABLE CREATION fails, a Table Not Found error is thrown and the table must be created by hand.

Example

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

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

database-type

Range of values: | DB2| INFORMIX| ORACLE| SQL_SERVER| 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 dbms.

>     <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. For more information on datasources, see Programming WebLogic JDBC.
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

See table-name.

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

See Cascade Delete Method.

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

See field-map.

dbms-column-type

Range of values: | Valid name
Default value: | n/a
Requirements: | Available for use with Oracle database only.
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>

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>

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>

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

See table-name.

enable-tuned-updates

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

Function

The enable-tuned-updates element specifies that when ejbStore is called that the EJB container automatically determine which container-managed fields have been modified and then writes only those fields back to the database.

Example

The following examples shows how to specify the enable-tuned-updates element.

<enable-tuned-updates>True</enable-tuned-updates>

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

See column-map.

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

See relationship-role-map.

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 NAMED_SEQUENCE_TABLE, then the generator-name element would be the name of the SEQUENCE_TABLE to be used.

Example

See automatic-key-generation.

generator-type

Range of values: | 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

- SQL_SERVER

- NAMED_SEQUENCE_TABLE

Example

See automatic-key-generation.

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

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

See automatic-key-generation.

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

See column-map.

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

See weblogic-query.

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

See weblogic-query.

optimistic-column

Range of values: | n/a
Default value: | n/a
Requirements: | Although not all databases are case sensitive, this element preserves case.
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. For more information on optimistic concurrency, see Optimistic Concurrency Strategy.

Example

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

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

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. For more information about primary keys, see Using Primary Keys.

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.

For more information, see Container-Managed Relationships.

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

See weblogic-query.

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. For more information on relationship caching, see Using Relationship Caching for CMRs.

Example

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

The accounts and phone fields are container-managed relationship (CMR) fields in the customerBean table; the address field is a CMR field in the accountBean table; and the addr_group and phone_group are groups in the addressBean and phoneBean.

Using nested caching-elements enables the bean to load more than one level of related beans. In this example, addressBean is the second level related bean because it is nested in the accountBean. Currently, there is no limitation on the number of caching-elements that you can specify. However, setting too many caching-element levels could have an impact on the performance of the current transaction.

Since relationship caching uses join queries, and a join query might duplicate results for a table in the ResultSet, the number of caching-element deployment descriptors specified in the relationship-caching element will have a direct impact on the number of duplicate results in the ResultSet. For one-to-many relationships, do not specify too many caching-element deployment descriptors in the relationship-caching element because the number of duplicate results might multiply for each caching-element deployment descriptor.

relationship-role-map

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.

For more information, see Container-Managed Relationships.

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

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.

Example

The XML stanza can contain the elements shown here:

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

sql-select-distinct

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 you must 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" for this flag causes SELECT ... FOR UPDATE to be used whenever the bean is loaded from the database. This is different from the transaction isolation level of TRANSACTION_READ_COMMITTED_FOR_UPDATE 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 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.

- Read—all of the columns in the table that have been read during the transaction are checked.

- Modified—only the columns that have been updated by the current transaction are checked.

- Version and Timestamp—specify that a version or timestamp (pseudo)column exists in the table and that this column is used to implement optimistic concurrency. The EJB container will automatically increment the version or timestamp column when a row in the table is updated. The name of the version (or timestamp) column is specified using the optimistic-column element. It is not necessary to map this column to a cmp field, unless desired.

If a bean is mapped to multiple tables, checking is only performed on the tables that are updated during the transaction. The verify-columns elements for each table do not need to have the same value.

See Optimistic Concurrency Strategy for more information.

Example

The XML stanza can contain the elements shown here:

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

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

See weblogic-query.

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
>     	delay-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 container-managed relationship (CMR).

For more information about CMRs, see Container-Managed Relationships.

Example

<weblogic-rdbms-relation>
<relation-name>...</relation-name>
<weblogic-relationship-role>...</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 or a one-to-many relationships. With a many-to-many relationship, you must specify two mappings

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

For more information, see Container-Managed Relationships.

Example

The XML stanza can contain the elements shown here:

>     <weblogic-relationship-role>
>        <relationship-role-name>...</relationhsip-role-name>
>        <relationship-role-map>
>     			<<column-map>
>     				<foreign-key-column>manager-id
>     					</foreign-key-column>
>     				<key-column>id</key-column>
>     			</column-map>
>     		<relationship-role-name>
>     	</weblogic-relationship-role>

1.1 weblogic-cmp-rdbms-jar.xml Deployment Descriptor File Structure

weblogic-cmp-rdbms-jar.xml defines deployment elements for a single entity EJB that uses WebLogic Server RDBMS-based persistence services.

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

>     description

>     weblogic-version

>     <weblogic-enterprise-bean>

>        <pool-name>finance_pool</pool-name>

>        <schema-name>FINANCE_APP</schema-name>

>        <table-name>ACCOUNT</table-name>

>        <attribute-map>

>           <object-link>

>              <bean-field>accountID</bean-field>

>              <dbms-column>ACCOUNT_NUMBER</dbms-column>

>           </object-link>

>           <object-link>

>              <bean-field>balance</bean-field>

>              <dbms-column>BALANCE</dbms-column>

>           </object-link>

>        </attribute-map>

>        <finder-list>

>           <finder>

>              <method-name>findBigAccounts</method-name>

>              <method-params>

>                 <<method-param>double</method-param>

>              </method-params>

>           <finder-query><![CDATA[(> balance $0)]]></finder-query>

>           <finder-expression>. . .</finder-expression>

>           </finder>

>        </finder-list>

>     </weblogic-enterprise-bean>

1.1 weblogic-cmp-rdbms-jar.xml Deployment Descriptor Elements

RDBMS Definition Elements

This section describes the RDBMS definition elements.

pool-name

pool-name specifies name of the WebLogic Server connection pool to use for this EJB's database connectivity. See Using connection pools for more information.

schema-name

schema-name specifies the schema where the source table is located in the database. This element is required only if you want to use a schema that is not the default schema for the user defined in the EJB's connection pool.

Note: This field is case sensitive, although many SQL implementations ignore case.

table-name

table-name specifies the source table in the database. This element is required in all cases.

Note: The user defined in the EJB's connection pool must have read and write privileges to the specified table, though not necessarily schema modification privileges. This field is case sensitive, although many SQL implementations ignore case.

EJB Field-Mapping Elements

This section describes the EJB field-mapping elements.

attribute-map

The attribute-map stanza links a single field in the EJB instance to a particular column in the database table. The attribute-map must have exactly one entry for each field of an EJB that uses WebLogic Server RDBMS-based persistence.

object-link

Each attribute-map entry consists of an object-link stanza, which represents a link between a column in the database and a field in the EJB instance.

bean-field

bean-field specifies the field in the EJB instance that should be populated from the database. This element is case sensitive and must precisely match the name of the field in the bean instance.

The field referenced in this tag must also have a cmp-field element defined in the ejb-jar.xml file for the bean.

dbms-column

dbms-column specifies the database column to which the EJB field is mapped. This tag is case sensitive, although many databases ignore the case.

Note: WebLogic Server does not support quoted RDBMS keywords as entries to dbms-column. For example, you cannot create an attribute map for column names such as "create" or "select" if those names are reserved in the underlying datastore.

Finder Elements

This section describes the finder elements.

finder-list

The finder-list stanza defines the set of all finders that are generated to locate sets of beans. See Writing for RDBMS Persistence for EJB 1.1 CMP for more information.

finder-list must contain exactly one entry for each finder method defined in the home interface, except for findByPrimarykey. If an entry is not provided for findByPrimaryKey, one is generated at compilation time.

Note: If you do provide an entry for findByPrimaryKey, WebLogic Server uses that entry without validating it for correctness. In most cases, you should omit an entry for findByPrimaryKey and accept the default, generated method.

finder

The finder stanza describes a finder method defined in the home interface. The elements contained in the finder stanza enable WebLogic Server to identify which method in the home interface is being described, and to perform required database operations.

method-name

method-name defines the name of the finder method in the home interface. This tag must contain the exact name of the method.

method-params

The method-params stanza defines the list of parameters to the finder method being specified in method-name.

Note: WebLogic Server compares this list against the parameter types for the finder method in the EJB's home interface; the order and type for the parameter list must exactly match the order and type defined in the home interface.

method-param

method-param defines the fully-qualified name for the parameter's type. The type name is evaluated into a java.lang.Class object, and the resultant object must precisely match the respective parameter in the EJB's finder method.

You can specify primitive parameters using their primitive names (such as "double" or "int"). If you use a non-primitive data type in a method-param element, you must specify a fully qualified name. For example, use java.sql.Timestamp rather than Timestamp. If you do not use a qualified name, ejbc generates an error message when you compile the deployment unit.

finder-query

finder-query specifies the WebLogic Query Language (WLQL) string that is used to retrieve values from the database for this finder. See Using WebLogic Query Language (WLQL) for EJB 1.1 CMP for more information.

Note: Always define the text of the finder-query value using the XML CDATA attribute. Using CDATA ensures that any special characters in the WLQL string do not cause errors when the finder is compiled.

finder-expression

finder-expression specifies a Java language expression to use as a variable in the database query for this finder.

Note: Future versions of the WebLogic Server EJB container will use the EJB QL query language (as required by the EJB 2.0 specification). EJB QL does not provide support for embedded Java expressions. Therefore, to ensure easier upgrades to future EJB containers, create entity EJB finders without embedding Java expressions in WLQL.