|
|
| |
weblogic-cmp-rdbms-
jar.xml Document Type Definitions
The chapter describes both the EJB 5.1 and EJB 6.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
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.
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 6.0.0 EJB RDBMS20 Persistence//EN' 'http://www.bea.com/servers/wls600/dtd/weblogic-rdbms20-persisten ce-600.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:
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
weblogic-rdbms-persistence.dtd contains the DTD that defines container-managed persistence properties for entity EJBs. This DTD is used to create the weblogic-rdbms-persistence.xml file for using WebLogic Server persistence services. Third-party persistence vendors may also create XML deployment files that conform to this DTD. This file is located at http://www.bea.com/servers/wls510/dtd/weblogic-rdbms-persistence.dtd
ejb-jar.xml
The following links provide the public DTD locations for the ejb-jar.xml deployment files 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.
6.0 weblogic-cmp-rdbms-jar.xml Deployment Descriptor File Structure
weblogic-cmp-rdbms-jar.xml defines deployment descriptors for a entity EJBs that uses WebLogic Server RDBMS-based persistence services. The EJB 2.0 container uses a version of weblogic-cmp-rdbms-jar.xml that is different from the one shipped with WebLogic Server Version 5.1. See Locking Services for Entity EJBs for more information.
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 6.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 6.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-name field-name field-map field-group weblogic-query delay-database-insert-until automatic-key-generation
weblogic-rdbms-relation relation-name table-name weblogic-relationship-role
6.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>NAMED_SEQUENCE_TABLE</generator-type> <generator-name>MY_SEQUENCE_TABLE_NAME</generator-name> <key-cache-size>100</key-cache-size> </automatic-key-generation>
cmp-field
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
Function
The cmr-field element specifies the name of a 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
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
<column-map <foreign-key-column>account-id</foreign-key-column> <key-column>id</key-column> </column-map>
create-default-dbms-tables
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>
data-source-name
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
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
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 |
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 in a Sybase database. This element can be one of the following:
Example
<field-map> <cmp-field>photo</cmp-field> <dbms-column>PICTURE</dbms-column> <dbms_column-type>OracleBlob</dbms-column-type> </field-map>
delay-database-insert-until
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
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
Note: This deployment descriptor applies to EJB 1.1 only.
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
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
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 |
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.
generator-name
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 generator-name element is used to specify the name of the generator.
For example;
Example
generator-type
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 generator-type element specifies the key generation method to use. The options include:
Example
group-name
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
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 |
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 |
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.
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
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-role-name
Function
The relationship-role-name element specifies the name of a relationship role.
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
Function
The sql-select-distinct element controls whether the generated SQL SELECT statement will contain a a DISTINCT qualifer. Using the DISTINCT qualifer caused the database to return unique rows.
Example
The XML example contains the element shown here:
<sql-select-distinct>True</sql-select-distinct>
table-name
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
<table-name>Accounts</table-name>
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>
Parent elements: |
weblogic-rdbms-jar |
Function
The weblogic-rdbms-relation element represents a single relationship that is managed by the WebLogic CMP persistence type. deployment descriptor. WebLogic Server supports the following three relationship mappings:
For more information on container managed relationships, see Container-Managed Relationships.
Example
weblogic-rdbms-relation relationship-role-name group-name column-map db-cascade-delete
weblogic-relationship-role
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, 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.
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>
5.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. See Locking Services for Entity EJBs for more information.
The top-level element of the WebLogic Server 5.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>
5.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.
|
Copyright © 2001 BEA Systems, Inc. All rights reserved.
|