The Java Persistence API (JPA) is the persistence component of EJB 3.0. "An EJB 3.0 entity is a lightweight persistent domain object." As discussed in the previous section, the entity class is a POJO annotated with the @Entity annotation. The relationship modeling annotations @OneToOne, @OneToMany, @ManyToOne, and @ManyToMany, are used for object/relational mapping of entity associations. EJB 3.0 specifies the object/relational mapping defaults for entity associations.

The annotations for object/relational mapping are defined in the javax.persistence package. An entity instance is created with the new operator and persisted using the EntityManager API. An EntityManager is injected into an entity bean using the @PersistenceContext annotation:

@PersistenceContext
EntityManager em;

An entity instance is persisted using the persist() method:

CatalogBean catalogBean=new CatalogBean();
em.persist(catalogBean);

The EntityManager is also used to remove entity instances using the remove() method:

em.remove(catalogBean);

EntityManager is also used to find entities by their primary key with the find method:

CatalogBean catalogbean=(CatalogBean)(em.find("CatalogBean", catalogId));

The @NamedQuery annotation is used to specify a named query in the Java Persistence Query language, which is an extension of EJB-QL. The Java Persistence Query language further adds operations for bulk update and delete, JOIN operations, GROUP BY, HAVING, and subqueries, and also supports dynamic queries and named parameters. Queries may also be specified in native SQL.

@NamedQuery(
name="findAllBlogsByName",
query="SELECT b FROM Blog b WHERE b.name LIKE :blogName"
)

The EntityManager is used to query entities using a Query object created from a named query:

Query query = em.createNamedQuery("findAllBlogsByName");

The named query parameters are set using the setParameter() method:

query.setParameter("blogName", "Smythe");

A SELECT query is run using the getResultList() method. A SELECT query that returns a single result is run using the getSingleResult() method. An UPDATE or DELETE statement is run using the executeUpdate() method. For a query that returns a list, the maximum number of results may be set using the setMaxResults() method.

List blogs=query.getResultList();

A persistence unit defines a set of entities that are mapped to a single database and managed by an EntityManager. A persistence unit is defined in the persistence.xml deployment descriptor, which is packaged in the META-INF directory of an entity bean JAR file. The root element of the persistence.xml file is persistence, which has one or more persistence-unit sub-elements. The persistence-unit element consists of the name and transaction-type attributes and subelements description, provider, jta-data-source, non-jta-data-source, mapping-file, jar-file, class, exclude-unlisted-classes, and properties. Only the name attribute is required; the other attributes and subelements are optional. The jta-data-source and non-jta-data-source are used to specify the global JNDI name of the data source to be used by the persistence provider. For all the elements in the persistence.xml and a detailed discussion on Java Persistence API, refer to the EJB 3.0 specification (ejb-3_0-fr-spec-persistence.pdf).