From e79afeb58806879eeb79c04c5bc8e6ab2d8c5632 Mon Sep 17 00:00:00 2001 From: Steve Ebersole Date: Tue, 31 Aug 2010 17:59:31 +0000 Subject: [PATCH] HHH-5445 - Write a jpa/entitymanager tutorial guide git-svn-id: https://svn.jboss.org/repos/hibernate/core/trunk@20292 1b8cb986-b30d-0410-93ca-fae66ebed9b2 --- .../en-US/Hibernate_Getting_Started_Guide.xml | 1 + .../en-US/content/tutorial_annotations.xml | 17 +-- .../docbook/en-US/content/tutorial_jpa.xml | 128 ++++++++++++++++++ .../docbook/en-US/content/tutorial_native.xml | 4 +- .../em/EntityManagerIllustrationTest.java | 3 +- .../test/resources/META-INF/persistence.xml | 2 +- 6 files changed, 143 insertions(+), 12 deletions(-) create mode 100644 documentation/quickstart/src/main/docbook/en-US/content/tutorial_jpa.xml diff --git a/documentation/quickstart/src/main/docbook/en-US/Hibernate_Getting_Started_Guide.xml b/documentation/quickstart/src/main/docbook/en-US/Hibernate_Getting_Started_Guide.xml index 42f639bfa0..c85e93d2b8 100644 --- a/documentation/quickstart/src/main/docbook/en-US/Hibernate_Getting_Started_Guide.xml +++ b/documentation/quickstart/src/main/docbook/en-US/Hibernate_Getting_Started_Guide.xml @@ -31,6 +31,7 @@ + \ No newline at end of file diff --git a/documentation/quickstart/src/main/docbook/en-US/content/tutorial_annotations.xml b/documentation/quickstart/src/main/docbook/en-US/content/tutorial_annotations.xml index f90c3b8d65..0cb001e683 100644 --- a/documentation/quickstart/src/main/docbook/en-US/content/tutorial_annotations.xml +++ b/documentation/quickstart/src/main/docbook/en-US/content/tutorial_annotations.xml @@ -30,7 +30,7 @@ -
+
The annotated entity Java class The entity class in this tutorial is org.hibernate.tutorial.annotations.Event @@ -39,7 +39,7 @@ annotations to provide the metadata instead of a separate hbm.xml file. - + Identifying the class as an entity @Entity @Table( name = "EVENTS" ) @@ -57,7 +57,7 @@ public class Event { EVENT). - + Identifying the identifier property @Id @GeneratedValue(generator="increment") @@ -75,7 +75,7 @@ public Long getId() { strategy for this entity's identifier values. - + Identifying basic properties public String getTitle() { return title; @@ -112,14 +112,15 @@ public Date getDate() { - With help of the Developer Guide, add an association to the Event - entity to model a message thread. + With help of the Developer Guide, add an association to + the Event entity to model a message thread. - With help of the Developer Guide, add a callback to receive notifications when an - Event is created, updated or deleted. Try the same with an event listener. + With help of the Developer Guide, add a callback to + receive notifications when an Event is created, updated or deleted. Try + the same with an event listener. diff --git a/documentation/quickstart/src/main/docbook/en-US/content/tutorial_jpa.xml b/documentation/quickstart/src/main/docbook/en-US/content/tutorial_jpa.xml new file mode 100644 index 0000000000..1dd1c54645 --- /dev/null +++ b/documentation/quickstart/src/main/docbook/en-US/content/tutorial_jpa.xml @@ -0,0 +1,128 @@ + + + + + Tutorial Using the <firstterm><phrase>Java Persistence API (JPA)</phrase></firstterm> + + + This tutorial is located within the download bundle under entitymanager and illustrates + + + + using annotations to provide mapping information + + + + + using JPA + + + + + +
+ <filename>persistence.xml</filename> + + + The previous tutorials used the Hibernate-specific + hibernate.cfg.xml configuration file. JPA, + however, defines a different bootstrap process that uses its own configuration file + named persistence.xml. How this bootstrapping works is defined + by the JPA specification. In Java SE environments the + persistence provider (Hibernate in this case) is required to locate all JPA + configuration files by classpath lookup of the META-INF/persistence.xml resource + name. + + + + <filename>persistence.xml</filename> + + + ... + +]]> + + + + persistence.xml files should provide a unique name for each + persistence unit. This name is how applications reference the configuration + while obtaining an javax.persistence.EntityManagerFactory reference. + + + + The settings defined in the properties element were already discussed in + . Here the javax.persistence-prefixed + varieties are used when possible. For the remaining Hibernate-specific configuration setting names notice + that they are now prefixed with hibernate.. + + + + Additionally, the class element functions the same as discussed in + . + +
+ +
+ The annotated entity Java class + + The entity is exactly the same as that from the annotations tutorial. See + + +
+ +
+ Example code + + The previous tutorials used the Hibernate APIs. This tutorial uses the JPA APIs. + + + + Obtaining the <interfacename>javax.persistence.EntityManagerFactory</interfacename> + protected void setUp() throws Exception { + entityManagerFactory = Persistence.createEntityManagerFactory( "org.hibernate.tutorial.jpa" ); +} + + + + Notice again the use of org.hibernate.tutorial.jpa as the + persistence unit name, which matches from + + + + Saving (persisting) entities + EntityManager entityManager = entityManagerFactory.createEntityManager(); +entityManager.getTransaction().begin(); +entityManager.persist( new Event( "Our very first event!", new Date() ) ); +entityManager.persist( new Event( "A follow up event", new Date() ) ); +entityManager.getTransaction().commit(); +entityManager.close(); + + + + The code is pretty similar to . Here + we use an javax.persistence.EntityManager as opposed to a + org.hibernate.Session. JPA calls this operation + persist instead of save. + + + + Obtaining a list of entities + result = entityManager.createQuery( "from Event", Event.class ).getResultList(); +for ( Event event : result ) { + System.out.println( "Event (" + event.getDate() + ") : " + event.getTitle() ); +} +entityManager.getTransaction().commit(); +entityManager.close();]]> + + + + Again, the code is pretty similar to . + +
+ + \ No newline at end of file diff --git a/documentation/quickstart/src/main/docbook/en-US/content/tutorial_native.xml b/documentation/quickstart/src/main/docbook/en-US/content/tutorial_native.xml index 037160c6d0..58f8e0f3f7 100644 --- a/documentation/quickstart/src/main/docbook/en-US/content/tutorial_native.xml +++ b/documentation/quickstart/src/main/docbook/en-US/content/tutorial_native.xml @@ -320,8 +320,8 @@ session.close();]]> - With help of the Developer Guide, add an association to the Event - entity to model a message thread. + With help of the Developer Guide, add an association to + the Event entity to model a message thread. diff --git a/documentation/quickstart/tutorials/entitymanager/src/test/java/org/hibernate/tutorial/em/EntityManagerIllustrationTest.java b/documentation/quickstart/tutorials/entitymanager/src/test/java/org/hibernate/tutorial/em/EntityManagerIllustrationTest.java index c55eb0f9d6..79d7280c86 100644 --- a/documentation/quickstart/tutorials/entitymanager/src/test/java/org/hibernate/tutorial/em/EntityManagerIllustrationTest.java +++ b/documentation/quickstart/tutorials/entitymanager/src/test/java/org/hibernate/tutorial/em/EntityManagerIllustrationTest.java @@ -42,7 +42,8 @@ public class EntityManagerIllustrationTest extends TestCase { @Override protected void setUp() throws Exception { // like discussed with regards to SessionFactory, an EntityManagerFactory is set up once for an application - entityManagerFactory = Persistence.createEntityManagerFactory( "hibernate-jpa-tutorial" ); + // IMPORTANT: notice how the name here matches the name we gave the persistence-unit in persistence.xml! + entityManagerFactory = Persistence.createEntityManagerFactory( "org.hibernate.tutorial.jpa" ); } @Override diff --git a/documentation/quickstart/tutorials/entitymanager/src/test/resources/META-INF/persistence.xml b/documentation/quickstart/tutorials/entitymanager/src/test/resources/META-INF/persistence.xml index fe0d665d84..95811097ba 100644 --- a/documentation/quickstart/tutorials/entitymanager/src/test/resources/META-INF/persistence.xml +++ b/documentation/quickstart/tutorials/entitymanager/src/test/resources/META-INF/persistence.xml @@ -26,7 +26,7 @@ xsi:schemaLocation="http://java.sun.com/xml/ns/persistence http://java.sun.com/xml/ns/persistence/persistence_2_0.xsd" version="2.0"> - + Persistence unit for the JPA tutorial of the Hibernate Getting Started Guide