| Download Docs | Site Map | Glossary | |
|
|
|||
| bea.com | products | dev2dev | support | askBEA |
|
|
|
|||||||
 |
|
e-docs >
WebLogic Server >
Programming WebLogic Enterprise JavaBeans
> The weblogic-cmp-rdbms- jar.xml Deployment Descriptor |
|
Programming WebLogic Enterprise JavaBeans
|
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.
The following sections provide a complete reference of the WebLogic-specific XML including the DOCTYPE header information. Use these deployment descriptor elements to specify container-managed-persistence (CMP).
For information on the EJB 1.1 deployment descriptor elements see Important Information for EJB 1.1 Users.
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:
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.
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.
The correct text for the PUBLIC elements for the Sun Microsystem-specific ejb-jar files are as follows.
|
`-//Sun Microsystems, Inc.//DTD Enterprise JavaBeans 2.0//EN' ` |
|
|
`-//Sun Microsystems, Inc.//DTD Enterprise JavaBeans 1.1//EN' |
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 8.1.0 EJB RDBMS Persistence//EN' 'http://www.bea.com/servers/wls810/dtd/weblogic-rdbms20-persistence-810.dtd '>
XML files with incorrect header information may yield error messages similar to the following, when used with a tool that parses the XML (such as appc):
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.
The following links provide the public locations for weblogic-cmp-rdbms-jar.xml DTDs, by version number.
The following links provide the public DTD locations for the weblogic-cmp-rdbms-jar.xml deployment files used with WebLogic Server:
The following links provide the public locations for the ejb-jar.xml DTDs used with WebLogic Server:
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.
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 8.1. 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 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
The automatic-key-generation element specifies the use of the Sequence/Key Generation feature.
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>
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.
For more information about relationship caching, see Relationship Caching with Entity Beans.
See relationship-caching:
The caching-name element specifies the name of a relationship cache. For more information about relationship caching, see Relationship Caching with Entity Beans.
See relationship-caching:
The check-exists-on method element specifies that WebLogic Server notify the application that a business method is invoked on a CMP entity bean that has been removed if the value is set to "True."
By default, WebLogic RDBMS CMP only checks that an entity bean actually exists in the underlying database when it needs to read or write data to the RDBMS. This provides most applications with higher performance and a sufficient level of checking. For example, when the value of a cmp-field is passed to an application for a bean that has been removed, it throws a NoSuchObjectException or NoSuchObjectLocalException error immediately while an
The following example specifies that WebLogic Server notify the application that a business method is invoked on a CMP entity bean that has been removed.
<check-exists-on-method>True</check-exists-on-method>
|
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. |
|
|
weblogic-rdbms-bean |
|
This name specifies the mapped field in the bean instance which should be populated with information from the database.
See field-map.
The cmr-field element specifies the name of a container-managed relationship field (cmr-field.)
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>
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.
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>
The create-default-dbms-table element serves two functions:
The following example specifies the create-default-dbms-tables element.
<create-default-dbms-tables>True</create-default-dbms-tables>
The database-type element specifies the database used as the underlying dbms.
The following example specifies the underlying dbms.
<database-type>POINTBASE</database-type>
|
Valid name of the data source used for all data base connectivity for this bean. |
|
|
Must be defined as a standard WebLogic Server JDBC data source for database connectivity. For more information on datasources, see Programming WebLogic JDBC. |
|
The data-source-name that specifies the JDBC data source name to be used for all database connectivity for this bean.
See table-name.
|
Only supported for Oracle database. Can only be specified for one-to-one or one-to-many relationships. |
|
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.
The name of the database column to which the field should be mapped.
See field-map.
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:
<field-map>
<cmp-field>photo</cmp-field>
<dbms-column>PICTURE</dbms-column>
<dbms_column-type>OracleBlob</dbms-column-type>
</field-map>
The description element is used to provide text that describes the parent element.
The following example specifies the description element.
<dscription>Contains a description of parent element</description>
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.
The following example specifies the delay-database-insert-until element.
<delay-database-insert-until>ejbPostCreate</delay-database-insert-until>
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.
See table-name.
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.
The following XML sample demonstrates use of the enable-batch-operations element:
<enable-batch-operations>True</enable-batch-operations>
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.
The following examples shows how to specify the enable-tuned-updates element.
<enable-tuned-updates>True</enable-tuned-updates>
|
A special group named default is used for finders and relationships that have no group specified. |
|
|
The default group contains all of a bean's cmp-fields, but none of its cmr-fields. |
|
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.
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>
The name of the mapped field for a particular column in a database that corresponds to a cmp field in the bean instance.
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>
The foreign-key-column element represents a column of a foreign key in the database.
See column-map.
The foreign-key-table element specifies the name of a DBMS table that contains a foreign key.
The generator-name element is used to specify the name of the generator.
The generator-type element specifies the key generation method to use. The options include:
The group-name element specifies the name of a field group.
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>
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.
The XML stanza can contain the elements shown here:
<include-updates>False</include_updates>
The key-cache-size element specifies the optional size of the primary key cache available in the automatic primary key generation feature.
The key-column element represents a column of a primary key in the database.
See column-map.
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.
The XML stanza can contain the elements shown here:
<max-elements>100</max-elements>
<!ELEMENT max-element (PCDATA)>
The method-name element specifies the name of a finder or ejbSelect method.
See weblogic-query.
The method-param element contains the fully qualified Java type name of a method parameter.
The XML stanza can contain the elements shown here:
<method-param>java.lang.String</method-param>
The method-params element contains an ordered list of the fully-qualified Java type names of the method parameters.
See weblogic-query.
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.
The following sample XML shows the use of the optimistic-column element.
<optimistic-column>ROW_VERSION</optimistic-column>
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.
The following sample XML demonstrates the use of the order-database-operations element.
<order-database-operations>True</order-database-operations>
|
Although not all databases are case sensitive, this element is case maintaining. |
|
|
weblogic-rdbms-jar |
|
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.
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>
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.
See weblogic-query.
The relation-name element specifies the name of a relation.
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>
The relation-caching element specifies relationship caching. For more information about relationship caching, see Relationship Caching with Entity Beans.
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>
|
The name must match the ejb-relationship-role-name of an ejb-relationship-role in the associated ejb-jar.xml descriptor file. |
|
The relationship-role-map element specifies foreign-key-column to key-column mapping for beans involved in a relationship.
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>
|
The name must match the ejb-relationship-role-name of an ejb-relationship-role in the associated ejb-jar.xml descriptor file. |
|
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. See foreign-key-table.
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>
Note: This element is deprecated. To achieve the same functionality, use the SELECT DISTINCT clause directly in finder queries.See Using SELECT DISTINCT
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.
The XML example contains the element shown here:
<sql-select-distinct>True</sql-select-distinct>
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.
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>
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.
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>
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.
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>
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.
The XML stanza can contain the elements shown here:
<validate-db-schema-with>TableQuery</validate-db-schema-with>
The verify-columns element specifies the columns in a table that you want WebLogic Server to check for validity when you use the optimistic concurrency strategy. WebLogic Server checks columns at the end of a transaction, before committing it to the database, to make sure that no other transaction has modified the data.
See Optimistic Concurrency Strategy for more information.
The XML stanza can contain the elements shown here:
<verify-columns>Modified</verify-columns>
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.
See weblogic-query.
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.
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>
The weblogic-rdbms-bean represents a single entity bean that is managed by the WebLogic RDBMS CMP persistence type.
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
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.
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
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:
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>
|
The mapping of a role to a table is specified in the associated weblogic-rdbms-bean and ejb-relation elements. |
|
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, you must 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.
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>
|
|
|
|
||
 |
|
|
 |
 |
 |
|
||
