| org.hibernate.Session
| Session | | public interface Session extends Serializable(Code) | | 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
author:
Gavin King |
| Method Summary | |
| public Transaction | beginTransaction()
Begin a unit of work and return the associated Transaction object.
If a new underlying transaction is required, begin the transaction. | | public void | cancelQuery()
Cancel the execution of the current query. | | public void | clear()
Completely clear the session. | | public Connection | close()
End the session by releasing the JDBC connection and cleaning up. | | public Connection | connection()
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. | | public boolean | contains(Object object)
Check if this instance is associated with this Session. | | public Criteria | createCriteria(Class persistentClass)
Create a new Criteria instance, for the given entity class,
or a superclass of an entity class. | | public Criteria | createCriteria(Class 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 | createCriteria(String entityName)
Create a new Criteria instance, for the given entity name. | | public Criteria | createCriteria(String entityName, String alias)
Create a new Criteria instance, for the given entity name,
with the given alias. | | public Query | createFilter(Object collection, String queryString)
Create a new instance of Query for the given collection and filter string. | | public Query | createQuery(String queryString)
Create a new instance of Query for the given HQL query string. | | public SQLQuery | createSQLQuery(String queryString)
Create a new instance of SQLQuery for the given SQL query string. | | public void | delete(Object object)
Remove a persistent instance from the datastore. | | public void | delete(String entityName, Object object)
Remove a persistent instance from the datastore. | | public void | disableFilter(String filterName)
Disable the named filter for the current session. | | Connection | disconnect()
Disconnect the Session from the current JDBC connection. | | public Filter | enableFilter(String filterName)
Enable the named filter for this current session.
Parameters:
filterName - The name of the filter to be enabled. | | public void | evict(Object object)
Remove this instance from the session cache. | | public void | flush()
Force this session to flush. | | public 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. | | public Object | get(Class clazz, Serializable id, LockMode lockMode)
Return the persistent instance of the given entity class with the given identifier,
or null if there is no such persistent instance. | | public 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. | | public Object | get(String entityName, Serializable id, LockMode lockMode)
Return the persistent instance of the given entity class with the given identifier,
or null if there is no such persistent instance. | | public CacheMode | getCacheMode()
Get the current cache mode. | | public LockMode | getCurrentLockMode(Object object)
Determine the current lock mode of the given object. | | public Filter | getEnabledFilter(String filterName)
Retrieve a currently enabled filter by name.
Parameters:
filterName - The name of the filter to be retrieved. | | public EntityMode | getEntityMode()
Retrieve the entity mode in effect for this session. | | public String | getEntityName(Object object)
| | public FlushMode | getFlushMode()
Get the current flush mode for this session. | | public Serializable | getIdentifier(Object object)
Return the identifier value of the given entity as associated with this
session. | | public Query | getNamedQuery(String queryName)
Obtain an instance of Query for a named query string defined in the
mapping file. | | public Session | getSession(EntityMode entityMode)
Starts a new Session with the given entity mode in effect. | | public SessionFactory | getSessionFactory()
Get the session factory which created this session. | | public SessionStatistics | getStatistics()
Get the statistics for this session. | | public Transaction | getTransaction()
Get the Transaction instance associated with this session. | | public boolean | isConnected()
Check if the session is currently connected. | | public boolean | isDirty()
| | public boolean | isOpen()
Check if the session is still open. | | public Object | load(Class theClass, Serializable id, LockMode lockMode)
Return the persistent instance of the given entity class with the given identifier,
obtaining the specified lock mode, assuming the instance exists. | | public Object | load(String entityName, Serializable id, LockMode lockMode)
Return the persistent instance of the given entity class with the given identifier,
obtaining the specified lock mode, assuming the instance exists. | | public Object | load(Class theClass, Serializable id)
Return the persistent instance of the given entity class with the given identifier,
assuming that the instance exists.
You should not use this method to determine if an instance exists (use get()
instead). | | public Object | load(String entityName, Serializable id)
Return the persistent instance of the given entity class with the given identifier,
assuming that the instance exists.
You should not use this method to determine if an instance exists (use get()
instead). | | public void | load(Object object, Serializable id)
Read the persistent state associated with the given identifier into the given transient
instance. | | public void | lock(Object object, LockMode lockMode)
Obtain the specified lock level upon the given object. | | public void | lock(String entityName, Object object, LockMode lockMode)
Obtain the specified lock level upon the given object. | | public Object | merge(Object object)
Copy the state of the given object onto the persistent object with the same
identifier. | | public Object | merge(String entityName, Object object)
Copy the state of the given object onto the persistent object with the same
identifier. | | public void | persist(Object object)
Make a transient instance persistent. | | public void | persist(String entityName, Object object)
Make a transient instance persistent. | | void | reconnect()
Obtain a new JDBC connection. | | void | reconnect(Connection connection)
Reconnect to the given JDBC connection. | | public void | refresh(Object object)
Re-read the state of the given instance from the underlying database. | | public void | refresh(Object object, LockMode lockMode)
Re-read the state of the given instance from the underlying database, with
the given LockMode. | | public void | replicate(Object object, ReplicationMode replicationMode)
Persist the state of the given detached instance, reusing the current
identifier value. | | public void | replicate(String entityName, Object object, ReplicationMode replicationMode)
Persist the state of the given detached instance, reusing the current
identifier value. | | public Serializable | save(Object object)
Persist the given transient instance, first assigning a generated identifier. | | public Serializable | save(String entityName, Object object)
Persist the given transient instance, first assigning a generated identifier. | | public void | saveOrUpdate(Object object)
Either
Session.save(Object) or
Session.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 object)
Either
Session.save(String,Object) or
Session.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 cacheMode)
Set the cache mode. | | public void | setFlushMode(FlushMode flushMode)
Set the flush mode for this session. | | public void | setReadOnly(Object entity, boolean readOnly)
Set an unmodified persistent object to read only mode, or a read only
object to modifiable mode. | | public void | update(Object object)
Update the persistent instance with the identifier of the given detached
instance. | | public void | update(String entityName, Object object)
Update the persistent instance with the identifier of the given detached
instance. |
| beginTransaction | | public Transaction beginTransaction() throws HibernateException(Code) | | 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.
a Transaction instance
throws:
HibernateException -
See Also: Transaction |
| cancelQuery | | public void cancelQuery() throws HibernateException(Code) | | 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 |
| clear | | public void clear()(Code) | | 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.
|
| connection | | public Connection connection() throws HibernateException(Code) | | 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.
the JDBC connection in use by the Session
throws:
HibernateException - if the Session is disconnected |
| contains | | public boolean contains(Object object)(Code) | | Check if this instance is associated with this Session.
Parameters:
object - an instance of a persistent class true if the given instance is associated with this Session |
| createCriteria | | public Criteria createCriteria(Class persistentClass)(Code) | | Create a new Criteria instance, for the given entity class,
or a superclass of an entity class.
Parameters:
persistentClass - a class, which is persistent, or has persistent subclasses Criteria |
| createCriteria | | public Criteria createCriteria(Class persistentClass, String alias)(Code) | | Create a new Criteria instance, for the given entity class,
or a superclass of an entity class, with the given alias.
Parameters:
persistentClass - a class, which is persistent, or has persistent subclasses Criteria |
| createCriteria | | public Criteria createCriteria(String entityName)(Code) | | Create a new Criteria instance, for the given entity name.
Parameters:
entityName - Criteria |
| createCriteria | | public Criteria createCriteria(String entityName, String alias)(Code) | | Create a new Criteria instance, for the given entity name,
with the given alias.
Parameters:
entityName - Criteria |
| createFilter | | public Query createFilter(Object collection, String queryString) throws HibernateException(Code) | | Create a new instance of Query for the given collection and filter string.
Parameters:
collection - a persistent collection
Parameters:
queryString - a Hibernate query Query
throws:
HibernateException - |
| delete | | public void delete(Object object) throws HibernateException(Code) | | 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
throws:
HibernateException - |
| delete | | public void delete(String entityName, Object object) throws HibernateException(Code) | | 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.
Parameters:
object - the instance to be removed
throws:
HibernateException - |
| disableFilter | | public void disableFilter(String filterName)(Code) | | Disable the named filter for the current session.
Parameters:
filterName - The name of the filter to be disabled. |
| enableFilter | | public Filter enableFilter(String filterName)(Code) | | Enable the named filter for this current session.
Parameters:
filterName - The name of the filter to be enabled. The Filter instance representing the enabled fiter. |
| evict | | public void evict(Object object) throws HibernateException(Code) | | 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
throws:
HibernateException - |
| flush | | public void flush() throws HibernateException(Code) | | Force this session to flush. Must be called at the end of a
unit of work, before commiting the transaction and closing the
session (depending on
Session.setFlushMode flush-mode ,
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 ortalking to the database. |
| get | | public Object get(Class clazz, Serializable id) throws HibernateException(Code) | | 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, or a proxy for the
instance, is already associated with the session, return that instance or proxy.)
Parameters:
clazz - a persistent class
Parameters:
id - an identifier a persistent instance or null
throws:
HibernateException - |
| get | | public Object get(Class clazz, Serializable id, LockMode lockMode) throws HibernateException(Code) | | Return the persistent instance of the given entity class with the given identifier,
or null if there is no such persistent instance. Obtain the specified lock mode
if the instance exists.
Parameters:
clazz - a persistent class
Parameters:
id - an identifier
Parameters:
lockMode - the lock mode a persistent instance or null
throws:
HibernateException - |
| get | | public Object get(String entityName, Serializable id) throws HibernateException(Code) | | 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, or a proxy for the
instance, is already associated with the session, return that instance or proxy.)
Parameters:
entityName - the entity name
Parameters:
id - an identifier a persistent instance or null
throws:
HibernateException - |
| get | | public Object get(String entityName, Serializable id, LockMode lockMode) throws HibernateException(Code) | | Return the persistent instance of the given entity class with the given identifier,
or null if there is no such persistent instance. Obtain the specified lock mode
if the instance exists.
Parameters:
entityName - the entity name
Parameters:
id - an identifier
Parameters:
lockMode - the lock mode a persistent instance or null
throws:
HibernateException - |
| getCacheMode | | public CacheMode getCacheMode()(Code) | | Get the current cache mode.
The current cache mode. |
| getEnabledFilter | | public Filter getEnabledFilter(String filterName)(Code) | | Retrieve a currently enabled filter by name.
Parameters:
filterName - The name of the filter to be retrieved. The Filter instance representing the enabled fiter. |
| getEntityMode | | public EntityMode getEntityMode()(Code) | | Retrieve the entity mode in effect for this session.
The entity mode for this session. |
| getFlushMode | | public FlushMode getFlushMode()(Code) | | Get the current flush mode for this session.
The flush mode |
| getIdentifier | | public Serializable getIdentifier(Object object) throws HibernateException(Code) | | 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 the identifier
throws:
TransientObjectException - if the instance is transient or associated witha different session |
| getNamedQuery | | public Query getNamedQuery(String queryName) throws HibernateException(Code) | | Obtain an instance of Query for a named query string defined in the
mapping file.
Parameters:
queryName - the name of a query defined externally Query
throws:
HibernateException - |
| getSession | | public Session getSession(EntityMode entityMode)(Code) | | 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.
Parameters:
entityMode - The entity mode to use for the new session. The new session |
| getTransaction | | public Transaction getTransaction()(Code) | | Get the Transaction instance associated with this session.
The class of the returned Transaction object is determined by the
property hibernate.transaction_factory.
a Transaction instance
throws:
HibernateException -
See Also: Transaction |
| isConnected | | public boolean isConnected()(Code) | | Check if the session is currently connected.
boolean |
| isDirty | | public boolean isDirty() throws HibernateException(Code) | | 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?
True if the session contains pending changes; false otherwise.
throws:
HibernateException - could not perform dirtying checking |
| isOpen | | public boolean isOpen()(Code) | | Check if the session is still open.
boolean |
| load | | public Object load(Class theClass, Serializable id, LockMode lockMode) throws HibernateException(Code) | | 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
Parameters:
id - a valid identifier of an existing persistent instance of the class
Parameters:
lockMode - the lock level the persistent instance or proxy
throws:
HibernateException - |
| load | | public Object load(String entityName, Serializable id, LockMode lockMode) throws HibernateException(Code) | | 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
Parameters:
id - a valid identifier of an existing persistent instance of the class
Parameters:
lockMode - the lock level the persistent instance or proxy
throws:
HibernateException - |
| load | | public Object load(Class theClass, Serializable id) throws HibernateException(Code) | | Return the persistent instance of the given entity class with the given identifier,
assuming that the instance exists.
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
Parameters:
id - a valid identifier of an existing persistent instance of the class the persistent instance or proxy
throws:
HibernateException - |
| load | | public Object load(String entityName, Serializable id) throws HibernateException(Code) | | Return the persistent instance of the given entity class with the given identifier,
assuming that the instance exists.
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
Parameters:
id - a valid identifier of an existing persistent instance of the class the persistent instance or proxy
throws:
HibernateException - |
| load | | public void load(Object object, Serializable id) throws HibernateException(Code) | | Read the persistent state associated with the given identifier into the given transient
instance.
Parameters:
object - an "empty" instance of the persistent class
Parameters:
id - a valid identifier of an existing persistent instance of the class
throws:
HibernateException - |
| lock | | public void lock(Object object, LockMode lockMode) throws HibernateException(Code) | | 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.UPGRADE), 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
Parameters:
lockMode - the lock level
throws:
HibernateException - |
| lock | | public void lock(String entityName, Object object, LockMode lockMode) throws HibernateException(Code) | | 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.UPGRADE), 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
Parameters:
lockMode - the lock level
throws:
HibernateException - |
| merge | | public Object merge(Object object) throws HibernateException(Code) | | 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 an updated persistent instance |
| merge | | public Object merge(String entityName, Object object) throws HibernateException(Code) | | 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 an updated persistent instance |
| persist | | public void persist(Object object) throws HibernateException(Code) | | 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 | | public void persist(String entityName, Object object) throws HibernateException(Code) | | 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 |
| reconnect | | void reconnect(Connection connection) throws HibernateException(Code) | | Reconnect to the given JDBC connection. This is used by applications
which require long transactions and use application-supplied connections.
Parameters:
connection - a JDBC connection
See Also: Session.disconnect() |
| refresh | | public void refresh(Object object) throws HibernateException(Code) | | 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
throws:
HibernateException - |
| refresh | | public void refresh(Object object, LockMode lockMode) throws HibernateException(Code) | | 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
Parameters:
lockMode - the lock mode to use
throws:
HibernateException - |
| replicate | | public void replicate(Object object, ReplicationMode replicationMode) throws HibernateException(Code) | | 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 |
| replicate | | public void replicate(String entityName, Object object, ReplicationMode replicationMode) throws HibernateException(Code) | | 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 |
| save | | public Serializable save(Object object) throws HibernateException(Code) | | 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 the generated identifier
throws:
HibernateException - |
| save | | public Serializable save(String entityName, Object object) throws HibernateException(Code) | | 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 the generated identifier
throws:
HibernateException - |
| setCacheMode | | public void setCacheMode(CacheMode cacheMode)(Code) | | 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. |
| setFlushMode | | public void setFlushMode(FlushMode flushMode)(Code) | | 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 |
| setReadOnly | | public void setReadOnly(Object entity, boolean readOnly)(Code) | | 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
and the instance is never dirty checked.
See Also: Query.setReadOnly(boolean) |
| update | | public void update(Object object) throws HibernateException(Code) | | 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
throws:
HibernateException - |
| update | | public void update(String entityName, Object object) throws HibernateException(Code) | | 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
throws:
HibernateException - |
|
|