Top Description Inners Methods
org.hibernate

public Interface Session

extends Serializable
Known Direct Subinterfaces
org.hibernate.classic.Session, org.hibernate.event.EventSource
Imports
java.io.Serializable, java.sql.Connection, org.hibernate.jdbc.Work, org.hibernate.stat.SessionStatistics
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.
Author
Gavin King
See Also
SessionFactory

Nested and Inner Type Summary

Modifier and TypeClass and Description
public static interface
Session.LockRequest

Contains locking details (LockMode, Timeout and Scope).

Method Summary

Modifier and TypeMethod and Description
public Transaction

Returns:

a Transaction instance
beginTransaction()

Begin a unit of work and return the associated Transaction object.

public Session.LockRequest

Returns:

a lockRequest that can be used to lock the passed object.
buildLockRequest(LockOptions
contains the lock level
lockOptions)

Build a LockRequest that specifies the LockMode, pessimistic lock timeout and lock scope.

public void
cancelQuery()

Cancel the execution of the current query.

public void
clear()

Completely clear the session.

public Connection

Returns:

the connection provided by the application or null.
close()

End the session by releasing the JDBC connection and cleaning up.

public Connection

Returns:

the JDBC connection in use by the Session
connection()

Deprecated (scheduled for removal in 4.x).
Get the JDBC connection of this Session.
public boolean

Returns:

true if the given instance is associated with this Session
contains(Object
an instance of a persistent class
object)

Check if this instance is associated with this Session.

public Criteria

Returns:

Criteria
createCriteria(Class<T>
a class, which is persistent, or has persistent subclasses
persistentClass)

Create a new Criteria instance, for the given entity class, or a superclass of an entity class.

public Criteria

Returns:

Criteria
createCriteria(Class<T>
a class, which is persistent, or has persistent subclasses
persistentClass, String alias)

Create a new Criteria instance, for the given entity class, or a superclass of an entity class, with the given alias.

public Criteria

Returns:

Criteria
createCriteria(String entityName)

Create a new Criteria instance, for the given entity name.

public Criteria

Returns:

Criteria
createCriteria(String entityName, String alias)

Create a new Criteria instance, for the given entity name, with the given alias.

public Query

Returns:

Query
createFilter(Object
a persistent collection
collection, String
a Hibernate query
queryString)

Create a new instance of Query for the given collection and filter string.

public Query

Returns:

Query
createQuery(String
a HQL query
queryString)

Create a new instance of Query for the given HQL query string.

public SQLQuery

Returns:

SQLQuery
createSQLQuery(String
a SQL query
queryString)

Create a new instance of SQLQuery for the given SQL query string.

public void
delete(Object
the instance to be removed
object)

Remove a persistent instance from the datastore.

public void
delete(String
The entity name for the instance to be removed.
entityName, Object
the instance to be removed
object)

Remove a persistent instance from the datastore.

public void
disableFetchProfile(String
The name of the fetch profile to be disabled.
name)

Disable a particular fetch profile on this session.

public void
disableFilter(String
The name of the filter to be disabled.
filterName)

Disable the named filter for the current session.

public Connection

Returns:

the application-supplied connection or null
disconnect()

Disconnect the Session from the current JDBC connection.

public void
doWork(Work
The work to be performed.
work)

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

public void
enableFetchProfile(String
The name of the fetch profile to be enabled.
name)

Enable a particular fetch profile on this session.

public Filter

Returns:

The Filter instance representing the enabled filter.
enableFilter(String
The name of the filter to be enabled.
filterName)

Enable the named filter for this current session.

public void
evict(Object
a persistent instance
object)

Remove this instance from the session cache.

public void
flush()

Force this session to flush.

public Object

Returns:

a persistent instance or null
get(Class<T>
a persistent class
clazz, Serializable
an identifier
id)

Return the persistent instance of the given entity class with the given identifier, or null if there is no such persistent instance.

public Object

Returns:

