1. Enterprise Java Java Persistence: EntityManager

2. Enterprise Java v070903Java Persistence: EntityManager2 Goals Become familiar with the Java Persistence EntityManager –API –Provider Hibernate

3. Enterprise Java v070903Java Persistence: EntityManager3 Overview Earlier versions of EJB Specification defined the persistence layer –javax.ejb.EntityBean Java EE 5 has moved persistence to its own specification –javax.persistence API (1.0)‏ ease of use API above JDBC Provides –Object/Relational Mapping (ORM) Engine –Query Language (SQL-Like, based on former EJB-QL)‏

4. Enterprise Java v070903Java Persistence: EntityManager4 javax.persistence.EntityManager Replaces much of the EJB 2.x “Home” functionality Handles O/R Mapping of Entities to the database Provides APIs –inserting objects into database –getting objects from database –synchronizing objects with database –querying database Provides caching Coordinates with transactional services (JTA)‏ Tightly integrated with Java EE and EJB, but not limited to that environment

5. Enterprise Java v070903Java Persistence: EntityManager5 Entities (formerly and sometimes still called Entity Beans)‏ are now Plain Old Java Objects (POJOs)‏ –nothing special happens when calling new Author author = new Author(); are not persistent until associated with an EntityManager em.persist(author);

6. Enterprise Java v070903Java Persistence: EntityManager6 Example Author POJO Entity @javax.persistence.Entity public class Author { private long id; private long version=0; private String firstName; private String lastName; private String subject; private Date publishDate; public Author() {} public Author(long id) { this.id = id; } @Id @GeneratedValue public long getId() { return id;} private void setId(long id) { this.id = id; } public String getFirstName() { return firstName; } public void setFirstName(String firstName) { this.firstName = firstName; }... }

7. Enterprise Java v070903Java Persistence: EntityManager7 Creating Entity in Database log_.info("testCreate()"); Author author = new Author(); //primary key will be gen author.setFirstName("dr"); author.setLastName("seuss"); author.setSubject("children"); author.setPublishDate(new Date()); log_.info("creating author:" + author); em.persist(author); log_.info("created author:" + author); //output -creating author:id=0, fn=dr, ln=seuss, subject=children, pdate=Fri Sep 15 11:54:15 EDT 2006 -created author:id=50, fn=dr, ln=seuss, subject=children, pdate=Fri Sep 15 11:54:15 EDT 2006

8. Enterprise Java v070903Java Persistence: EntityManager8 Managed and Unmanaged Entities Unmanaged state (detached)‏ –instance not associated with an EntityManager –state changes are not tracked –can be serialized to client and returned to be synchronized with database –nothing equivalent to this state in EJB 2.1 entity beans Managed state (attached)‏ –instance associated with an EntityManager –state changes are tracked within a Persistence Context –EJB 2.1 entity beans were always managed client interfaced with data through a proxy or state transferred through a Data Transfer Object

9. Enterprise Java v070903Java Persistence: EntityManager9 Persistence Context A set of attached entity instances managed by an EntityManager All entities become detached once closed Two types –Transaction-scoped Persistence Contexts begin/end at transaction boundaries only made available through container managed persistence contexts –Extended Persistence Contexts live beyond any single transaction allow longer-lived interactions with database without lengthy transactions tying up database resources

10. Enterprise Java v070903Java Persistence: EntityManager10 Persistence Context Examples Transaction-scoped (inside server container)‏ @PersistenceContext(unitName=”jpaDemo”) EntityManager em; @TransactionAttribute(REQUIRED)‏ public void update(long authorId, String type) { Author author = em.find(Author.class, authorId); author.setType(type); } Extended (inside or outside server container)‏ EntityManager em = Persistence. createEntityManagerFactory(“jpaDemo”).createEntityManager(); tx.begin(); //tx 1 begins Author author = em.find(Author.class, authorId); tx.commit(); //tx 1 ends, but author remains managed... tx.begin(); //tx 2 begins author.setType(type); tx.commit(); //tx 2 ends, and author is still managed until close

11. Enterprise Java v070903Java Persistence: EntityManager11 Persistence Unit A set of classes that are mapped to the database defined in META-INF/persistence.xml must have an identity –“” is a valid identity Classes –may be named in persistence.xml file –may be automatically scanned for in the classpath orm.xml –optionally provided to augment, provide, or replace class persistence metadata –(more on orm.xml in Core ORM topic)‏

12. Enterprise Java v070903Java Persistence: EntityManager12 Example Component Layout META-INF/ +---persistence.xml ejava + ---examples +---dao +---DAOException.class +---AuthorDAO.class +---jpa | +---JPAAuthorDAO.class | +---JPADAOBase.class +--domain +---Author.class

