Session (Hibernate JavaDocs)
Date: 2012-04-05

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

## org.hibernate
Interface Session

All Superinterfaces:
  Serializable, SharedSessionContract

All Known Subinterfaces:
  EventSource

All Known Implementing Classes:
  SessionImpl

    public interface Session

extends SharedSessionContract

The main runtime interface between a Java application and Hibernate. This is the central API class abstracting the notion of a persistence service.
The lifecycle of a `Session` is bounded by the beginning and end of a logical transaction. (Long transactions might span several database transactions.)
The main function of the `Session` is to offer create, read and delete operations for instances of mapped entity classes. Instances may exist in one of three states:
transient: never persistent, not associated with any `Session`
persistent: associated with a unique `Session`
detached: previously persistent, not associated with any `Session`
Transient instances may be made persistent by calling `save()`, `persist()` or `saveOrUpdate()`. Persistent instances may be made transient by calling`delete()`. Any instance returned by a `get()` or `load()` method is persistent. Detached instances may be made persistent by calling `update()`, `saveOrUpdate()`, `lock()` or `replicate()`. The state of a transient or detached instance may also be made persistent as a new persistent instance by calling `merge()`.
`save()` and `persist()` result in an SQL `INSERT`, `delete()` in an SQL `DELETE` and `update()` or `merge()` in an SQL `UPDATE`. Changes to persistent instances are detected at flush time and also result in an SQL `UPDATE`. `saveOrUpdate()` and `replicate()` result in either an `INSERT` or an `UPDATE`.
It is not intended that implementors be threadsafe. Instead each thread/transaction should obtain its own instance from a `SessionFactory`.
A `Session` instance is serializable if its persistent classes are serializable.
A typical transaction should use the following idiom:

     Session sess = factory.openSession();
     Transaction tx;
     try {
         tx = sess.beginTransaction();
         //do some work
         ...
         tx.commit();
     }
     catch (Exception e) {
         if (tx!=null) tx.rollback();
         throw e;
     }
     finally {
         sess.close();
     }

If the `Session` throws an exception, the transaction must be rolled back and the session discarded. The internal state of the `Session` might not be consistent with the database after the exception occurs.

See Also:
  `SessionFactory`

Nested Class Summary
`static interface` | `Session.LockRequest` Contains locking details (LockMode, Timeout and Scope).

