jpa_2009-09_24_en

8/8/2019 JPA_2009-09_24_en

http://slidepdf.com/reader/full/jpa2009-0924en 1/57

JPA

Java Persistence API

8/8/2019 JPA_2009-09_24_en


Introduction The Java Persistence API provides an

object/relational mapping facility for managing

relational data in Java applications

Created as a part of EJB 3.0 within JSR 220

Merger of expertise from TopLink, Hibernate, JDO,EJB vendors and individuals

Released in May 2006 as a part of Java EE 5

Integration with Java EE web and EJB containers provides enterprise ³ease of use´ features

Can also be used in Java Standard Edition

8/8/2019 JPA_2009-09_24_en


Java Persistence

Java Persistence consists of three areas:

The Java Persistence API

The query language

Object/relational mapping metadata

Versions JPA 1.0 (part of EJB 3.0, Java EE 5)

JSR 220: http://jcp.org/en/jsr/detail?id=220

JPA 2.0 (part of EJB 3.1, Java EE 6)

JSR 318: http://jcp.org/en/jsr/detail?id=318

8/8/2019 JPA_2009-09_24_en


Reference implementations

JPA 1.0 reference implementation

TopLink Essentials by GlassFish project

javax.persistence package

open source (under CDDL license)https://glassfish.dev.java.net/javaee5/persistence/

JPA 2.0 reference implementation

EclipseLink http://www.eclipse.org/eclipselink/

8/8/2019 JPA_2009-09_24_en


Entities

An entity is a lightweight persistence domain object

Java class that typically represents a table in a

relational database, instances correspond to rows

Requirements:

annotated with the javax.persistence.Entity

annotation

public or protected , no-argument constructor

the class must not be declared final

no methods or persistent instance variables must be

declared final

8/8/2019 JPA_2009-09_24_en


Requirements for Entities (cont.) May be Serializable, but not required

Only needed if passed by value (in a remote call)

Entities may extend both entity and non-entity classes

Non-entity classes may extend entity classes

Persistent instance variables must be declared private,

protected, or package-private

No required business/callback interfaces

Example:@Entity

class Person{

. . .

}

8/8/2019 JPA_2009-09_24_en


Persistent Fields and Properties The persistent state of an entity can be accessed:

through the entity¶s instance variables

through JavaBeans-style properties

Supported types:

primitive types, String, other serializable types,

enumerated types

other entities and/or collections of entities

embeddable classes

All fields not annotated with @Transient or not marked

as Java transient will be persisted to the data store!

8/8/2019 JPA_2009-09_24_en


Primary Keys in Entities Each entity must have a unique object identifier

(persistent identifier)

@Entity

public class Employee {

@Id private int id;

private String name;

private Date age;

public int getId() { return id; }

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

. . .

}

primary key

8/8/2019 JPA_2009-09_24_en


Persistent Identity

Identifier (id) in entity = primary key in database

Uniquely identifies entity in memory and in DB

Persistent identity types:

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;

8/8/2019 JPA_2009-09_24_en


Identifier Generation

@Id @GeneratedValue private int id;

Identifiers can be generated in the database by

specifying @GeneratedValue on the identifier

Four pre-defined generation strategies:

AUTO, IDENTITY, SEQUENCE, TABLE

Generators may pre-exist or be generated

Specifying strategy of AUTO indicates that the provider will choose a strategy

8/8/2019 JPA_2009-09_24_en


Customizing the Entity Object In most of the cases, the defaults are sufficient

By default the table name corresponds to the unqualified

name of the class Customization:

The defaults of columns can be customized using the

@Column annotation

@Entity(name = ³FULLTIME_EMPLOYEE")

public class Employee{ «« }

@Id @Column(name = ³EMPLOYEE_ID´, nullable = false)

private String id;

@Column(name = ³FULL_NAME´ nullable = true, length = 100)

private String name;

8/8/2019 JPA_2009-09_24_en


Entity Relationships There are four types of relationship multiplicities:

@OneToOne

@OneToMany @ManyToOne

@ManyToMany

The direction of a relationship can be:

bidirectional ± owning side and inverse side unidirectional ± owning side only

Owning side specifies the physical mapping Inverse side is indicated by ³ mappedBy´ attribute

8/8/2019 JPA_2009-09_24_en


OneToOne Mapping [1]

@Entity

@DiscriminatorValue("S

INGER") public class Singer extends Artist{

@OneToOne

private Person person;

. . .

}

Create unidirectional relationship from Singer to Person:

Result:In database ³ person_id ́ field is added to ³artist´ table,

which contains foreign keys to ³ person

´ table

8/8/2019 JPA_2009-09_24_en


OneToOne Mapping [2]

Make this relationship bidirectional:

@Entity

public class Person implements PersistentEntity {

. . .

@OneToOne(mappedBy="person")

private Singer singerInfo;

. . .}

8/8/2019 JPA_2009-09_24_en


ManyToOne Mapping

public class Sale {

int id;

...

Customer cust;}}

