Overview | Package | Class | Tree | Deprecated | Index | Help
| Java EE 5 SDK
PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD

## javax.persistence
Interface EntityManager

    public interface EntityManager

Interface used to interact with the persistence context.

An `EntityManager` instance is associated with a persistence context. A persistence context is a set of entity instances in which for any persistent entity identity there is a unique entity instance. Within the persistence context, the entity instances and their lifecycle are managed. This interface defines the methods that are used to interact with the persistence context. The `EntityManager` API is used to create and remove persistent entity instances, to find entities by their primary key, and to query over entities.

The set of entities that can be managed by a given `EntityManager` instance is defined by a persistence unit. A persistence unit defines the set of all classes that are related or grouped by the application, and which must be colocated in their mapping to a single database.

Since:
  Java Persistence 1.0

Method Summary
`void` | `clear()` Clear the persistence context, causing all managed entities to become detached.
`void` | `close()` Close an application-managed EntityManager.
`boolean` | `contains(Object entity)` Check if the instance belongs to the current persistence context.
`Query` | `createNamedQuery(String name)` Create an instance of Query for executing a named query (in the Java Persistence query language or in native SQL).
`Query` | `createNativeQuery(String sqlString)` Create an instance of Query for executing a native SQL statement, e.g., for update or delete.
`Query` | `createNativeQuery(String sqlString, Class resultClass)` Create an instance of Query for executing a native SQL query.
`Query` | `createNativeQuery(String sqlString, String resultSetMapping)` Create an instance of Query for executing a native SQL query.
`Query` | `createQuery(String qlString)` Create an instance of Query for executing a Java Persistence query language statement.
`
`<T> T`
` | `find(Class<T> entityClass, Object primaryKey)` Find by primary key.
`void` | `flush()` Synchronize the persistence context to the underlying database.
`Object` | `getDelegate()` Return the underlying provider object for the EntityManager, if available.
`FlushModeType` | `getFlushMode()` Get the flush mode that applies to all objects contained in the persistence context.
`
`<T> T`
` | `getReference(Class<T> entityClass, Object primaryKey)` Get an instance, whose state may be lazily fetched.
`EntityTransaction` | `getTransaction()` Returns the resource-level transaction object.
`boolean` | `isOpen()` Determine whether the EntityManager is open.
`void` | `joinTransaction()` Indicate to the EntityManager that a JTA transaction is active.
`void` | `lock(Object entity, LockModeType lockMode)` Set the lock mode for an entity object contained in the persistence context.
`
`<T> T`
` | `merge(T entity)` Merge the state of the given entity into the current persistence context.
`void` | `persist(Object entity)` Make an entity instance managed and persistent.
`void` | `refresh(Object entity)` Refresh the state of the instance from the database, overwriting changes made to the entity, if any.
`void` | `remove(Object entity)` Remove the entity instance.
`void` | `setFlushMode(FlushModeType flushMode)` Set the flush mode that applies to all objects contained in the persistence context.

Method Detail

### persist

    void persist(Object entity)

  Make an entity instance managed and persistent.

  Parameters:
    `entity` -
  Throws:
    `EntityExistsException` - if the entity already exists. (The EntityExistsException may be thrown when the persist operation is invoked, or the EntityExistsException or another PersistenceException may be thrown at flush or commit time.)
    `IllegalStateException` - if this EntityManager has been closed.
    `IllegalArgumentException` - if not an entity
    `TransactionRequiredException` - if invoked on a container-managed entity manager of type PersistenceContextType.TRANSACTION and there is no transaction.

### merge

    <T> T merge(T entity)

  Merge the state of the given entity into the current persistence context.

  Parameters:
    `entity` -
  Returns:
    the instance that the state was merged to
  Throws:
    `IllegalStateException` - if this EntityManager has been closed.
    `IllegalArgumentException` - if instance is not an entity or is a removed entity
    `TransactionRequiredException` - if invoked on a container-managed entity manager of type PersistenceContextType.TRANSACTION and there is no transaction.

### remove

    void remove(Object entity)

  Remove the entity instance.

  Parameters:
    `entity` -
  Throws:
    `IllegalStateException` - if this EntityManager has been closed.
    `IllegalArgumentException` - if not an entity or if a detached entity
    `TransactionRequiredException` - if invoked on a container-managed entity manager of type PersistenceContextType.TRANSACTION and there is no transaction.

### find

    <T> T find(Class<T> entityClass,
               Object primaryKey)

  Find by primary key.

  Parameters:
    `entityClass` -
    `primaryKey` -
  Returns:
    the found entity instance or null if the entity does not exist
  Throws:
    `IllegalStateException` - if this EntityManager has been closed.
    `IllegalArgumentException` - if the first argument does not denote an entity type or the second argument is not a valid type for that entity's primary key

### getReference

    <T> T getReference(Class<T> entityClass,
                       Object primaryKey)

  Get an instance, whose state may be lazily fetched. If the requested instance does not exist in the database, throws `EntityNotFoundException` when the instance state is first accessed. (The persistence provider runtime is permitted to throw `EntityNotFoundException` when `getReference(java.lang.Class, java.lang.Object)` is called.) The application should not expect that the instance state will be available upon detachment, unless it was accessed by the application while the entity manager was open.

  Parameters:
    `entityClass` -
    `primaryKey` -
  Returns:
    the found entity instance
  Throws:
    `IllegalStateException` - if this EntityManager has been closed.
    `IllegalArgumentException` - if the first argument does not denote an entity type or the second argument is not a valid type for that entity's primary key
    `EntityNotFoundException` - if the entity state cannot be accessed