Method Summary
`Session.LockRequest` | `buildLockRequest(LockOptions lockOptions)` Build a LockRequest that specifies the LockMode, pessimistic lock timeout and lock scope.
`IdentifierLoadAccess` | `byId(Class entityClass)` Create an `IdentifierLoadAccess` instance to retrieve the specified entity by primary key.
`IdentifierLoadAccess` | `byId(String entityName)` Create an `IdentifierLoadAccess` instance to retrieve the specified entity type by primary key.
`NaturalIdLoadAccess` | `byNaturalId(Class entityClass)` Create an `NaturalIdLoadAccess` instance to retrieve the specified entity by its natural id.
`NaturalIdLoadAccess` | `byNaturalId(String entityName)` Create an `NaturalIdLoadAccess` instance to retrieve the specified entity by its natural id.
`SimpleNaturalIdLoadAccess` | `bySimpleNaturalId(Class entityClass)` Create an `SimpleNaturalIdLoadAccess` instance to retrieve the specified entity by its simple (single attribute) natural id.
`SimpleNaturalIdLoadAccess` | `bySimpleNaturalId(String entityName)` Create an `SimpleNaturalIdLoadAccess` instance to retrieve the specified entity by its natural id.
`void` | `cancelQuery()` Cancel the execution of the current query.
`void` | `clear()` Completely clear the session.
`Connection` | `close()` End the session by releasing the JDBC connection and cleaning up.
`boolean` | `contains(Object object)` Check if this instance is associated with this `Session`.
`Query` | `createFilter(Object collection, String queryString)` Create a `Query` instance for the given collection and filter string.
`void` | `delete(Object object)` Remove a persistent instance from the datastore.
`void` | `delete(String entityName, Object object)` Remove a persistent instance from the datastore.
`void` | `disableFetchProfile(String name)` Disable a particular fetch profile on this session.
`void` | `disableFilter(String filterName)` Disable the named filter for the current session.
`Connection` | `disconnect()` Disconnect the session from its underlying JDBC connection.
`
`<T> T`
` | `doReturningWork(ReturningWork<T> work)` Controller for allowing users to perform JDBC related work using the Connection managed by this Session.
`void` | `doWork(Work work)` Controller for allowing users to perform JDBC related work using the Connection managed by this Session.
`void` | `enableFetchProfile(String name)` Enable a particular fetch profile on this session.
`Filter` | `enableFilter(String filterName)` Enable the named filter for this current session.
`void` | `evict(Object object)` Remove this instance from the session cache.
`void` | `flush()` Force this session to flush.
`Object` | `get(Class clazz, Serializable id)` Return the persistent instance of the given entity class with the given identifier, or null if there is no such persistent instance.
`Object` | `get(Class clazz, Serializable id, LockMode lockMode)` Deprecated. LockMode parameter should be replaced with LockOptions
`Object` | `get(Class clazz, Serializable id, LockOptions lockOptions)` Return the persistent instance of the given entity class with the given identifier, or null if there is no such persistent instance.
`Object` | `get(String entityName, Serializable id)` Return the persistent instance of the given named entity with the given identifier, or null if there is no such persistent instance.
`Object` | `get(String entityName, Serializable id, LockMode lockMode)` Deprecated. LockMode parameter should be replaced with LockOptions
`Object` | `get(String entityName, Serializable id, LockOptions lockOptions)` Return the persistent instance of the given entity class with the given identifier, or null if there is no such persistent instance.
`CacheMode` | `getCacheMode()` Get the current cache mode.
`LockMode` | `getCurrentLockMode(Object object)` Determine the current lock mode of the given object.
`Filter` | `getEnabledFilter(String filterName)` Retrieve a currently enabled filter by name.
`String` | `getEntityName(Object object)` Return the entity name for a persistent entity
`FlushMode` | `getFlushMode()` Get the current flush mode for this session.
`Serializable` | `getIdentifier(Object object)` Return the identifier value of the given entity as associated with this session.
`LobHelper` | `getLobHelper()` Retrieve this session's helper/delegate for creating LOB instances.
`SessionFactory` | `getSessionFactory()` Get the session factory which created this session.
`SessionStatistics` | `getStatistics()` Get the statistics for this session.
`TypeHelper` | `getTypeHelper()` Convenience access to the `TypeHelper` associated with this session's `SessionFactory`.
`boolean` | `isConnected()` Check if the session is currently connected.
`boolean` | `isDefaultReadOnly()` Will entities and proxies that are loaded into this session be made read-only by default? To determine the read-only/modifiable setting for a particular entity or proxy:
`boolean` | `isDirty()` Does this session contain any changes which must be synchronized with the database? In other words, would any DML operations be executed if we flushed this session?
`boolean` | `isFetchProfileEnabled(String name)` Is a particular fetch profile enabled on this session?
`boolean` | `isOpen()` Check if the session is still open.
`boolean` | `isReadOnly(Object entityOrProxy)` Is the specified entity or proxy read-only? To get the default read-only/modifiable setting used for entities and proxies that are loaded into the session:
`Object` | `load(Class theClass, Serializable id)` Return the persistent instance of the given entity class with the given identifier, assuming that the instance exists.
`Object` | `load(Class theClass, Serializable id, LockMode lockMode)` Deprecated. LockMode parameter should be replaced with LockOptions
`Object` | `load(Class theClass, Serializable id, LockOptions lockOptions)` Return the persistent instance of the given entity class with the given identifier, obtaining the specified lock mode, assuming the instance exists.
`void` | `load(Object object, Serializable id)` Read the persistent state associated with the given identifier into the given transient instance.
`Object` | `load(String entityName, Serializable id)` Return the persistent instance of the given entity class with the given identifier, assuming that the instance exists.
`Object` | `load(String entityName, Serializable id, LockMode lockMode)` Deprecated. LockMode parameter should be replaced with LockOptions
`Object` | `load(String entityName, Serializable id, LockOptions lockOptions)` Return the persistent instance of the given entity class with the given identifier, obtaining the specified lock mode, assuming the instance exists.
`void` | `lock(Object object, LockMode lockMode)` Deprecated. instead call buildLockRequest(LockMode).lock(object)
`void` | `lock(String entityName, Object object, LockMode lockMode)` Deprecated. instead call buildLockRequest(LockMode).lock(entityName, object)
`Object` | `merge(Object object)` Copy the state of the given object onto the persistent object with the same identifier.
`Object` | `merge(String entityName, Object object)` Copy the state of the given object onto the persistent object with the same identifier.
`void` | `persist(Object object)` Make a transient instance persistent.
`void` | `persist(String entityName, Object object)` Make a transient instance persistent.
`void` | `reconnect(Connection connection)` Reconnect to the given JDBC connection.
`void` | `refresh(Object object)` Re-read the state of the given instance from the underlying database.
`void` | `refresh(Object object, LockMode lockMode)` Deprecated. LockMode parameter should be replaced with LockOptions
`void` | `refresh(Object object, LockOptions lockOptions)` Re-read the state of the given instance from the underlying database, with the given `LockMode`.
`void` | `refresh(String entityName, Object object)` Re-read the state of the given instance from the underlying database.
`void` | `refresh(String entityName, Object object, LockOptions lockOptions)` Re-read the state of the given instance from the underlying database, with the given `LockMode`.
`void` | `replicate(Object object, ReplicationMode replicationMode)` Persist the state of the given detached instance, reusing the current identifier value.
`void` | `replicate(String entityName, Object object, ReplicationMode replicationMode)` Persist the state of the given detached instance, reusing the current identifier value.
`Serializable` | `save(Object object)` Persist the given transient instance, first assigning a generated identifier.
`Serializable` | `save(String entityName, Object object)` Persist the given transient instance, first assigning a generated identifier.
`void` | `saveOrUpdate(Object object)` Either `save(Object)` or `update(Object)` the given instance, depending upon resolution of the unsaved-value checks (see the manual for discussion of unsaved-value checking).
`void` | `saveOrUpdate(String entityName, Object object)` Either `save(String, Object)` or `update(String, Object)` the given instance, depending upon resolution of the unsaved-value checks (see the manual for discussion of unsaved-value checking).
`SharedSessionBuilder` | `sessionWithOptions()` Obtain a `Session` builder with the ability to grab certain information from this session.
`void` | `setCacheMode(CacheMode cacheMode)` Set the cache mode.
`void` | `setDefaultReadOnly(boolean readOnly)` Change the default for entities and proxies loaded into this session from modifiable to read-only mode, or from modifiable to read-only mode.
`void` | `setFlushMode(FlushMode flushMode)` Set the flush mode for this session.
`void` | `setReadOnly(Object entityOrProxy, boolean readOnly)` Set an unmodified persistent object to read-only mode, or a read-only object to modifiable mode.
`void` | `update(Object object)` Update the persistent instance with the identifier of the given detached instance.
`void` | `update(String entityName, Object object)` Update the persistent instance with the identifier of the given detached instance.

