Skip Headers
Oracle® Containers for J2EE Enterprise JavaBeans Developer's Guide
10g (10.1.3.1.0)

Part Number B28221-02
Go to Documentation Home
Home
Go to Book List
Book List
Go to Table of Contents
Contents
Go to Index
Index
Go to Feedback page
Contact Us

Go to previous page
Previous
Go to next page
Next
View PDF

What is a JPA Entity?

The Java Persistence API (JPA), part of the Java Enterprise Edition 5 (Java EE 5) EJB 3.0 specification, greatly simplifies Java persistence and provides an object-relational mapping approach that lets you declaratively define how to map Java objects to relational database tables in a standard, portable way that works both inside a Java EE 5 application server and outside an EJB container in a Java Standard Edition 5 (Java SE 5) application.

Using JPA, you can designate any POJO class as a JPA entity–a Java object whose nontransient fields should be persisted to a relational database using the services of an entity manager obtained from a JPA persistence provider (either within a Java EE EJB container or outside of an EJB container in a Java SE application).

An entity has the following characteristics:

Entities represent persistent data stored in a relational database automatically using container-managed persistence.They are persistent because their data is stored persistently in some form of data storage system, such as a database: they do survive a server failure, failover, or a network failure. When an entity is reinstantiated, the state of the previous instance is automatically restored.

An entity models a business entity or multiple actions within a single business process. Entities are often used to facilitate business services that involve data and computations on that data. For example, you might implement an entity to retrieve and perform computation on items within a purchase order. Your entity can manage multiple, dependent, persistent objects in performing its tasks.

Entities can represent fine-grained persistent objects, because they are not remotely accessible components.

An entity can aggregate objects together and effectively persist data and related objects using the transactional, security, and concurrency services of a JPA persistence provider.

This section describes the following:

For more information, see "Implementing a JPA Entity".

What are JPA Entity Container-Managed Persistent Fields?

A container-managed persistent field is a state-field that represents data that must be persisted to a database.

All the data members of a JPA entity are considered persistent fields unless annotated with @Transient.

The JPA persistence provider that you specify in the entity's persistence unit (see "What is the persistence.xml File?") is responsible for ensuring that persistent fields are persisted to the database.

By default, a JPA persistence provider automatically configures a basic mapping for most Java primitive types, wrappers of the primitive types, and enumerations. You can customize this mapping using the @Basic, @Enumerated, @Temporal, and @Lob annotations.

What are JPA Entity Container-Managed Relationship Fields?

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

All the data members of a JPA entity are considered persistent fields unless annotated with @Transient.

The JPA persistence provider you specify in the entity's persistence unit (see "What is the persistence.xml File?") is responsible for ensuring that persistent fields are persisted to the database.

You must configure your entity (using annotations or persistence.xml) to specify mappings to other entities. This configuration specifies how the entities relate to one another and how a JPA persistence provider should map the reference to a relational database.

For example, you can configure a relationship mapping for any persistent relationship using relationship mapping annotations @OneToOne, @ManyToOne, @OneToMany, and @ManyToMany.

An entity relationship has the following characteristics:

  • Multiplicity–there are four types of multiplicities all of which are supported by Oracle Application Server: one-to-one, many-to-one, one-to-many, and many-to-many.

  • 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 it "knows" about its related object. For example, if an ProjectEJB bean knows what TaskEJB beans it has, and if each TaskEJB bean knows to which ProjectEJB bean it belongs, 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 enterprise beans.

  • Java Persistence query language support–JP QL is an extension of the Enterprise JavaBeans query language (EJB QL) that adds bulk update and delete, JOIN, GROUP BY, HAVING, projection, subqueries, and named parameters. It supports both static and dynamic queries.

    JP QL queries often navigate across relationships. The direction of a relationship determines whether a query can navigate from one bean to another.

For more information, see the following:

What is the JPA Entity Life Cycle?

Figure 1-5 shows the life cycle of a JPA entity.

Figure 1-5 JPA Entity Life Cycle

Description of Figure 1-5 follows
Description of "Figure 1-5 JPA Entity Life Cycle"

Table 1-11 lists the optional JPA entity life cycle callback methods you can define using annotations. For EJB 3.0 entities, you do not need to implement these methods.

Table 1-11 Life Cycle Methods for a JPA Entity

Annotation Description

@PrePersist

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.

@PostPersist

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.

@PreRemove

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.

@PostRemove

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.

@PreUpdate

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.

OC4J calls this method only if it determines that an actual update is required (only if it is prepared to send SQL to the database). Contrast this with a post-update callback which is called regardless of whether or not an actual change was required.