### flush

    void flush()

  Synchronize the persistence context to the underlying database.

  Throws:
    `IllegalStateException` - if this EntityManager has been closed.
    `TransactionRequiredException` - if there is no transaction
    `PersistenceException` - if the flush fails

### setFlushMode

    void setFlushMode(FlushModeType flushMode)

  Set the flush mode that applies to all objects contained in the persistence context.

  Parameters:
    `flushMode` -
  Throws:
    `IllegalStateException` - if this EntityManager has been closed.

### getFlushMode

    FlushModeType getFlushMode()

  Get the flush mode that applies to all objects contained in the persistence context.

  Returns:
    flush mode
  Throws:
    `IllegalStateException` - if this EntityManager has been closed.

### lock

    void lock(Object entity,
              LockModeType lockMode)

  Set the lock mode for an entity object contained in the persistence context.

  Parameters:
    `entity` -
    `lockMode` -
  Throws:
    `IllegalStateException` - if this EntityManager has been closed.
    `PersistenceException` - if an unsupported lock call is made
    `IllegalArgumentException` - if the instance is not an entity or is a detached entity
    `TransactionRequiredException` - if there is no transaction

### refresh

    void refresh(Object entity)

  Refresh the state of the instance from the database, overwriting changes made to the entity, if any.

  Parameters:
    `entity` -
  Throws:
    `IllegalStateException` - if this EntityManager has been closed.
    `IllegalArgumentException` - if not an entity or entity is not managed
    `TransactionRequiredException` - if invoked on a container-managed entity manager of type PersistenceContextType.TRANSACTION and there is no transaction.
    `EntityNotFoundException` - if the entity no longer exists in the database.

### clear

    void clear()

  Clear the persistence context, causing all managed entities to become detached. Changes made to entities that have not been flushed to the database will not be persisted.

  Throws:
    `IllegalStateException` - if this EntityManager has been closed.

### contains

    boolean contains(Object entity)

  Check if the instance belongs to the current persistence context.

  Parameters:
    `entity` -
  Returns:
    `true` if the instance belongs to the current persistence context.
  Throws:
    `IllegalStateException` - if this EntityManager has been closed.
    `IllegalArgumentException` - if not an entity

### createQuery

    Query createQuery(String qlString)

  Create an instance of Query for executing a Java Persistence query language statement.

  Parameters:
    `qlString` - a Java Persistence query language query string
  Returns:
    the new query instance
  Throws:
    `IllegalStateException` - if this EntityManager has been closed.
    `IllegalArgumentException` - if query string is not valid

### createNamedQuery

    Query createNamedQuery(String name)

  Create an instance of Query for executing a named query (in the Java Persistence query language or in native SQL).

  Parameters:
    `name` - the name of a query defined in metadata
  Returns:
    the new query instance
  Throws:
    `IllegalStateException` - if this EntityManager has been closed.
    `IllegalArgumentException` - if a query has not been defined with the given name

### createNativeQuery

    Query createNativeQuery(String sqlString)

  Create an instance of Query for executing a native SQL statement, e.g., for update or delete.

  Parameters:
    `sqlString` - a native SQL query string
  Returns:
    the new query instance
  Throws:
    `IllegalStateException` - if this EntityManager has been closed.

### createNativeQuery

    Query createNativeQuery(String sqlString,
                            Class resultClass)

  Create an instance of Query for executing a native SQL query.

  Parameters:
    `sqlString` - a native SQL query string
    `resultClass` - the class of the resulting instance(s)
  Returns:
    the new query instance
  Throws:
    `IllegalStateException` - if this EntityManager has been closed.

### createNativeQuery

    Query createNativeQuery(String sqlString,
                            String resultSetMapping)

  Create an instance of Query for executing a native SQL query.

  Parameters:
    `sqlString` - a native SQL query string
    `resultSetMapping` - the name of the result set mapping
  Returns:
    the new query instance
  Throws:
    `IllegalStateException` - if this EntityManager has been closed.

### joinTransaction

    void joinTransaction()

  Indicate to the EntityManager that a JTA transaction is active. This method should be called on a JTA application managed EntityManager that was created outside the scope of the active transaction to associate it with the current JTA transaction.

  Throws:
    `IllegalStateException` - if this EntityManager has been closed.
    `TransactionRequiredException` - if there is no transaction.

### getDelegate

    Object getDelegate()

  Return the underlying provider object for the EntityManager, if available. The result of this method is implementation specific.

  Throws:
    `IllegalStateException` - if this EntityManager has been closed.

### close

    void close()

  Close an application-managed EntityManager. After the close method has been invoked, all methods on the EntityManager instance and any Query objects obtained from it will throw the IllegalStateException except for getTransaction and isOpen (which will return false). If this method is called when the EntityManager is associated with an active transaction, the persistence context remains managed until the transaction completes.

  Throws:
    `IllegalStateException` - if the EntityManager is container-managed or has been already closed..

### isOpen

    boolean isOpen()

  Determine whether the EntityManager is open.

  Returns:
    true until the EntityManager has been closed.

### getTransaction

    EntityTransaction getTransaction()

  Returns the resource-level transaction object. The EntityTransaction instance may be used serially to begin and commit multiple transactions.

  Returns:
    EntityTransaction instance
  Throws:
    `IllegalStateException` - if invoked on a JTA EntityManager.

Overview | Package | Class | Tree | Deprecated | Index | Help
| Java EE 5 SDK
PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD

Submit a bug or feature

Copyright 2006 Sun Microsystems, Inc. All rights reserved.