Java Persistence API

1. Java Persistence API Mario Peshev Svetlin Nakov National Academy for Software Development National Academy for Software Development academy.devbg.org academy.devbg.org

2. Contents • About JPA • Entities • Queries • Mappings • Persistence

3. About JPA Introduction

4. About JPA • What is Java Persistence API (JPA)? • Database persistence technology for Java • Object-relational mapping (ORM) engine • Operates with POJO entities • Similar to Hibernate and JDO • JPA maps Java classes to database tables • Maps relationships between tables as associations between classes • Provides CRUD functionality • Create, read, update, delete

5. History of JPA • History of JPA • Created as part of EJB 3.0 within JSR 220 • Released May 2006 as part of Java EE 5 • Can be used as standalone library • Standard API with many implementations • OpenJPA – http://openjpa.apache.org/ • Hibernate – http://www.hibernate.org • TopLink JPA – http://www.oracle.com/technology/jpa • JPOX – http://www.jpox.org/

6. JPA Reference Implementation • Part of “Glassfish” project on java.net • Glassfish is RI for the entire Java EE platform • Sun and Oracle partnership • Sun Application Server + Oracle persistence • JPA open-source implementation called “TopLink Essentials” • Donated by Oracle, derived from Oracle TopLink • All open source (under CDDL license) • Anyone can download/use source code or binary code in development or production

7. Entities Defining Simple Entity Classes

8. Anatomy of an Entity • Just a POJO class • Abstract or concrete top level Java class • Non-final fields/properties, no-arguments constructor • No required interfaces • No requirement for business or callback interfaces • Direct field or property-based access • Getter/setter can contain logic (e.g. validation)

9. The Minimal Entity • Must be indicated as an Entity • @Entity annotation on the class: • Entity entry in XML mapping file @Entity public class Employee { … } <entity class="com.acme.Employee"/>

10. The Minimal Entity • Must have a persistent identifier (primary key): @Entity public class Employee { @Id int id; public int getId() { return id; } public void setId(int id) { this.id = id;} }

11. Persistent Identity (Id) • Identifier (id) in entity, primary key in database • Uniquely identifies entity in memory and in db • Different ID definitions • Simple id • Compound id • Embedded id

12. Id Definitions • Simple id – single field/property • Compound id – multiple fields • Embedded id – single field of PK class type @Id int id; @Id int id; @Id String name; @EmbeddedId EmployeePK id;

13. Identifier Generation • Identifiers can be generated in the database • @GeneratedValue on the ID • 3 pre-defined generation strategies: • IDENTITY, SEQUENCE, TABLE • May pre-exist or be generated • AUTO strategy indicates that the provider will choose a strategy @Id @GeneratedValue int id;

14. Using Identity or Sequence • Using identity (auto increment column in the database) for Id generation: • Using database sequence for Id generation: @Id@GeneratedValue(strategy=GenerationType.IDENTITY)private int id; @Id@GeneratedValue(generator="UsersSeq")@SequenceGenerator(name="UsersSeq", sequenceName="USERS_SEQ")private long id;

15. Simple Column Mappings • Mapping a property to a database column: • A column name can be explicitly given: @Entity public class Message { private String message; public void setMessage(String msg) {message = msg; } public String getMessage() { return message; } } @Column(name="SAL") private double salary;

16. Persistent Contexts and EntityManager Manipulating Database Entities

17. Persistence Context (PC) • A set of “managed” entity instances • Keyed by persistent identity • Only one entity with a given persistent ID may exist in the PC • Added to the PC, but not individually removable (“detached”) • Managed by EntityManager • Contents of PC change as a result of operations on EntityManager API

18. Persistence Context (PC) Persistence Context Application EntityManager MyEntity A MyEntity C MyEntity a MyEntity B MyEntity b Entities Entity state

19. Entities Lifecycle

20. Entity Manager • Client-visible object for operating on entities • API for all the basic persistence operations (CRUD) • Manages connection and transaction • Can think of it as a proxy to a persistence context

21. Operations on Entities • EntityManager API • persist() – persists given entity object into the database (SQL INSERT) • remove() – deletes given entity object into the database (SQL DELETE by PK) • refresh() – reloads given entity object from the database (SQL SELECT by PK) • merge() – synchronize the state of detached entity with the PC • find() – execute a simple query by PK

22. Operations on Entities (2) • createQuery()– creates a query instance using dynamic JPQL • createNamedQuery()– creates an instance for a predefined JPQL query • createNativeQuery()– creates an instance for an SQL query • contains()– determine if given entity is managed by the PC • flush()– forces changes in the PC to be saved in the database (automatically called on transaction commit)

23. persist() • Insert a new entity instance into the database (SQL INSERT / UPDATE) • Save the persistent state of the entity and any owned relationship references • Entity instance becomes managed public Customer createCustomer(int id, String name) { Customer cust = new Customer(id, name); entityManager.persist(cust); return cust; }

