The Java Persistence API

©SoftMoore Consulting Slide 1

The Java Persistence API

• The Java Persistence API (JPA) is a Java programming language framework that allows developers to manage relational data in Java development environments.

Provides a higher-level framework than JDBC for managing persistent objects

• Background– originated within the Enterprise JavaBeans 3.0 (JSR 220) expert

group, but a Java EE application server is not required– merged expertise from TopLink, Hibernate, JDO, EJB vendors,

and individuals– first released in May 2006 as part of Java EE 5

©SoftMoore Consulting Slide 2

JPA Implementations

• GlassFish (Java EE application server)– reference implementation– called “TopLink Essentials” (derived from Oracle TopLink)– https://glassfish.dev.java.net/javaee5/persistence/

• Eclipse Persistence Services Project (EclipseLink)• JBoss Hibernate• Apache OpenJPA

©SoftMoore Consulting Slide 3

JPA Major Components

• The API– defined in the javax.persistence package

• The Java Persistence Query Language (JPQL)– used to make queries against entities stored in a relational

database– resembles SQL but operates against entity objects rather than

database tables

• Object/Relational Metadata– can be specified directly in the entity class using annotations or

in a separate XML descriptor file

©SoftMoore Consulting Slide 4

JPA Overview

• JPA provides persistence for “Plain Old Java Object” (POJO) entities.

• Entities can be defined using annotations or an XML mapping file.

• An entity typically represents a table in a relational database, and each object of the class corresponds to a row in that table.

• Primary keys and relationships are also indicated by appropriate annotations on the entity class or entries in the XML mapping file.

• Entities are managed by an entity manager.

©SoftMoore Consulting Slide 5

Requirements for Entity Classes

• Must be annotated with javax.persistence.Entity• Must have a public or protected, no-argument

constructor (may have other constructors)• Must not be declared final. Also, no methods or

persistent instance variables must be declared final.• Must have persistent instance variables declared as

private, protected, or package-private– entity’s state accessed through accessor (get) methods

• May need to implement the Serializable interface(if passed by value in a remote call)

©SoftMoore Consulting Slide 6

Persistent Fields and Properties

• The persistent state of an entity can be accessed either through the entity’s instance variables or through JavaBeans-style properties.– If the mapping annotations are applied to the entity’s instance

variables, the entity uses persistent fields.– If the mapping annotations are applied to the entity’s getter

methods for JavaBeans-style properties, the entity uses persistent properties.

• You cannot apply mapping annotations to both fields and properties in a single entity.

©SoftMoore Consulting Slide 7

Java Types for Persistent Fields/Properties

• Primitive types• String• Enumerated types• Other entities and/or

collections of entities– java.util.Collection– java.util.Set– java.util.List– java.util.Map

• Embeddable classes

• Other serializable types:– Wrappers classes– java.math.BigInteger– java.math.BigDecimal– java.util.Date– java.util.Calendar– java.sql.Date– java.sql.Time– java.sql.TimeStamp– User-defined

serializable types– byte[]– Byte[]– char[]– Character[]

©SoftMoore Consulting Slide 8

The Minimal Entity

• Must be annotated as an Entity• Must have a persistent identifier (primary key)• Example using annotations

@Entitypublic class Employee {

@Id private int id;

public int getId() { return id; } public void setId(int id) { this.id = id; }

}

©SoftMoore Consulting Slide 9

The Minimal Entity(continued)

• Example Entity entry in XML mapping file</xml version="1.0" encoding="UTF-8"?><entity-mappings xmlns=...> <entity class="com.acme.Employee"> <attributes> <id name="id"/> </attributes> </entity></entity-mappings>

©SoftMoore Consulting Slide 10

• Identifier in entity, primary key in database• Uniquely identifies entity in memory and in database• Examples

– Simple id – single field/property@Id int id;

– Compound id – multiple fields/properties@Id int id;@Id String name;

– Embedded id – single field of PK class type@EmbeddedId EmployeePK id;

UsesPK

class

Persistent Identity

• Identifiers can be generated in the database by specifying @GeneratedValue on the identifier

• Three pre-defined generation strategies:– IDENTITY– SEQUENCE– TABLE

• Specifying strategy of AUTO indicates that the provider will choose a strategy@Id @GeneratedValue int id;

Identifier Generation

Persistence Context

• Abstraction representing a set of “managed” entity instances – Entities keyed by their persistent identity– Only one entity with a given persistent identity may exist in the

persistence context– Entities are added to the persistence context, but are not

individually removable (“detached”)

• Controlled and managed by EntityManager– Contents of persistent context change as a result of operations

on EntityManager API

Application Persistence Context

Entities

MyEntity A

MyEntity B

MyEntity CMyEntity a

EntityManager

MyEntity b

Entity state

Persistence Context

Entity Manager

• Client-visible artifact for operating on entities– API for all the basic persistence operations

• Can think of it as a proxy to a persistence context– May access multiple different persistence contexts throughout its

lifetime

• Multi-dimensionality leads to different aspects of EntityManager (and persistence context) naming– Transaction type, life cycle

EntityManager Methods

• persist() - insert the entity into the database• remove() - delete the entity from the database• refresh() - reload the entity state from the database• merge() - synchronize state of detached entity with the persistence

context• find() - execute a simple primary key query• createQuery() - create query instance using dynamic JPQL• createNamedQuery() - create instance for a predefined query• createNativeQuery() - create instance for an SQL query• contains() - true if entity is managed by persistence context• flush() - force synchronization of persistence context to database

