org.hibernate
Interface Session

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 Sessionpersistent: associated with a unique Sessiondetached: 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.

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.

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.

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.

getEntityMode

getSession

Starts a new Session with the given entity mode in effect. This secondary
Session inherits the connection, transaction, and other context
information from the primary Session. It doesn't need to be flushed
or closed by the developer.

getSessionFactory

connection

Deprecated.(scheduled for removal in 4.x). Replacement depends on need; for doing direct JDBC stuff use
doWork(org.hibernate.jdbc.Work); for opening a 'temporary Session' use (TBD).

Get the JDBC connection of this Session.

If the session is using aggressive collection release (as in a
CMT environment), it is the application's responsibility to
close the connection returned by this call. Otherwise, the
application should not close the connection.

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

evict

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".

load

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

load

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

save

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".

save

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".

update

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".

update

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".

merge

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".

merge

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".

delete

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".

delete

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".

lock

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".

lock

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".

buildLockRequest

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.
Use: session.buildLockRequest().
setLockMode(LockMode.PESSIMISTIC_WRITE).setTimeOut(1000 * 60).lock(entity);

refresh

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

refresh

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.

refresh

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.

beginTransaction

Begin a unit of work and return the associated Transaction object.
If a new underlying transaction is required, begin the transaction. Otherwise
continue the new work in the context of the existing underlying transaction.
The class of the returned Transaction object is determined by the
property hibernate.transaction_factory.

get

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.)

get

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.

get

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.

get

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.)

get

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.

get

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.

setReadOnly

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 - if true, the entity or proxy is made read-only;
if false, the entity or proxy is made modifiable.