Methods inherited from interface org.hibernate.SharedSessionContract
`beginTransaction, createCriteria, createCriteria, createCriteria, createCriteria, createQuery, createSQLQuery, getNamedQuery, getTenantIdentifier, getTransaction`

Method Detail

### sessionWithOptions

    SharedSessionBuilder sessionWithOptions()

  Obtain a `Session` builder with the ability to grab certain information from this session.

  Returns:
    The session builder

### flush

    void flush()
               throws HibernateException

  Force this session to flush. Must be called at the end of a unit of work, before committing the transaction and closing the session (depending on `setFlushMode(FlushMode)`, `Transaction.commit()` calls this method).

  Flushing is the process of synchronizing the underlying persistent store with persistable state held in memory.

  Throws:
    `HibernateException` - Indicates problems flushing the session or talking to the database.

### setFlushMode

    void setFlushMode(FlushMode flushMode)

  Set the flush mode for this session.

  The flush mode determines the points at which the session is flushed. Flushing is the process of synchronizing the underlying persistent store with persistable state held in memory.

  For a logically "read only" session, it is reasonable to set the session's flush mode to `FlushMode.MANUAL` at the start of the session (in order to achieve some extra performance).

  Parameters:
    `flushMode` - the new flush mode
  See Also:
    `FlushMode`

### getFlushMode

    FlushMode getFlushMode()

  Get the current flush mode for this session.

  Returns:
    The flush mode

### setCacheMode

    void setCacheMode(CacheMode cacheMode)

  Set the cache mode.

  Cache mode determines the manner in which this session can interact with the second level cache.

  Parameters:
    `cacheMode` - The new cache mode.

### getCacheMode

    CacheMode getCacheMode()

  Get the current cache mode.

  Returns:
    The current cache mode.

### getSessionFactory

    SessionFactory getSessionFactory()

  Get the session factory which created this session.

  Returns:
    The session factory.
  See Also:
    `SessionFactory`

### close

    Connection close()
                     throws HibernateException

  End the session by releasing the JDBC connection and cleaning up. It is not strictly necessary to close the session but you must at least `disconnect()` it.

  Returns:
    the connection provided by the application or null.
  Throws:
    `HibernateException` - Indicates problems cleaning up.

### cancelQuery

    void cancelQuery()
                     throws HibernateException

  Cancel the execution of the current query.

  This is the sole method on session which may be safely called from another thread.

  Throws:
    `HibernateException` - There was a problem canceling the query

### isOpen

    boolean isOpen()

  Check if the session is still open.

  Returns:
    boolean

### isConnected

    boolean isConnected()

  Check if the session is currently connected.

  Returns:
    boolean

### isDirty

    boolean isDirty()
                    throws HibernateException

  Does this session contain any changes which must be synchronized with the database? In other words, would any DML operations be executed if we flushed this session?

  Returns:
    True if the session contains pending changes; false otherwise.
  Throws:
    `HibernateException` - could not perform dirtying checking

### isDefaultReadOnly

    boolean isDefaultReadOnly()

  Will entities and proxies that are loaded into this session be made read-only by default? To determine the read-only/modifiable setting for a particular entity or proxy:

  Returns:
    true, loaded entities/proxies will be made read-only by default; false, loaded entities/proxies will be made modifiable by default.
  See Also:
    `isReadOnly(Object)`