SALE

CUST_IDID

CUSTOMER

. . .ID

@Entity

@ManyToOne

@Id . . .

8/8/2019 JPA_2009-09_24_en


OneToMany Mapping

public class Sale {

int id;...

Customer cust;}

public class Customer {

int id;...

Set<Sale> sales;}

CUSTOMER

ID . . .

SALECUST_IDID . . .

@Entity

@ManyToOne

@Id

@Entity

@Id

@OneToMany(mappedBy=³cust´)

8/8/2019 JPA_2009-09_24_en


Additional notes

³Many´ end of the bidirectional ManyToOne

relationship cannot be the inverse side of the

relationship @ManyToOne annotation cannot contain attribute

³ mappedBy´

8/8/2019 JPA_2009-09_24_en


General rules

If ³One´ end of the relationship is the owning

side, then foreign key column is generated for

this entity in database

If ³Many´ end of the relationship is the owning

side (e.g. unidirectional ManyToOne or any kind

of ManyToMany), then join table is generated

8/8/2019 JPA_2009-09_24_en


ManyToMany Mapping@Entity public class Customer {

...

@ManyToMany

@JoinTable(

name="CUSTOMER_ S ALE",

joinColumns=@JoinColumn(

name="CUSTOMER_ID",referencedColumnName="customer_id"),

inverseJoinColumns=@JoinColumn(

name="S ALE_ID", referencesColumnName="sale_id")

Collection<Sale> sales;}

@Entity public class Sale {

...@ManyToMany(mappedBy=³sales´)

Collection<Customer> customers;}

8/8/2019 JPA_2009-09_24_en


Relation Attributes

CascadeType ALL, PER SIST, MERGE, REMOVE, REFRESH

FetchType LAZY, EAGER

@ManyToMany(cascade = {CascadeType.PER SIST, CascadeType.MERGE},fetch = FetchType.EAGER)

8/8/2019 JPA_2009-09_24_en


Entity Inheritance

An important capability of the JPA is its support

for inheritance and polymorphism

Entities can inherit from other entities and from

non-entities

The@Inheritance

annotation identifies a

mapping strategy:

SINGLE_TABLE

JOINED

TABLE_PER_CLASS

8/8/2019 JPA_2009-09_24_en


Inheritance Example@Entity

@Inheritance(strategy=SINGLE_TABLE)

@DiscriminatorColumn(name="DISC", discriminatorType=STRING)

@DiscriminatorValue(name="CUS

TOMER") public class Customer { . . . }

@Entity

@DiscriminatorValue(name="VCUSTOMER")

public class ValuedCustomer extends Customer { . . . }

SINGLE_TABLE strategy - all classes in the hierarchy are mapped

to a single table in the database

Discriminator column - contains a value that identifies the subclass

Discriminator type - {STRING, CHAR, INTEGER}

Discriminator value - value entered into the discriminator column

for each entity in a class hierarchy

8/8/2019 JPA_2009-09_24_en


Managing Entities

Entities are managed by the entity manager

The entity manager is represented byjavax.persistence.EntityManager instances

Each EntityManager instance is associated with a

persistence context

A persistence context defines the scope under

which particular entity instances are created,

persisted, and removed

8/8/2019 JPA_2009-09_24_en


Persistence Context

A persistence context is a set of managed entity

instances that exist in a particular data store

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 persistence context change as a result of operations on EntityManager API

8/8/2019 JPA_2009-09_24_en


ApplicationPersistence

Context

Entities

MyEntity A

MyEntity B

MyEntity C

MyEntity a

EntityManager

MyEntity b

Entity

state

Persistence Context

8/8/2019 JPA_2009-09_24_en


Entity Manager An EntityManager instance is used to manage

the state and life cycle of entities within a

persistence context

The EntityManager API:

creates and removes persistent entity instances

finds entities by the entity¶s primary key

allows queries to be run on entities

There are two types of EntityManagers:

Application-Managed EntityManagers

Container-Managed EntityManagers

8/8/2019 JPA_2009-09_24_en


Application-Managed EntityManager

Applications create EntityManager instances by usingdirectly Persistence and EntityManagerFactory:

javax.persistence.Persistence

Root class for obtaining an EntityManager

Locates provider service for a named persistence unit

Invokes on the provider to obtain an

EntityManagerFactory

javax.persistence.EntityManagerFactory

Creates EntityManagers for a named persistence unitor configuration

8/8/2019 JPA_2009-09_24_en


Application-Managed EntityManager

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();

}

}

