Standardizing Java Persistence with the EJB3 Java Persistence API

The Query API

Retrieving entities is an important aspect of persistence. When using EJB3 JPA, queries are expressed using Java Persistence Query Language (JPQL). JPQL is an extension of EJBQL, which was introduced as part of the EJB 2.0 specification. EJB3 JPA, however, addresses all the limitations of EJBQL and adds many new features, making it a powerful query language.

JPQL Enhancements over EJBQL 2.x

Here are the new features of JPQL in EJB3 JPA:

• Simplified query syntax
• JOIN operations
• Group By and Having Clause
• Subqueries
• Dynamic queries
• Named parameters
• Bulk update and delete

In addition, if you want to benefit from database-specific query extensions, you must use native SQL to query entities.

Dynamic vs. Named Queries

You can use either a dynamic or named query. A named query is stored with the entity and can be reused from applications.

To create a dynamic query, use the createQuery method of the entity manager interface, like this:

 Query query = em.createQuery( 

 "select e from Employee e where e.empNo > ?1"); 

 query.setParameter(1,100); 

 return query.getResultList();

If you want to use this query as a named query, use the NamedQuery annotation in the entity, as follows:

@Entity 

@NamedQuery(name="findAllEmployee", 

   query="select e from Employee e where e.empNo > ?1")

 public abstract class Employee implements Serializable { 

 }

To execute a named query, first create a Query instance using the createNamedQuery method on the EntityManager interface, like this:

query = em.createNamedQuery(" findAllEmployee"); 

query.setParameter(1,100); 

return query.getResultList();

Named Parameters

You can use a named parameter in an EJBQL query instead of a positional parameter. For example, you can rewrite the above query as follows:

"select e from Employee e where e.empNo > :empNo "

If you use a named parameter in your query, you must set the parameter as follows:

 query = em.createNamedQuery("findAllEmployee"); 

 query.setParameter("empNo",100); 

 return query.getResultList();

Packaging

EJB3 JPA is standardizing POJO persistence. Thus, entities aren't limited to EJB modules; they can be packaged in a Web module, ejb-jar module, library module in the EAR level, or a standard jar file. You can also use entities in Java SE. You must package a descriptor (persistence.xml), like the following, in the archive that contain entities:

<persistence> 

<persistence-unit name="onjava"> 

<provider>oracle.toplink.essentials.PersistenceProvider</provider>

<jta-data-source>jdbc/OracleDS</jta-data-source> 

...

</persistence-unit> 

</persistence>

This descriptor identifies the persistence provider, persistent units, and the data source used by a persistent unit. As the name suggests, a persistent unit is a collection of entities that are managed together. If you have a single persistent unit defined in a specific module, you don't have to identify the entity classes in the persistence.xml; it will be dynamically discovered by the persistence provider.

TopLink Essentials: The Reference Implementation

TopLink Essentials, which is derived from the leading commercial O-R mapping framework Oracle TopLink, is the reference implementation for EJB3 JPA. It's available in Sun Microsystems' GlassFish open source project at the Java Persistence API implementation home page.

You can use the code in this article with the Reference Implementation Server or any other application server that complies with the EJB3 JPA.

Tools for EJB3 JPA

Development tools really do help you build better applications--and if you're using XML for O-R mapping, things can get pretty hairy. The Eclipse Dali O-R mapping project aims to make EJB3 JPA easier to use by providing comprehensive tools through the Eclipse Web Tool Project. This project is led by Oracle and supported by JBoss, BEA, and Versant. Learn more about Dali at its home page.

Also, tools such as Oracle JDeveloper 10.1.3 and BEA Workshop studio support EJB3 JPA.

Conclusion

The EJB3 Java Persistence API standardizes the persistence API for the Java platform. It simplifies the use of transparent persistence by using metadata annotations and the configuration by exception approach. Several application servers, including Oracle Application Server 10g (10.1.3), Sun's open-source GlassFish Application Server, and JBoss Application Server 4.0, provide early support for the EJB3 specification. With the Java EE 5.0 and EJB 3.0 specifications finalized, you'll soon see many leading application server and persistence providers implementing EJB3 Java Persistence API. You can get a jump-start on EJB3 Persistence by using the Reference Implementation from the GlassFish project.

Resources

• EJB 3.0 specification
• JPA Resources
• EJB 3.0 Resources
• EJB3 Reference Implementation in Sun's Glassfish project
• Blogs on EJB3 and Java EE

Debu Panda is a Senior Principal Product Manager of the Oracle Application Server development team.

Return to ONJava.com.