### setDefaultReadOnly

    void setDefaultReadOnly(boolean readOnly)

  Change the default for entities and proxies loaded into this session from modifiable to read-only mode, or from modifiable to read-only mode. Read-only entities are not dirty-checked and snapshots of persistent state are not maintained. Read-only entities can be modified, but changes are not persisted. When a proxy is initialized, the loaded entity will have the same read-only/modifiable setting as the uninitialized proxy has, regardless of the session's current setting. To change the read-only/modifiable setting for a particular entity or proxy that is already in this session:

  Parameters:
    `readOnly` - true, the default for loaded entities/proxies is read-only; false, the default for loaded entities/proxies is modifiable
  See Also:
    `To override this session's read-only/modifiable setting for entities and proxies loaded by a Query:`, `Query.setReadOnly(boolean)`

### getIdentifier

    Serializable getIdentifier(Object object)

  Return the identifier value of the given entity as associated with this session. An exception is thrown if the given entity instance is transient or detached in relation to this session.

  Parameters:
    `object` - a persistent instance
  Returns:
    the identifier
  Throws:
    `TransientObjectException` - if the instance is transient or associated with a different session

### contains

    boolean contains(Object object)

  Check if this instance is associated with this `Session`.

  Parameters:
    `object` - an instance of a persistent class
  Returns:
    true if the given instance is associated with this `Session`

### evict

    void evict(Object object)

  Remove this instance from the session cache. Changes to the instance will not be synchronized with the database. This operation cascades to associated instances if the association is mapped with `cascade="evict"`.

  Parameters:
    `object` - a persistent instance

### load

    @Deprecated
    Object load(Class theClass,
                           Serializable id,
                           LockMode lockMode)

  Deprecated. LockMode parameter should be replaced with LockOptions

  Return the persistent instance of the given entity class with the given identifier, obtaining the specified lock mode, assuming the instance exists.

  Parameters:
    `theClass` - a persistent class
    `id` - a valid identifier of an existing persistent instance of the class
    `lockMode` - the lock level
  Returns:
    the persistent instance or proxy

### load

    Object load(Class theClass,
                Serializable id,
                LockOptions lockOptions)

  Return the persistent instance of the given entity class with the given identifier, obtaining the specified lock mode, assuming the instance exists.

  Parameters:
    `theClass` - a persistent class
    `id` - a valid identifier of an existing persistent instance of the class
    `lockOptions` - contains the lock level
  Returns:
    the persistent instance or proxy

### load

    @Deprecated
    Object load(String entityName,
                           Serializable id,
                           LockMode lockMode)

  Deprecated. LockMode parameter should be replaced with LockOptions

  Return the persistent instance of the given entity class with the given identifier, obtaining the specified lock mode, assuming the instance exists.

  Parameters:
    `entityName` - a persistent class
    `id` - a valid identifier of an existing persistent instance of the class
    `lockMode` - the lock level
  Returns:
    the persistent instance or proxy

### load

    Object load(String entityName,
                Serializable id,
                LockOptions lockOptions)

  Return the persistent instance of the given entity class with the given identifier, obtaining the specified lock mode, assuming the instance exists.

  Parameters:
    `entityName` - a persistent class
    `id` - a valid identifier of an existing persistent instance of the class
    `lockOptions` - contains the lock level
  Returns:
    the persistent instance or proxy

### load

    Object load(Class theClass,
                Serializable id)

  Return the persistent instance of the given entity class with the given identifier, assuming that the instance exists. This method might return a proxied instance that is initialized on-demand, when a non-identifier method is accessed.
  You should not use this method to determine if an instance exists (use `get()` instead). Use this only to retrieve an instance that you assume exists, where non-existence would be an actual error.

  Parameters:
    `theClass` - a persistent class
    `id` - a valid identifier of an existing persistent instance of the class
  Returns:
    the persistent instance or proxy

### load

    Object load(String entityName,
                Serializable id)

  Return the persistent instance of the given entity class with the given identifier, assuming that the instance exists. This method might return a proxied instance that is initialized on-demand, when a non-identifier method is accessed.
  You should not use this method to determine if an instance exists (use `get()` instead). Use this only to retrieve an instance that you assume exists, where non-existence would be an actual error.

  Parameters:
    `entityName` - a persistent class
    `id` - a valid identifier of an existing persistent instance of the class
  Returns:
    the persistent instance or proxy

### load

    void load(Object object,
              Serializable id)

  Read the persistent state associated with the given identifier into the given transient instance.

  Parameters:
    `object` - an "empty" instance of the persistent class
    `id` - a valid identifier of an existing persistent instance of the class

### replicate

    void replicate(Object object,
                   ReplicationMode replicationMode)

  Persist the state of the given detached instance, reusing the current identifier value. This operation cascades to associated instances if the association is mapped with `cascade="replicate"`

  Parameters:
    `object` - a detached instance of a persistent class
    `replicationMode` - The replication mode to use

### replicate

    void replicate(String entityName,
                   Object object,
                   ReplicationMode replicationMode)

  Persist the state of the given detached instance, reusing the current identifier value. This operation cascades to associated instances if the association is mapped with `cascade="replicate"`

  Parameters:
    `entityName` - The entity name
    `object` - a detached instance of a persistent class
    `replicationMode` - The replication mode to use