13. Enterprise Java v070903Java Persistence: EntityManager13 Example persistence.xml <persistence xmlns="http://java.sun.com/xml/ns/persistence" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://java.sun.com/xml/ns/persistence http://java.sun.com/xml/ns/persistence/persistence_1_0.xsd" version="1.0"> java:/ejavaDS <property name="jboss.entity.manager.jndi.name" value="java:/EntityManagers/ejava"/> referenced by name global JNDI name by which provider references resource (will be used when deployed within server)‏ may use properties element in Java SE environments that lack JNDI vendor-specific way to configure persistence provider

14. Enterprise Java v070903Java Persistence: EntityManager14 Another Example persistence.xml <persistence xmlns="http://java.sun.com/xml/ns/persistence" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://java.sun.com/xml/ns/persistence http://java.sun.com/xml/ns/persistence/persistence_1_0.xsd" version="1.0"> org.hibernate.ejb.HibernatePersistence <property name="hibernate.cache.provider_class" value="net.sf.ehcache.hibernate.Provider"/> <property name="hibernate.dialect" value="org.hibernate.dialect.HSQLDialect"/> <property name="hibernate.connection.url" value="jdbc:hsqldb:hsql://localhost:9001"/> <property name="hibernate.connection.driver_class" value="org.hsqldb.jdbcDriver"/> <property name="hibernate.connection.password" value=""/> <property name="hibernate.connection.username" value="sa"/> </persistence

15. Enterprise Java v070903Java Persistence: EntityManager15 persistence.xml elements name – identity to reference Persistence Unit provider – fully qualified name of javax.persistence.PersistenceProvider –not needed if provider found in classpath acceptable mapping-file – resource path to optional mapping file –can be used to specify es or specify/override @Annotation details jta-data-source –vendor-specific reference to data source using JTA transactions non-jta-data-source –vendor-specific reference to data source using RESOURCE_LOCAL transactions jar-file –optional/additional jar file to scan for classes class –specifies entity classes not automatically scanned by provider exclude-unlisted-classes –if set, provider will not automatically scan archive for entity classes properties –may be used to provide vendor-specific properties to configure persistence providers

16. Enterprise Java v070903Java Persistence: EntityManager16 Specifying an optional orm.xml file <persistence xmlns="http://java.sun.com/xml/ns/persistence" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://java.sun.com/xml/ns/persistence http://java.sun.com/xml/ns/persistence/persistence_1_0.xsd" version="1.0">... META-INF/orm.xml... </persistence

17. Enterprise Java v070903Java Persistence: EntityManager17 Optional orm.xml overrides <entity-mappings xmlns="http://java.sun.com/xml/ns/persistence/orm" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://java.sun.com/xml/ns/persistence/orm http://java.sun.com/xml/ns/persistence/orm_1_0.xsd" version="1.0"> <entity class="ejava.examples.dao.domain.Author" metadata-complete="false">

18. Enterprise Java v070903Java Persistence: EntityManager18 Entities Discovered classes with @Entity annotation –in the persistence.xml's JAR file –contained in any JAR file listed in jar-file element classes mapped –with META-INF/orm.xml –with custom mapping files classes listed in persistence.xml's “ ” element

19. Enterprise Java v070903Java Persistence: EntityManager19 Java SE Steps Startup –Get EntityManagerFactory Runtime –Create EntityManager –Start Transaction –Interact with Entity Manager –Commit Transaction –Close EntityManager Shutdown –Close EntityManagerFactory

20. Enterprise Java v070903Java Persistence: EntityManager20 javax.persistence.Persistence used to bootstrap persistence in Java SE environments public class javax.persistence.Persistence { public static java.lang.String PERSISTENCE_PROVIDER; public javax.persistence.Persistence(); public static EntityManagerFactory createEntityManagerFactory(String puName); public static EntityManagerFactory createEntityManagerFactory(String puName, Map props); } example usage EntityManagerFactory emf = Persistence.createEntityManagerFactory(“jpaDemo”);

21. Enterprise Java v070903Java Persistence: EntityManager21 javax.persistence.EntityManagerFactory used to obtain reference to EntityManager in standard Java SE environments package javax.persistence; public interface EntityManagerFactory{ EntityManager createEntityManager(); EntityManager createEntityManager(Map props); void close(); boolean isOpen(); } Map used to supply or override properties in persistence.xml close() and isOpen() only valid for non-injected EMFs example usage – EntityManager em = emf.createEntityManagerFactory();

