|
Oracle® Containers for J2EE Enterprise JavaBeans Developer's Guide
10g Release 3 (10.1.3) B14428-01 |
|
 Previous |
 Next |
|
Oracle® Containers for J2EE Enterprise JavaBeans Developer's Guide
10g Release 3 (10.1.3) B14428-01 |
|
|
Previous |
Next |
An EJB 3.0 entity is an EJB 3.0 compliant light-weight entity object that manages persistent data, performs complex business logic, potentially uses several dependent Java objects, and can be uniquely identified by a primary key.
EJB 3.0 entities represent persistent data stored in a relational database automatically using container-managed persistence.
EJB 3.0 entities are persistent because their data is stored persistently in some form of data storage system, such as a database: they do survive a server crash, failover, or a network failure. When an entity is re-instantiated, the state of the previous instance is automatically restored.
An entity models a business entity or models multiple actions within a business process. Entity beans are often used to facilitate business services that involve data and computations on that data. For example, an application developer might implement an entity bean to retrieve and perform computation on items within a purchase order. Your entity bean can manage multiple, dependent, persistent objects in performing its tasks.
EJB 3.0 entities can represent fine-grained persistent objects because they are not remotely accessible components.
An EJB 3.0 entity can aggregate objects together and effectively persist data and related objects using container transactional, security, and concurrency services.
This section describes:
For more information, see "Implementing an EJB 3.0 Entity".
A container-managed persistence field is a state-field that represents data that must be persisted to a database.
By specifying a CMP field, you are instructing OC4J to take responsibility for ensuring that the field's value is persisted to the database.
Using EJB 3.0, all data members are by default considered container-managed persistence fields unless annotated with @Transient.
A container-managed relationship (CMR) field is an association-field that represents a persistent relationship to one or more other EJB 3.0 entities or EJB 2.1 CMP entity beans. For example, in an order management application the OrderEJB might be related to a collection of LineItemEJB beans and to a single CustomerEJB bean.
By specifying a CMR field, you are instructing OC4J to take responsiblity for ensuring that a reference to one or more related EJB 3.0 entities or EJB 2.1 CMP entity beans is persisted to the database. For this reason, this relationship is often referred to as a CMR or a mapping from one EJB 3.0 entity or EJB 2.1 CMP entity bean to another.
A container-managed relationship has the following characteristics:
Multiplicity - There are four types of multiplicities all of which are supported by Oracle Application Server:
Directionality - The direction of a relationship may be either bi-directional or unidirectional. In a bi-directional relationship, 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 relative field, then we often say that it "knows" about its related object. For example, if an ProjectEJB bean knows what TaskEJB beans it has and if each TaskEJB bean knows what ProjectEJB bean it belongs to, then they have a bi-directional relationship. In a unidirectional relationship, only one entity bean has a relationship field that refers to the other. Oracle Application Server supports both unidirectional and bi-directional relationships between EJBs.
EJB QL query support - EJB QL queries often navigate across relationships. The direction of a relationship determines whether a query can navigate from one bean to another. With OC4J, EJB QL queries can traverse CMP Relationships with any type of multiplicity and with both unidirectional and bi-directional relationships.
For more information, see:
Table 1-9 lists the optional EJB 3.0 entity lifecycle callback methods you can define using annotations. For EJB 3.0 entities, you do not need to implement these methods.
Table 1-9 Lifecycle Methods for an EJB 3.0 Entity
| Annotation | Description |
|---|---|
|
This optional method is invoked for an entity before the corresponding EntityManager persist operation is executed. This callback will be invoked on all entities to which these operations are cascaded. If this callback throws an Exception, it will cause the current transaction to be rolled back. |
|
|
This optional method is invoked for an entity after the corresponding EntityManager persist operation is executed. This callback will be invoked on all entities to which these operations are cascaded. This method will be invoked after the database insert operation. This may be directly after the persist operation, a flush operation, or at the end of a transaction. If this callback throws an Exception, it will cause the current transaction to be rolled back. |
|
|
This optional method is invoked for an entity before the corresponding EntityManager remove operation is executed. This callback will be invoked on all entities to which these operations are cascaded. If this callback throws an Exception, it will cause the current transaction to be rolled back. |
|
|
This optional method is invoked for an entity after the corresponding EntityManager remove operation is executed. This callback will be invoked on all entities to which these operations are cascaded. This method will be invoked after the database delete operation. This may be directly after the remove operation, a flush operation, or at the end of a transaction. If this callback throws an Exception, it will cause the current transaction to be rolled back. |
|
|
This optional method is invoked before the database update operation on entity data. This may be at the time of the entity state update, a flush operation, or at the end of a transaction. |
|
|
This optional method is invoked after the database update operation on entity data. This may be at the time of the entity state update, a flush operation, or at the end of a transaction. |
|
|
This optional method is invoked after the entity has been loaded into the current persistence context from the database or after the refresh operation has been applied to it and before a query result is returned or accessed or an association is traversed. |
For more information, see "Configuring a Lifecycle Callback Method for an EJB 3.0 Entity".
Each EJB 3.0 entity instance has a primary key that uniquely identifies it from other instances. The primary key (or the fields contained within a complex primary key) must be a container-managed persistent fields.
All fields within the primary key are restricted to::
primitive object types
serializable types
types that can be mapped to SQL types
In this release, you can define a primary key made up of a single, well-known serializable Java primitive or object type. The primary key variable that is declared within the bean class must be declared as public (see "Configuring an EJB 3.0 Entity Primary Key Field").
You can assign primary key values yourself, or more typically, you can create an auto-generated primary key (see "Configuring EJB 3.0 Entity Automatic Primary Key Generation").
|
Note: Once the primary key for an entity bean has been set, the EJB 3.0 specification forbids you from attempting to change it. Therefore, do not expose the primary key set methods in an entity component interface. |
For more information, see "Configuring an EJB 3.0 Entity Primary Key"
In EJB 3.0, you use a javax.persistence.EntityManager to create, find, merge, and persist your EJB 3.0 entities (see "Accessing an EJB 3.0 Entity Using an EntityManager").
You can express your selection criteria using an appropriate query syntax (see "Understanding EJB Query Syntax").
Table 1-15 summarizes the types of query syntax you can use to define EJB queries.
Table 1-10 OC4J EJB Query Syntax Support
| Query Syntax | See Also |
|---|---|
|
EJB QL |
"Understanding EJB Query Syntax" |
|
Native SQL |
"Understanding Native SQL Query Syntax" |
Oracle recommends EJB QL because it is both portable and optimizable.
EJB QL is a specification language used to define query semantics in a portable and optimizable format.
Although similar to SQL, EJB QL offers significant advantages over native SQL. While SQL applies queries against tables, using column names, EJB QL applies queries against CMP entity beans, using the abstract schema name and the CMP and CMR fields of the bean within the query. The EJB QL statement retains the object terminology. The container translates the EJB QL statement to the appropriate database SQL statement when the application is deployed. Thus, the container is responsible for converting the entity bean name, CMP field names, and CMR field names to the appropriate database tables and column names. EJB QL is portable to all databases supported by OC4J.
In EJB 3.0, EJB QL syntax includes everything in EJB 2.1 plus additional features such as bulk update and delete, JOIN operations, GROUP BY, HAVING, projection, subqueries, and the use of EJB QL in dynamic queries using the EJB 3.0 EntityManager API (see "Understanding the EJB 3.0 EntityManager Query API"). For complete details, see the EJB 3.0 persistence specification.
Oracle Application Server provides complete support for EJB QL with the following important features:
Automatic Code Generation: EJB QL queries are defined in the deployment descriptor of the entity bean. When the EJBs are deployed to Oracle Application Server, the container automatically translates the queries into the SQL dialect of the target data store. Because of this translation, entity beans with container-managed persistence are portable -- their code is not tied to a specific type of data store.
Optimized SQL Code Generation: Further, in generating the SQL code, Oracle Application Server makes several optimizations such as the use of bulk SQL, batched statement dispatch, and so on to make database access efficient.
Support for Oracle and Non-Oracle Databases: Further, Oracle Application Server provides the ability to execute EJB QL against any database - Oracle, MS SQL-Server, IBM DB/2, Informix, and Sybase.
Relationships: Oracle Application Server supports EJB QL for both single entity beans and also with entity beans that have relationships, with support for any type of multiplicity and directionality.
Using EJB 3.0, OC4J supports all of the enhanced EJB QL features defined in the EJB 3.0 persistence specification, including SQRT and date, time, and timestamp options.
In this release, the TopLink persistence manager takes the query syntax you specify (see "Understanding EJB Query Syntax") and generates Sequential Query Language (SQL) native to your underlying relational database.
EJB QL is the preferred syntax because it is portable and optimizable.
Native SQL is appropriate for taking advantage of advanced query features of your underlying relational database that EJB QL does not support.
Using EJB 3.0, you can use EntityManager method createNativeQuery(String sqlString, Class resultType) to create a native SQL query (see "Creating a Dynamic Native SQL Query with the EntityManager").
|
Note: OC4J does not supportEntityManager method createNativeQuery(String sqlString) nor does it support native SQL named queries (see "Implementing an EJB 3.0 Named Query" ).
|
To use native SQL otherwise, you must use straight JDBC calls.
In EJB 3.0, you can use the javax.persistence.EntityManager and javax.persistence.Query API to create and execute named queries (see "What is an EJB 3.0 Named (Predefined) Query?") or dynamic queries (see "What is an EJB 3.0 Dynamic (Ad-Hoc) Query?").
Using Query API, you can bind parameters, configure hints, and control the number of results returned.
For more information, see:
A named query is the EJB 3.0 improvement of the EJB 2.1 finder method. In EJB 3.0, you can implement a named query using metadata (see "Implementing an EJB 3.0 Named Query") and then create and execute the query by name at runtime (see "Creating a Named Query with the EntityManager").
In this release OC4J supports only EJB QL named queries.
A dynamic query is a query that you can compose, configure, and execute at runtime. You can use dynamic queries in addition to named queries.
OC4J supports both EJB QL ("Creating a Dynamic EJB QL Query with the Entity Manager") and native SQL ("Creating a Dynamic Native SQL Query with the EntityManager") dynamic queries.
You can also create a dynamic query using the TopLink query and expression framework (see "Creating a Dynamic TopLink Expression Query with the EntityManager").