### save

    Serializable save(Object object)

  Persist the given transient instance, first assigning a generated identifier. (Or using the current value of the identifier property if the `assigned` generator is used.) This operation cascades to associated instances if the association is mapped with `cascade="save-update"`

  Parameters:
    `object` - a transient instance of a persistent class
  Returns:
    the generated identifier

### save

    Serializable save(String entityName,
                      Object object)

  Persist the given transient instance, first assigning a generated identifier. (Or using the current value of the identifier property if the `assigned` generator is used.) This operation cascades to associated instances if the association is mapped with `cascade="save-update"`

  Parameters:
    `entityName` - The entity name
    `object` - a transient instance of a persistent class
  Returns:
    the generated identifier

### saveOrUpdate

    void saveOrUpdate(Object object)

  Either `save(Object)` or `update(Object)` the given instance, depending upon resolution of the unsaved-value checks (see the manual for discussion of unsaved-value checking).

  This operation cascades to associated instances if the association is mapped with `cascade="save-update"`

  Parameters:
    `object` - a transient or detached instance containing new or updated state
  See Also:
    `save(java.lang.Object)`, `update(Object object)`

### saveOrUpdate

    void saveOrUpdate(String entityName,
                      Object object)

  Either `save(String, Object)` or `update(String, Object)` the given instance, depending upon resolution of the unsaved-value checks (see the manual for discussion of unsaved-value checking).

  This operation cascades to associated instances if the association is mapped with `cascade="save-update"`

  Parameters:
    `entityName` - The entity name
    `object` - a transient or detached instance containing new or updated state
  See Also:
    `save(String,Object)`, `update(String,Object)`

### update

    void update(Object object)

  Update the persistent instance with the identifier of the given detached instance. If there is a persistent instance with the same identifier, an exception is thrown. This operation cascades to associated instances if the association is mapped with `cascade="save-update"`

  Parameters:
    `object` - a detached instance containing updated state

### update

    void update(String entityName,
                Object object)

  Update the persistent instance with the identifier of the given detached instance. If there is a persistent instance with the same identifier, an exception is thrown. This operation cascades to associated instances if the association is mapped with `cascade="save-update"`

  Parameters:
    `entityName` - The entity name
    `object` - a detached instance containing updated state

### merge

    Object merge(Object object)

  Copy the state of the given object onto the persistent object with the same identifier. If there is no persistent instance currently associated with the session, it will be loaded. Return the persistent instance. If the given instance is unsaved, save a copy of and return it as a newly persistent instance. The given instance does not become associated with the session. This operation cascades to associated instances if the association is mapped with `cascade="merge"`

  The semantics of this method are defined by JSR-220.

  Parameters:
    `object` - a detached instance with state to be copied
  Returns:
    an updated persistent instance

### merge

    Object merge(String entityName,
                 Object object)

  Copy the state of the given object onto the persistent object with the same identifier. If there is no persistent instance currently associated with the session, it will be loaded. Return the persistent instance. If the given instance is unsaved, save a copy of and return it as a newly persistent instance. The given instance does not become associated with the session. This operation cascades to associated instances if the association is mapped with `cascade="merge"`

  The semantics of this method are defined by JSR-220.

  Parameters:
    `entityName` - The entity name
    `object` - a detached instance with state to be copied
  Returns:
    an updated persistent instance

### persist

    void persist(Object object)

  Make a transient instance persistent. This operation cascades to associated instances if the association is mapped with `cascade="persist"`

  The semantics of this method are defined by JSR-220.

  Parameters:
    `object` - a transient instance to be made persistent

### persist

    void persist(String entityName,
                 Object object)

  Make a transient instance persistent. This operation cascades to associated instances if the association is mapped with `cascade="persist"`

  The semantics of this method are defined by JSR-220.

  Parameters:
    `entityName` - The entity name
    `object` - a transient instance to be made persistent

### delete

    void delete(Object object)

  Remove a persistent instance from the datastore. The argument may be an instance associated with the receiving `Session` or a transient instance with an identifier associated with existing persistent state. This operation cascades to associated instances if the association is mapped with `cascade="delete"`

  Parameters:
    `object` - the instance to be removed

### delete

    void delete(String entityName,
                Object object)

  Remove a persistent instance from the datastore. The object argument may be an instance associated with the receiving `Session` or a transient instance with an identifier associated with existing persistent state. This operation cascades to associated instances if the association is mapped with `cascade="delete"`

  Parameters:
    `entityName` - The entity name for the instance to be removed.
    `object` - the instance to be removed

### lock

    @Deprecated
    void lock(Object object,
                         LockMode lockMode)

  Deprecated. instead call buildLockRequest(LockMode).lock(object)

  Obtain the specified lock level upon the given object. This may be used to perform a version check (`LockMode.READ`), to upgrade to a pessimistic lock (`LockMode.PESSIMISTIC_WRITE`), or to simply reassociate a transient instance with a session (`LockMode.NONE`). This operation cascades to associated instances if the association is mapped with `cascade="lock"`.

  Parameters:
    `object` - a persistent or transient instance
    `lockMode` - the lock level