22. Enterprise Java v070903Java Persistence: EntityManager22 javax.persistence.EntityManager package javax.persistence; public interface EntityManager{ EntityTransaction getTransaction(); void persist(java.lang.Object); Object find(Class, Object pKey); Object getReference(Class, Object pKey); boolean contains(Object); Object merge(java.lang.Object); void refresh(java.lang.Object); void remove(java.lang.Object); Object find(java.lang.Class, java.lang.Object); void flush(); void clear(); void close(); isOpen(); --- Query createQuery(java.lang.String); Query createNamedQuery(java.lang.String); Query createNativeQuery(java.lang.String); Query createNativeQuery(java.lang.String, java.lang.Class); Query createNativeQuery(java.lang.String, java.lang.String);...

23. Enterprise Java v070903Java Persistence: EntityManager23 persist()‏ Author author = new Author(nextId()); author.setFirstName("dr"); author.setLastName("seuss"); author.setSubject("children"); author.setPublishDate(new Date()); em.persist(author); Extended persistence contexts –queues write until associated with transaction Transaction-scoped persistence contexts –illegal to call outside the scope of a transaction Actual write to the database depends on FlushMode –manually controlled with flush() call

24. Enterprise Java v070903Java Persistence: EntityManager24 find()‏ Author author2=null; author2 = em.find(Author.class, id); log_.info("got author author:" + author2); got author author:id=51, fn=thing, ln=one, subject=children, pdate=Fri Sep 15 11:54:15 EDT 2006 Returns an instance of the class associated with the specified primary key value –relationships are instantiated according to lazy-loading policies Returns null if primary key not found Uses generics, so no casting is necessary Ids can be autoboxed without a manual wrapper can be called outside the scope of a transaction will be attached to open persistence context –second find() will return same object

25. Enterprise Java v070903Java Persistence: EntityManager25 getReference()‏ Author author2=null; author2 = em.getReference(Author.class, id); log_.info("got author author:" + author2); Similar to find()‏ –Returns an instance of the class associated with the specified primary key value no guarantee that object state initialized –Throws EntityNotFoundException if primary key not found

26. Enterprise Java v070903Java Persistence: EntityManager26 createQuery()‏ 5 createQuery() methods Query createQuery(String ejbqlString); Query createNamedQuery(String name); Query createNativeQuery(String sqlString); Query createNativeQuery(String sqlString, Class resultClass); Query createNativeQuery(String sqlString, String resultSetMap); example usage Query query = em.createQuery("from jpaAuthor where id=" + id); Author author = (Author)query.getSingleResult(); use EJB-QL and native (SQL) query languages similar to find/getReference()‏ –returned objects attached to open persistence context

27. Enterprise Java v070903Java Persistence: EntityManager27 updating entities Updates to managed entities automatically get propagated to database according to flush policy public Author update(Author author) { Author dbAuthor = em.find(Author.class,author.getId()); dbAuthor.setFirstName(author.getFirstName()); dbAuthor.setLastName(author.getLastName()); dbAuthor.setSubject(author.getSubject()); dbAuthor.setPublishDate(author.getPublishDate()); return dbAuthor; }

28. Enterprise Java v070903Java Persistence: EntityManager28 merge()‏ merges state changes to detached objects back into persistent storage public Author updateByMerge(Author author) { Author managedAuthor = em.merge(author); return managedAuthor; } Original is left detached Object returned is managed Returned object is added to persistence if did not already exist Updates are made to existing object if already exists

29. Enterprise Java v070903Java Persistence: EntityManager29 remove()‏ public void remove(Author author) { em.remove(author); } –removes object from database physically performed in database according to flush policy cascades to related objects according to cascade policy –object will be detached

30. Enterprise Java v070903Java Persistence: EntityManager30 refresh() and contains()‏ refresh()‏ Author author = em.find(Author.class, id); em.refresh(author); –used to make sure entity is in sync with database cascades to related entities depending on cascade policy –entity must be currently managed by entity manager instance contains()‏ if (em.contains(author)) {... } –used to test if instance is being managed by entity manager instance

31. Enterprise Java v070903Java Persistence: EntityManager31 clear() and flush()‏ clear()‏ –detaches all entities –does not commit queued changes call flush() prior to clear()‏ flush()‏ –changes not synchronized with database until entity manager flushed persist(), merge(), remove()‏ –occurs automatically before executing correlated queries –permits query to reflect changes in persistence context transaction commit –not impacted by primary key finders find(), getReference()‏ –FlushMode AUTO – default and most sane COMMIT – an optimization to only flush and end of transaction. May limit amount of database locking that occurs

32. Enterprise Java v070903Java Persistence: EntityManager32 lock() and getDelegate()‏ lock()‏ –provides a pessimistic write lock for entity –will be covered with later during transaction topics getDelegate()‏ –returns vendor object that implements EntityManager interface –used to expose vendor-specific extension API

33. Enterprise Java v070903Java Persistence: EntityManager33 EntityTransactions Only available for Entity Managers with an extended persistence context –Transaction-scoped persistence contexts are only available with containers that support JTA transactions –Extended persistence contexts generally pertain to Java SE applications using javax.persistence.Persistence class to get EntityManagerFactory transaction-like API for managing transactions within the single resource transaction context obtained from EntityManager javax.persistence.EntityTransaction tx = em.getTransaction(); tx.begin()‏ tx.commit()‏ tx.isActive()‏ tx.rollback()‏

34. Enterprise Java v070903Java Persistence: EntityManager34 Example private EntityManager em =... public void testQuery() throws Exception { Author author = new Author(); author.setFirstName("test"); author.setLastName("Query"); author.setSubject("testing"); author.setPublishDate(new Date()); em.persist(author); //need to associate em with Tx to allow query to see entity in DB try { em.getTransaction().begin(); //note that the persist does not have to be within the tx em.getTransaction().commit(); } catch (Exception ex) { em.getTransaction().rollback(); fail("" + ex); } Author author2 = null; Query query = em.createQuery( "from jpaAuthor where id=" + author.getId()); author2 = (Author)query.getSingleResult(); assertNotNull(author2); assertEquals(author.getFirstName(), author2.getFirstName()); assertEquals(author.getLastName(), author2.getLastName()); assertEquals(author.getSubject(), author2.getSubject()); assertEquals(author.getPublishDate(), author2.getPublishDate()); }

35. Enterprise Java v070903Java Persistence: EntityManager35 Hibernate Persistence Container

36. Enterprise Java v070903Java Persistence: EntityManager36 Classpath hibernate.jar hibernate-annotations.jar hibernate-entitymanager.jat third party jars –automatically downloaded with maven –can also get them using the thirdparty-all.jar that is distributed with the JBoss embeddable container

37. Enterprise Java v070903Java Persistence: EntityManager37 Example Hibernate Maven Dependencies org.hibernate hibernate 3.2.1.ga test org.hibernate hibernate-annotations 3.2.1.ga test org.hibernate hibernate-entitymanager 3.2.1.ga test

38. Enterprise Java v070903Java Persistence: EntityManager38 JPAUtil.java package ejava.examples.dao.jpa; import java.util.HashMap; import java.util.Map; import javax.persistence.EntityManagerFactory; import javax.persistence.Persistence; public class JPAUtil { private static final Map factories = new HashMap (); public static EntityManagerFactory getEntityManagerFactory(String puName) { EntityManagerFactory emf = factories.get(puName); if (emf == null) { synchronized(factories) { emf = factories.get(puName); if (emf == null) { emf = Persistence.createEntityManagerFactory(puName); factories.put(puName, emf); } return emf; } public static void close() { synchronized(factories) { for(String puName : factories.keySet()) { factories.get(puName).close(); } factories.clear(); }

39. Enterprise Java v070903Java Persistence: EntityManager39 JUnit Setup public class AllTest extends TestCase { private static Log log_ = LogFactory.getLog(AllTest.class); public static Test suite() { TestSuite tests = new TestSuite(); tests.addTestSuite(JPAExtendedOnlyDemo.class); TestSetup wrapper = new TestSetup(tests) { //one-time setup public void setUp() throws Exception { } //one-time tear down public void tearDown() throws Exception { JPAUtil.close(); } }; return wrapper; }

40. Enterprise Java v070903Java Persistence: EntityManager40 JUnit Tests public class JPAExtendedOnlyDemo extends TestCase { private EntityManager em; public void setUp() throws Exception { EntityManagerFactory emf = JPAUtil.getEntityManagerFactory(“jpaDemo”); em = emf.createEntityManager(); } public void tearDown() throws Exception { em.getTransaction().begin(); em.flush(); em.close(); em.getTransaction().commit(); } public void testCreate() throws Exception { Author author = new Author(); author.setFirstName("dr"); author.setLastName("seuss"); author.setSubject("children"); author.setPublishDate(new Date()); em.persist(author); }

41. Enterprise Java v070903Java Persistence: EntityManager41 Build and Test Environment org.apache.maven.plugins maven-compiler-plugin 1.5 <!-- set test JVM root classpath so persistence framework can locate entities during classpath scan --> org.apache.maven.plugins maven-surefire-plugin ${surefire.argLine} java.class.path target/classes

42. Enterprise Java v070903Java Persistence: EntityManager42 Summary Java Persistence API –Java standard for mapping objects to relational databases –currently part of Java EE; will be in Java SE 6 –eliminates the need or desire for EJB 2.1 entity Entity –a POJO –operates both detached and managed by OR Mapping Persistence Unit –a set of entity classes mapped to the database schema Persistence Context –a set of objects that managed –Transaction-scoped or Extended javax.persistence.EntityManager –manages objects in a persistence context javax.persistence.EntityManagerFactory –used to create individual entity managers javax.persistence.Persistence –used to bootstrap EntityManagerFactory into Java SE applications

43. Enterprise Java v070903Java Persistence: EntityManager43 References “Enterprise JavaBeans 3.0, 5 th Edition”; Burke & Monsen-Haefel; ISBN 0-596-00978-X; O'Reilly