Previous Contents Index Next |
Sun Java System Application Server Standard and Enterprise Edition 7 2004Q2 Developer's Guide to Enterprise JavaBeans Technology

> ## Chapter 4
> Using Container-Managed Persistence for Entity Beans

> This section contains information on how container-managed persistence works in the Sun Java System Application Server 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” on page 61.

> This section addresses the following topics:

> - Sun Java System Application Server Support
> - About Container-Managed Persistence
> - Using Container-Managed Persistence
> - Third-Party Pluggable Persistence Manager API
> - Restrictions and Optimizations
> - Elements in the sun-cmp-mappings.xml File
> - Examples

> Extensive information on container-managed persistence is contained in chapters 10, 11, and 14 of the Enterprise JavaBeans Specification, v2.0.

> ##

> Sun Java System Application Server Support

> Sun Java System 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” on page 153 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 Java System Application Server container-managed persistence implementation which provides:
> - An Object/Relational (O/R) mapping tool (part of the Sun Java System 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 support. The following JDBC driver and database combinations are supported for Sun Java System Application Server Standard and Enterprise Editions 7.1. The combinations listed here have been tested with the Sun Java System Application Server and are found to be J2EE compatible.
> - Data Direct Connect JDBC3.0/ Type4 Driver for Oracle 8.1.7 Databases

> For an up to date list of the JDBC drivers currently supported by the Sun Java System Application Server, see the Sun Java System Application Server 7.1 Platform Summary.

> Other JDBC drivers have been used with Sun Java System Application Server 7.1, but J2EE compliance tests have not been completed with these drivers.

> - Oracle 8i, Oracle 9
> - Sybase 12
> - Microsoft SQLServer 2000
> - Pointbase 4.2
> - 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 Persistence

> An entity bean using container-managed persistence delegates the management of its state (or persistence) to the Sun Java System 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:

> - Mapping—Information on how to map an entity bean to a resource, such as a table in a relational database
> - Runtime environment—A container-managed persistence runtime environment that uses the mapping information to perform persistence operations on each bean

> This section addresses the following container-managed persistence topics:

> - CMP Components
> - Relationships
> - Abstract Schema
> - Deployment Descriptors
> - Persistence Manager

> ### 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 abstract bean class, written by you.
> - The remote interface, written by you.
> - The local interface, written by you.
> - The deployment descriptor, written by you.
> - An optional primary key class, written by you.
> - The concrete bean class, generated by the container-managed persistence implementation.

> This class inherits from the abstract bean class and uses information from the deployment descriptor. Accessor (read) and mutator (write) methods in the bean class are implemented here to the concrete state class.

> - The concrete remote bean implementation class, generated by the container-managed persistence implementation.
> - The EJBObject (skeleton), generated by the container-managed persistence implementation.
> - The remote stub, generated by the container-managed persistence implementation.

> The following classes are used for container-managed persistence:

> - Generation class—Called from the ejbc compile utility; generates the concrete classes.
> - Generated classes—Use container-managed persistence to effect persistence behavior at server runtime.
> - Management classes—Collect and report statistics at server runtime.

> ### Relationships

> Note | This section applies only if you are using container-managed persistence 2.0 beans.

> 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.

> Note | Even if a relationship is unidirectional, if you make a change to that relationship, other enterprise beans will be affected if they are associated with that relationship.

> 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.

> Note | No warning is given if you delete one object in a managed relationship. Container-managed persistence automatically nullifies the relationship on the foreign key side and deletes the object without asking for confirmation.

> 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
> - One-to-Many Relationships
> - Many-to-Many 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” on page 181 and “Sample EJB XML Files” on page 217 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 Java System 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 Java System 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 Persistence

> Implementation 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
> - Mapping Capabilities
> - Supported Data Types for Mapping
> - BLOB Support
> - Using the capture-schema Utility
> - Mapping Fields and Relationships
> - Configuring the Resource Manager
> - Using EJB QL
> - Configuring Queries for 1.1 Finders

> ### 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
> - Phase 2. Generating and compiling concrete beans and delegates
> - Phase 3. Running in the Sun Java System Application Server runtime

> #### Phase 1. Creating the mapping deployment descriptor file

> Note | The Sun ONE Studio IDE will create this descriptor automatically for deployment.

> This phase can be done concurrent with development of the container-managed persistence beans in the Sun ONE Studio 5 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 5 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 5 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.

> Note | There is no automatic procedure for performing this remapping; you must do it manually.

> #### Phase 2. Generating and compiling concrete beans and delegates

> This phase is done during deployment of an EJB application to the Sun Java System 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 file, which extends the abstract bean written by you

> 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.

> - The compiled EJB-QL for finder and selector methods, stored as a properties file

> This file contains the container-managed persistence query parameter list, the query filter, the query ordering expression, the query candidate class name, and the query result type.

> - A generation log file that reports errors to you, including EJB-QL syntax and usage errors
> - State and helper classes

> #### Phase 3. Running in the Sun Java System 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 Java System 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 5 to map container-managed persistence for enterprise beans is contained in the Sun Java System Application Server Integration Module for the Sun ONE Studio 5 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 as follows:

> BIGINT DOUBLE SMALLINT BIT FLOAT

> TIME BLOB INTEGER TIMESTAMP CHAR

> LONGVARCHAR TINYINT DATE NUMERIC VARCHAR

> DECIMAL REAL

> The following table contains suggested mappings.

> Table 4-1 Suggested Data Type Mappings

> Java Type | JDBC Type | Nullability
> --- | --- | ---
> boolean | BIT | NON NULL
> java.lang.Boolean | BIT | NULL
> byte | TINYINT | NON NULL
> java.lang.Byte | TINYINT | NULL
> double | FLOAT | NON NULL
> java.lang.Double | FLOAT | NULL
> double | DOUBLE | NON NULL
> java.lang.Double | DOUBLE | NULL
> float | REAL | NON NULL
> java.lang.Float | REAL | NULL
> int | INTEGER | NON NULL
> java.lang.Integer | INTEGER | NULL
> long | BIGINT | NON NULL
> java.lang.Long | BIGINT | NULL
> long | DECIMAL (scale==0) | NON NULL
> java.lang.Long | DECIMAL (scale==0) | NULL
> long | NUMERIC (scale==0) | NON NULL
> java.lang.Long | NUMERIC (scale==0) | NULL
> short | SMALLINT | NON NULL
> java.lang.Short | SMALLINT | NULL
> java.math.BigDecimal | DECIMAL (scale!=0) | NON NULL
> java.math.BigDecimal | DECIMAL (scale!=0) | NULL
> java.math.BigDecimal | NUMERIC | NULL
> java.math.BigDecimal | NUMERIC | NON NULL
> java.lang.String | CHAR | NON NULL
> java.lang.String | CHAR | NULL
> java.lang.String | VARCHAR | NON NULL
> serializable | BLOB | NULL

> ### 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 Java System Application Server environment:

> 1. Declare the variable in the bean class with a serializable type.
> 2. Edit the XML file by declaring the CMP mapping deployment descriptor in the sun-cmp-mappings.xml file.
> 3. Create the BLOB in the database.

> Note | Performance may be negatively impacted due to the size of the BLOB object.

> ##### 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 BLOB

> ### Using 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 IDE to capture the database schema; refer to Capturing a Schema.

> Note | The database user running capture-schema needs ANALYZE ANY TABLE privileges if that user does not own the schema. These privileges are granted to the user by the database administrator. The capture-schema utility does not modify the schema in any way. Its only purpose is to provide the persistence engine with information about the structure of the database (the 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 | 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 if this parameter is not set.

> -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>

> Note | If no table flags are given, all the tables in the database are captured in the 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 Java System Application Server deploytool.

> 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.

> Note | Relationships should always be mapped to the primary key field(s) of the related table.

> 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
> - Specifying the Mapping Components
> - Specifying Field Mappings
> - Specifying Relationships

> #### 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
> - sun-cmp-mapping
> - schema
> - entity-mapping

> ### 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
> - ejb-name
> - table-name
> - secondary-table
> - consistency

> ### 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 Table

> The 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 varchar

> Table Student:
> --------------
> StudentId Number
> StudentName varchar
> deptId Number
> AddressId Number
> AccountId Varchar

> When 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.

> Table 4-2 Consistency Flags

> Flag Element | Description
> --- | ---
> check-all-at-commit | This flag is not implemented for Sun Java System Application Server 7.1.
> check-modified-at-commit | Checks modified instances at commit time.
> lock-when-loaded | A lock is implemented when the data is loaded.
> lock-when-modified | This flag is not implemented for Sun Java System Application Server 7.1.
> none | No consistency checking occurs.

> #### Specifying Field Mappings

> Field mapping is done using the following elements:

> - cmp-field-mapping
> - field-name
> - column-name
> - read-only
> - fetched-with
> - level
> - named-group
> - 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.

> 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.

> Note | When mapping multiple columns, any JAVA type can be used.

> ##### 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 Number

> The 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.

> - If there is no fetched-with sub-element of a cmp-field-mapping, the default value is assumed to be:

> <fetched-with><level>0</level></fetched-with>

> - If there is no fetched-with sub-element of a cmr-field-mapping, the default value is assumed to be:

> <fetched-with><none/></fetched-with>

> 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
> - cmr-field-name
> - column-pair
> - fetched-with

> ### 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.

> - If there is no fetched-with sub-element of a cmp-field-mapping, the default value is assumed to be:

> <fetched-with><level>0</level></fetched-with>

> - If there is no fetched-with sub-element of a cmr-field-mapping, the default value is assumed to be:

> <fetched-with><none/></fetched-with>

> 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 server.xml file.

> Refer to the Sun Java System Application Server Administration 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.

> 1. Specify the Persistence Manager used for deployment in the sun-ejb-jar.xml file:

> <pm-descriptors>
> <pm-descriptor>
> <pm-identifier>Sun</pm-identifier>
> <pm-version>1.0</pm-version>
> <pm-class-generator>com.sun.enterprise.persistence.internal.ejb.ejbc.JDOCodeGenerator
> </pm-class-generator>
> <pm-mapping-factory>com.sun.enterprise.cmp.NullFactory</pm-mapping-factory>
> </pm-descriptor
> <pm-inuse>
> <pm-identifier>Sun</pm-identifier>
> <pm-version>1.0</pm-version>
> </pm-inuse>
> </pm-descriptors>

> 2. 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 is 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.PersistenceManagerFactoryImpl"
> enabled="true"
> jndi-name="jdo/pmf"
> jdbc-resource-jndi-name="jdo/pmfPM" />

> Set the CMP resource in the sun-ejb-jar.xml file as:

> <cmp-resource>
> <jndi-name>jdo/pmf</jndi-name
> </cmp-resource>

> Note | The Sun ONE Studio IDE creates pm-descriptors automatically for deployment. Information on how to set up the container-managed persistence resources is contained in the Sun Java System Application Server Integration Module for the Sun ONE Studio 5 online help.

> ### 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 Java System 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 Java System Application Server-specific deployment descriptor (sun-ejb-jar.xml) provides the following elements to store the EJB 1.1 finder method settings:

> query-filter
> query-params
> query-variables

> The Sun Java System 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:
> - =, +=, etc.
> - pre- and post-increment
> - pre- and post-decrement
> - Methods, including object construction, are not supported, except for:

> Collection.contains(Object o)
> Collection.isEmpty()
> String.startsWith(String s)
> String.endsWith(String e)

> In addition, the Sun Java System Application Server supports the following non-standard JDOQL methods:

> String.like(String pattern)
> String.like(String pattern, char escape)
> String.substring(int start, int length)
> String.indexOf(String str), String.indexOf(String str, int start)
> String.length()
> Math.abs(numeric n), and Math.sqrt(double d)

> - Navigation through a null-valued field, which would throw NullPointerException, is treated as if the subexpression returned false.

> Note | Comparisons between floating point values are by nature inexact. Therefore, equality comparisons (== and !=) with floating point values should be used with caution. Identifiers in the expression are considered to be in the name space of the candidate class, with the addition of declared parameters and variables. As in the Java language, this is a reserved word, and refers to the current instance being evaluated.

> The following expressions are supported:

> - Operators applied to all types where they are defined in the Java language:
> - relational operators (==, !=, >, <, >=, <=)
> - boolean operators (&, &&, |, ||, ~, !)
> - arithmetic operators (+, -, *, /)

> String concatenation is supported only for String + String.

> - 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:

> "name == \"Michael\""

> 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:

> "low < price && price < high"

> 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 &lt; price &amp;&amp; price &lt
> 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 this:

> <finder>
> <method-name>findByHigherSalary</method-name>
> <query-params>java.lang.String name</query-params>
> <query-filter>
> (this.salary &gt; p.salary) &amp;&amp;
> (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 Java System Application Server using the Sun Java System 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 Java System 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 Java System Application Server.

> To use a third-party tool:

> 1. Build your enterprise beans using the third-party O/R mapping tool.
> 2. Deploy the beans using the Assembly Tool or the command-line interface.

> 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:

> - The persistence mechanism
> - The persistence vendor/version
> - Additional information required by the persistence mechanism

> ##

> Restrictions and Optimizations

> This 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
> - Data Aliasing
> - Eager Loading of Field State
> - Restrictions on Remote Interfaces
> - Sybase Finder Limitation
> - Date and Time Fields as CMP Field Types

> ### 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 .dbschema files for jar1 and jar2 must have unique fully qualified names.

> ### Data Aliasing

> 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 Field State

> By default, the EJB container loads the state for all CMP fields (except BLOB and CLOB 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:

> - Do not expose the get and set methods for CMR fields or the persistence Collection classes that are used in container-managed relationships through the remote interface of the bean.

> However, you are free to expose the get and set methods that correspond to the CMP fields of the entity bean through the bean’s remote interface.

> - Do not expose local interface types or local home interface types through the remote interface or remote home interface of the bean.
> - Do not expose the container-managed collection classes that are used for relationships through the remote interface of the bean.

> Dependent value classes can be exposed in the remote interface or remote home interface, and can be included in the client EJB JAR file.

> ### Sybase Finder Limitation

> If you execute any finder method with an input greater than 255 characters and map the primary key column to a VARCHAR column, Sybase attempts to convert type VARCHAR to type TEXT and generates the following error:

> com.sybase.jdbc2.jdbc.SybSQLException: Implicit conversion from datatype 'TEXT' to 'VARCHAR' is not allowed. Use the CONVERT function to run this query.

> To avoid this error, make sure your finder method input is less than 255 characters.

> ### Date and Time Fields as CMP Field Types

> If a CMP field type is a Java date or time type (java.util.Date, java.sql.Date, java.sql.Time, java.sql.Timestamp), make sure that the field value exactly matches the value in the database.

> For example, the following code uses a java.sql.Date type as a primary key field:

> java.sql.Date myDate = new java.sql.Date(System.currentTimeMillis())
> beanHome.create(myDate, ...);

> This code results in only the year, month, and date portion of the field value being stored in the database. Later on if the client tries to find this bean by primary key as follows:

> myBean = beanHome.findByPrimaryKey(myDate);

> the bean is not found in the database because the value does not match the one that is stored in the database.

> Similar problems can happen if the database truncates the timestamp value while storing it, or if a custom query has a date or time value comparison in its WHERE clause.

> ##

> Elements in the sun-cmp-mappings.xml File

> “Assembling and Deploying Enterprise Beans” on page 173, provides general information and guidelines on assembling your enterprise beans for deployment. Additional deployment information and instructions are contained in the Sun Java System Application Server Developer’s Guide.

> “Persistence Elements” on page 201 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
> - check-modified-at-commit
> - cmr-field-mapping
> - cmr-field-name
> - column-name
> - column-pair
> - consistency
> - ejb-name
> - entity-mapping
> - fetched-with
> - field-name
> - level
> - lock-when-loaded
> - lock-when-modified
> - named-group
> - none
> - read-only
> - schema
> - sun-cmp-mapping
> - sun-cmp-mappings
> - table-name

> ### check-all-at-commit

> This flag is not implemented for Sun Java System Application Server 7.1.

> ##### 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.

> Table 4-3 cmp-field-mapping Subelements

> Subelement | Required | Description
> --- | --- | ---
> field-name | only one | 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.
> column-name | one or more | 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.
> read-only | zero or one | Flag that indicates a field is read-only. Optional.
> fetched-with | zero or one | Specifies the fetch group configuration for fields and relationships. Optional.

> ### 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.

> Table 4-4 cmr-field-mapping Subelements

> Subelement | Required | Description
> --- | --- | ---
> cmr-field-name | only one | 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.
> column-pair | one or more | The name of the pair of columns in a database table.
> fetched-with | zero or one | Specifies the fetch group configuration for fields and relationships. Optional.

> ### 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.

> Table 4-5 column-pair Subelements

> Subelement | Required | Description
> --- | --- | ---
> column-name | two | 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.

> ### 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.

> Table 4-6 Consistency Flags

> Flag Element | Description
> --- | ---
> check-all-at-commit | Checks modified instances at commit time.
> check-modified-at-commit | This flag is not implemented for Sun Java System Application Server 7.1.
> lock-when-loaded | An exclusive lock is obtained when the data is loaded.
> lock-when-modified | This flag is not implemented for Sun Java System Application Server 7.1.
> none | No consistency checking occurs.

> ### 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.

> Table 4-7 entity-mapping Subelements

> Subelement | Required | Description
> --- | --- | ---
> ejb-name | only one | Specifies the name of the entity bean in the ejb-jar.xml file to which the container-managed persistence beans relates. One is required.
> table-name | only one | Specifies the name of a database table. The table must be present in the database schema file.
> cmp-field-mapping | one or more | 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.
> cmr-field-mapping | zero or more | 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.
> secondary-table | zero or more | Describes the relationship between a bean’s primary and secondary table. Column pairs are used to describe this relationship.
> consistency | zero or one | Specifies container behavior in guaranteeing transactional consistency of the data in the bean. If the consistency checking flag element is not present, none is assumed.

> ### 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.

> Table 4-8 fetched-with Subelements

> Subelement | Required | Description
> --- | --- | ---
> level | exactly one of these elements is required | 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.
> 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.
> none | A consistency level flag that indicates that this field or relationship is fetched by itself.

> ### 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 Java System Application Server 7.1.

> ##### 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.

> Table 4-9 secondary table Subelements

> Subelement | Required | Description
> --- | --- | ---
> table-name | only one | Specifies the name of a database table. The table must be present in the database schema file.
> column-pair | one or more | The name of the pair of related columns in two database tables.

> ### 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
> --- | --- | ---
> schema | only one | Specifies the path to the schema file.
> entity-mapping | 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
> --- | --- | ---
> sun-cmp-mapping | 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

> ##

> Examples

> The following examples are contained in this section:

> - Sample Schema Definition
> - Sample CMP Mapping XML File
> - Sample EJB QL Queries

> ### 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>

> Previous Contents Index Next

> Copyright 2004 Sun Microsystems, Inc. All rights reserved.