a persistent instance or null
get(Class<T>
a persistent class
clazz, Serializable
an identifier
id, LockMode
the lock mode
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.
public Object

Returns:

a persistent instance or null
get(Class<T>
a persistent class
clazz, Serializable
an identifier
id, LockOptions
the lock mode
lockOptions)

Return the persistent instance of the given entity class with the given identifier, or null if there is no such persistent instance.

public Object

Returns:

a persistent instance or null
get(String
the entity name
entityName, Serializable
an identifier
id)

Return the persistent instance of the given named entity with the given identifier, or null if there is no such persistent instance.

public Object

Returns:

a persistent instance or null
get(String
the entity name
entityName, Serializable
an identifier
id, LockMode
the lock mode
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.
public Object

Returns:

a persistent instance or null
get(String
the entity name
entityName, Serializable
an identifier
id, LockOptions
contains the lock mode
lockOptions)

Return the persistent instance of the given entity class with the given identifier, or null if there is no such persistent instance.

public CacheMode

Returns:

The current cache mode.
getCacheMode()

Get the current cache mode.

public LockMode

Returns:

the current lock mode
getCurrentLockMode(Object
a persistent instance
object)

Determine the current lock mode of the given object.

public Filter

Returns:

The Filter instance representing the enabled filter.
getEnabledFilter(String
The name of the filter to be retrieved.
filterName)

Retrieve a currently enabled filter by name.

public EntityMode

Returns:

The entity mode for this session.
getEntityMode()

Retrieve the entity mode in effect for this session.

public String

Returns:

the entity name
getEntityName(Object
a persistent entity
object)

Return the entity name for a persistent entity

public FlushMode

Returns:

The flush mode
getFlushMode()

Get the current flush mode for this session.

public Serializable

Returns:

the identifier
getIdentifier(Object
a persistent instance
object)

Return the identifier value of the given entity as associated with this session.

public LobHelper

Returns:

This session's LOB helper
getLobHelper()

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

public Query

Returns:

Query
getNamedQuery(String
the name of a query defined externally
queryName)

Obtain an instance of Query for a named query string defined in the mapping file.

public Session

Returns:

The new session
getSession(EntityMode
The entity mode to use for the new session.
entityMode)

Starts a new Session with the given entity mode in effect.

public SessionFactory

Returns:

The session factory.
getSessionFactory()

Get the session factory which created this session.

public SessionStatistics
getStatistics()

Get the statistics for this session.

public Transaction

Returns:

a Transaction instance
getTransaction()

Get the Transaction instance associated with this session.

public TypeHelper

Returns:

The TypeHelper associated with this session's SessionFactory
getTypeHelper()

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

public boolean

Returns:

boolean
isConnected()

Check if the session is currently connected.

public boolean

Returns:

true, loaded entities/proxies will be made read-only by default; false, loaded entities/proxies will be made modifiable by default.
isDefaultReadOnly()

Will entities and proxies that are loaded into this session be made read-only by default?

public boolean

Returns:

True if the session contains pending changes; false otherwise.
isDirty()

Does this session contain any changes which must be synchronized with the database?

public boolean

Returns:

True if fetch profile is enabled; false if not.
isFetchProfileEnabled(String
The name of the profile to be checked.
name)

Is a particular fetch profile enabled on this session?

public boolean

Returns:

boolean
isOpen()

Check if the session is still open.

public boolean

Returns:

true, the entity or proxy is read-only; false, the entity or proxy is modifiable.
isReadOnly(Object
an entity or HibernateProxy
entityOrProxy)

Is the specified entity or proxy read-only?

public Object

Returns:

the persistent instance or proxy
load(Class<T>
a persistent class
theClass, Serializable
a valid identifier of an existing persistent instance of the class
id, LockMode
the lock level
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.
public Object

Returns:

the persistent instance or proxy
load(Class<T>
a persistent class
theClass, Serializable
a valid identifier of an existing persistent instance of the class
id, LockOptions
contains the lock level
lockOptions)

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

public Object

Returns:

the persistent instance or proxy
load(String
a persistent class
entityName, Serializable
a valid identifier of an existing persistent instance of the class
id, LockMode
the lock level
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.
public Object

Returns:

the persistent instance or proxy
load(String
a persistent class
entityName, Serializable
a valid identifier of an existing persistent instance of the class
id, LockOptions
contains the lock level
lockOptions)

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

public Object

Returns:

the persistent instance or proxy
load(Class<T>
a persistent class
theClass, Serializable
a valid identifier of an existing persistent instance of the class
id)

Return the persistent instance of the given entity class with the given identifier, assuming that the instance exists.

public Object

Returns:

the persistent instance or proxy
load(String
a persistent class
entityName, Serializable
a valid identifier of an existing persistent instance of the class
id)

Return the persistent instance of the given entity class with the given identifier, assuming that the instance exists.

public void
load(Object
an "empty" instance of the persistent class
object, Serializable
a valid identifier of an existing persistent instance of the class
id)

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

public void
lock(Object
a persistent or transient instance
object, LockMode
the lock level
lockMode)

Deprecated instead call buildLockRequest(LockMode).lock(object)
Obtain the specified lock level upon the given object.
public void
lock(String entityName, Object
a persistent or transient instance
object, LockMode
the lock level
lockMode)

Deprecated instead call buildLockRequest(LockMode).lock(entityName, object)
Obtain the specified lock level upon the given object.
public Object

Returns:

an updated persistent instance
merge(Object
a detached instance with state to be copied
object)

Copy the state of the given object onto the persistent object with the same identifier.

public Object

Returns:

an updated persistent instance
merge(String entityName, Object
a detached instance with state to be copied
object)

Copy the state of the given object onto the persistent object with the same identifier.

public void
persist(Object
a transient instance to be made persistent
object)

Make a transient instance persistent.

public void
persist(String entityName, Object
a transient instance to be made persistent
object)

Make a transient instance persistent.

public void
reconnect()

Deprecated Manual reconnection is only needed in the case of application-supplied connections, in which case the reconnect(java.sql.Connection) for should be used.
Obtain a new JDBC connection.
public void
reconnect(Connection
a JDBC connection
connection)

Reconnect to the given JDBC connection.

public void
refresh(Object
a persistent or detached instance
object)

Re-read the state of the given instance from the underlying database.

public void
refresh(Object
a persistent or detached instance
object, LockMode
the lock mode to use
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.
public void
refresh(Object
a persistent or detached instance
object, LockOptions
contains the lock mode to use
lockOptions)

Re-read the state of the given instance from the underlying database, with the given LockMode.

public void
replicate(Object
a detached instance of a persistent class
object, ReplicationMode replicationMode)

Persist the state of the given detached instance, reusing the current identifier value.

public void
replicate(String entityName, Object
a detached instance of a persistent class
object, ReplicationMode replicationMode)

Persist the state of the given detached instance, reusing the current identifier value.

public Serializable

Returns:

the generated identifier
save(Object
a transient instance of a persistent class
object)

Persist the given transient instance, first assigning a generated identifier.

public Serializable

Returns:

the generated identifier
save(String entityName, Object
a transient instance of a persistent class
object)

Persist the given transient instance, first assigning a generated identifier.

public void
saveOrUpdate(Object
a transient or detached instance containing new or updated state
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).

public void
saveOrUpdate(String entityName, Object
a transient or detached instance containing new or updated state
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).

public void
setCacheMode(CacheMode
The new cache mode.
cacheMode)

Set the cache mode.

public void
setDefaultReadOnly(boolean
true, the default for loaded entities/proxies is read-only; false, the default for loaded entities/proxies is modifiable
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.

public void
setFlushMode(FlushMode
the new flush mode
flushMode)

Set the flush mode for this session.

public void
setReadOnly(Object
an entity or HibernateProxy
entityOrProxy, boolean
if true, the entity or proxy is made read-only; if false, the entity or proxy is made modifiable.
readOnly)

Set an unmodified persistent object to read-only mode, or a read-only object to modifiable mode.

public void
update(Object
a detached instance containing updated state
object)

Update the persistent instance with the identifier of the given detached instance.

public void
update(String entityName, Object
a detached instance containing updated state
object)

Update the persistent instance with the identifier of the given detached instance.