Main JPA Interfaces

Main JPA Interfaces

Working with the Java Persistence API (JPA) consists of using the following interfaces:

Overview

A connection to a database is represented by an EntityManager javax.persistence.EntityManager JPA interface Interface used to interact with the persistence context.
See JavaDoc Reference Page... instance, which also provides functionality for performing operations on a database. Many applications require multiple database connections during their lifetime. For instance, in a web application it is common to establish a separate database connection, using a separate EntityManager instance, for every HTTP request.

The main role of an EntityManagerFactory javax.persistence.EntityManagerFactory JPA interface Interface used to interact with the entity manager factory for the persistence unit.
See JavaDoc Reference Page... instance is to support instantiation of EntityManager javax.persistence.EntityManager JPA interface Interface used to interact with the persistence context.
See JavaDoc Reference Page... instances. An EntityManagerFactory is constructed for a specific database, and by managing resources efficiently (e.g. a pool of sockets), provides an efficient way to construct multiple EntityManager instances for that database. The instantiation of the EntityManagerFactory itself might be less efficient, but it is a one time operation. Once constructed, it can serve the entire application.

Operations that modify the content of a database require active transactions. Transactions are managed by an EntityTransaction javax.persistence.EntityTransaction JPA interface Interface used to control transactions on resource-local entity managers.
See JavaDoc Reference Page... instance obtained from the EntityManager .

An EntityManager instance also functions as a factory for Query javax.persistence.Query JPA interface Interface used to control query execution.
See JavaDoc Reference Page... instances, which are needed for executing queries on the database.

Every JPA implementation defines classes that implement these interfaces. When you use ObjectDB you work with instances of ObjectDB classes that implement these interfaces, and because standard JPA interfaces are used your application is portable.

EntityManagerFactory

An EntityManagerFactory javax.persistence.EntityManagerFactory JPA interface Interface used to interact with the entity manager factory for the persistence unit.
See JavaDoc Reference Page... instance is obtained by using a static factory method:

  EntityManagerFactoryjavax.persistence.EntityManagerFactory

JPA interface

Interface used to interact with the entity manager factory for the persistence unit.

See JavaDoc Reference Page...



 emf =


      Persistencejavax.persistence.Persistence

JPA class

Bootstrap class that is used to obtain an EntityManagerFactory in Java SE environments.

See JavaDoc Reference Page...



.createEntityManagerFactorycreateEntityManagerFactory(persistenceUnitName)

Persistence's static method

Create and return an EntityManagerFactory for the named persistence unit.

See JavaDoc Reference Page...



(
"myDbFile.odb"
)
;

Persistence javax.persistence.Persistence JPA class Bootstrap class that is used to obtain an EntityManagerFactory in Java SE environments.
See JavaDoc Reference Page... is a JPA bootstrap class that serves as a factory of EntityManagerFactory . The createEntityManagerFactory createEntityManagerFactory(persistenceUnitName) Persistence's static method Create and return an EntityManagerFactory for the named persistence unit.
See JavaDoc Reference Page... method takes as an argument a name of a persistence unit . As an extension, ObjectDB enables specifying a database url (or path) directly, bypassing the need for a persistence unit. Any string that ends with .odb or .objectdb is considered by ObjectDB to be a database url rather than as a persistence unit name.

To use ObjectDB embedded directly in your application (embedded mode), an absolute path or a relative path of a local database file has to be specified. To use client server mode, a url in the format objectdb://host:port/path has to be specified. In this case, an ObjectDB Database Server is expected to be running on a machine named host (could be domain name or IP address) and listening on the specified port (the default is 6136 when not specified). The path indicates the location of the database file on the server, relative to the server data root path.

Another form of the createEntityManagerFactory createEntityManagerFactory(persistenceUnitName, properties) Persistence's static method Create and return an EntityManagerFactory for the named persistence unit using the given properties.
See JavaDoc Reference Page... method takes a map of properties as a second parameter. This form is useful when a user name and a password are required (in client-server mode) and no persistence unit is defined:

Map<String, String> properties =
 new
 HashMap<String, String>(
)
;
   properties.put
(
"javax.persistence.jdbc.user"
, "admin"
)
;
  properties.put
(
"javax.persistence.jdbc.password"
, "admin"
)
;


EntityManagerFactoryjavax.persistence.EntityManagerFactory

JPA interface

Interface used to interact with the entity manager factory for the persistence unit.

See JavaDoc Reference Page...



 emf =
 Persistencejavax.persistence.Persistence

JPA class

Bootstrap class that is used to obtain an EntityManagerFactory in Java SE environments.

See JavaDoc Reference Page...



.createEntityManagerFactorycreateEntityManagerFactory(persistenceUnitName, properties)

Persistence's static method

Create and return an EntityManagerFactory for the named persistence unit using the given properties.

See JavaDoc Reference Page...



(


    "objectdb://localhost:6136/myDbFile.odb"
, properties)
;

The EntityManagerFactory javax.persistence.EntityManagerFactory JPA interface Interface used to interact with the entity manager factory for the persistence unit.
See JavaDoc Reference Page... instance, when constructed, opens the database file. If the database does not yet exist a new database file is created.

When the application is finished using the EntityManagerFactory it has to be closed:

 emf.closeclose()

