|
|
|
|
| |
WebLogic Server Container-Managed Persistence Services
The following sections describe the new container-managed persistence (CMP) services available with the EJB 2.0 for BEA WebLogic Server container. This information supplements the basic discussion of WebLogic RDBMS-based persistence services in Persistence Services.
EJB 2.0 Persistence Features and Changes
The EJB 2.0 specification places new requirements on entity EJB finder methods and field accessor methods, and introduces a new, portable query language for creating finders. This section summarizes those features. See the complete EJB 2.0 specification for details.
Note: Container-managed persistence beans need to be configured with a connection pool with maximum connections greater than 1. This is because WebLogic Server's container-managed persistence service may sometimes need to get two connections simultaneously.
"get" and "set" Method Restrictions
The EJB 2.0 specification standardizes the "get" and "set" methods that a container uses for reading and modifying container-managed fields. These container-generated classes must begin with "get" or "set" and use the actual name of a persistent field defined in ejb-jar.xml. The methods are also declared as public, protected, and abstract.
BLOB and CLOB DBMS Column Restrictions
WebLogic Server cannot support BLOB and CLOB DBMS columns with EJB CMP at this time, until JDBC defines a standard UPDATE mechanism for BLOBs and CLOBs. The small BLOB/CLOB is accessible by JDBC1.x getX/setX methods. However, if the column exceeds a certain size, the DBMS will shift to normal BLOB/CLOB semantics which are not supported in CMP.
To work around this restriction, you can do one of the following:
EJB QL Requirement for EJB 2.0 Beans
The deployment descriptors must define each finder query for EJB 2.0 entity beans by using an EJB QL query string.
You cannot use WebLogic Query Language (WLQL) with entity EJBs that use EJB 2.0 features, or that use EJB 2.0 deployment files. If you want to use WLQL, the entity EJB and its deployment files must be based on the EJB 1.1 specification. See Using WebLogic Server RDBMS Persistence for more information on WLQL.
isModified() Not Required for CMP Beans
The isModified() method is no longer required for CMP entity EJBs based on the EJB 2.0 specification. When you deploy EJB 2.0 entity beans with container-managed persistence, WebLogic Server automatically detects which EJB fields have been modified during a transaction, and writes only those fields to the underlying datastore.
You can still use isModified() for entity EJBs in the EJB 2.0 container that use bean-managed persistence and CMP. See is-modified-method-name for more information.
The EJB 2.0 specification introduces EJB QL as a portable query language for creating entity EJB finders. EJB QL is an SQL-like language that uses a single WHERE clause to select one or more entity EJB objects. The search space for an EJB QL query consists of the EJB's schema as defined in ejb-jar.xml (the bean's collection of container-managed fields and their associated database columns). Because EJB QL is portable among containers, EJB QL strings are defined in ejb-jar.xml rather than in weblogic-cmp-rdbms-jar.xml.
Basic EJB QL Syntax
The basic syntax of an EJB QL query consists of a mandatory FROM clause followed by a WHERE clause.
The WHERE clause defines conditions that limit the result set in a similar manner to WebLogic Query Language (WLQL). The remaining sections focus on the EJB QL clauses and operators that you can specify in the WHERE clause.
Note: Because EJB QL queries may contain ">" and "<" characters, always specify the entire EJB QL string within the CDATA tag to avoid confusing the query syntax with XML elements.
EJB QL String Literals
As with WLQL, EJB QL designates literal string values by enclosing them within single quotes. To represent a single quote as part of a literal string, use two consecutive single quotes, as in:
WHERE accountType = 'partner''s'
EJB QL Operators
EJB QL uses many of the same logical and arithmetic operators used in WLQL. See Migrating from (EJB 1.1) WLQL to (EJB 2.0) EJB QL for a list of WLQL operators and their EJB QL counterparts. See the EJB 2.0 specification for more detailed information about all EJB QL operators.
Finder Methods
The home interface of the entity bean defines one or more finder method. One is defined for each way to find an entity object or collection of entity objects within the home. The entity bean implementation uses the arguments of the finder method to locate the requested entity objects. The finder method must be associated with a query element in the deployment descriptor. The entity bean specifies the EJB QL finder query and associates it with the finder method in the deployment descriptor. The finder method is characterized by an EJB QL query string specified in the query element.
Finder Parameter Placeholders
EJB QL enables you to represent finder method parameters using the convention ?n where n indicates the number of the parameter in the associated finder method. In EJB QL, the first finder parameter is represented by ?1.
If you are familiar with WLQL, be extra careful when converting WLQL strings that contain parameter placeholders. In WLQL, the first finder parameter is represented by 0 (as in $0), whereas in EJB QL the parameter is represented by 1 (?1).
Select Methods
Select methods are special finder methods used within the entity bean instance. Select methods are abstract methods that are defined in the entity bean's implementation class AND are defined by an EJB QL query string. Although these select methods are similar to finder methods, they can return values of any cmp-field or cmr-field.
The EJB QL string that is specified for a select methods must have a SELECT clause that designates the result type. Select methods are executed using the instance on which the query is invoked.
EJB QL Conditional Expressions
The following table summarizes conditional expressions that you can use in the WHERE clause of an EJB QL query. For more details on using EJB QL, see the EJB 2.0 specification.
|
EJB QL Expression |
Function |
Sample Syntax |
|---|---|---|
|
[NOT] BETWEEN |
Compares values that are between (or are not between) a range of values. |
WHERE accountId BETWEEN 1000 and 2000 |
|
[NOT] IN |
Selects EJBs that match (or do not match) those in a specified list of string literals. Note that the specified list must contain only string literals. |
WHERE accountId IN ('1000', '1020', '1025') |
|
=, <> |
Selects value that are equal.
|
WHERE accountId = 1000 |
|
[NOT] LIKE |
Selects values based on wildcard symbol (%) in the supplied text_string |
WHERE accountType LIKE `custom%' |
|
IS [NOT] NULL |
Tests for NULL values. |
WHERE accountId IS NOT NULL |
EJB QL Examples
The following excerpts show sample EJB QL strings from the ejb-jar.xml file.
This example returns a collection of AccountBean EJBs whose balance values are greater than the parameter passed to the findBigAccounts method:
<query>
<query-method>
<method-name>findBigAccounts</method-name>
<method-params>
<method-param>double</method-param>
</method-params>
</query-method>
<ejb-ql>
<![CDATA[WHERE balance > ?1]]>
</ejb-ql>
</query>
The following ejb-ql element returns an account balance:
<ejb-ql><![CDATA[WHERE accountType IN ('partners', 'channels')]]></ejb-ql>
The following ejb-ql element returns a collection of EJBs whose accountType field is NULL:
<ejb-ql><![CDATA[WHERE accountType IS NULL]]></ejb-ql>
Migrating from (EJB 1.1) WLQL to (EJB 2.0) EJB QL
If you have used previous versions of WebLogic Server, you may already have container-managed entity EJBs that utilize (EJB 1.1) WLQL for finder methods. This section provides a quick reference to common (EJB 1.1) WLQL operations, and explains how to express those operations using (EJB 2.0) EJB QL. See the EJB 2.0 specification for a complete discussion of WLQL syntax.
|
Sample (EJB 1.1 )WLQL Syntax |
Equivalent (EJB 2.0) EJB QL Syntax |
|---|---|
|
(= operand1 operand2) |
WHERE operand1 = operand2 |
|
(< operand1 operand2) |
WHERE operand1 < operand2 |
|
(> operand1 operand2) |
WHERE operand1 > operand2 |
|
(<= operand1 operand2) |
WHERE operand1 <= operand2 |
|
(>= operand1 operand2) |
WHERE operand1 >= operand2 |
|
(! operand) |
WHERE operand NOT value |
|
(& operand) |
WHERE expression1 AND expression2 |
|
(| operand) |
WHERE expression1 OR expression2 |
|
(like text_string%) |
WHERE operand LIKE `text_string%' |
|
(isNull operand) |
WHERE operand IS NULL |
|
(isNotNull operand) |
WHERE operand IS NOT NULL |
Using WebLogic Query Language Extension
WebLogic Server has a SQL-like language, called WebLogic QL, that works with the Finder expressions and is used to query EJB objects from the RDBMS. The query is defined in the ejb-jar.xml deployment descriptor. The WebLogic specific query extension included in Version 6.0 is ORDERBY.
ORDERBY
The WebLogic Query Language extension, ORDERBY, is a keyword that works with the Finder method to allow you to specify which CMP file you want to use for your selections.
The following example shows the use of the extension, ORDERBY.
ORDERBY
SELECT A from A for Account.Bean
ORDERBY A.id
Container-Managed Relationships
The entity bean relies on container-managed persistence to generate the methods that perform persistent data access for the entity bean instances. The generated methods transfer data between entity bean instances and the underlying resource manager. Persistence is handled by the Container at runtime. The advantage of using container-managed persistence is that the entity bean can be logically independent of the data source in which the entity is stored. The container manages the mapping between the logical and physical relationships at runtime and manages their referential integrity.
Persistent fields and relationships make up the entity bean's abstract persistence schema. The deployment descriptors indicate that the entity bean uses container-managed persistence, and these descriptors are used as input to the container well as data access, is deferred to the container.
Entity beans can have relationships with other beans. These relationships can be either bidirectional or unidirectional. Also, support is provided for local and remote relationships between EJBs. If the EJBs are on the same server and are part of the same .jar file, they can have local relationships. If the EJBs are not on the same server, they must be remote. For a relationship between local beans, multiple column mappings are specified if the key implementing the relation is a compound key. For a remote bean, only a single column-map is specified, since the primary key of the remote bean is opaque. No column-map are specified if the role just specifies a group-name. No group-name is specified if the relationship is remote.
You specify relationships in the ejb-jar.xml file and weblogic-cmp-rdbms-jar.xml. You specify container-managed field mappings in the weblogic-cmp-rdbms-jar.xml.
WebLogic Server supports three types of relationship mappings that are managed by WebLogic RDBMS container-managed persistence (CMP):
A WebLogic Server one-to-one relationship involves the physical mapping from a foreign key in one bean to the primary key in another bean. See Primary Keys for more information on primary keys.
One-to-Many Relationships
A WebLogic Server one -o-many relationship involves the physical mapping from a foreign key in one bean to the primary key of another. However, in a one-to-many relationship, the foreign key is always contained in the role that occupies the "many" side of the relationship.
Many-to-Many Relationships
A WebLogic Server many-to-many relationship involves the physical mapping of a join table. Each row in the join table contains two foreign keys that map to the primary keys of the entities involved in the relationship.
Unidirectional Relationships
Unidrectional relationships can only navigate in one direction. These types of relationships are used with remote beans, and only unidirectional relationships can be remote. A remote bean is one whose abstract persistence schema is not defined in the same ejb-jar file. For example, if entity A and entity B are in a one-to-one, unidirectional relationship and the direction is from entity A to entity B, than entity A is aware of entity B, but entity B is unaware of entity A. This type of relationship is implemented with a cmr-field on the entity bean from which navigation can take place and no related cmr-field on the target entity bean.
Bidirectional Relationships
Bidirectional relationships can be navigated in both directions. These types of container-managed relationships can exist only among beans whose abstract persistence schemas are defined in the same ejb-jar file and therefore managed by the same container. For example, if entity A and entity B are in a one-to-one bidirectional relationship, both are aware of each other.
Primary Keys
The primary key is an object that uniquely identifies an entity bean within its home. The container must be able to manipulate the primary key of an entity bean. The primary key is specified in the deployment descriptor. You can specify a primary key class for an entity bean with container-managed persistence by mapping the primary key to either a single field or to multiple fields in the entity bean class.
A cmp field of the type BigDecimal should not be used as a primary key field for CMP beans. The boolean BigDecimal.equals (object x) method considers two BigDecimal equal only if they are equal in value and scale. This is because there are differences in precision between the Java language and different databases. For example, the method does not consider 7.1 and 7.10 to be equal. Consequently, this method will most likely return false or cause the CMP bean to fail. If you need to use BigDecimal as the primary key, you should:
Foreign Keys
Foreign key columns in the database that are mapped to cmr fields in a bean must allow null values. If not, an error will be thrown by JDBC when a bean instance is created.
Groups
In container-managed persistence, you use groups to specify certain persistent attributes of an entity bean. A field-group represents a subset of the cmp and cmr-fields of a bean. You can out related fields in a bean into groups that are faulted into memory together as a unit. You can associate a group with a query or relationship, so that when a bean is loaded as the result of executing a query or following a relationship, only the fields mentioned in the group are loaded.
A special group named "default" is used for queries and relationships that have no group specified. By default, the default group contains all of a bean's cmp-fields and any cmr-fields that add a foreign key to the persistent state of the bean.
A field can belong to multiple groups. In this case, the getXXX() method for the field will fault in the first group that contains the field.
Field groups are specified in the weblogic-rdbms-cmp-jar.xml file. You use field groups when you want to access a subset of fields.
Specifying Field Groups
Field groups are specified in the weblogic-rdbms-cmp-jar.xml file as follows:
<group-name>financial-data</group-name>
<group-name>medical-data</group-name>
<cmr-field>patient</cmr-field>
<cmr-field>doctors</cmr-fields>
<cmr-field>insurance-providers</cmr-fields>
You use field groups when you want to access a subset of fields.
Using Groups
The field group is an optimizing element that should be used with care because it is possible to corrupt the database.
You have the following cmp fields; A, B, and C.
A and B belong to the same group.
You set up the following scenario:
getA() // loads A and B
modify A
// then an external process modifies the row getC()
Because C is not in the group, there are two possibilities:
In both cases, the database will be corrupted. The reason is that you told the container that within this transaction, that only A and B would be read and instead C also was read. The correct step to take would have been to add C to the group or to specify no groups at all.
Supported Data Types
The following table provides a list of the Java data types for CMP fields used in WebLogic Server and shows how they map to the Oracle extensions for the standard SQL data types.
The SQL CHAR data type should not be used for database columns that are mapped to cmp fields. This is especially important for fields that are part of the primary key, because padding blanks that are returned by the JDBC driver can cause equality comparisons to fail when they should not. Use the SQL VARCHAR data type instead of SQL CHAR.
A cmp field of type byte[] cannot be used as a primary key unless it is wrapped in a user-defined primary key class that provides meaningful equals() and hashCode() methods. This is because the byte[] class does not provide useful equals/hashCode.
|
|
|
Copyright © 2000 BEA Systems, Inc. All rights reserved.
|