@PostUpdate

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.

OC4J calls this method even if it determines that no actual update is required (even if it determines that no SQL needs to be sent to the database). Use the pre-update callback if you want to be notified only when the object has actually been changed.

@PostLoad

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

What is a JPA Entity Primary Key?

Each JPA entity must have a primary key that uniquely identifies it from other instances. The primary key (or the fields contained within a complex primary key) must be persistent fields.

All fields within the primary key are restricted to the following:

  • 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 a JPA Entity Simple Primary Key Field").

You can assign primary key values yourself, or more typically, you can create an auto-generated primary key (see "Configuring JPA 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 a JPA Entity Primary Key"

How do you Query for a JPA Entity?

In EJB 3.0, you use a javax.persistence.EntityManager to create, find, merge, and persist your EJB 3.0 entities. To find entities, you use the EntityManager query API (see "Understanding the JPA EntityManager Query API").

You can express your selection criteria using an appropriate query syntax (see "Understanding JPA Entity Query Syntax").

Using query hints, you can use EJB 3.0 JPA persistence provider vendor extensions to this API (see "Configuring TopLink Query Hints in a JPA Query").

Understanding the JPA EntityManager Query API

In EJB 3.0, you can use the javax.persistence.EntityManager and javax.persistence.Query API to create and execute named queries or dynamic queries.

Using Query API, you can bind parameters, configure hints, and control the number of results returned.

For more information, see the following:

What is a JPA Named (Predefined) Query?

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 a JPA Named Query"), and then create and execute the query by name at run time (see "Creating a Named Query With the EntityManager").

OC4J supports both Java persistence query language and native SQL named queries.

What is a JPA Dynamic (Ad-Hoc) Query?

A dynamic query is a query that you can compose, configure, and execute at run time. You can use dynamic queries in addition to named queries.

OC4J supports both Java persistence query language and native SQL named 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").

Understanding JPA Entity Query Syntax

Table 1-16 summarizes the types of query syntax you can use to define queries for EJB 3.0 entities.

Table 1-12 OC4J JPA Entity Query Syntax Support

Query Syntax See Also

Java Persistence Query Language

"Understanding Java Persistence Query Language Query Syntax"


Native SQL

"Understanding Native SQL Query Syntax in EJB 2.1"



Oracle recommends the use of Java persistence query language, because it is both portable and optimizable.

Understanding Java Persistence Query Language Query Syntax

Java persistence query language is a specification language used to define query semantics in a portable and optimizable format.

Although similar to SQL, Java persistence query language offers significant advantages over native SQL. While SQL applies queries against tables using column names, Java persistence query language applies queries against EJB 3.0 entities using the abstract schema name and the fields of the bean within the query. The Java persistence query language statement retains the object terminology. The JPA persistence provider translates the Java persistence query language statement to the appropriate database SQL statement when the application is deployed. Thus, the JPA persistence provider is responsible for converting the entity name and the names of its persistent fields to the appropriate database table and column names. Java persistence query language is portable to all databases supported by OC4J.

In EJB 3.0, Java persistence query language syntax includes everything that is in EJB 2.1 EJB QL (see "Understanding EJB 2.1 Query Syntax"), plus additional features such as bulk update and delete, JOIN operations, GROUP BY, HAVING, projection, subqueries, and the use of Java persistence query language in dynamic queries using the EJB 3.0 EntityManager API (see "What is a JPA Dynamic (Ad-Hoc) Query?").

For more information, see the JSR-220 Enterprise JavaBeans v.3.0 Java Persistence API specification, Chapter 4.

OC4J provides complete support for Java persistence query language with the following important features:

  • Automatic Code Generation: Java persistence query language queries are defined in the deployment descriptor of the entity bean. When enterprise beans are deployed to Oracle Application Server, the container automatically translates the queries into the SQL dialect of the target data store. Due to this translation, entity beans with container-managed persistence are portable: their code is not tied to a specific type of a 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 Java persistence query language against any database such as Oracle, MS SQL-Server, IBM DB/2, Informix, and Sybase.

  • Relationships: Oracle Application Server supports Java persistence query language 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 Java persistence query language features defined in the EJB 3.0 persistence specification, including SQRT and date, time, and timestamp options.

Understanding Native SQL Query Syntax in EJB 3.0

In this release, the TopLink JPA persistence provider takes the query syntax you specify (see "Understanding JPA Entity Query Syntax") and generates Sequential Query Language (SQL) native to your underlying relational database.

Java persistence query language 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 Java persistence query language does not support.

OC4J supports native SQL in both named and dynamic queries.