Hibernate.org Community Documentation

- Prev
- Next

## Chapter 4. Tutorial Using the Java Persistence API (JPA)

This tutorial is located within the download bundle under `entitymanager`.

Objectives

- Use annotations to provide mapping information.

- Use `JPA`.

## 4.1. `persistence.xml`

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`. This bootstrapping process 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.

Example 4.1. `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_2_0.xsd"
            version="2.0">
        <persistence-unit name="org.hibernate.tutorial.jpa">
            ...
        </persistence-unit>
    </persistence>

`persistence.xml` files should provide a unique name for each persistence unit. Applications use this name to reference the configuration when obtaining an `javax.persistence.EntityManagerFactory` reference.

The settings defined in the `properties` element are discussed in Section 2.1, “The Hibernate configuration file”. Here the `javax.persistence`-prefixed varieties are used when possible. Notice that the remaining Hibernate-specific configuration setting names are now prefixed with `hibernate.`.

Additionally, the `class` element functions the same as in Section 3.1, “The Hibernate configuration file”.

## 4.2. The annotated entity Java class

The entity is exactly the same as in Section 3.2, “The annotated entity Java class”

## 4.3. Example code

The previous tutorials used the Hibernate APIs. This tutorial uses the `JPA` APIs.

Example 4.2. Obtaining the `javax.persistence.EntityManagerFactory`

    protected void setUp() throws Exception {
        entityManagerFactory = Persistence.createEntityManagerFactory( "org.hibernate.tutorial.jpa" );
    }

Notice again that the persistence unit name is `org.hibernate.tutorial.jpa`, which matches Example 4.1, “`persistence.xml`”

Example 4.3. 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 similar to Example 2.5, “Saving entities”. An `javax.persistence.EntityManager` interface is used instead of a `org.hibernate.Session` interface. `JPA` calls this operation `persist` instead of `save`.

Example 4.4. Obtaining a list of entities

    entityManager = entityManagerFactory.createEntityManager();
    entityManager.getTransaction().begin();
    List<Event> 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 Example 2.6, “Obtaining a list of entities”.

## 4.4. Take it further!

Practice Exercises

- Develop an EJB Session bean to investigate implications of using a container-managed persistence context (`javax.persistence.EntityManager`). Try both stateless and stateful use-cases.

- PrevChapter 3. Tutorial Using Native Hibernate APIs a...
- Up
- Home
- NextChapter 5. Tutorial Using Envers