### lock

    @Deprecated
    void lock(String entityName,
                         Object object,
                         LockMode lockMode)

  Deprecated. instead call buildLockRequest(LockMode).lock(entityName, object)

  Obtain the specified lock level upon the given object. This may be used to perform a version check (`LockMode.OPTIMISTIC`), to upgrade to a pessimistic lock (`LockMode.PESSIMISTIC_WRITE`), or to simply reassociate a transient instance with a session (`LockMode.NONE`). This operation cascades to associated instances if the association is mapped with `cascade="lock"`.

  Parameters:
    `object` - a persistent or transient instance
    `lockMode` - the lock level

### buildLockRequest

    Session.LockRequest buildLockRequest(LockOptions lockOptions)

  Build a LockRequest that specifies the LockMode, pessimistic lock timeout and lock scope. timeout and scope is ignored for optimistic locking. After building the LockRequest, call LockRequest.lock to perform the requested locking.

  Example usage: `session.buildLockRequest().setLockMode(LockMode.PESSIMISTIC_WRITE).setTimeOut(60000).lock(entity);`

  Parameters:
    `lockOptions` - contains the lock level
  Returns:
    a lockRequest that can be used to lock the passed object.

### refresh

    void refresh(Object object)

  Re-read the state of the given instance from the underlying database. It is inadvisable to use this to implement long-running sessions that span many business tasks. This method is, however, useful in certain special circumstances. For example
  - where a database trigger alters the object state upon insert or update
  - after executing direct SQL (eg. a mass update) in the same session
  - after inserting a `Blob` or `Clob`

  Parameters:
    `object` - a persistent or detached instance

### refresh

    void refresh(String entityName,
                 Object object)

  Re-read the state of the given instance from the underlying database. It is inadvisable to use this to implement long-running sessions that span many business tasks. This method is, however, useful in certain special circumstances. For example
  - where a database trigger alters the object state upon insert or update
  - after executing direct SQL (eg. a mass update) in the same session
  - after inserting a `Blob` or `Clob`

  Parameters:
    `entityName` - a persistent class
    `object` - a persistent or detached instance

### refresh

    @Deprecated
    void refresh(Object object,
                            LockMode lockMode)

  Deprecated. LockMode parameter should be replaced with LockOptions

  Re-read the state of the given instance from the underlying database, with the given `LockMode`. It is inadvisable to use this to implement long-running sessions that span many business tasks. This method is, however, useful in certain special circumstances.

  Parameters:
    `object` - a persistent or detached instance
    `lockMode` - the lock mode to use

### refresh

    void refresh(Object object,
                 LockOptions lockOptions)

  Re-read the state of the given instance from the underlying database, with the given `LockMode`. It is inadvisable to use this to implement long-running sessions that span many business tasks. This method is, however, useful in certain special circumstances.

  Parameters:
    `object` - a persistent or detached instance
    `lockOptions` - contains the lock mode to use

### refresh

    void refresh(String entityName,
                 Object object,
                 LockOptions lockOptions)

  Re-read the state of the given instance from the underlying database, with the given `LockMode`. It is inadvisable to use this to implement long-running sessions that span many business tasks. This method is, however, useful in certain special circumstances.

  Parameters:
    `entityName` - a persistent class
    `object` - a persistent or detached instance
    `lockOptions` - contains the lock mode to use

### getCurrentLockMode

    LockMode getCurrentLockMode(Object object)

  Determine the current lock mode of the given object.

  Parameters:
    `object` - a persistent instance
  Returns:
    the current lock mode

### createFilter

    Query createFilter(Object collection,
                       String queryString)

  Create a `Query` instance for the given collection and filter string. Contains an implicit `FROM` element named `this` which refers to the defined table for the collection elements, as well as an implicit `WHERE` restriction for this particular collection instance's key value.

  Parameters:
    `collection` - a persistent collection
    `queryString` - a Hibernate query fragment.
  Returns:
    The query instance for manipulation and execution

### clear

    void clear()

  Completely clear the session. Evict all loaded instances and cancel all pending saves, updates and deletions. Do not close open iterators or instances of `ScrollableResults`.

### get

    Object get(Class clazz,
               Serializable id)

  Return the persistent instance of the given entity class with the given identifier, or null if there is no such persistent instance. (If the instance is already associated with the session, return that instance. This method never returns an uninitialized instance.)

  Parameters:
    `clazz` - a persistent class
    `id` - an identifier
  Returns:
    a persistent instance or null

### get

    @Deprecated
    Object get(Class clazz,
                          Serializable id,
                          LockMode lockMode)

  Deprecated. LockMode parameter should be replaced with LockOptions

  Return the persistent instance of the given entity class with the given identifier, or null if there is no such persistent instance. (If the instance is already associated with the session, return that instance. This method never returns an uninitialized instance.) Obtain the specified lock mode if the instance exists.

  Parameters:
    `clazz` - a persistent class
    `id` - an identifier
    `lockMode` - the lock mode
  Returns:
    a persistent instance or null