24. find() and remove() • find() • Obtain a managed entity instance (SQL SELECT by PK) • Return null if not found • remove() • Delete a managed entity by PK public void removeCustomer(Long custId) { Customer cust = entityManager. find(Customer.class, custId); entityManager.remove(cust); }

25. merge() • Merges the state of detached entity into a managed copy of the detached entity • Returned entity has a different Java identity than the detached entity • May invoke SQL SELECT public Customer storeUpdatedCustomer(Customer cust) { return entityManager.merge(cust); }

26. Queries Using JPQL

27. Queries • Dynamic or statically defined (named queries) • Criteria using JPQL (Java Persistence API Query Language, a kind of SQL) • Native SQL support (when required) • Named parameters bound at execution time (no SQL injection)

28. Queries (2) • Pagination and ability to restrict size of result • Single/multiple-entity results, data projections • Bulk update and delete operation on an entity • Standard hooks for vendor-specific hints

29. Query API • Query instances are obtained from factory methods on EntityManager, e.g. • Query API: • getResultList() – execute query returning multiple results • getSingleResult() – execute query returning single result • executeUpdate() – execute bulk update or delete Query query = entityManager.createQuery( "SELECT e from Employee e");

30. Query API (2) • 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

31. 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

32. Dynamic Queries – Example • Return all instances of the given entity type • JPQL string composed from entity type • For example, if “Account” was passed in then JPQL string would be: “select a from Account a” public List findAll(String entityName){ return entityManager.createQuery( "select e from " + entityName + " e") .setMaxResults(100) .getResultList(); }

33. Named Queries • Use createNamedQuery() factory method at runtime and pass in the query name • Query must be statically defined • Query names are “globally” scoped • Provider can to precompile the queries and return errors at deployment time • Can include parameters and hints in static query definition

34. Named Queries – Example @NamedQuery(name="Sale.findByCustId", query="select s from Sale s where s.customer.id = :custId order by s.salesDate") public List findSalesByCustomer(Customer cust) { return (List<Customer>)entityManager. createNamedQuery("Sale.findByCustId") .setParameter("custId", cust.getId()) .getResultList(); }

35. ORM Mappings Annotations or XML

36. Object/Relational Mapping • Map persistent object state to relational database • Map relationships to other entities • Metadata may be annotations or XML (or both)

37. Annotations / XML • Annotations • Logical—object model (e.g. @OneToMany) • Physical—DB tables and columns (e.g. @Table) • XML • Can specify scoped settings or defaults • Standard rules for default db table/column names

38. Fetching and Cascading • State may be “fetched” as EAGER or LAZY • LAZY – container defers 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

39. Simple Mappings • Direct mappings of fields to columns • @Basic – optional, indicates simple mapped attribute • Can specify fetch=EAGER / LAZY • Maps any of the common simple Java types • Primitives, wrappers, serializable, etc. • Used in conjunction with @Column • Can override any of the defaults

40. @Entity @Id @Column(name=“CREDIT”) @Lob Simple Mappings public class Customer { int id; String name; int c_rating; Image photo; } CUSTOMER PHOTO ID NAME CREDIT

41. Simple Mappings <entity class="example.Customer"> <attributes> <id name="id"/> <basic name="c_rating"> <column name="CREDIT"/> </basic> <basic name="photo"><lob/></basic> </attributes> </entity>

42. Relationship Mappings • Common relationship mappings supported • @ManyToOne, @OneToOne – single entity • @OneToMany, @ManyToMany – collection • Unidirectional or bidirectional • Owning and inverse sides • Owning side specifies the physical mapping • @JoinColumn to specify foreign key column • @JoinTable decouples physical relationship mappings from entity tables

43. @Entity @Id @ManyToOne ManyToOne Mapping public class Sale { int id; ... Customer cust; } } SALE ID CUST_ID . . . CUSTOMER ID . . .

44. ManyToOne Mapping <entity class="example.Sale"> <attributes> <id name="id" /> ... <many-to-one name="cust" /> </attributes> </entity>

45. @Entity @Id OneToMany Mapping public class Customer { int id; ... Set<Sale> sales; } CUSTOMER ID . . . @OneToMany(mappedBy=“cust”) public class Sale { int id; ... Customer cust; } @Entity SALE ID . . . CUST_ID @Id @ManyToOne

46. OneToMany Mapping <entity class="example.Customer"> <attributes> <id name="id" /> ... <one-to-many name="sales" mapped- by="cust"/> </attributes> </entity>

47. Using Persistence API Creating JPA Applications

48. Persistence in Java SE • No deployment phase • Application must use a “Bootstrap API” to obtain an EntityManagerFactory • Resource-local EntityManagers • Application uses a local EntityTransaction obtained from the EntityManager

49. Entity Transactions • Only used by resource-local EntityManagers • Transaction demarcation under explicit application control using EntityTransaction API • begin(), commit(), rollback(), isActive() • Underlying (JDBC) resources allocated by EntityManager as required

50. Persistence Class • javax.persistence.Persistence • Root class for bootstrapping an EntityManager • Locates provider service for a named persistence unit • Invokes on the provider to obtain an EntityManagerFactory