Programming WebLogic Enterprise JavaBeans
|
 |
 |
|
 |
 |
The following sections describe the EJB 2.1 elements in the weblogic-cmp-jar.xml file, the WebLogic-specific XML Schema-based (XSD) deployment descriptor file. Use these definitions to create the WebLogic-specific weblogic-cmp-jar.xml file that is part of your EJB deployment. Use this deployment descriptor file to specify container-managed-persistence (CMP) behavior.
In this release of WebLogic Server, weblogic-cmp-jar.xml is XML Schema-based (XSD). In prior releases, weblogic-cmp-jar.xml was Document Type Definition-based (DTD). For backward compatibility, this release of WebLogic Server supports XSD- or DTD-based EJB descriptors. In this release of WebLogic Server, the EJB container still supports all older DTD-based descriptors; you can deploy applications that use DTD-based descriptors in this release of WebLogic Server without modifying the descriptors.
For information on the EJB 1.1 deployment descriptor elements see Important Information for EJB 1.1 Users.
weblogic-cmp-jar.xml, as well as Document Type Definitions and DOCTYPE headers, see Deployment Descriptor Schema and Document Type Definitions Reference.weblogic-ejb-jar.xml file, see weblogic-ejb-jar.xml Deployment Descriptor Reference.EJB 1.1 deployment descriptor elements, see Important Information for EJB 1.1 Users.
The weblogic-cmp-jar.xml file defines deployment descriptors for entity EJBs that use WebLogic Server RDBMS-based persistence services. The EJB container uses a version of weblogic-cmp-jar.xml that is different from the XML shipped with pre-9.0 releases of WebLogic Server.
You can continue to use the earlier weblogic-cmp-jar.xml DTD beans that you deploy to this release of WebLogic Server; likewise, you can continue to use the weblogic-cmp-jar.xml DTD that was supported in WebLogic Server 8.1. Though deployment descriptors are XSD-based beginning with WebLogic Server 9.0, for backward compatibility, WebLogic Server continues to support DTD-based descriptors. However, if you want to use any of the CMP 2.1 features, you must use the XSD described below.
BEA recommends that you run DDConverter to convert EJB deployment descriptors from pre-9.0 releases of WebLogic Server to conform to the current release of WebLogic Server. DDConverter converts your DTD-based EJB deployment descriptors from pre-9.0 releases of WebLogic Server to XSD-based descriptors supported in this release.
Note: BEA recommends that you always convert descriptors when migrating applications to a new WebLogic Server release.
The top-level element of the WebLogic Server 9.x weblogic-cmp-jar.xml consists of a weblogic-rdbms-jar element:
weblogic-rdbms-jar
weblogic-rdbms-bean
ejb-name
data-source-jndi-name
table-map
field-group
relationship-caching
sql-shape
weblogic-query
delay-database-insert-until
use-select-for-update
lock-order
instance-lock-order
automatic-key-generation
check-exists-on-method
cluster-invalidation-disabled
weblogic-rdbms-relation
relation-name
table-name
weblogic-relationship-role
order-database-operations
enable-batch-operations
create-default-dbms-tables
validate-db-schema-with
database-type
default-dbms-tables-ddl
compatibility
serialize-byte-array-to-oracle-blob
serialize-char-array-to-bytes
allow-readonly-create-and-remove
disable-string-trimming
This list of the elements in weblogic-cmp-jar.xml includes all elements that are supported in WebLogic Server 9.1.
This element, introduced in WebLogic Server 8.1 SP02, is a backward compatibility flag. It is used to enable create and remove operations for an EJB that uses ReadOnly concurrency.
Prior to WebLogic Server 8.1 SP2, these operations were allowed, although they had no transactional meaning. They have been disallowed so that more efficient code can be generated for ReadOnly beans, and because using them is a bad practice.
<compatibility>
<allow-readonly-create-and-remove>
true
</allow-readonly-create-and-remove>
</compatibility>
The automatic-key-generation element specifies how primary keys will be automatically generated. For more information about this feature, see Automatically Generating Primary Keys.
The following code samples show the automatic-key-generation element for different primary key generation methods. For supported generation methods, see generator-type
Listing C-1 automatic-key-generation With generator-type=Oracle
<automatic-key-generation>
<generator-type>Oracle</generator-type>
<generator-name>test_sequence</generator-name>
<key-cache-size>10</key-cache-size>
</automatic-key-generation>
Listing C-2 automatic-key-generation With generator-type=SQL-SERVER
<automatic-key-generation>
<generator-type>SQL-SERVER</generator-type>
</automatic-key-generation>
Listing C-3 automatic-key-generation With generator-type=NamedSequenceTable
<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>
Specifies the cmr-field 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, see group-name.
caching-element can contain nested caching elements, as in the example shown in relationship-caching.
For information about relationship caching, see Relationship Caching.
See relationship-caching:
The caching-name element specifies the name of a relationship cache. For more information about relationship caching, see Relationship Caching.
See relationship-caching.
By default, the EJB container checks that a container-managed persistence (CMP) entity bean exists before any business method invoked on the bean completes. This means the container notifies an application as soon as any business method is invoked on a container-managed entity bean that has been removed.
To specify that the EJB container wait for transaction completion to perform the existence check, set check-exists-on-method to False. This results in high performance and still provides a sufficient level of checking for most applications.
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>
This flag, introduced in WebLogic Server 9.0, is used to disable or enable invalidation of an EJB that uses Optimistic or ReadOnly concurrency when the EJB is updated by a member of a cluster to which it is deployed. For more information, see Invalidation Options for Optimistic Concurrency in Clusters.
<cluster-invalidation-disabled>true</cluster-invalidation-disabled>
This name specifies the mapped field in the bean instance which should be populated with information from the database.
See field-map.
Specifies the name of a container-managed relationship field.
<cmr-field>stock options</cmr-field>
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 columns belong are implicit from the context in which the column-map element appears in the deployment descriptor.
The following is an example of the column-map element:
Note: You do not need to specify the key-column element if the foreign-key-column refers to a remote bean.
<column-map>
<foreign-key-column>account-id</foreign-key-column>
<key-column>id</key-column>
</column-map>
The <compatibility> element, introduced in WebLogic Server 8.1 SP02, contains elements that specify compatibility flags for all of the cmp beans described in the descriptor file.
<compatibility>
<serialize-byte-array-to-oracle-blob>
<serialize-char-array-to-bytes>
<allow-readonly-create-and-remove>
<disable-string-trimming>
</compatibility>
The create-default-dbms-table element performs two functions:
Use this element only for convenience during development phases. This is because the table schema in the DBMS CREATE statement used are the EJB container's best approximation of the definition. A production environment typically requires more precise schema definition.
The following table describes how WebLogic Server handles automatic table creation, based on the value of create-default-dbms-tables.
If TABLE CREATION fails, the server throws a Table Not Found error and the table must be created manually.
See Automatic Table Creation (Development Only).
Note: Automatic Oracle SEQUENCE generation works only with servers running in development mode.
The following table describes how WebLogic Server handles automatic SEQUENCE generation, based on the value of create-default-dbms-tables.
|
The EJB container takes no action with respect to SEQUENCE generation. This is the default value. |
|
|
The EJB container creates a SEQUENCE, and constructs its name by appending "_WL" to the value of the |
|
|
The EJB container creates a SEQUENCE, and constructs its name by appending "_WL" to the value of the If the SEQUENCE's increment value does not match the value of the key-cache-size element, the container alters the increment value to match the value of key-cache-size. |
|
|
The EJB container creates a SEQUENCE, and constructs its name by appending "_WL" to the value of the If the SEQUENCE's increment value does not match the value of the key-cache-size element, the container alters the increment value to match the value of key-cache-size. |
|
|
The EJB container creates a SEQUENCE, and constructs its name by appending "_WL" to the value of the If the SEQUENCE's increment value does not match the value of the key-cache-size element, the container alters the increment value to match the value of key-cache-size. |
For more information on automatic generation of an Oracle SEQUENCE, see Support for Oracle SEQUENCE.
The following example specifies the create-default-dbms-tables element.
<create-default-dbms-tables>CreateOnly</create-default-dbms-tables>
|
database-type must be specified. |
|
|
|
The database-specific-sql element specifies a database-specific SQL statement.
<database-specific-sql>
<database-type>SQLServer</database-type>
<sql>SELECT name, phone, location, testid FROM medrecappPharmacyBeanTable WHERE testid = ?1 AND SUBSTRING(testid, 1,5) = 'local' ORDER BY name</sql>
</database-specific-sql>
The database-type element specifies the database used as the underlying WebLogic Server dbms or the dbms against which to execute a vendor-specific SQL statement. If you specify database-type in the weblogic-rdbms-jar element, the database you specify applies to the entire weblogic-rdbms-jar deployment descriptor file unless it is overridden in a database-specific-sql element by another database-type element.
<database-type>POINTBASE</database-type>
Specifies the JDBC data source name to be used for database connectivity for this bean. For more information on data sources, see Programming WebLogic JDBC.
Note: Prior to WebLogic Server 9.0, this element was data-source-name.
See table-name.
Allows an application to take advantage of a database's built-in support for cascade delete, and possibly improve performance. This functionality is supported only for:
If db-cascade-delete is enabled in weblogic-cmp-rdbms-jar.xml, you must
Note: If db-cascade-delete is not specified, do not enable the database's cascade delete functionality, as this will produce incorrect results.
The following Oracle table definition will cause deletion all of the emp rows if the owning dept is deleted in the database.
CREATE TABLE dept
(deptno NUMBER(2) CONSTRAINT pk_dept PRIMARY KEY,
dname VARCHAR2(9) );
CREATE TABLE emp
(empno NUMBER(4) PRIMARY KEY,
ename VARCHAR2(10),
deptno NUMBER(2) CONSTRAINT fk_deptno
REFERENCES dept(deptno)
ON DELETE CASCADE );
<weblogic-relationship-role>
<db-cascade-delete/>
</weblogic-relationship-role>
The name of the database column to which the field should be mapped.
Note: dbms-column is case maintaining, although not all database are case sensitive.
See field-map.
|
To specify |
|
Specifies the type of the cmp-field. Maps the current field to a Blob or Clob in an Oracle or DB2 database or to a LongString or SybaseBinary in a Sybase database.
Blob—maps the field to an Oracle or DB2 Blob.Clob—maps the field to an Oracle or DB2 Clob.LongString—tells the container to use setCharacterStream to write String data into the database. Some JDBC drivers have problems writing more than 4K of data using setString.SybaseBinary—tells the container to use setBytes to write bytes into the binary column, because setBinaryStream does not work with SybaseXADriver.<field-map>
<cmp-field>photo</cmp-field>
<dbms-column>PICTURE</dbms-column>
<dbms_column-type>OracleBlob</dbms-column-type>
</field-map>
Specifies the database used as the default underlying dbms. This value can be overridden by the database-type element.
<dbms-default-value>Oracle</dbms-default-value>
Specifies the DDL file name to which the EJB container writes the table creation scripts.
Specifies when a new CMP bean is inserted into the database. The allowable values cause the following behavior:
ejbCreate - perform database insert immediately after ejbCreate. This setting yields better performance than ejbCreate by avoiding an unnecessary store operation.ejbPostCreate - perform insert immediately after ejbPostCreate.This element has an effect only when order-database-operations is False. By default, order-database-operations is true, which causes new beans to be inserted at the transaction commit time.
Delaying the database insert until after ejbPostCreate is required when a cmr-field is mapped to a foreign-key column that does not allow null values. In this case, the cmr-field must be set to a non-null value in ejbPostCreate before the bean is inserted into the database.
For maximum flexibility, avoid creating related beans in your ejbPostCreate method. If ejbPostCreate creates related beans, and database constraints prevent related beans from referring to a bean that has not yet been created, it is not possible to perform a database insert until after the method completion.
Note: cmr-fields may not be set during ejbCreate, before the primary key of the bean is known.
<delay-database-insert-until>ejbPostCreate</delay-database-insert-until>
The description element provides text that describes the parent element.
<description>Contains a description of parent element</description>
This element, introduced in WebLogic Server 9.0, is a compatibility flag. It is used to specify whether a cmp-field of type string[] should be trimmed. Set this flag to True to disable string trimming. For more information on string trimming, see String-Valued CMP Field Trimming and Disabling String Trimming.
<compatibility>
<disable-string-trimming>True</disable-string-trimming>
</compatibility>
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.
The ejb-ql-query element specifies an EJB-QL query. You should only specify EJB-QL queries that implement EJB finders or contain WebLogic-specific extensions in the weblogic-cmp-jar.xml deployment descriptor; specify queries that use only standard EJB-QL features in the ejb-jar.xml deployment descriptor.
See weblogic-query.
This element, introduced in WebLogic Server 8.1, controls whether or not the EJB container allows batch database operations, including batch inserts, batch updates, and batch deletes.
If this element is set to True, the EJB delays database operations in a transaction until commit time.
The following XML sample demonstrates use of the enable-batch-operations element:
<enable-batch-operations>True</enable-batch-operations>
This element, introduced in WebLogic Server 9.0, controls whether read-only entity EJBs can be cached at the query level. Caching read-only entity EJBs at the query level improves performance because it enables the EJBs to be accessed in cache by any finder, thereby avoiding the need to access the database. If you set this value to True, you can specify the maximum number of queries to cache at the application or bean level. To specify the maximum number of queries to cache, set max-queries-in-cache in the weblogic-ejb-jar.xml deployment descriptor. For information, see max-queries-in-cache.
The following XML sample demonstrates use of the enable-query-caching element:
<enable-query-caching>True</enable-query-caching>
The field-group element represents a subset of the cmp-fields and cmr-fields of a bean. Related fields in a bean can be put into groups that are faulted into memory together as a unit. A group can be associated with a finder or relationship, so that when a bean is loaded as the result of executing a finder or following a relationship, only the fields specified in the group are loaded.
A field may belong to multiple groups. In this case, the getXXX method for the field faults in the first group that contains the field.
The field-group element 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 field-map element represents a mapping between a particular column in a database and a cmp-field in the bean instance.
The optional group-name element specifies a field group that is to be loaded when the getXXX method for the cmp-field is called and the EJB container needs to read the value from the DBMS because it is not in memory. If group-name is omitted, the default group, which contains all cmp-fields, is used when the cmp-field is not explicitly listed in any field groups, otherwise a field group that contains the cmp-field is chosen. Thus, developers should specify a group-name if the cmp-field is listed in multiple field groups or the container will pick one of the groups arbitrarily.
The dbms-column-type element is optional.
The field-map element can contain the elements shown here:
<field-map>
<cmp-field>....</cmp-field>
<dbms-column>...</dbms-column>
<dbms-column-type>...</dbms-column-type>
<group-name>...</group name>
</field-map>
This element, introduced in WebLogic Server 9.0, is a compatibility flag. It is used to specify whether finders can return null results.
<compatibility>
<finders-return-nulls>
True
</finders-return-value>
</compatibility>
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 primary key generator.
Oracle, and WebLogic Server is running in development mode, then the EJB container constructs the Oracle SEQUENCE name by appending "_WL" to the generator-name as part of the container's automatic SEQUENCE generation feature.For more information on automatic Oracle SEQUENCE generation, see Support for Oracle SEQUENCE.
generator-type element is Oracle, and WebLogic Server is running in production mode, then the EJB container sets the name of the Oracle SEQUENCE to the value of generator-name.generator-type element is NamedSequenceTable, then the generator-name element would be the name of the SEQUENCE_TABLE to be used.
The generator-type element specifies the primary key generation method to use.
In addition, generator-type is used in conjunction with automatic Oracle SEQUENCE generation. See Support for Oracle SEQUENCE.
Specifies the name of a field group.
See field-group.
Specifies whether 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. A value of False provides best performance.
<weblogic-query>
<query-method>
<method-name>findBigAccounts</method-name>
<method-params>
<method-param>double</method-param>
</method-params>
</query-method>
<ejb-ql-query>
<weblogic-ql>WHERE BALANCE>10000 ORDER BY NAME</weblogic-ql>
</ejb-ql-query>
<include-updates>True</include-updates>
</weblogic-query>
Specifies a locking or processing order for instances of a particular EJB. This element can be used to prevent deadlocks in an application that would otherwise experience deadlocks. instance-lock-order is used whenever database operations (update, for example) that apply to multiple instances of the same EJB are performed by the container. It specifies an order for operations that can cause a database lock to be acquired for a bean instance.
For example, instance-lock-order could be used to specify the order in which the EJB container calls ejbStore for instances of a particular EJB that uses database concurrency; ejbStore may acquire an exclusive lock when a database update is done. instance-lock-order also controls the order in which beans using optimistic concurrency are locked when optimistic checking is performed.
AccessOrder—The container will process beans so that locks are acquired (or upgraded) in the order in which the application originally accessed the beans during the transaction. This is the recommended value when all transactions in the system access instances of the bean, and ultimately rows in a database table, in the same order.ValueOrder—Beans are processed in order based on the value of their primary key. ValueOrder should be specified to avoid deadlocks when concurrent transactions access instances of the same EJB in different orders.Note: The EJB's primary key class is not required to implement the java.lang.Comparable interface when ValueOrder is specified, although this will result in a total ordering. Beans are ordered partially using the hash code value of the primary key when the primary key does not implement java.lang.Comparable.
<instance-lock-order>ValueOrder</instance-lock-order>
Specifies the optional size of the primary key cache available in the automatic primary key generation feature. In addition, the EJB container uses this value to calculate the increment value for an Oracle SEQUENCE when automatic SEQUENCE generation is enabled. See Support for Oracle SEQUENCE.
If generator-type is:
Oracle—key-cache-size must match the Oracle SEQUENCE INCREMENT value. If there is a mismatch between this value and the Oracle SEQUENCE INCREMENT value, then there will likely be duplicate key problems.NamedSequenceTable—key-cache-size specifies how many keys the container will fetch in a single DBMS call.key-cache-size is ignored.
The key-column element represents a column of a primary key in the database.
See column-map.
Use this flag to specify the database locking order of an entity bean when a transaction involves multiple beans and exclusive concurrency. The bean with the lowest number is locked first.
This flag should only be used to prevent a deadlock situation and, currently, only applies when a transaction performs cascade deletes.
An example of the lock-order element is:
<lock-order>1</lock-order>
<!ELEMENT lock-order (PCDATA)>
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.
An example of the max-elements element is shown here:
<max-elements>100</max-elements>
<!ELEMENT max-element (PCDATA)>
The method-name element specifies the name of a finder or ejbSelect method.
Note: The `*' character cannot be used as a wildcard.
See weblogic-query.
The method-param element contains the fully qualified Java type name of a method parameter.
<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 Choosing a Concurrency Strategy.
Note: Although not all databases are case sensitive, this element is case maintaining.
The following sample XML shows the use of the optimistic-column element.
<optimistic-column>ROW_VERSION</optimistic-column>
where ROW_VERSION is the name of a database column that contains the value used for concurrency checking.