Entities and Persistence

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. Managed/Unmanaged Entities • 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. Persistence Unit • 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 <persistence> <persistence-unit name=“titan> <jta-data-source>java:/OracleDS</jta-data-source> <properties> <property name=“org.hibernate.hbm2ddl”>update</property> </properties> </persistence-unit> </persistence>

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