EntityManagerFactory's method

Close the factory, releasing any resources that it holds.

See JavaDoc Reference Page...



(
)
;

Closing the EntityManagerFactory closes the database file.

EntityManager

An EntityManager javax.persistence.EntityManager JPA interface Interface used to interact with the persistence context.
See JavaDoc Reference Page... instance may represent either a remote connection to a remote database server (in client-server mode) or a local connection to a local database file (in embedded mode). The functionality in both cases is the same. Given an EntityManagerFactoryjavax.persistence.EntityManagerFactory JPA interface Interface used to interact with the entity manager factory for the persistence unit.
See JavaDoc Reference Page... emf , a short term connection to the database might have the following form:

  EntityManagerjavax.persistence.EntityManager

JPA interface

Interface used to interact with the persistence context.

See JavaDoc Reference Page...



 em =
 emf.createEntityManagercreateEntityManager()

EntityManagerFactory's method

Create a new application-managed EntityManager.

See JavaDoc Reference Page...



(
)
;


  try
 {


      // TODO: Use the EntityManager to access the database


  }


  finally
 {


      em.closeclose()

EntityManager's method

Close an application-managed entity manager.

See JavaDoc Reference Page...



(
)
;


  }

The EntityManager instance is obtained from the owning EntityManagerFactory instance. Calling the close close() EntityManager's method Close an application-managed entity manager.
See JavaDoc Reference Page... method is essential to release resources (such as a socket in client-server mode) back to the owning EntityManagerFactory .

EntityManagerFactory defines another method for instantiation of EntityManager that, like the factory, takes a map of properties as an argument. This form is useful when a user name and a password other than the EntityManagerFactory 's default user name and password have to specified:

  Map<String, String> properties =
 new
 HashMap<String, String>(
)
;


  properties.put
(
"javax.persistence.jdbc.user"
, "user1"
)
;


  properties.put
(
"javax.persistence.jdbc.password"
, "user1pwd"
)
;


  EntityManagerjavax.persistence.EntityManager

JPA interface

Interface used to interact with the persistence context.

See JavaDoc Reference Page...



 em =
 emf.createEntityManagercreateEntityManager(map)

EntityManagerFactory's method

Create a new application-managed EntityManager with the specified Map of properties.

See JavaDoc Reference Page...



(
properties)
;

EntityTransaction

Operations that affect the content of the database (store, update, delete) must be performed within an active transaction. The EntityTransaction javax.persistence.EntityTransaction JPA interface Interface used to control transactions on resource-local entity managers.
See JavaDoc Reference Page... interface represents and manages database transactions. Every EntityManager javax.persistence.EntityManager JPA interface Interface used to interact with the persistence context.
See JavaDoc Reference Page... holds a single attached EntityTransaction instance that is available via the getTransactiongetTransaction() EntityManager's method Return the resource-level EntityTransaction object.
See JavaDoc Reference Page... method:

    try
 {


        em.getTransactiongetTransaction()

EntityManager's method

Return the resource-level EntityTransaction object.

See JavaDoc Reference Page...



(
)
.beginbegin()

EntityTransaction's method

Start a resource transaction.

See JavaDoc Reference Page...



(
)
;


        // Operations that modify the database should come here.


        em.getTransactiongetTransaction()

EntityManager's method

Return the resource-level EntityTransaction object.

See JavaDoc Reference Page...



(
)
.commitcommit()

EntityTransaction's method

Commit the current resource transaction, writing any unflushed changes to the database.

See JavaDoc Reference Page...



(
)
;


    }


    finally
 {


        if
 (
em.getTransactiongetTransaction()

EntityManager's method

Return the resource-level EntityTransaction object.

See JavaDoc Reference Page...



(
)
.isActiveisActive()

EntityTransaction's method

Indicate whether a resource transaction is in progress.

See JavaDoc Reference Page...



(
)
)


            em.getTransactiongetTransaction()

EntityManager's method

Return the resource-level EntityTransaction object.

See JavaDoc Reference Page...



(
)
.rollbackrollback()

EntityTransaction's method

Roll back the current resource transaction.

See JavaDoc Reference Page...



(
)
;


    }

A transaction is started by a call to begin begin() EntityTransaction's method Start a resource transaction.
See JavaDoc Reference Page... and ended by a call to either commit commit() EntityTransaction's method Commit the current resource transaction, writing any unflushed changes to the database.
See JavaDoc Reference Page... or rollback rollback() EntityTransaction's method Roll back the current resource transaction.
See JavaDoc Reference Page... . All the operations on the database within these boundaries are associated with that transaction and are kept in memory until the transaction is ended. If the transaction is ended with a rollback , all the modifications to the database are discarded. However, by default, the in-memory instance of the managed entity is not affected by the rollback and is not returned to its pre-modified state.

Ending a transaction with a commit propagates all the modifications physically to the database. If for any reason a commit fails, the transaction is rolled back automatically (including rolling back modifications that have already been propagated to the database prior to the failure) and a RollbackException javax.persistence.RollbackException JPA exception Thrown by the persistence provider when EntityTransaction.commit() fails.
See JavaDoc Reference Page... is thrown.

< 3  Using JPA ^ 3  Using JPA Working with Entities