| Sun ONE Application Server 7 Developer's Guide to Enterprise Java Beans Technology |
Chapter 4
Using Container-Managed Persistence for Entity BeansThis section contains information on how container-managed persistence works in the Sun ONE Application Server 7 environment. Implementation procedures are included.
Note
To implement container-managed persistence, you should already be familiar with entity beans, which are discussed in "Using Entity Beans".
This section addresses the following topics:
Extensive information on container-managed persistence is contained in chapters 10, 11, and 14 of the Enterprise JavaBeans Specification, v2.0.
Sun ONE Application Server SupportSun ONE Application Server support for container-managed persistence includes:
- Full support for the J2EE v 1.3 specification’s container-managed persistence model.
- Support for commit options B and C for transactions as defined in the Enterprise JavaBeans Specification, v2.0. Refer to "Commit Options" for further information.
- The primary key class must be a subclass of java.lang.Object. This ensures portability, and is noted because some vendors allow primitive types (such as int) to be listed as the primary key class.
- The Sun ONE Application Server container-managed persistence implementation which provides:
- An Object/Relational (O/R) mapping tool (part of the Sun ONE Application Server Assembly Tool) that creates XML deployment descriptors for EJB JAR files that contain beans that use container-managed persistence
- Support for compound (multi-column) primary keys
- Support for sophisticated custom finder methods
- Standards-based query language (EJB QL)
- Container-managed persistence runtime, which supports the following JDBC drivers/databases:
- Support for third-party object-to-relational (O/R) mapping tools. An explanation of the third-party API is contained in "Third-Party Pluggable Persistence Manager API".
About Container-Managed PersistenceAn entity bean using container-managed persistence delegates the management of its state (or persistence) to the Sun ONE Application Server container. Rather than write the JDBC code that is needed to implement bean-managed persistence, a developer implementing container-managed persistence uses tools to create the bean’s deployment descriptors. The deployment descriptors then provide the information that the container uses to map bean fields to columns in a relational database.
An EJB container needs two things to support container-managed persistence:
This section addresses the following container-managed persistence topics:
CMP Components
Unlike bean-managed persistence, container-managed persistence does not require you to write database access calls in the methods of the entity bean class. Because persistence is handled by the container at runtime, you must specify in the deployment descriptor those persistence fields and relationships for which the container must handle data access. You access persistent data using the accessor methods that are defined for the abstract persistence schema.
An entity bean that uses container-managed persistence consists of several components that interoperate:
The following classes are used for container-managed persistence:
Relationships
A relationship allows you to navigate from an object to its related objects. Relationships can be either bidirectional or unidirectional.
- Bidirectional—Each entity bean has a relationship field that refers to the other bean. Through the relationship field, an entity bean's code can access its related object. If an entity bean has a relationship field, we often say it "knows" about its related object.
- Unidirectional—Only one entity bean has a relationship field that refers to the other.
A container-managed relationship (CMR) between fields in a pair of classes allows operations on one side of the relationship to affect the other side. At runtime, if a field in one instance is modified to refer to another instance, the referred instance will have its relationship field modified to reflect the change in relationship.
In the Java code, relationships are represented by object reference (either collections or fields that are typed to an EJB local interface), depending on the relationship cardinality. A relationship can be one-to-one, one-to-many, or many-to-many, depending on the number of instances of each class in the relationship. In the database, this might be represented by foreign key columns and, in the case of many-to-many relationships, join tables.
The following sections describe the various types of relationships:
One-to-One Relationships
With one-to-one relationships, there is a single-valued field in each class whose type is the local interface of the other bean type. Any change to the field on either side of the relationship is handled as a relationship change. If the field on one side is changed from null to non-null, then the field on the other side is changed to refer to this instance. If the field on the other side had been non-null, that other relationship is made null before the change is made.
One-to-Many Relationships
With one-to-many relationships, there is a single-valued field on the many side and a multi-valued field (collection) on the one side.
If an instance is added to the collection field, the field in the new instance is updated to reference the instance containing the collection field. If an instance is deleted from the collection, the field on the instance is nullified.
Any change, addition or removal of a field on the many side is handled as a relationship change. If the field on the many side is changed from null to non-null, this instance is added to the collection-valued field on the one side. If the field on the many side is changed from non-null to null, then this instance is removed from the collection-valued field on the one side.
Many-to-Many Relationships
With many-to-many relationships, there are multi-valued, or collection, fields on both sides of the relationship. Any change to the contents of the collection on either side of the relationship is handled as a relationship change. If an instance is added to the collection on this side, then this instance is added to the collection on the other side. If an instance is removed from a collection on this side, then this instance is removed from the collection on the other side.
Abstract Schema
Part of an entity bean's deployment descriptor, the abstract schema defines the bean's persistent fields and relationships. The term abstract distinguishes this schema from the physical schema of the underlying data store.
You specify the name of an abstract schema in the deployment descriptor. This name is referenced by queries written in the EJB Query Language (EJB QL). For an entity bean using container-managed persistence, you must define an EJB-QL query for every finder method (except findByPrimaryKey). The EJB-QL query determines the query that is executed by the EJB container when the finder method is invoked.
Example
<ejb-relation>
<ejb-relation-name>OrderLineItem</ejb-relation-name>
<ejb-relationship-role>
<ejb-relationship-role-name>
OrderHasLineItems
</ejb-relationship-role-name>
<multiplicity>One</multiplicity>
<relationship-role-source>
<ejb-name>Order</ejb-name>
</relationship-role-source>
<cmr-field>
<cmr-field-name>lineItems</cmr-field-name>
<cmr-field-type>java.util.Collection</cmr-field-type>
</cmr-field>
</ejb-relationship-role>
<ejb-relationship-role>
<ejb-relationship-role-name>
LineItemInOrder
</ejb-relationship-role-name>
<multiplicity>Many</multiplicity>
<relationship-role-source>
<ejb-name>LineItemEJB</ejb-name>
</relationship-role-source>
</ejb-relationship-role>
</ejb-relation>Deployment Descriptors
If your container-managed fields are to be mapped to database fields, you must provide mapping information to the deployer. Each module with container-managed persistence beans must have the following files for the deployment process
- ejb-jar.xml—Contains information such as the transactional attributes of the beans and the fields of a bean that are going to be container-managed.
- sun-ejb-jar.xml—The standard file for assembling enterprise beans. Refer to "Elements in the sun-ejb-jar.xml File" and "Sample EJB XML Files" for information.
- sun-cmp-mappings.xml—The file for mapping container-managed persistence. Refer to "Elements in the sun-cmp-mappings.xml File" and "Sample Schema Definition" for information.
Persistence Manager
In the Sun ONE Application Server, the container-managed persistence model is based on the Pluggable Persistence Manager API which provides the role of the persistence manager in defining and supporting the mapping between an entity bean and the persistence store.
The persistence manager is the component responsible for the persistence of the entity beans installed in the container. The classes provided by the persistence manager vendor are responsible for managing the relationships between the entity beans, and for managing access to their persistent state. The persistence manager vendor is also responsible for providing the implementation of the Java classes that are used in maintaining the container-managed relationships. The persistence manager uses the data source registry provided by the container to access data sources.
The following figure illustrates how persistence works in the Sun ONE Application Server environment.
It is also possible to write custom persistence managers to support legacy systems, or to implement caching strategies that improve performance for your container-managed persistence solution.
Using Container-Managed PersistenceImplementation for entity beans that use container-managed persistence is mostly a matter of mapping and assembly/deployment.
Note
Java types assigned to the container-managed fields must be restricted to the following: Java primitive types, Java serializable types, and references to EJB remote or remote home interfaces.
This section addresses the following topics:
Process Overview
The container-managed persistence process consists of three operations: mapping, deploying, and running. These operations are accomplished as described in the following phases:
Phase 1. Creating the mapping deployment descriptor file
This phase can be done concurrent with development of the container-managed persistence beans in the Sun ONE Studio 4 IDE, or after development while preparing for deployment.
During this phase, you map CMP fields and CMR fields (relationships) to the database. A primary table is selected for each container-managed persistence bean, and optionally, multiple secondary tables. CMP fields are mapped to columns in either the primary or secondary table(s). CMR fields are mapped to pairs of column lists (normally, column lists are the list of columns associated with pairs of primary and foreign keys).
- The mapping is saved in a file which conforms to the sun-cmp-mapping_1_0.dtd. The resulting XML file is packaged with the user-defined bean classes in an EJB JAR file and must be named META-INF/sun-cmp-mappings.xml.
- Errors are reported during the deployment process. Errors may be triggered from within the Sun ONE Studio 4 environment or at the command line.
- The mapping information is developed in conjunction with the database schema file. This file must be captured using the Sun ONE Studio 4 IDE ("Capturing a Schema") or the capture-schema utility ("Using the capture-schema Utility").
- If the database table structure is changed, you first capture the schema of the updated tables after the database administrator updates the tables. You then remap the CMP fields and relationships.
Phase 2. Generating and compiling concrete beans and delegates
This phase is done during deployment of an EJB application to the Sun ONE Application Server. During this phase, deployment information is combined with the mapping information created during Phase 1.
The following files are generated:
The concrete bean implements the EJB life cycle methods ejbSetEntityContext, ejbUnsetEntityContext, ejbCreate, ejbRemove, ejbLoad, ejbStore. It also contains implementation of getXXX and setXXX for each CMP field and the CMR field, ejbFindByPrimaryKey, other finder methods, and any selector methods defined by the user.
Phase 3. Running in the Sun ONE Application Server runtime
At runtime, the information provided at deployment is used to service requests on entities implemented as enterprise beans.
Mapping Capabilities
Mapping refers to the ability to tie an object-oriented model to a relational model of data, usually the schema of a relational database. The container-managed persistence implementation provides the ability to tie a set of interrelated classes containing data and associated behaviors to the interrelated meta-data of the schema. You can then use this object representation of the database to form the basis of a Java application. You can also customize this mapping to optimize these underlying classes for the particular needs of an application.
The result is a single data model through which you can access both persistent database information and regular transient program data. You only need to understand the Java programming language objects; you do not need to know or understand the underlying database schema.
Information on the container-managed persistence DTD and XML file elements is contained in "Elements in the sun-cmp-mappings.xml File".
Mapping Features
The mapping capabilities provided by the Sun ONE Application Server include:
- Mapping a container-managed persistence bean to a single table
- Mapping a container-managed persistence bean to multiple tables
- Mapping container-managed persistence fields to columns
- Mapping container-managed persistence fields to different column types
- Mapping tables with compound primary keys
- Mapping container-managed persistence relationships to foreign key columns
- Mapping tables with overlapping primary and foreign keys
Mapping Tool
The mapping tool generates information that maps the entity bean’s container-managed fields to a data source, such as a column in a relational database table. This mapping information is stored in an XML file.
The meet-in-the-middle mapping of the container-managed persistence implementation creates a custom mapping between an existing schema and existing Java classes, using the Mapping Tool.
Mapping Techniques
A container-managed persistence class should represent a data entity, such as an employee or a department. To model a specific data entity, you add persistent fields to the class that correspond to the columns in the data store.
The simplest kind of modeling is to have a persistence-capable class represent a single table in the data store, with a persistent field for each of the table’s columns. An Employee class, for example, would have persistent fields for all the columns found in the EMPLOYEE table of the data store, such as lastname, firstname, department, and salary.
Note
You can choose to have only a subset of the data store columns used as persistent fields, but if a field is persistent, it must be mapped.
Information on how to use Sun ONE Studio 4 to map container-managed persistence for enterprise beans is contained in the Sun ONE Application Server Integration Module for the Sun ONE Studio 4 online help.
Supported Data Types for Mapping
Container-managed persistence supports a set of JDBC 1.0 SQL data types that are used in mapping Java data fields to SQL types. Supported JDBC 1.0 SQL data types are listed in the following table.
Supported JDBC 1.0 SQL Data Types
BIGINT
DOUBLE
SMALLINT
BIT
FLOAT
TIME
BLOB
INTEGER
TIMESTAMP
CHAR
LONGVARCHAR
TINYINT
DATE
NUMERIC
VARCHAR
DECIMAL
REAL
The following table contains suggested mappings.
BLOB Support
Binary Large Object (BLOB) is a data type used to store and retrieve complex object fields. BLOBs are binary or serializable objects, such as pictures, that translate into large byte arrays which are then serialized into CMP fields.
Note
On Oracle, using the Oracle thin driver (JDBC type 4), it is not possible to insert more than 2000 bytes of data into a column. To circumvent this problem, use the OCI driver (JDBC type 2).
To enable BLOB support in the Sun ONE Application Server environment:
Example
<cmp-field-mapping>
<field-name>syllabus</field-name>
<column-name>COURSE.SYLLABUS</column-name>
</cmp-field-mapping>Example
/******************************************************
Serializable class Syllabus : BLOB Testing
******************************************************/package collegeinfo
public class Syllabus implements java.io.Serializable
{
public String author;
public String syllabi;
}Schema for Course:
table course
------------
courseId Number
deptId Number
courseName Varchar
syllabus BLOBUsing the capture-schema Utility
Mapping information is developed by first capturing the database schema. Use the capture-schema command to store the database metadata (schema) in a file for use in mapping and execution. You can also use the Sun ONE Studio (formerly Forte for Java) IDE to capture the database schema; refer to "Capturing a Schema".
Syntax
capture-schema -dburl url -username name -password password -driver ajdbcdriver [-schemaname name] [-table TableName]* [-out filename]
Where:
-dburl url: Specifies the JDBC URL expected by the driver for accessing a database.
-username name: Specifies the user name for authenticating access to a database.
-password password: Specifies the password for accessing the selected database.
-driver ajdbcdriver: Specifies the JDBC driver class name. This class must be in your CLASSPATH.
-schemaname name: Specifies the name of the user schema being captured. If not specified, the default will capture metadata for all tables from all the schemas accessible to this user.
Note
Specifying this parameter is highly recommended. If more than one schema is accessible for this user, more than one table with the same name might be captured, which will cause problems.
-table TableName: Specifies a table name. Multiple table names can be specified. If not specified, all the tables in the database schema will be captured.
-out: Specifies the output target. Defaults to stdout. To be able to use the output for the CMP mapping, the output file name must have the .dbschema suffix.
For container-managed persistence mapping, the -out parameter correlates to the schema subelement of the sun-cmp-mapping element in the sun-cmp-mapping_1_0.dtd file:
<!ELEMENT sun-cmp-mapping ( schema, entity-mapping+) >
In the sun-cmp-mappings.xml file, this element must be represented without the .dbschema suffix. For example:
<schema>RosterSchema</schema>
Example
capture-schema -dburl jdbc:pointbase:server://localhost:9092/sample -username public -password public -driver com.pointbase.jdbc.jdbcUniversalDriver -out RosterSchema.dbschema
Mapping Fields and Relationships
This section discusses how to map the fields and relationships of your entity beans by editing the sun-cmp-mappings.xml deployment descriptor. This can be done either manually (provided you are proficient in editing XML) or using the Sun ONE Application Server assembly and deployment tools.
A container-managed persistence bean has a name, a primary table, one or more fields, zero or more relationships, and zero or more secondary tables, plus flags for consistency checking. You will need to map the CMP fields and CMR fields to the database using the elements in the sun-cmp-mappings.xml file. CMP fields are mapped to columns in either the primary or secondary database table(s); CMR fields are mapped to pairs of column lists.
An alphabetic listing of the mapping elements in the container-managed persistence deployment descriptors is contained in "Elements in the sun-cmp-mappings.xml File". A sample XML file is contained in "Sample Schema Definition".
This section contains instructions for accomplishing the following mapping tasks:
Specifying the Beans to Be Mapped
You must start by using the following elements to specify the database schema and the container-managed persistence beans being mapped:
sun-cmp-mappings
Specifies the collection of subelements for all the beans that will be mapped in an EJB JAR collection.
Subelement is sun-cmp-mapping.
Example
Refer to "Sample Schema Definition".
sun-cmp-mapping
Specifies beans mapped to a particular schema.
Subelements are schema, entity-mapping.
schema
Specifies the path to the schema file. Only one is required. For further information, refer to "Sample EJB QL Queries" and "Capturing a Schema".
Example
<schema>RosterSchema</schema>
entity-mapping
Specifies the mapping of beans to database columns.
Subelements are ejb-name, table-name, cmp-field-mapping, cmr-field-mapping, secondary-table, consistency.
Example
For an example, see "entity-mapping".
Specifying the Mapping Components
The next step is to use the following elements to specify components that are part of the mapping, and to indicate how consistency checking will occur.
entity-mapping
Specifies the mapping of beans to database columns.
Subelements are ejb-name, table-name, cmp-field-mapping, cmr-field-mapping, secondary-table, consistency.
Example
<entity-mapping>
<ejb-name>Player</ejb-name>
<table-name>PLAYER</table-name>
<cmp-field-mapping>
<field-name>salary</field-name>
<column-name>PLAYER.SALARY</column-name>
</cmp-field-mapping>
<cmp-field-mapping>
<field-name>playerId</field-name>
<column-name>PLAYER.PLAYER_ID</column-name>
</cmp-field-mapping>
<cmp-field-mapping>
<field-name>position</field-name>
<column-name>PLAYER.POSITION</column-name>
</cmp-field-mapping>
<field-name>name</field-name>
<column-name>PLAYER.NAME</column-name>
</cmp-field-mapping>
<cmr-field-mapping>
<cmr-field-name>teamId</cmr-field-name>
<column-pair>
<column-name>PLAYER.PLAYER_ID</column-name>
<column-name>TEAMPLAYER.PLAYER_ID</column-name>
</column-pair>
<column-pair>
<column-name>TEAMPLAYER.TEAM_ID</column-name>
<column-name>TEAM.TEAM_ID</column-name>
</column-pair>
</cmr-field-mapping>
</entity-mapping>ejb-name
Specifies the name of the entity bean in the ejb-jar.xml file to which the container-managed persistence beans relates. One is required.
Example
<ejb-name>Player</ejb-name>
table-name
Specifies the name of a database table. The table must be present in the database schema file. One is required.
Example
<table-name>PLAYER</table-name>
secondary-table
Specifies a bean’s secondary table(s). Optional.
Subelements are table-name, column-pair.
Example
This secondary table example adds an email field in the StudentEjb class.
public abstract class StudentEJB implements EntityBean {
/***************************************************
Write ur set,get methods for Entity bean variables and
business methods here
***************************************************/
//Access methods for CMP fields
public abstract Integer getStudentId();
public abstract void setStudentId(Integer studentId);
public abstract String getStudentName();
public abstract void setStudentName(String studentName);public abstract void setEmail(String Email); <-----Column from
Secondary TableThe Student and the Email table should be related by a foreign key. The schema for the Email table may look like this:
Table Email:
------------
Student_id Number
email varcharTable Student:
--------------
StudentId Number
StudentName varchar
deptId Number
AddressId Number
AccountId VarcharWhen adding the secondary table, the tables will both apply to the same enterprise bean.
consistency
Specifies container behavior in guaranteeing transactional consistency of the data in the bean. Optional. If the consistency checking flag element is not present, none is assumed.
The following table describes the elements used for consistency checking.
Specifying Field Mappings
Field mapping is done using the following elements:
cmp-field-mapping
The cmp-field-mapping element associates a field with one or more columns that it maps to. The column can be from a bean’s primary table or any defined secondary table. If a field is mapped to multiple columns, the column listed first is used as a SOURCE for getting the value from the database. The columns are updated in the order they appear. There is one cmp-field-mapping element for each cmp-field element defined in the EJB JAR file.
A field can be marked as read-only.
Subelements are field-name, column-name, read-only, and fetched-with.
Example
<cmp-field-mapping>
<field-name>name</field-name>
<column-name>LEAGUE.NAME</column-name>
</cmp-field-mapping>field-name
Specifies the Java identifier of a field. This identifier must match the value of the field-name subelement of the cmp-field that is being mapped. One is required.
Example
<field-name>name</field-name>
column-name
Specifies the name of a column from the primary table, or the table qualified name (TABLE.COLUMN) of a column from a secondary or related table. One or more is required.
Example
<column-name>PLAYER.NAME</column-name>
Example
Use this with non-normalized tables where the same information appears in multiple places, and the information needs to be kept synchronized if it is updated.
public abstract class StudentEJB implements EntityBean {
.
.
.
public abstract String getInstallments();The three columns from the student table can be mapped to a single installments column in the Student enterprise bean.
Table student:
.
.
.
installment1 Number
installment2 Number
installment3 NumberThe same value will be written to all the columns in the database.
read-only
The read-only flag indicates that a field is read-only.
Example
<read-only>name</read-only>
fetched-with
Specifies the fetch group configuration for fields and relationships. A field may participate in a hierarchical or independent fetch group. Optional.
The fetched-with element has different default values based on its context.
Subelements are level, named-group, or none.
level
Specifies the name of a hierarchical fetch group. The value must be an integer. Fields and relationships that belong to a hierarchical fetch group of equal (or lesser) value are fetched at the same time. The value of level must be greater than zero. Only one is allowed.
named-group
Specifies the name of an independent fetch group. All the fields and relationships that are part of a named group are fetched at the same time. Only one is allowed.
none
A consistency level flag that indicates that this field or relationship is fetched by itself.
Specifying Relationships
The following elements are used to specify the mapping for container-managed relationships:
cmr-field-mapping
A container-managed relationship field has a name and one or more column pairs that define the relationship. There is one cmr-field-mapping element for each cmr-field. A relationship can also participate in a fetch group.
Subelements are cmr-field-name, column-pair, fetched-with.
Example
<cmr-field-mapping>
<cmr-field-name>teamId</cmr-field-name>
<column-pair>
<column-name>PLAYER.PLAYER_ID</column-name>
<column-name>TEAMPLAYER.PLAYER_ID</column-name>
</column-pair>
<column-pair>
<column-name>TEAM.TEAM_ID</column-name>
<column-name>TEAMPLAYER.TEAM_ID</column-name>
</column-pair>
<fetched-with>
<none/>
</fetched-with>
</cmr-field-mapping>cmr-field-name
Specifies the Java identifier of a field. This must match the value of the cmr-field-name subelement of the cmr-field that is being mapped. One is required.
Example
<cmr-field-name>team</cmr-field-name>
column-pair
Specifies the pair of related columns in two database tables. One or more is required.
The columns names are specified in the column-name element.
Example
<column-pair>
<column-name>PLAYER.PLAYER_ID</column-name>
<column-name>TEAMPLAYER.PLAYER_ID</column-name>
</column-pair>column-name
Specifies the name of a column from the primary table, or the table qualified name (TABLE.COLUMN) of a column from a secondary or related table. Two are required as subelements of a column-pair.
Example
<column-name>PLAYER.NAME</column-name>
fetched-with
Specifies the fetch group configuration for fields and relationships. A field may participate in a hierarchical or independent fetch group. Optional.
The fetched-with element has different default values based on its context.
Subelements are level, named-group, or none.
Configuring the Resource Manager
The resource manager used by the container-managed persistence implementation is PersistenceManagerFactory, which is configured using the Sun ONE Application Server DTD file, sun-server_7_0-0.dtd.
Refer to the Sun ONE Application Server Administrator’s Guide for information on creating a new persistence manager.
To deploy an EJB module that contains container-managed persistence beans, you need to add the following information to the sun-ejb-jar.xml deployment descriptor.
- Specify the Persistence Manager to be used for the deployment:
<pm-descriptors>
<pm-descriptor>
<pm-identifier>SunONE</pm-identifier>
<pm-version>1.0</pm-version>
<pm-class-generator>com.iplanet.ias.persistence.internal.ejb.ejbc.J DOCodeGenerator
</pm-class-generator>
<pm-mapping-factory>com.iplanet.ias.cmp.
NullFactory</pm-mapping-factory>
</pm-descriptor
<pm-inuse>
<pm-identifier>SunONE</pm-identifier>
<pm-version>1.0</pm-version>
</pm-inuse>
</pm-descriptors>- Specify the JNDI name of the Persistence Manager's resource (listed under persistence-manager-factory-resource entry in the server.xml file) and the JNDI name for cmp-resource. This name will be used at run time to manage persistent resources.
For example, if you have the following entry in the server.xml file:
<persistence-manager-factory-resource
factory-class="com.sun.jdo.spi.persistence.support.
sqlstore.impl.PersistenceMan
gerFactoryImpl"
enabled="true"
jndi-name="jdo/pmf"
jdbc-resource-jndi-name="jdo/pmfPM"
</persistence-manager-factory-resource>Set the CMP resource as:
<cmp-resource>
<jndi-name>jdo/pmf</jndi-name
</cmp-resource>
Using EJB QL
The Enterprise JavaBeans Specification, v2.0 specifies a new query language (EJB QL) that can be used to define portable queries for the finder and select methods of CMP beans. These queries use a SQL-like syntax to select entity objects or field values based on the abstract schema types and relationships of CMP beans.
Finder methods are defined in the home and/or local home interfaces of the bean, and return instances of the same bean. Select methods are defined only in the abstract bean class, and can be used for selecting entity objects of any local or remote type as well as field values for beans from the same schema.
For more information, refer to the Chapter 11, "EJB QL: EJB Query Language for Container-Managed Persistence Query Methods" in the Enterprise JavaBeans Specification, v2.0.
Some EJB QL sample queries are contained in "Sample EJB QL Queries".
Configuring Queries for 1.1 Finders
The Enterprise JavaBeans Specification, v1.1 spec does not specify the format of the finder method description. The Sun ONE Application Server uses Java Data Objects Query Language (JDOQL) queries to implement finder and selector methods. For EJB 2.0, the container automatically maps an EJB QL query to JDOQL. For EJB 1.1, this mapping is partially done by the developer. You can specify the following elements of the underlying JDOQL query:
- Filter expression—A Java-like expression that specifies a condition that each object returned by the query must satisfy. Corresponds to the WHERE clause in EJB QL.
- Query parameter declaration—Specifies the name and the type of one or more query input parameters. Follows the syntax for formal parameters in the Java language.
- Query variable declaration—Specifies the name and type of one or more query variables. Follows the syntax for local variables in the Java language. Query variables might be used in the filter to implement joins.
The Sun ONE Application Server-specific deployment descriptor (sun-ejb-jar.xml) provides the following elements to store the EJB 1.1 finder method settings:
The Sun ONE Application Server constructs a JDOQL query using the persistence capable class of the EJB 1.1 entity bean as the candidate class. It adds the filter, parameter declarations, and variable declarations as specified by the developer to the JDOQL query. It executes the query and passes the parameters of the finder method to the execute call. The objects from the JDOQL query result set are converted into primary key instances to be returned by the EJB 1.1 ejbFind method.
The JDO specification (see JSR 12) provides a comprehensive description of JDOQL. The following information summarizes the elements used to define EJB 1.1 finders.
Query Filter Expression
The filter expression is a String containing a boolean expression evaluated for each instance of the candidate class. If the filter is not specified, it defaults to true. Rules for constructing valid expressions follow the Java language, with the following differences:
- Equality and ordering comparisons between primitives and instances of wrapper classes are valid.
- Equality and ordering comparisons of Date fields and Date parameters are valid.
- Equality and ordering comparisons of String fields and String parameters are valid.
- White space (non-printing characters space, tab, carriage return, and line feed) is a separator and is otherwise ignored.
- The following assignment operators are not supported:
- Methods, including object construction, are not supported, except for:
- Navigation through a null-valued field, which would throw NullPointerException, is treated as if the subexpression returned false.
The following expressions are supported:
- Parentheses to explicitly mark operator precedence
- Cast operator
- Promotion of numeric operands for comparisons and arithmetic operations. The rules for promotion follow the Java rules (see the numeric promotions of the Java language specification) extended by BigDecimal, BigInteger, and numeric wrapper classes.
Query Parameter
The parameter declaration is a String containing one or more parameter type declarations separated by commas. This follows the Java syntax for method signatures.
Query Variables
The type declarations follow the Java syntax for local variable declarations.
Example1
The following query returns all players called Michael. It defines a filter that compares the name field with a string literal:
The finder element of the sun-ejb-jar.xml file would look like this:
<finder>
<method-name>findPlayerByName</method-name>
<query-filter>name == "Michael"</query-filter>
</finder>Example 2
This query returns all products in a specified price range. It defines two query parameters which are the lower and upper bound for the price: double low, double high. The filter compares the query parameters with the price field:
The finder element of the sun-ejb-jar.xml file would look like this:
<finder>
<method-name>findInRange</method-name>
<query-params>double low, double high</query-params>
<query-filter>low < price && price <
high</query-filter
</finder>Example 3
This query returns all players having a higher salary than the player with the specified name. It defines a query parameter for the name java.lang.String name. Furthermore, it defines a variable for the player to compare with. It has the type of the persistence capable class that corresponds to the bean:
mypackage.PlayerEJB_170160966_JDOState p
The filter compares the salary of the current player denoted by this keyword with the salary of the player with the specified name:
(this.salary > p.salary) && (p.name == name)
The finder element of the sun-ejb-jar.xml file would look like:
<finder>
<method-name>findByHigherSalary</method-name>
<query-params>java.lang.String name</query-params>
<query-filter>
(this.salary > p.salary) &&
(p.name ==name)
</query-filter>
<query-variables></query-variables
</finder>
Third-Party Pluggable Persistence Manager API
Container-managed persistence in the EJB container can support persistence vendors integrating their runtimes into the Sun ONE Application Server using the Sun ONE Application Server Pluggable Persistence Manager API. The API describes integration requirements at deployment, at code-generation, and at runtime. It supports callouts to implement the concrete bean implementations when EJBs are compiled.
The Sun ONE Application Server enables the container-managed persistence implementation to use its startup framework to load classes and to register the persistence manager. The Pluggable Persistence Manager API also supports integration requirements with regard to transactions and dynamic deployment.
In general, the objective is that any third-party container-managed persistence solution that fully supports the Enterprise JavaBeans Specification, v2.0 can be made to work with the Sun ONE Application Server.
To use a third-party tool:
Third-party persistence tools must use Java Database Connectivity (JDBC) resources or Java Connector API (JCA) resources at runtime to access relational data sources. This allows the pluggable persistence managers to automatically use the Connection Pooling, transaction handling, and security management features of the container. Third-party vendors will be able to plug in their concrete class generators and their mapping factory to generate a valid vendor-specific mapping object model.
The configuration requirements specify a number of properties which must be defined for a bean, including:
Restrictions and OptimizationsThis section discusses any restrictions and performance optimizations you should be aware of in implementing container-managed persistence for entity beans.
Unique Database Schema Names in EAR File
In a situation where there are multiple JAR files within an EAR file, for example jar1 and jar2, any corresponding database schema files for jar1 and jar2 must have unique fully qualified names.
In other words, the database schema file names must be unique in a given EAR file.
Limitations on Container-Managed Persistence Protocol
- Data aliasing problems—If container-managed fields of multiple entity beans map to the same data item in the underlying database, the entity beans may see an inconsistent view of the data item if the multiple entity beans are invoked in the same transaction.
- Eager loading of state—The container loads the entire entity object state into the container-managed fields before invoking the ejbLoad method of the abstract bean. This approach may not be optimal for entity objects with large state if most business methods require access to only parts of the state. If this is an issue, use the <fetched-with> element for fields that are used infrequently.
Restrictions on Remote Interfaces
The following restrictions apply to the remote interface of an entity bean that uses container-managed persistence:
Dependent value classes can be exposed in the remote interface or remote home interface, and can be included in the client EJB JAR file.
Elements in the sun-cmp-mappings.xml File"Assembling and Deploying Enterprise Beans", provides general information and guidelines on assembling your enterprise beans for deployment. Additional deployment information and instructions are contained in the Sun ONE Application Server Developer’s Guide.
"Persistence Elements" provides information on the information on persistence-related elements in the sun-ejb-jar.xml file.
A sample XML file is contained in "Sample Schema Definition".
This section describes the elements in the sun-cmp-mappings.xml file:
check-all-at-commit
This flag is not implemented for Sun ONE Application Server 7.
Subelements
none
check-modified-at-commit
A consistency level flag that indicates to check modified bean instances at commit time.
Subelements
none
cmp-field-mapping
The cmp-field-mapping element associates a field with one or more columns that it maps to. The column can be from a bean’s primary table or any defined secondary table. If a field is mapped to multiple columns, the column listed first is used as a SOURCE for getting the value from the database. The columns are updated in the order they appear. There is one cmp-field-mapping element for each cmp-field element defined in the EJB JAR file.
A field can be marked as read-only.
A field may participate in a fetch group if the fetched-with element is not specified. The following is assumed:
<fetched-with><level>0</level></fetched-with>
Subelements
The following table describes subelements for the cmp-field-mapping element.
cmr-field-mapping
A container-managed relationship field has a name and one or more column pairs that define the relationship. There is one cmr-field-mapping element for each cmr-field. A relationship can also participate in a fetch group.
If the fetched-with element is not present, the following value is assumed: <fetched-with><none/></fetched-with>.
Subelements
The following table describes subelements for the cmr-field-mapping element.
cmr-field-name
Specifies the Java identifier of a field. Must match the value of the cmr-field-name subelement of the cmr-field that is being mapped.
Subelements
none
column-name
Specifies the name of a column from the primary table, or the table qualified name (TABLE.COLUMN) of a column from a secondary or related table. One is required.
Subelements
none
column-pair
The name of the pair of related columns in two database tables. One is required.
Subelements
The following table describes subelements for the column-pair element.
consistency
Specifies container behavior in guaranteeing transactional consistency of the data in the bean. Optional. If the consistency checking flag element is not present, none is assumed.
Subelements
The following table describes the elements used for consistency checking.
ejb-name
Specifies the name of the entity bean in the ejb-jar.xml file to which the container-managed persistence beans relates. One is required.
Subelements
none
entity-mapping
Specifies the mapping a bean to database columns.
Subelements
The following table describes subelements for the entity-mapping element.
fetched-with
Specifies the fetch group configuration for fields and relationships. Optional.
A field may participate in a hierarchical or independent fetch group. If the fetched-with element is not present, the following value is assumed: <fetched-with><none/></fetched-with>.
Subelements
The following table describes subelements for the fetched-with element.
field-name
Specifies the Java identifier of a field. This identifier must match the value of the field-name subelement of the cmp-field that is being mapped. One is required.
Subelements
none
level
Specifies a hierarchical fetch group. The value of this element must be an integer. Fields and relationships that belong to a hierarchical fetch group of equal (or lesser) value are fetched at the same time. The value of level must be greater than zero. Only one is allowed.
Subelements
none
lock-when-loaded
A consistency level flag that indicates a lock will be implemented when the data is loaded.
Subelements
none
lock-when-modified
This flag is not implemented for Sun ONE Application Server 7.
Subelements
none
named-group
Specifies the name of an independent fetch group. All the fields and relationships that are part of a named group are fetched at the same time. One is allowed.
Subelements
none
none
A consistency level flag that indicates that this field or relationship is fetched with no other fields or relationships, or it specifies the fetched-with semantics.
Subelements
none
read-only
Flag that indicates a field is read-only.
Subelements
none
schema
Specifies the path to the schema file. Only one is required. For further information, refer to "Capturing a Schema"
Subelements
none
secondary-table
Specifies a bean’s secondary table(s).
Subelements
The following table describes subelements for the secondary-table element.
sun-cmp-mapping
Specifies beans mapped to a particular schema.
Note
A bean cannot be related to a bean that maps to a different schema, even if the beans are deployed in the same EJB JAR file.
Subelements
The following table describes subelements for the sun-cmp-mapping element.
Table 4-10 sun-cmp-mapping Subelements
Subelement
Required
Description
only one
Specifies the path to the schema file.
one or more
Specifies the mapping of beans to database columns.
sun-cmp-mappings
Specifies the collection of subelements for all the beans that will be mapped in an EJB JAR collection.
Subelements
The following table describes subelements for the sun-cmp-mappings element.
Table 4-11 sun-cmp-mappings Subelements
Subelement
Required
Description
one or more
Specifies beans mapped to a particular schema.
table-name
Specifies the name of a database table. The table must be present in the database schema file. One is required.
Subelements
none
ExamplesThe following examples are contained in this section:
Sample Schema Definition
CREATE TABLE Player
(
player_Id VARCHAR(255) PRIMARY KEY,
name VARCHAR(255) ,
position VARCHAR(255) ,
salary DOUBLE PRECISION NOT NULL ,
picture BLOB,
);CREATE TABLE League
(
league_Id VARCHAR(255) PRIMARY KEY,
name VARCHAR(255) ,
sport VARCHAR(255) ,
);CREATE TABLE Team
(
team_Id VARCHAR(255) PRIMARY KEY,
city VARCHAR(255) ,
name VARCHAR(255) ,
league_Id VARCHAR(255) ,
FOREIGN KEY (league_Id) REFERENCES League (league_Id) ,
);CREATE TABLE TeamPlayer
(
player_Id VARCHAR(255) ,
team_Id VARCHAR(255),
CONSTRAINT pk_TeamPlayer PRIMARY KEY (player_Id , team_Id) ,
FOREIGN KEY (team_Id) REFERENCES Team (team_Id),
FOREIGN KEY (player_Id) REFERENCES Player (player_Id) ,
);Sample CMP Mapping XML File
For information on these elements, refer to "Elements in the sun-cmp-mappings.xml File".
The following sample mapping file would have the name META-INF/sun-cmp-mappings.xml in a deployable EJB JAR file:
<?xml version="1.0" encoding="UTF-8"?>
<sun-cmp-mappings>
<sun-cmp-mapping>
<schema>RosterSchema</schema>
<entity-mapping>
<ejb-name>League</ejb-name>
<table-name>LEAGUE</table-name>
<cmp-field-mapping>
<field-name>name</field-name>
<column-name>LEAGUE.NAME</column-name>
</cmp-field-mapping>
<cmp-field-mapping>
<field-name>leagueId</field-name>
<column-name>LEAGUE.LEAGUE_ID</column-name>
</cmp-field-mapping>
<cmp-field-mapping>
<field-name>sport</field-name>
<column-name>LEAGUE.SPORT</column-name>
</cmp-field-mapping>
<cmr-field-mapping>
<cmr-field-name>team</cmr-field-name>
<column-pair>
<column-name>LEAGUE.LEAGUE_ID</column-name>
<column-name>TEAM.LEAGUE_ID</column-name>
</column-pair>
</cmr-field-mapping>
</entity-mapping>
<entity-mapping>
<ejb-name>Team</ejb-name>
<table-name>TEAM</table-name>
<cmp-field-mapping>
<field-name>name</field-name>
<column-name>TEAM.NAME</column-name>
</cmp-field-mapping>
<cmp-field-mapping>
<field-name>city</field-name>
<column-name>TEAM.CITY</column-name>
</cmp-field-mapping>
<cmp-field-mapping>
<field-name>teamId</field-name>
<column-name>TEAM.TEAM_ID</column-name>
</cmp-field-mapping>
<cmr-field-mapping>
<cmr-field-name>playerId</cmr-field-name>
<column-pair>
<column-name>TEAM.TEAM_ID</column-name>
<column-name>TEAMPLAYER.TEAM_ID</column-name>
</column-pair>
<column-pair>
<column-name>TEAMPLAYER.PLAYER_ID</column-name>
<column-name>PLAYER.PLAYER_ID</column-name>
</column-pair>
<fetched-with>
<none/>
</fetched-with>
</cmr-field-mapping>
<cmr-field-mapping>
<cmr-field-name>leagueId</cmr-field-name>
<column-pair>
<column-name>TEAM.LEAGUE_ID</column-name>
<column-name>LEAGUE.LEAGUE_ID</column-name>
</column-pair>
<fetched-with>
<none/>
</fetched-with>
</cmr-field-mapping>
</entity-mapping>
<entity-mapping>
<ejb-name>Player</ejb-name>
<table-name>PLAYER</table-name>
<cmp-field-mapping>
<field-name>salary</field-name>
<column-name>PLAYER.SALARY</column-name>
</cmp-field-mapping>
<cmp-field-mapping>
<field-name>playerId</field-name>
<column-name>PLAYER.PLAYER_ID</column-name>
</cmp-field-mapping>
<cmp-field-mapping>
<field-name>position</field-name>
<column-name>PLAYER.POSITION</column-name>
</cmp-field-mapping>
<cmp-field-mapping>
<field-name>name</field-name>
<column-name>PLAYER.NAME</column-name>
</cmp-field-mapping>
<cmr-field-mapping>
<cmr-field-name>teamId</cmr-field-name>
<column-pair>
<column-name>PLAYER.PLAYER_ID</column-name>
<column-name>TEAMPLAYER.PLAYER_ID</column-name>
</column-pair>
<column-pair>
<column-name>TEAMPLAYER.TEAM_ID</column-name>
<column-name>TEAM.TEAM_ID</column-name>
</column-pair>
</cmr-field-mapping>
</entity-mapping>
</sun-cmp-mapping>
</sun-cmp-mappings>Sample EJB QL Queries
<query>
<description></description>
<query-method>
<method-name>findAll</method-name>
<method-params />
</query-method>
<ejb-ql>select object(l) from League l</ejb-ql>
</query><query>
<description></description>
<query-method>
<method-name>findByName</method-name>
<method-params>
<method-param>java.lang.String</method-param>
</method-params>
</query-method>
<ejb-ql>select object(l) from League l where l.name = ?1</ejb-ql>
</query><query>
<description></description>
<query-method>
<method-name>findByPosition</method-name>
<method-params>
<method-param>java.lang.String</method-param>
</method-params>
</query-method>
<ejb-ql>select distinct object(p) from Player p where p.position = ?1</ejb-ql>
</query><query>
<description>Selector returning SET</description>
<query-method>
<method-name>ejbSelectTeamsCity</method-name>
<method-params>
<method-param>team.LocalLeague</method-param>
</method-params>
</query-method>
<ejb-ql>select distinct t.city from Team t where t.league = ?1</ejb-ql>
</query><query>
<description>Selector returning single object LocalInterface</description>
<query-method>
<method-name>ejbSelectTeamByCity</method-name>
<method-params>
<method-param>java.lang.String</method-param>
</method-params>
</query-method>
<result-type-mapping>Local</result-type-mapping>
<ejb-ql>select distinct Object(t) from League l, in(l.teams) as t where t.city = ?1</ejb-ql>
</query><query>
<description>Selector returning single object String</description>
<query-method>
<method-name>ejbSelectTeamsNameByCity</method-name>
<method-params>
<method-param>java.lang.String</method-param>
</method-params>
</query-method>
<ejb-ql>select distinct t.name from League l, in(l.teams) as t where t.city = ?1</ejb-ql>
</query><query>
<description>Selector returning Set using multiple collection declarations</description>
<query-method>
<method-name>ejbSelectPlayersByLeague</method-name>
<method-params>
<method-param>team.LocalLeague</method-param>
</method-params>
</query-method>
<result-type-mapping>Local</result-type-mapping>
<ejb-ql>select Object(p) from League l, in(l.teams) as t, in(t.players) p where l = ?1</ejb-ql>
</query><query>
<description>Selector single object int</description>
<query-method>
<method-name>ejbSelectSalaryOfPlayerInTeam</method-name>
<method-params>
<method-param>team.LocalTeam</method-param>
<method-param>java.lang.String</method-param>
</method-params>
</query-method>
<ejb-ql>select p.salary from Team t, in(t.players) as p where t = ?1 and p.name = ?2</ejb-ql>
</query><query>
<description>Finder using the IN Expression</description>
<query-method>
<method-name>findByPositionsGoalkeeperOrDefender</method-name>
<method-params/>
</query-method>
<ejb-ql>select object(p) from Player p where p.position IN ('goalkeeper', 'defender')</ejb-ql>
</query><query>
<description>Finder using the LIKE Expression</description>
<query-method>
<method-name>findByNameEndingWithON</method-name>
<method-params/>
</query-method>
<ejb-ql>select object(p) from Player p where p.name LIKE '%on'</ejb-ql>
</query><query>
<description>Finder using the IS NULL Expression</description>
<query-method>
<method-name>findByNullName</method-name>
<method-params/>
</query-method>
<ejb-ql>select object(p) from Player p where p.name IS NULL</ejb-ql>
</query><query>
<description>Finder using the MEMBER OF Expression</description>
<query-method>
<method-name>findByTeam</method-name>
<method-params>
<method-param>team.LocalTeam</method-param>
</method-params>
</query-method>
<ejb-ql>select object(p) from Player p where ?1 MEMBER p.teams</ejb-ql>
</query><query>
<description>Finder using the ABS function</description>
<query-method>
<method-name>findBySalarayWithArithmeticFunctionABS</method-name>
<method-params>
<method-param>double</method-param>
</method-params>
</query-method>
<ejb-ql>select object(p) from Player p where p.salary = ABS(?1)</ejb-ql>
</query><query>
<description>Finder using the SQRT function</description>
<query-method>
<method-name>findBySalarayWithArithmeticFunctionSQRT</method-name>
<method-params>
<method-param>double</method-param>
</method-params>
</query-method>
<ejb-ql>select object(p) from Player p where p.salary = SQRT(?1)</ejb-ql>
</query>
