File	Doc	Category	Size	Date	Package
Session.java	API Doc	Hibernate 3.2.5	29166	Tue May 08 21:00:06 BST 2007	org.hibernate

Session

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();
}

Fields Summary

Constructors Summary

Methods 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. 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. return a Transaction instance throws HibernateException see Transaction
public void	cancelQuery() 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
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.
public java.sql.Connection	close() End the session by releasing the JDBC connection and cleaning up. It is not strictly necessary to close the session but you must at least {@link #disconnect()} it. return the connection provided by the application or null. throws HibernateException Indicates problems cleaning up.
public 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. Otherwise, the application should not close the connection. return the JDBC connection in use by the Session throws HibernateException if the Session is disconnected deprecated To be replaced with a SPI for performing work against the connection; scheduled for removal in 4.x
public boolean	contains(java.lang.Object object) Check if this instance is associated with this Session. param object an instance of a persistent class return true if the given instance is associated with this Session
public Criteria	createCriteria(java.lang.Class persistentClass) Create a new Criteria instance, for the given entity class, or a superclass of an entity class. param persistentClass a class, which is persistent, or has persistent subclasses return Criteria
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. param persistentClass a class, which is persistent, or has persistent subclasses return Criteria
public Criteria	createCriteria(java.lang.String entityName) Create a new Criteria instance, for the given entity name. param entityName return Criteria
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. param entityName return Criteria
public Query	createFilter(java.lang.Object collection, java.lang.String queryString) Create a new instance of Query for the given collection and filter string. param collection a persistent collection param queryString a Hibernate query return Query throws HibernateException
public Query	createQuery(java.lang.String queryString) Create a new instance of Query for the given HQL query string. param queryString a HQL query return Query throws HibernateException
public SQLQuery	createSQLQuery(java.lang.String queryString) Create a new instance of SQLQuery for the given SQL query string. param queryString a SQL query return SQLQuery throws HibernateException
public void	delete(java.lang.Object object) Remove a persistent instance from the datastore. The argument may be an instance associated with the receiving Session or a transient instance with an identifier associated with existing persistent state. This operation cascades to associated instances if the association is mapped with cascade="delete". param object the instance to be removed throws HibernateException
public void	delete(java.lang.String entityName, java.lang.Object object) Remove a persistent instance from the datastore. The object argument may be an instance associated with the receiving Session or a transient instance with an identifier associated with existing persistent state. This operation cascades to associated instances if the association is mapped with cascade="delete". param entityName The entity name for the instance to be removed. param object the instance to be removed throws HibernateException
public void	disableFilter(java.lang.String filterName) Disable the named filter for the current session. param filterName The name of the filter to be disabled.
public java.sql.Connection	disconnect() 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 {@link org.hibernate.connection.ConnectionProvider} has no effect, provided {@link ConnectionReleaseMode#ON_CLOSE} is not in effect. return the application-supplied connection or null see #reconnect(Connection) see #reconnect()
public Filter	enableFilter(java.lang.String filterName) Enable the named filter for this current session. param filterName The name of the filter to be enabled. return The Filter instance representing the enabled fiter.
public void	evict(java.lang.Object object) Remove this instance from the session cache. Changes to the instance will not be synchronized with the database. This operation cascades to associated instances if the association is mapped with cascade="evict". param object a persistent instance throws HibernateException
public void	flush() 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 {@link #setFlushMode flush-mode}, {@link Transaction#commit()} calls this method). Flushing is the process of synchronizing the underlying persistent store with persistable state held in memory. throws HibernateException Indicates problems flushing the session or talking to the database.
public 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. (If the instance, or a proxy for the instance, is already associated with the session, return that instance or proxy.) param clazz a persistent class param id an identifier return a persistent instance or null throws HibernateException
public 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. Obtain the specified lock mode if the instance exists. param clazz a persistent class param id an identifier param lockMode the lock mode return a persistent instance or null throws HibernateException
public 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. (If the instance, or a proxy for the instance, is already associated with the session, return that instance or proxy.) param entityName the entity name param id an identifier return a persistent instance or null throws HibernateException
public 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. Obtain the specified lock mode if the instance exists. param entityName the entity name param id an identifier param lockMode the lock mode return a persistent instance or null throws HibernateException
public CacheMode	getCacheMode() Get the current cache mode. return The current cache mode.
public LockMode	getCurrentLockMode(java.lang.Object object) Determine the current lock mode of the given object. param object a persistent instance return the current lock mode throws HibernateException
public Filter	getEnabledFilter(java.lang.String filterName) Retrieve a currently enabled filter by name. param filterName The name of the filter to be retrieved. return The Filter instance representing the enabled fiter.
public EntityMode	getEntityMode() Retrieve the entity mode in effect for this session. return The entity mode for this session.
public java.lang.String	getEntityName(java.lang.Object object) Return the entity name for a persistent entity param object a persistent entity return the entity name throws HibernateException
public FlushMode	getFlushMode() Get the current flush mode for this session. return The flush mode
public java.io.Serializable	getIdentifier(java.lang.Object object) Return the identifier value of the given entity as associated with this session. An exception is thrown if the given entity instance is transient or detached in relation to this session. param object a persistent instance return the identifier throws TransientObjectException if the instance is transient or associated with a different session
public Query	getNamedQuery(java.lang.String queryName) Obtain an instance of Query for a named query string defined in the mapping file. param queryName the name of a query defined externally return Query throws HibernateException
public org.hibernate.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. param entityMode The entity mode to use for the new session. return The new session
public SessionFactory	getSessionFactory() Get the session factory which created this session. return The session factory. see SessionFactory
public org.hibernate.stat.SessionStatistics	getStatistics() Get the statistics for this session.
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. return a Transaction instance throws HibernateException see Transaction
public boolean	isConnected() Check if the session is currently connected. return boolean
public boolean	isDirty() Does this session contain any changes which must be synchronized with the database? In other words, would any DML operations be executed if we flushed this session? return True if the session contains pending changes; false otherwise. throws HibernateException could not perform dirtying checking
public boolean	isOpen() Check if the session is still open. return boolean
public 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. param theClass a persistent class param id a valid identifier of an existing persistent instance of the class param lockMode the lock level return the persistent instance or proxy throws HibernateException
public 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. param entityName a persistent class param id a valid identifier of an existing persistent instance of the class param lockMode the lock level return the persistent instance or proxy throws HibernateException
public 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. 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. param theClass a persistent class param id a valid identifier of an existing persistent instance of the class return the persistent instance or proxy throws HibernateException
public 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. 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. param entityName a persistent class param id a valid identifier of an existing persistent instance of the class return the persistent instance or proxy throws HibernateException
public void	load(java.lang.Object object, java.io.Serializable id) Read the persistent state associated with the given identifier into the given transient instance. param object an "empty" instance of the persistent class param id a valid identifier of an existing persistent instance of the class throws HibernateException
public void	lock(java.lang.Object object, LockMode lockMode) 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". param object a persistent or transient instance param lockMode the lock level throws HibernateException
public void	lock(java.lang.String entityName, java.lang.Object object, LockMode lockMode) 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". param object a persistent or transient instance param lockMode the lock level throws HibernateException
public java.lang.Object	merge(java.lang.Object object) Copy the state of the given object onto the persistent object with the same identifier. If there is no persistent instance currently associated with the session, it will be loaded. Return the persistent instance. If the given instance is unsaved, save a copy of and return it as a newly persistent instance. The given instance does not become associated with the session. This operation cascades to associated instances if the association is mapped with cascade="merge". The semantics of this method are defined by JSR-220. param object a detached instance with state to be copied return an updated persistent instance
public 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. 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. param object a detached instance with state to be copied return an updated persistent instance
public void	persist(java.lang.Object object) Make a transient instance persistent. This operation cascades to associated instances if the association is mapped with cascade="persist". The semantics of this method are defined by JSR-220. param object a transient instance to be made persistent
public void	persist(java.lang.String entityName, java.lang.Object object) Make a transient instance persistent. This operation cascades to associated instances if the association is mapped with cascade="persist". The semantics of this method are defined by JSR-220. param object a transient instance to be made persistent
public void	reconnect() Obtain a new JDBC connection. This is used by applications which require long transactions and do not supply connections to the session. see #disconnect() deprecated Manual reconnection is only needed in the case of application-supplied connections, in which case the {@link #reconnect(java.sql.Connection)} for should be used.
public void	reconnect(java.sql.Connection connection) Reconnect to the given JDBC connection. This is used by applications which require long transactions and use application-supplied connections. param connection a JDBC connection see #disconnect()
public void	refresh(java.lang.Object object) Re-read the state of the given instance from the underlying database. It is inadvisable to use this to implement long-running sessions that span many business tasks. This method is, however, useful in certain special circumstances. For example where a database trigger alters the object state upon insert or update after executing direct SQL (eg. a mass update) in the same session after inserting a Blob or Clob param object a persistent or detached instance throws HibernateException
public void	refresh(java.lang.Object object, LockMode lockMode) 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. param object a persistent or detached instance param lockMode the lock mode to use throws HibernateException
public void	replicate(java.lang.Object object, ReplicationMode replicationMode) Persist the state of the given detached instance, reusing the current identifier value. This operation cascades to associated instances if the association is mapped with cascade="replicate". param object a detached instance of a persistent class
public 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. This operation cascades to associated instances if the association is mapped with cascade="replicate". param object a detached instance of a persistent class
public java.io.Serializable	save(java.lang.Object object) Persist the given transient instance, first assigning a generated identifier. (Or using the current value of the identifier property if the assigned generator is used.) This operation cascades to associated instances if the association is mapped with cascade="save-update". param object a transient instance of a persistent class return the generated identifier throws HibernateException
public java.io.Serializable	save(java.lang.String entityName, java.lang.Object object) Persist the given transient instance, first assigning a generated identifier. (Or using the current value of the identifier property if the assigned generator is used.) This operation cascades to associated instances if the association is mapped with cascade="save-update". param object a transient instance of a persistent class return the generated identifier throws HibernateException
public void	saveOrUpdate(java.lang.Object object) Either {@link #save(Object)} or {@link #update(Object)} the given instance, depending upon resolution of the unsaved-value checks (see the manual for discussion of unsaved-value checking). This operation cascades to associated instances if the association is mapped with cascade="save-update". see Session#save(Object) see Session#update(Object) param object a transient or detached instance containing new or updated state throws HibernateException
public void	saveOrUpdate(java.lang.String entityName, java.lang.Object object) Either {@link #save(String, Object)} or {@link #update(String, Object)} the given instance, depending upon resolution of the unsaved-value checks (see the manual for discussion of unsaved-value checking). This operation cascades to associated instances if the association is mapped with cascade="save-update". see Session#save(String,Object) see Session#update(String,Object) param entityName The name of the entity param object a transient or detached instance containing new or updated state throws HibernateException
public void	setCacheMode(CacheMode cacheMode) Set the cache mode. Cache mode determines the manner in which this session can interact with the second level cache. param cacheMode The new cache mode.
public void	setFlushMode(FlushMode flushMode) Set the flush mode for this session. The flush mode determines the points at which the session is flushed. Flushing is the process of synchronizing the underlying persistent store with persistable state held in memory. For a logically "read only" session, it is reasonable to set the session's flush mode to {@link FlushMode#MANUAL} at the start of the session (in order to achieve some extra performance). param flushMode the new flush mode see FlushMode
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. see Query#setReadOnly(boolean)
public void	update(java.lang.Object object) Update the persistent instance with the identifier of the given detached instance. If there is a persistent instance with the same identifier, an exception is thrown. This operation cascades to associated instances if the association is mapped with cascade="save-update". param object a detached instance containing updated state throws HibernateException
public void	update(java.lang.String entityName, java.lang.Object object) Update the persistent instance with the identifier of the given detached instance. If there is a persistent instance with the same identifier, an exception is thrown. This operation cascades to associated instances if the association is mapped with cascade="save-update". param object a detached instance containing updated state throws HibernateException