8/8/2019 JPA_2009-09_24_en


Container-Managed EntityManagersAn EntityManager with a transactional persistence context can be injected by

using the @PersistenceContext annotation

@Transactional public class PersistenceHelperImpl implements PersistenceHelper {. . .

@PersistenceContext

public void setEntityManager(EntityManager em) {

this.em = em;

}

public void save(PersistentEntity object) {if (object.getId() == null) {

getEntityManager().persist(object);

} else {

getEntityManager().merge(object);

}

}

}

8/8/2019 JPA_2009-09_24_en


Transactions JPA transactions can be managed by:

the users application

a framework (such as Spring)

a JavaEE container

Transactions can be controller in two ways:

Java Transaction API (JTA) container-managed entity manager

EntityTransaction API (tx.begin(), tx.commit(), etc)

application-managed entity manager

8/8/2019 JPA_2009-09_24_en


Operations on Entity Objects EntityManager API operations:

persist()- Insert the state of an entity into the db

remove()- Delete the entity state from the db

refresh()- Reload the entity state from the db

merge()- Synchronize the state of detached entity with the pc

find()- Execute a simple PK query

createQuery()

- Create query instance using dynamic JP QL

createNamedQuery()- Create instance for a predefined query

createNativeQuery()- Create instance for an SQL query

contains()- Determine if entity is managed by pc

flush()- Force synchronization of pc to database

8/8/2019 JPA_2009-09_24_en


Entity Instance¶s Life Cycle Instances are in one of four states:

New

Managed

Detached

Removed

The state of persistent entities is synchronized tothe database when the transaction commits

To force synchronization of the managed entity to

the data store, invoke the flush() method

8/8/2019 JPA_2009-09_24_en


Persistence Units A persistence unit defines a set of all entity

classes that are managed by EntityManager

instances in an application

For example, some set of entities can share onecommon provider (TopLink), whereas other setof entities can depend on a different provider

(Hibernate)

Persistence units are defined by the persistence.xml configuration file

8/8/2019 JPA_2009-09_24_en


persistence.xmlA persistence.xml file defines one or more

persistence units

<persistence>

<persistence-unit name=" MyMobilePersistentUnit">

<provider> oracle.toplink.essentials.ejb.cmp3.EntityManagerFactoryProvider

</provider>

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

<class> com.javabeat.ejb30.persistence.entities.mobile.MobileEntity </class>

</persistence-unit> <persistence-unit name=" MyOtherPersistentUnit">

<provider> org.hibernate.ejb.HibernatePersistence </provider>

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

<class> com.javabeat.ejb30.persistence.entities.mobile.OtherEntity </class>

</persistence-unit>

</persistence>

8/8/2019 JPA_2009-09_24_en


HibernatePersistence provider Sample configuration:

<persistence-unit name="hibernate_mysql" transaction-type="RESOURCE_LOCAL">

<provider>org.hibernate.ejb.HibernatePersistence</provider><properties>

<property name="hibernate.dialect" value="org.hibernate.dialect.MySQLDialect"/>

<property name="hibernate.hbm2ddl.auto" value="create"/>

<property name="hibernate.connection.driver_class" value="com.mysql.jdbc.Driver"/>

<property name="hibernate.connection.username" value="musicuser"/>

<property name="hibernate.connection.password" value="musicpassword"/>

<property name="hibernate.connection.url" value="jdbc:mysql://localhost/music"/><property name="hibernate.show_sql" value="true">

</persistence-unit>

8/8/2019 JPA_2009-09_24_en


hibernate.hbm2ddl.auto Automatically validates or exports schema DDL

to the database when the SessionFactory is

created. With create-drop, the database schemawill be dropped when the SessionFactory isclosed explicitly

Possible values:

validate create

update

create-drop

8/8/2019 JPA_2009-09_24_en


Example of Spring ConfigurationEntityManager injection

<bean id="entityManagerFactory³ class="org.springframework.orm

.jpa.LocalContainerEntityManagerFactoryBean">

<property name="persistenceUnitName"

value="hibernate_mysql"/>

<property name="jpaVendorAdapter">

<bean class="org.springframework.orm

.jpa.vendor.HibernateJpaVendorAdapter³ />

</property>

</bean>

8/8/2019 JPA_2009-09_24_en


Example of Spring ConfigurationTransaction Manager injection

<bean id="transactionManager³ class="org.springframework.orm .jpa.JpaTransactionManager">

<property name="entityManagerFactory"ref="entityManagerFactory"/>

</bean>

<tx:annotation-driven transaction-manager="transactionManager"/>

8/8/2019 JPA_2009-09_24_en


JPA exceptions All exceptions

are unchecked

Exceptions in

javax.persistence

package are

self-explanatory

http://openjpa.apache.org/docs/openjpa-0.9.0-incubating/manual/manual.html

8/8/2019 JPA_2009-09_24_en


JPQL

Java Persistence Query Language

8/8/2019 JPA_2009-09_24_en


Introduction The Java Persistence API specifies a query

language that allows to define queries over

entities and their persistent state

JPQL is an extension of EJB QL

More robust flexible and object-oriented than

SQL

The persistence engine parse the query string,

transform the JPQL to the native SQL before

executing it

8/8/2019 JPA_2009-09_24_en


Creating Queries Query instances are obtained using:

EntityManager.createNamedQuery (static query)

EntityManager.createQuery (dynamic query)

Query API:

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

setParameter() ± bind a value to a named or positional parameter

setHint() ± apply a vendor-specific hint to the query

setFlushMode() ± apply a flush mode to the query when it gets run

8/8/2019 JPA_2009-09_24_en


Static (Named) Queries Defined statically with the help of @NamedQuery

annotation together with the entity class

@NamedQuery elements: name - the name of the query that will be used with the

createNamedQuery method

query ± query string

@NamedQuery(name="findAllCustomers",

query="SELECT c FROM Customer")

Query findAllQuery =entityManager.createNamedQuery(³findAllCustomers´);

List customers = findAllQuery.getResultList();

8/8/2019 JPA_2009-09_24_en


Multiple Named QueriesMultiple named queries can be logically defined

with the help of @NamedQueries annotation

@NamedQueries( {

@NamedQuery(name = ³Mobile.selectAllQuery´

query = ³SELECT M FROM MOBILEENTITY´),

@NamedQuery(name = ³Mobile.deleteAllQuery´query = ³DELETE M FROM MOBILEENTITY´)

} )

8/8/2019 JPA_2009-09_24_en


Dynamic Queries Dynamic queries are queries that are defined

directly within an application¶s business logic

Worse efficiency and slower query execution, as

the persistence engine has to do all the parsing

and validation stuffs, along with mapping the

JPQL to the SQL at the run-time public List findAll(String entityName){

return entityManager.createQuery(

"select e from " + entityName + " e")

.getResultList();

}

8/8/2019 JPA_2009-09_24_en


Named Parameters Named parameters are parameters in a query that are

prefixed with a colon (:)

To bound parameter to an argument use method: Query.setParameter(String name, Object value)

public List findWithName(String name) {

return em.createQuery(

"SELECT c FROM Customer c W HERE c.name LIKE :custName")

.setParameter("custName", name)

.getResultList();

}

8/8/2019 JPA_2009-09_24_en


Positional Parameters Positional parameters are prefixed with a question mark

(?) followed the numeric position of the parameter in the

query To set parameter values use method:

Query.setParameter(integer position, Object value)

public List findWithName(String name) {

return em.createQuery(

³SELECT c FROM Customer c W HERE c.name LIKE ?1´)

.setParameter(1, name)

.getResultList();

}

8/8/2019 JPA_2009-09_24_en


Native Queries Queries may be expressed in native SQL

Support for cases where it is necessary to use the

native SQL of the target database in use

Query q = em.createNativeQuery(

"SELECT o.id, o.quantity, o.item " +

"FROM Order o, Item i " +

"W HERE (o.item = i.id) AND (i.name = 'widget')",

com.acme.Order.class);

@SqlResultSetMapping annotaton is used for

more advanced cases

8/8/2019 JPA_2009-09_24_en


Query Operations ± Multiple Results

Query.getResultList() will execute a query

and may return a List object containing multiple

entity instances

Will return a non-parameterized List object

Can only execute on select statements as opposed

to UPDATE or DELETE statements

For a statement other than SELECT run-time

IllegalS

tateExceptionwill be thrown

Query query = entityManager.createQuery(³SELECT C FROM CUSTOMER´);

List<MobileEntity> mobiles = (List<MobileEntity>)query.getResultList();

8/8/2019 JPA_2009-09_24_en


Query Operations ± Single Result A query that returns a single entity object

If the match wasn¶t successful, then

EntityNotFoundException is returned

If more than one matches occur during query

execution a run-time exception

NonUniqueResultException will be thrown

Query singleSelectQuery = entityManager.createQuery(

³SELECT C FROM CUSTOMER W HERE C.ID = µABC-123¶´);

Customer custObj = singleSelectQuery.getSingleResult();

8/8/2019 JPA_2009-09_24_en


Paging Query Results

int maxRecords = 10; int startPosition = 0;

String queryString = ³SELECT M FROM MOBILEENTITY´;

while(true){Query selectQuery = entityManager.createQuery(queryString);

selectQuery.setMaxResults(maxRecords);

selectQuery.setFirstResult(startPosition);

List<MobileEntity> mobiles =

entityManager.getResultList(queryS

tring);if (mobiles.isEmpty()){ break; }

process(mobiles); // process the mobile entities

entityManager.clear(); // detach the mobile objects

startPosition = startPosition + mobiles.size();

}

8/8/2019 JPA_2009-09_24_en


Flushing Query Objects Two modes of flushing query objects

AUTO (default) and COMMIT

AUTO - any changes made to entity objects will be

reflected the very next time when a SELECT query is

made

COMMIT - the persistence engine may only update all thestate of the entities during the database COMMIT

8/8/2019 JPA_2009-09_24_en


JPQL Statement Language JPQL statement types:

SELECT, UPDATE, DELETE

Supported clauses: FROM

WHERE

GROUP_BY

HAVING ORDER BY

«

Conditional expressions, aggregate functions,«

8/8/2019 JPA_2009-09_24_en


JPQL Enhancements over EJBQL 2.x

Simplified query syntax

JOIN operations

Group By and Having Clause

Subqueries

Dynamic queries

Named parameters

Bulk update and delete

8/8/2019 JPA_2009-09_24_en


OO-style vs. SQL-style queries The main difference is that you query the application

model, i.e. the entities, rather than any database tables

Productivity can be increased if OO-style queries,e.g.

employeeXYZ.getManager().getAddress()

are automatically translated by the ORM engine intocorrect SQL code, e.g.

SELECT t3.* FROM EMP t1, EMP t2, ADDR t3

W HERE t1.EMP_ID = ³XYZ´ AND t1.MGR_ID = t2.EMP_ID

AND t2.ADDR_ID = t3.ADDR_ID

Notice that the two-step object traversal was packedinto a single DB query

8/8/2019 JPA_2009-09_24_en


Resources The Java Persistence API - A Simpler Programming Model for Entity

Persistencehttp://java.sun.com/developer/technicalArticles/J2EE/jpa/

JavaWorld: Understanding JPA, Part 1http://www.javaworld.com/javaworld/jw-01-2008/jw-01-jpa1.html

JavaWorld: Understanding JPA, Part 2

http://www.javaworld.com/javaworld/jw-01-2008/jw-01-jpa2.html?page=1

Article ³Introduction to Java Persistence API´http://www.javabeat.net/javabeat/ejb3/articles/2007/04/introduction _to_java_persistence_api_jpa_ejb_3_0_1.php

TopLink Essentials (reference implementation)https://glassfish.dev.java.net/javaee5/persistence/

8/8/2019 JPA_2009-09_24_en


Resources JPA Annotation Reference

http://www.oracle.com/technology/products/ias/toplink/jpa/resources/toplink-jpa-annotations.html

Hibernate Reference Documentationhttp://docs.jboss.org/hibernate/core/3.3/reference/en/html/index.html

JPQL Language Referencehttp://openjpa.apache.org/builds/1.0.2/apache-openjpa-1.0.2/docs/manual/jpa_langref.html

JPA Query APIhttp://www.javabeat.net/javabeat/ejb3/articles/2007/04/introduction_to_java_persistence_api_jpa_ejb_3_0_6

Standardizing Java Persistence with the EJB3 Java Persistence API ±

Query APIhttp://www.onjava.com/pub/a/onjava/2006/05/17/standardizing-with-ejb3-java-

i t i ht l? l t& h t t t t

jpa_2009-09_24_en

Documents