### get

    Object get(Class clazz,
               Serializable id,
               LockOptions lockOptions)

  Return the persistent instance of the given entity class with the given identifier, or null if there is no such persistent instance. (If the instance is already associated with the session, return that instance. This method never returns an uninitialized instance.) Obtain the specified lock mode if the instance exists.

  Parameters:
    `clazz` - a persistent class
    `id` - an identifier
    `lockOptions` - the lock mode
  Returns:
    a persistent instance or null

### get

    Object get(String entityName,
               Serializable id)

  Return the persistent instance of the given named entity with the given identifier, or null if there is no such persistent instance. (If the instance is already associated with the session, return that instance. This method never returns an uninitialized instance.)

  Parameters:
    `entityName` - the entity name
    `id` - an identifier
  Returns:
    a persistent instance or null

### get

    @Deprecated
    Object get(String entityName,
                          Serializable id,
                          LockMode lockMode)

  Deprecated. LockMode parameter should be replaced with LockOptions

  Return the persistent instance of the given entity class with the given identifier, or null if there is no such persistent instance. (If the instance is already associated with the session, return that instance. This method never returns an uninitialized instance.) Obtain the specified lock mode if the instance exists.

  Parameters:
    `entityName` - the entity name
    `id` - an identifier
    `lockMode` - the lock mode
  Returns:
    a persistent instance or null

### get

    Object get(String entityName,
               Serializable id,
               LockOptions lockOptions)

  Return the persistent instance of the given entity class with the given identifier, or null if there is no such persistent instance. (If the instance is already associated with the session, return that instance. This method never returns an uninitialized instance.) Obtain the specified lock mode if the instance exists.

  Parameters:
    `entityName` - the entity name
    `id` - an identifier
    `lockOptions` - contains the lock mode
  Returns:
    a persistent instance or null

### getEntityName

    String getEntityName(Object object)

  Return the entity name for a persistent entity

  Parameters:
    `object` - a persistent entity
  Returns:
    the entity name

### byId

    IdentifierLoadAccess byId(String entityName)

  Create an `IdentifierLoadAccess` instance to retrieve the specified entity type by primary key.

  Parameters:
    `entityName` - The entity name of the entity type to be retrieved
  Returns:
    load delegate for loading the specified entity type by primary key
  Throws:
    `HibernateException` - If the specified entity name cannot be resolved as an entity name

### byId

    IdentifierLoadAccess byId(Class entityClass)

  Create an `IdentifierLoadAccess` instance to retrieve the specified entity by primary key.

  Parameters:
    `entityClass` - The entity type to be retrieved
  Returns:
    load delegate for loading the specified entity type by primary key
  Throws:
    `HibernateException` - If the specified Class cannot be resolved as a mapped entity

### byNaturalId

    NaturalIdLoadAccess byNaturalId(String entityName)

  Create an `NaturalIdLoadAccess` instance to retrieve the specified entity by its natural id.

  Parameters:
    `entityName` - The entity name of the entity type to be retrieved
  Returns:
    load delegate for loading the specified entity type by natural id
  Throws:
    `HibernateException` - If the specified entity name cannot be resolved as an entity name

### byNaturalId

    NaturalIdLoadAccess byNaturalId(Class entityClass)

  Create an `NaturalIdLoadAccess` instance to retrieve the specified entity by its natural id.

  Parameters:
    `entityClass` - The entity type to be retrieved
  Returns:
    load delegate for loading the specified entity type by natural id
  Throws:
    `HibernateException` - If the specified Class cannot be resolved as a mapped entity

### bySimpleNaturalId

    SimpleNaturalIdLoadAccess bySimpleNaturalId(String entityName)

  Create an `SimpleNaturalIdLoadAccess` instance to retrieve the specified entity by its natural id.

  Parameters:
    `entityName` - The entity name of the entity type to be retrieved
  Returns:
    load delegate for loading the specified entity type by natural id
  Throws:
    `HibernateException` - If the specified entityClass cannot be resolved as a mapped entity, or if the entity does not define a natural-id or if its natural-id is made up of multiple attributes.

### bySimpleNaturalId

    SimpleNaturalIdLoadAccess bySimpleNaturalId(Class entityClass)

  Create an `SimpleNaturalIdLoadAccess` instance to retrieve the specified entity by its simple (single attribute) natural id.

  Parameters:
    `entityClass` - The entity type to be retrieved
  Returns:
    load delegate for loading the specified entity type by natural id
  Throws:
    `HibernateException` - If the specified entityClass cannot be resolved as a mapped entity, or if the entity does not define a natural-id or if its natural-id is made up of multiple attributes.

### enableFilter

    Filter enableFilter(String filterName)

  Enable the named filter for this current session.

  Parameters:
    `filterName` - The name of the filter to be enabled.
  Returns:
    The Filter instance representing the enabled filter.

