1. Entities and Persistence

2. Entity Beans Topics to be Covered: Entities are POJOs Managed/Unmanaged Entities Persistence Unit EntityManager Basic Relational Mapping The Primary Key

3. Entities and Persistence Entities are POJOs

4. Entities and Persistence In Java EE 5, persistence no longer defined by EJB specification Java Persistence API –Abstraction on top of JDBC –Object-to-Relational Mapping (ORM) Engine

5. Entities and Persistence javax.persistence.EntityManager –Service that performs persistence actions Entity Creation Entity Update Entity Removal Entity Query –Manages ORM between entity classes and underlying data source –Tightly integrated with Java EE and EJB but not limited to this environment

6. POJOs Entities are plain old Java objects (POJOs) Allocated using new operator Entities do not become persistent until they are associated with an EntityManager

7. POJOs import javax.persistence.*; @Entity public class Customer { private int id; private String name; @Id @GeneratedValue public int getId() { return id; } public void setId(int id) { this.id = id; }

8. POJOs String getName() { return name; } public void setName(String name) { this.name = name; }

9. POJOs Allocated instances of the Customer class remain POJOs until you ask the EntityManager to create the entity in the database The following does not create a Customer instance in the database: Customer cust = new Customer(); cust.setName(“Bill”);

10. Entities and Persistence Managed/Unmanaged Entities

11. Entity is either –managed (attached) by an entity manager Or –unmanaged (detached) Managed –EntityManager tracks state changes –Synchronizes changes to database Unmanaged –Any state changes are not tracked by EntityManager

12. Persistence Context Set of managed entity object instances Managed by an entity manager –Tracks all changes –Flushes changes to the database Once persistence context is closed –All managed entity object instances becomes detached –Any state changes will not be synchronized to the database

13. Persistence Context Transaction-scoped –Life of context as long as a transaction –Closed with a transaction completes –Application server persistence contexts EntityManager instances injected with the PersistenceContext annotation @PersistenceContext(unitName=“titan”) EntityManager entityManager;

14. Persistence Context Transaction-scoped –Methods invoked within the context of JTA transaction @TransactionAttribute(REQUIRED) public Customer someMethod() { Customer cust = entityManager.find(Customer.class, 1); cust.setName(“new name”); return cust; }

15. Persistence Context Extended –Live longer than a transaction –Maintains conversation with database without the overhead of a transaction –Managed by application code and stateful session beans

16. Persistence Context Extended Customer cust = null; trans.begin(); cust = extendedEntityManager.find( Customer.class, 1); trans.commit(); trans.begin(); cust.setName(“Bill”); extendedEntityManager.flush(); trans.commit();

17. Persistence Context Detached Entities –Occurs when transaction scope or extended persistence context ends –Can be serialized and sent across the network to a remote client –Client can make changes and send them back to server to be merged back and synchronized with the database –Persistent objects become value objects when they are detached from a persistent context

18. Entities and Persistence Persistence Unit

19. A fixed set of classes mapped by an EntityManager to a particular database Defined in a persistence.xml file –Required deployment descriptor for Java Persistence specification Set of classes may be specified or persistence provider can scan JAR file to identify classes –Classes scanned for @Entity annotation Tied to only one data source

20. Persistence Unit java:/OracleDS update

21. Entities and Persistence EntityManager

22. Obtaining an EntityManager Java SE (and less frequently in Java EE) –Use an EntityManagerFactory –createEntityManager() returns EntityManager instances that manage an extended persistence context –Remember to close() the EntityManagerFactory

23. Obtaining an EntityManager Use static createEntityManagerFactory() method of javax.persistence.Persistence class EntityManagerFactory factory = Persistence.createEntityManagerFactory (“CRM”); ……… factory.close();

24. Obtaining an EntityManager Now to get an EntityManager, use createEntityManager() method of EntityManagerFactory class Returned EntityManager represents an extended persistence context Must explicitly enlist EntityManager instance into JTA-enabled transactions using the joinTransaction() method

25. Obtaining an EntityManager Java EE –Use EntityManager injection with @PersistenceContext annotation @Stateless public class MySessionBean implements MySessionRemote { @PersistenceContext(unitName=“titan”) private EntityManager entityManager; ……… }

26. Obtaining an EntityManager The unitName attribute identifies the persistence unit A transaction-scoped persistence context is injected by default Never call close() on an injected EntityManager

27. Interacting with an EntityManager Persisting Entities (INSERT) –Allocate an instance of entity –Set its properties –Wire up relationships with other entities –Interact with EntityManager service Customer cust = new Customer(); cust.setName(“Bill”); entityManager.persist(cust);

28. Interacting with an EntityManager Finding Entities (SELECT) –Locate by Primary Key –find() method –Returns null if entity is not found –Initializes state Customer cust = entityManager.find(Customer.class, 2);

29. Interacting with an EntityManager Finding Entities (SELECT) –Locate by Primary Key –getReference() method –Throws EntityNotFoundException if entity is not found –State not guaranteed Customer cust = null; try{ cust = entityManager.getReference(Customer.class, 2); } catch(EntityNotFoundException e) { //recovery logic }

30. Interacting with an EntityManager Finding Entities (SELECT) –Locate by Querying –EJB QL Query query = entityManager.createQuery(“from Customer c where id=2”); Customer cust = (Customer)query.getSingleResult();

31. Interacting with an EntityManager Updating Entities (UPDATE) –After locating an entity and prior to closing the persistence context –Change the state of the entity –Wire up relationships with other entities –Interact with EntityManager service // Same active persistence context Cabin cabin = entityManager.find(Cabin.class, id); cabin.setBedCount(newCount)

32. Interacting with an EntityManager Merging Entities –Merges state changes made to a detached entity back into persistent storage –Scenario: Remote client finds an object in the database using a session bean method Object detached from entity manager, serialized, and returned to the remote client Client makes changes to detached object, and sends the object back to the server using a session bean method Method takes updated object and merges it into the current persistence context using merge() method public void updateCabin(Cabin cabin) { Cabin copy = entityManager.merge(cabin); }

33. Interacting with an EntityManager Merging Entities –If no Cabin instance with the same ID currently being managed, a managed copy is returned by merge() method –If Cabin instance with the same ID currently being managed, contents of parameter are copied into managed instance, and a managed instance is returned by merge() method. –In both cases above, the parameter remains detached and unmanaged public void updateCabin(Cabin cabin) { Cabin copy = entityManager.merge(cabin); }

34. Interacting with an EntityManager Removing Entities (DELETE) –After locating an entity and prior to closing the persistence context –Remove the entity –After remove() is invoked, instance will no longer be managed (it becomes detached) // Same active persistence context Cabin cabin = entityManager.find(Cabin.class, id); entityManager.remove(cabin);

35. Interacting with an EntityManager refresh() –Refreshes state of entity from the database contains() –Takes entity instance as a parameter –Returns true if instance is currently being managed by the persistence context clear() –Detaches all managed entity instances from the current persistence context

36. Interacting with an EntityManager flush() –Changes made when calling persist(), merge(), and remove() are not synchronized with the database until the entity manager decides to flush –flush() forces synchronization to occur

37. Entities and Persistence Basic Relational Mapping

38. Mapping Persistent Objects Entities –Model business concepts that can be expressed as nouns –Describe both the state and behavior of real-world objects –Represent data in the database –Provide a simple mechanism for accessing and changing data –Provide opportunities for software reuse Persistence –The process of coordinating the data represented by a bean instance with the database –Java persistence specification provides a portable object-to-relational mapping (ORM)

39. Programming Model Summary Entities are POJOs Interact with entity manager service to persist, update, remove, locate, and query entities –Enrolls entity in transactions –Persists state to database

40. An Entity Must have a no-argument constructor @javax.persistence.Entity annotation denotes the class should be mapped to a database @javax.persistence.Id annotation marks which property will be used as the primary key All other properties map to a column of the same name and type Table name default to the unqualified name of the entity

41. An Entity Example package edu.weber.domain; import javax.persistence.*; import java.io.*; @Entity public class Customer implements Serializable { private long id; private String firstName; private String lastName; @Id public long getId() { return id; } public void setId(long id) { this.id = id; } public String getFirstName() { return firstName; } public void setFirstName(String fn) { this.firstName = fn; } public String getLastName() { return lastName; } public void setLastName(String ln) { this.lastName = ln; } }

42. Corresponding Table Definition create table Customer ( id long primary key not null, firstName VARCHAR(255), lastName VARCHAR(255) );

43. Elementary Schema Mappings @javax.persistence.Table @javax.persistence.Column Assume a different table definition from before create table CUSTOMER_TABLE ( CUST_ID integer primary key not null, FIRST_NAME VARCHAR(20) not null, lastName VARCHAR(255) not null );

44. Elementary Schema Mappings @javax.persistence.Table Specifies the relational table the bean class maps to @Entity @Table(name=“CUSTOMER_TABLE”) public class Customer implements …………

45. Elementary Schema Mappings @javax.persistence.Column Specifies how a particular field or property is mapped to a column in a table @Id @Column(name=“CUST_ID”, nullable=false, columnDefinition=“integer”) public long getId() { return id; } public void setId(long id) { this.id = id; } @Column(name=“FIRST_NAME”, length=20, nullable=false) public String getFirstName() { return firstName; } public void setFirstName(String fn) { this.firstName = fn; } @Column(nullable=false) public String getLastName() { return lastName; } public void setLastName(String ln) { this.lastName = ln; }

46. Entities and Persistence The Primary Key

47. Primary Key Overview Uniquely identifies an entity Can be any serializable type –Primitive type –Primitive wrappers (Integer, Double, etc.) –java.lang.String –Custom Classes composed of the above Single-Field (or Property) Primary Key –Map to a single persistence field Compound Primary Key –Custom-defined object whose instance variables map to several persistence fields

48. Single-Property Primary Keys Map to one of the entity’s persistence fields @javax.persistence.Id Identifies one (or more) properties that make up the primary key @Id public long getId() { return id; } public void setId(long id) { this.id = id; }

49. Autogenerated keys @javax.persistence.GeneratedValue @Id @GeneratedValue(strategy=GenerationType.AUTO) public long getId() { return id; } public void setId(long id) { this.id = id; }

50. Compound Primary Keys Map to one or more of the entity’s persistence fields Implemented by a custom class –Must be serializable –Define equals() and hashcode() methods –Instance fields must correspond to entity’s persistence fields in both name and type –Public no-argument constructor required

51. Compound Primary Key Example public class CustomerPK implements java.io.Serializable { private String lastName; private long ssn; public CustomerPK() { } public CustomerPK(String lname, long ssn) { this.lastName = lname; this.ssn = ssn } // …getters and setters… public boolean equals(Object obj) { if (obj == this) return true; if (!(obj instanceof CustomerPK)) return false; CustomerPK pk = (CustomerPK)obj; if(!lastName.equals(pk.lastName) || ssn != pk.ssn) return false; else return true; } public int hashCode() { return lastName.hashCode() + (int)ssn; } }

52. Annotating the Entity Use @javax.persistence.IdClass @Entity @IdClass(CustomerPK.class) public class Customer implements Serializable { private String firstName; private String lastName; private long ssn; public String getFirstName() { return firstName; } public void setFirstName(String fn) { this.firstName = fn; } @Id public String getLastName() { return lastName; } public void setLastName(String ln) { this.lastName = ln; } @Id public long getSsn() { return ssn; } public void setSsn(long ssn) { this.ssn = ssn; } }

53. Querying the Customer CustomerPK pk = new CustomerPK(“Burke”, 012345678); Customer cust = entityManager.find(Customer.class, pk);

54. Entity Beans Topics to be Covered: Entities are POJOs Managed/Unmanaged Entities Persistence Unit EntityManager Basic Relational Mapping The Primary Key