Method persist()

• Insert a new entity instance into the database• Save the persistent state of the entity and any owned

relationship references• Entity instance becomes managed• Example

public Customer createCustomer(int id, String name) { Customer cust = new Customer(id, name); entityManager.persist(cust); return cust; }

Method find()

• Obtains a managed entity instance with a given persistent identity– returns null if not found

• Examplepublic void removeCustomer(Long custId) { Customer cust

= entityManager.find(Customer.class, custId); entityManager.remove(cust); }

Queries

• Dynamic or statically defined (named queries)• Criteria using JPQL• Native SQL support when required• Named parameters bound at execution time• Pagination and ability to restrict size of result• Single/multiple-entity results• Bulk update and delete operation on an entity• Standard hooks for vendor-specific hints

Queries

• Query instances are obtained from factory methods on EntityManager

• Query methods– getResultList() - execute query returning multiple results– getSingleResult() - execute query returning single result– executeUpdate() - execute bulk update or delete– setFirstResult() - set the first result to retrieve– setMaxResults() - set the maximum number of results to

retrieve– setHint() - apply a vendor-specific hint to the query– setFlushMode() - apply a flush mode to the query when it

gets run

Dynamic Queries

• Use createQuery() factory method at runtime and pass in the JPQL query string

• Use correct execution method– getResultList()– getSingleResult()– executeUpdate()

• Query may be compiled/checked at creation time or when executed

• Maximal flexibility for query definition and execution

Example: Dynamic Queries

public List findAll(String entityName) { return entityManager.createQuery( "select e from " + entityName + " e") .setMaxResults(100).getResultList(); }

Named Queries

• Use createNamedQuery() factory method at runtime and pass in the query name

• Query must have already been statically defined either in an annotation or XML

• Query names are “globally” scoped• Provider has opportunity to precompile the queries and

return errors at deployment time• Can include parameters and hints in static query

definition

Example: Named Queries

@NamedQuery(name="Sale.findByCustId", query="select s from Sale s where s.customer.id = :custId order by s.salesDate")

/** * Returns all sales for a given customer */public List findSalesByCustomer(Customer cust) { return entityManager.createNamedQuery("Sale.findByCustId") .setParameter("custId", cust.getId()) .getResultList(); }

Object/Relational Mapping

• Map persistent object state to relational database • Map relationships to other entities• Metadata may be annotations or XML (or both)• Annotations

– Logical: object model (e.g. @OneToMany)– Physical: database tables and columns (e.g. @Table)

• XML can additionally specify scoped settings or defaults• Standard rules for default database table/column names

Object/Relational Mapping(continued)

• State or relationships may be loaded or “fetched” as EAGER or LAZY– LAZY - hint to defer loading until the field or property is accessed– EAGER - requires that the field or relationship be loaded when

the referencing entity is loaded

• Cascading of entity operations to related entities– Setting may be defined per relationship– Configurable globally in mapping file for

persistence-by-reachability

Simple Mappings

• Direct mappings of fields/properties to columns• Maps any of the common simple Java types

– primitives – wrappers– enumerated – serializable– etc.

• Used in conjunction with @Column • Defaults to the type deemed most appropriate if no

mapping annotation is present• Can override any of the defaults

CUSTOMERID NAME CREDIT PHOTO

Simple Mappings

@Entitypublic class Customer { @Id private int id;

private String name;

@Column(name="CREDIT") private int creditRating;

@Lob private Image photo; }

Relationship Mappings

• Common relationship mappings supported– @ManyToOne, @OneToOne (single entity)– @OneToMany, @ManyToMany (collection of entities)

• Unidirectional or bidirectional• Owning and inverse sides of every bidirectional

relationship• Owning side specifies the physical mapping

– @JoinColumn to specify foreign key column – @JoinTable decouples physical relationship mappings from

entity tables

CUSTOMER. . .ID

SALECUST_IDID . . .

Many-to-One Mapping

@Entitypublic class Sale { @Id private int id;

...

@ManyToOne private Customer cust;}

CUSTOMERID . . .

SALECUST_IDID . . .

OneToMany Mapping

@Entitypublic class Customer { @Id private int id; ... @OneToMany(mappedBy="cust") private Set<Sale> sales; }

@Entitypublic class Sale { @Id private int id; ... @ManyToOne private Customer cust; }

Persistence in Java SE

• No deployment phase– Application must use a “Bootstrap API” to obtain an EntityManagerFactory

• Application uses a local EntityTransaction obtained from the EntityManager– begin() – commit()– rollback() – isActive()

• New application-managed persistence context for every EntityManager– No propagation of persistence contexts

Bootstrap Classes

• javax.persistence.Persistence– root class for bootstrapping an EntityManager– used to obtain an EntityManagerFactory

• javax.persistence.EntityManagerFactory– creates EntityManager objects for a named persistence unit

or configuration

Example

public class PersistenceProgram { public static void main(String[] args) { EntityManagerFactory emf = Persistence .createEntityManagerFactory("SomePUnit"); EntityManager em = emf.createEntityManager(); em.getTransaction().begin();

// Perform finds, execute queries, // update entities, etc.

em.getTransaction().commit(); em.close(); emf.close(); } }

References

• The Java EE Tutorial, Part VIII: Persistence.https://docs.oracle.com/javaee/7/tutorial/index.html

• Pro EJB 3: Java Persistence API by Mike Keith and Merrick Schincariol, Apress, 2006,ISBN: 978-1590596456.

©SoftMoore Consulting Slide 35