### getEnabledFilter

    Filter getEnabledFilter(String filterName)

  Retrieve a currently enabled filter by name.

  Parameters:
    `filterName` - The name of the filter to be retrieved.
  Returns:
    The Filter instance representing the enabled filter.

### disableFilter

    void disableFilter(String filterName)

  Disable the named filter for the current session.

  Parameters:
    `filterName` - The name of the filter to be disabled.

### getStatistics

    SessionStatistics getStatistics()

  Get the statistics for this session.

  Returns:
    The session statistics being collected for this session

### isReadOnly

    boolean isReadOnly(Object entityOrProxy)

  Is the specified entity or proxy read-only? To get the default read-only/modifiable setting used for entities and proxies that are loaded into the session:

  Parameters:
    `entityOrProxy` - an entity or HibernateProxy
  Returns:
    `true` if the entity or proxy is read-only, `false` if the entity or proxy is modifiable.
  See Also:
    `isDefaultReadOnly()`

### setReadOnly

    void setReadOnly(Object entityOrProxy,
                     boolean readOnly)

  Set an unmodified persistent object to read-only mode, or a read-only object to modifiable mode. In read-only mode, no snapshot is maintained, the instance is never dirty checked, and changes are not persisted. If the entity or proxy already has the specified read-only/modifiable setting, then this method does nothing. To set the default read-only/modifiable setting used for entities and proxies that are loaded into the session:

  Parameters:
    `entityOrProxy` - an entity or HibernateProxy
    `readOnly` - `true` if the entity or proxy should be made read-only; `false` if the entity or proxy should be made modifiable
  See Also:
    `To override this session's read-only/modifiable setting for entities and proxies loaded by a Query:`, `Query.setReadOnly(boolean)`

### doWork

    void doWork(Work work)
                throws HibernateException

  Controller for allowing users to perform JDBC related work using the Connection managed by this Session.

  Parameters:
    `work` - The work to be performed.
  Throws:
    `HibernateException` - Generally indicates wrapped `SQLException`

### doReturningWork

    <T> T doReturningWork(ReturningWork<T> work)
                      throws HibernateException

  Controller for allowing users to perform JDBC related work using the Connection managed by this Session. After execution returns the result of the `ReturningWork.execute(java.sql.Connection)` call.

  Parameters:
    `work` - The work to be performed.
  Returns:
    the result from calling `ReturningWork.execute(java.sql.Connection)`.
  Throws:
    `HibernateException` - Generally indicates wrapped `SQLException`

### disconnect

    Connection disconnect()

  Disconnect the session from its underlying JDBC connection. This is intended for use in cases where the application has supplied the JDBC connection to the session and which require long-sessions (aka, conversations).

  It is considered an error to call this method on a session which was not opened by supplying the JDBC connection and an exception will be thrown.

  For non-user-supplied scenarios, normal transaction management already handles disconnection and reconnection automatically.

  Returns:
    the application-supplied connection or `null`
  See Also:
    `reconnect(Connection)`

### reconnect

    void reconnect(Connection connection)

  Reconnect to the given JDBC connection.

  Parameters:
    `connection` - a JDBC connection
  See Also:
    `disconnect()`

### isFetchProfileEnabled

    boolean isFetchProfileEnabled(String name)
                                  throws UnknownProfileException

  Is a particular fetch profile enabled on this session?

  Parameters:
    `name` - The name of the profile to be checked.
  Returns:
    True if fetch profile is enabled; false if not.
  Throws:
    `UnknownProfileException` - Indicates that the given name does not match any known profile names
  See Also:
    `for discussion of this feature`

### enableFetchProfile

    void enableFetchProfile(String name)
                            throws UnknownProfileException

  Enable a particular fetch profile on this session. No-op if requested profile is already enabled.

  Parameters:
    `name` - The name of the fetch profile to be enabled.
  Throws:
    `UnknownProfileException` - Indicates that the given name does not match any known profile names
  See Also:
    `for discussion of this feature`

### disableFetchProfile

    void disableFetchProfile(String name)
                             throws UnknownProfileException

  Disable a particular fetch profile on this session. No-op if requested profile is already disabled.

  Parameters:
    `name` - The name of the fetch profile to be disabled.
  Throws:
    `UnknownProfileException` - Indicates that the given name does not match any known profile names
  See Also:
    `for discussion of this feature`

### getTypeHelper

    TypeHelper getTypeHelper()

  Convenience access to the `TypeHelper` associated with this session's `SessionFactory`.

  Equivalent to calling `getSessionFactory()`.`getTypeHelper()`

  Returns:
    The `TypeHelper` associated with this session's `SessionFactory`

### getLobHelper

    LobHelper getLobHelper()

  Retrieve this session's helper/delegate for creating LOB instances.

  Returns:
    This session's LOB helper

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

Copyright © 2001-2012 Red Hat, Inc. All Rights Reserved.