Docjar: A Java Source and Docuemnt Enginecom.*    java.*    javax.*    org.*    all    new    plug-in

Quick Search    Search Deep
Overview  Package   Class  Use  Deprecated  Index 
Home >> All >> org >> [ hibernate overview ]  PREV CLASS  NEXT CLASS
SUMMARY: JavaDoc of org.hibernate.Session JAVADOC | Sourc code of org.hibernate.Session SOURCE | Download org.hibernate.Session DOWNLOAD | NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

org.hibernate
Interface Session  view Session download Session.java

All Superinterfaces:
java.io.Serializable
public interface Session
extends java.io.Serializable

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.

Method Summary
 Transaction beginTransaction()
          Begin a unit of work and return the associated Transaction object.
 void cancelQuery()
          Cancel execution of the current query.
 void clear()
          Completely clear the session.
 java.sql.Connection close()
          End the Session by disconnecting from the JDBC connection and cleaning up.
 java.sql.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.
 boolean contains(java.lang.Object object)
          Check if this instance is associated with this Session.
 Criteria createCriteria(java.lang.Class persistentClass)
          Create a new Criteria instance, for the given entity class, or a superclass of an entity class.
 Criteria createCriteria(java.lang.Class persistentClass, java.lang.String alias)
          Create a new Criteria instance, for the given entity class, or a superclass of an entity class, with the given alias.
 Criteria createCriteria(java.lang.String entityName)
          Create a new Criteria instance, for the given entity name.
 Criteria createCriteria(java.lang.String entityName, java.lang.String alias)
          Create a new Criteria instance, for the given entity name, with the given alias.
 Query createFilter(java.lang.Object collection, java.lang.String queryString)
          Create a new instance of Query for the given collection and filter string.
 Query createQuery(java.lang.String queryString)
          Create a new instance of Query for the given HQL query string.
 SQLQuery createSQLQuery(java.lang.String queryString)
          Create a new instance of SQLQuery for the given SQL query string.
 void delete(java.lang.Object object)
          Remove a persistent instance from the datastore.
 void delete(java.lang.String entityName, java.lang.Object object)
          Remove a persistent instance from the datastore.
 void disableFilter(java.lang.String filterName)
          Disable the named filter for the current session.
 java.sql.Connection disconnect()
          Disconnect the Session from the current JDBC connection.
 Filter enableFilter(java.lang.String filterName)
          Enable the named filter for this current session.
 void evict(java.lang.Object object)
          Remove this instance from the session cache.
 void flush()
          Force the Session to flush.
 java.lang.Object get(java.lang.Class clazz, java.io.Serializable id)
          Return the persistent instance of the given entity class with the given identifier, or null if there is no such persistent instance.
 java.lang.Object get(java.lang.Class clazz, java.io.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.
 java.lang.Object get(java.lang.String entityName, java.io.Serializable id)
          Return the persistent instance of the given named entity with the given identifier, or null if there is no such persistent instance.
 java.lang.Object get(java.lang.String entityName, java.io.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.
 CacheMode getCacheMode()
          Get the current cache mode.
 LockMode getCurrentLockMode(java.lang.Object object)
          Determine the current lock mode of the given object.
 Filter getEnabledFilter(java.lang.String filterName)
          Retrieve a currently enabled filter by name.
 EntityMode getEntityMode()
          Retrieve the entity mode in effect for this session.
 java.lang.String getEntityName(java.lang.Object object)
          Return the entity name for a persistent entity
 FlushMode getFlushMode()
          Get the current flush mode.
 java.io.Serializable getIdentifier(java.lang.Object object)
          Return the identifier of an entity instance cached by the Session, or throw an exception if the instance is transient or associated with a different Session.
 Query getNamedQuery(java.lang.String queryName)
          Obtain an instance of Query for a named query string defined in the mapping file.
 Session getSession(EntityMode entityMode)
          Starts a new Session with the given entity mode in effect.
 SessionFactory getSessionFactory()
          Get the SessionFactory that created this instance.
 org.hibernate.stat.SessionStatistics getStatistics()
          Get the statistics for this session.
 Transaction getTransaction()
          Get the Transaction instance associated with this session.
 boolean isConnected()
          Check if the Session is currently connected.
 boolean isDirty()
          Does this Session contain any changes which must be synchronized with the database? Would any SQL be executed if we flushed this session?
 boolean isOpen()
          Check if the Session is still open.
 java.lang.Object load(java.lang.Class theClass, java.io.Serializable id)
          Return the persistent instance of the given entity class with the given identifier, assuming that the instance exists.
 java.lang.Object load(java.lang.Class theClass, java.io.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.
 void load(java.lang.Object object, java.io.Serializable id)
          Read the persistent state associated with the given identifier into the given transient instance.
 java.lang.Object load(java.lang.String entityName, java.io.Serializable id)
          Return the persistent instance of the given entity class with the given identifier, assuming that the instance exists.
 java.lang.Object load(java.lang.String entityName, java.io.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.
 void lock(java.lang.Object object, LockMode lockMode)
          Obtain the specified lock level upon the given object.
 void lock(java.lang.String entityName, java.lang.Object object, LockMode lockMode)
          Obtain the specified lock level upon the given object.
 java.lang.Object merge(java.lang.Object object)
          Copy the state of the given object onto the persistent object with the same identifier.
 java.lang.Object merge(java.lang.String entityName, java.lang.Object object)
          Copy the state of the given object onto the persistent object with the same identifier.
 void persist(java.lang.Object object)
          Make a transient instance persistent.
 void persist(java.lang.String entityName, java.lang.Object object)
          Make a transient instance persistent.
 void reconnect()
          Deprecated. Manual reconnection is only needed in the case of application-supplied connections, in which case the reconnect(java.sql.Connection) 55 for should be used.
 void reconnect(java.sql.Connection connection)
          Reconnect to the given JDBC connection.
 void refresh(java.lang.Object object)
          Re-read the state of the given instance from the underlying database.
 void refresh(java.lang.Object object, LockMode lockMode)
          Re-read the state of the given instance from the underlying database, with the given LockMode.
 void replicate(java.lang.Object object, ReplicationMode replicationMode)
          Persist the state of the given detached instance, reusing the current identifier value.
 void replicate(java.lang.String entityName, java.lang.Object object, ReplicationMode replicationMode)
          Persist the state of the given detached instance, reusing the current identifier value.
 java.io.Serializable save(java.lang.Object object)
          Persist the given transient instance, first assigning a generated identifier.
 java.io.Serializable save(java.lang.String entityName, java.lang.Object object)
          Persist the given transient instance, first assigning a generated identifier.
 void saveOrUpdate(java.lang.Object object)
          Either save() or update() the given instance, depending upon the value of its identifier property.
 void saveOrUpdate(java.lang.String entityName, java.lang.Object object)
          Either save() or update() the given instance, depending upon the value of its identifier property.
 void setCacheMode(CacheMode cacheMode)
          Set the cache mode.
 void setFlushMode(FlushMode flushMode)
          Set the flush mode.
 void setReadOnly(java.lang.Object entity, boolean readOnly)
          Set an unmodified persistent object to read only mode, or a read only object to modifiable mode.
 void update(java.lang.Object object)
          Update the persistent instance with the identifier of the given detached instance.
 void update(java.lang.String entityName, java.lang.Object object)
          Update the persistent instance with the identifier of the given detached instance.
 

Method Detail

getEntityMode

public EntityMode getEntityMode()
Retrieve the entity mode in effect for this session.

getSession

public Session getSession(EntityMode entityMode)
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.

flush

public void flush()
           throws HibernateException
Force the Session to flush. Must be called at the end of a unit of work, before commiting the transaction and closing the session (Transaction.commit() calls this method). Flushing is the process of synchronising the underlying persistent store with persistable state held in memory.

setFlushMode

public void setFlushMode(FlushMode flushMode)
Set the flush mode. The flush mode determines at which points Hibernate automatically flushes the session. For a readonly session, it is reasonable to set the flush mode to FlushMode.NEVER at the start of the session (in order to achieve some extra performance).

getFlushMode

public FlushMode getFlushMode()
Get the current flush mode.

setCacheMode

public void setCacheMode(CacheMode cacheMode)
Set the cache mode.

getCacheMode

public CacheMode getCacheMode()
Get the current cache mode.

getSessionFactory

public SessionFactory getSessionFactory()
Get the SessionFactory that created this instance.

connection

public java.sql.Connection connection()
                               throws HibernateException
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.

close

public java.sql.Connection close()
                          throws HibernateException
End the Session by disconnecting from the JDBC connection and cleaning up. It is not strictly necessary to close() the Session but you must at least disconnect() it.

cancelQuery

public void cancelQuery()
                 throws HibernateException
Cancel execution of the current query. May be called from one thread to stop execution of a query in another thread. Use with care!

isOpen

public boolean isOpen()
Check if the Session is still open.

isConnected

public boolean isConnected()
Check if the Session is currently connected.

isDirty

public boolean isDirty()
                throws HibernateException
Does this Session contain any changes which must be synchronized with the database? Would any SQL be executed if we flushed this session?

getIdentifier

public java.io.Serializable getIdentifier(java.lang.Object object)
                                   throws HibernateException
Return the identifier of an entity instance cached by the Session, or throw an exception if the instance is transient or associated with a different Session.

contains

public boolean contains(java.lang.Object object)
Check if this instance is associated with this Session.

evict

public void evict(java.lang.Object object)
           throws HibernateException
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

public java.lang.Object load(java.lang.Class theClass,
                             java.io.Serializable id,
                             LockMode lockMode)
                      throws HibernateException
Return the persistent instance of the given entity class with the given identifier, obtaining the specified lock mode, assuming the instance exists.

load

public java.lang.Object load(java.lang.String entityName,
                             java.io.Serializable id,
                             LockMode lockMode)
                      throws HibernateException
Return the persistent instance of the given entity class with the given identifier, obtaining the specified lock mode, assuming the instance exists.

load

public java.lang.Object load(java.lang.Class theClass,
                             java.io.Serializable id)
                      throws HibernateException
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.

load

public java.lang.Object load(java.lang.String entityName,
                             java.io.Serializable id)
                      throws HibernateException
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.

load

public void load(java.lang.Object object,
                 java.io.Serializable id)
          throws HibernateException
Read the persistent state associated with the given identifier into the given transient instance.

replicate

public void replicate(java.lang.Object object,
                      ReplicationMode replicationMode)
               throws HibernateException
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".

replicate

public void replicate(java.lang.String entityName,
                      java.lang.Object object,
                      ReplicationMode replicationMode)
               throws HibernateException
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".

save

public java.io.Serializable save(java.lang.Object object)
                          throws HibernateException
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

public java.io.Serializable save(java.lang.String entityName,
                                 java.lang.Object object)
                          throws HibernateException
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".

saveOrUpdate

public void saveOrUpdate(java.lang.Object object)
                  throws HibernateException
Either save() or update() the given instance, depending upon the value of its identifier property. By default the instance is always saved. This behaviour may be adjusted by specifying an unsaved-value attribute of the identifier property mapping. This operation cascades to associated instances if the association is mapped with cascade="save-update".

saveOrUpdate

public void saveOrUpdate(java.lang.String entityName,
                         java.lang.Object object)
                  throws HibernateException
Either save() or update() the given instance, depending upon the value of its identifier property. By default the instance is always saved. This behaviour may be adjusted by specifying an unsaved-value attribute of the identifier property mapping. This operation cascades to associated instances if the association is mapped with cascade="save-update".

update

public void update(java.lang.Object object)
            throws HibernateException
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

public void update(java.lang.String entityName,
                   java.lang.Object object)
            throws HibernateException
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

public java.lang.Object merge(java.lang.Object object)
                       throws HibernateException
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.

merge

public java.lang.Object merge(java.lang.String entityName,
                              java.lang.Object object)
                       throws HibernateException
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.

persist

public void persist(java.lang.Object object)
             throws HibernateException
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.

persist

public void persist(java.lang.String entityName,
                    java.lang.Object object)
             throws HibernateException
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.

delete

public void delete(java.lang.Object object)
            throws HibernateException
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

public void delete(java.lang.String entityName,
                   java.lang.Object object)
            throws HibernateException
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

public void lock(java.lang.Object object,
                 LockMode lockMode)
          throws HibernateException
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".

lock

public void lock(java.lang.String entityName,
                 java.lang.Object object,
                 LockMode lockMode)
          throws HibernateException
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".

refresh

public void refresh(java.lang.Object object)
             throws HibernateException
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

refresh

public void refresh(java.lang.Object object,
                    LockMode lockMode)
             throws HibernateException
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.

getCurrentLockMode

public LockMode getCurrentLockMode(java.lang.Object object)
                            throws HibernateException
Determine the current lock mode of the given object.

beginTransaction

public Transaction beginTransaction()
                             throws HibernateException
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.

getTransaction

public Transaction getTransaction()
Get the Transaction instance associated with this session. The class of the returned Transaction object is determined by the property hibernate.transaction_factory.

createCriteria

public Criteria createCriteria(java.lang.Class persistentClass)
Create a new Criteria instance, for the given entity class, or a superclass of an entity class.

createCriteria

public Criteria createCriteria(java.lang.Class persistentClass,
                               java.lang.String alias)
Create a new Criteria instance, for the given entity class, or a superclass of an entity class, with the given alias.

createCriteria

public Criteria createCriteria(java.lang.String entityName)
Create a new Criteria instance, for the given entity name.

createCriteria

public Criteria createCriteria(java.lang.String entityName,
                               java.lang.String alias)
Create a new Criteria instance, for the given entity name, with the given alias.

createQuery

public Query createQuery(java.lang.String queryString)
                  throws HibernateException
Create a new instance of Query for the given HQL query string.

createSQLQuery

public SQLQuery createSQLQuery(java.lang.String queryString)
                        throws HibernateException
Create a new instance of SQLQuery for the given SQL query string.

createFilter

public Query createFilter(java.lang.Object collection,
                          java.lang.String queryString)
                   throws HibernateException
Create a new instance of Query for the given collection and filter string.

getNamedQuery

public Query getNamedQuery(java.lang.String queryName)
                    throws HibernateException
Obtain an instance of Query for a named query string defined in the mapping file.

clear

public 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

public java.lang.Object get(java.lang.Class clazz,
                            java.io.Serializable id)
                     throws HibernateException
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.)

get

public java.lang.Object get(java.lang.Class clazz,
                            java.io.Serializable id,
                            LockMode lockMode)
                     throws HibernateException
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.

get

public java.lang.Object get(java.lang.String entityName,
                            java.io.Serializable id)
                     throws HibernateException
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.)

get

public java.lang.Object get(java.lang.String entityName,
                            java.io.Serializable id,
                            LockMode lockMode)
                     throws HibernateException
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.

getEntityName

public java.lang.String getEntityName(java.lang.Object object)
                               throws HibernateException
Return the entity name for a persistent entity

enableFilter

public Filter enableFilter(java.lang.String filterName)
Enable the named filter for this current session.

getEnabledFilter

public Filter getEnabledFilter(java.lang.String filterName)
Retrieve a currently enabled filter by name.

disableFilter

public void disableFilter(java.lang.String filterName)
Disable the named filter for the current session.

getStatistics

public org.hibernate.stat.SessionStatistics getStatistics()
Get the statistics for this session.

setReadOnly

public void setReadOnly(java.lang.Object entity,
                        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 and the instance is never dirty checked.

disconnect

public java.sql.Connection disconnect()
                               throws HibernateException
Disconnect the Session from the current JDBC connection. If the connection was obtained by Hibernate close it and return it to the connection pool; otherwise, return it to the application.

This is used by applications which supply JDBC connections to Hibernate and which require long-sessions (or long-conversations)

Note that disconnect() called on a session where the connection was retrieved by Hibernate through its configured org.hibernate.connection.ConnectionProvider has no effect, provided ConnectionReleaseMode.ON_CLOSE 55 is not in effect.

reconnect

public void reconnect()
               throws HibernateException
Deprecated. Manual reconnection is only needed in the case of application-supplied connections, in which case the reconnect(java.sql.Connection) 55 for should be used.

Obtain a new JDBC connection. This is used by applications which require long transactions and do not supply connections to the session.

reconnect

public void reconnect(java.sql.Connection connection)
               throws HibernateException
Reconnect to the given JDBC connection. This is used by applications which require long transactions and use application-supplied connections.

Overview  Package   Class  Use  Deprecated  Index 
Home >> All >> org >> [ hibernate overview ]  PREV CLASS  NEXT CLASS
SUMMARY: JavaDoc of org.hibernate.Session JAVADOC | Sourc code of org.hibernate.Session SOURCE | Download org.hibernate.Session DOWNLOAD | NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD