[hibernate-commits] Hibernate SVN: r10914 - branches/Branch_3_2/Hibernate3/src/org/hibernate
hibernate-commits at lists.jboss.org
hibernate-commits at lists.jboss.org
Mon Dec 4 15:34:47 EST 2006
Author: steve.ebersole at jboss.com
Date: 2006-12-04 15:34:46 -0500 (Mon, 04 Dec 2006)
New Revision: 10914
Modified:
branches/Branch_3_2/Hibernate3/src/org/hibernate/Session.java
Log:
javadocs
Modified: branches/Branch_3_2/Hibernate3/src/org/hibernate/Session.java
===================================================================
--- branches/Branch_3_2/Hibernate3/src/org/hibernate/Session.java 2006-12-04 20:32:20 UTC (rev 10913)
+++ branches/Branch_3_2/Hibernate3/src/org/hibernate/Session.java 2006-12-04 20:34:46 UTC (rev 10914)
@@ -24,12 +24,12 @@
* <tt>persist()</tt> or <tt>saveOrUpdate()</tt>. Persistent instances may be made transient
* by calling<tt> delete()</tt>. Any instance returned by a <tt>get()</tt> or
* <tt>load()</tt> method is persistent. Detached instances may be made persistent
- * by calling <tt>update()</tt>, <tt>saveOrUpdate()</tt>, <tt>lock()</tt> or <tt>replicate()</tt>.
+ * by calling <tt>update()</tt>, <tt>saveOrUpdate()</tt>, <tt>lock()</tt> or <tt>replicate()</tt>.
* The state of a transient or detached instance may also be made persistent as a new
* persistent instance by calling <tt>merge()</tt>.<br>
* <br>
* <tt>save()</tt> and <tt>persist()</tt> result in an SQL <tt>INSERT</tt>, <tt>delete()</tt>
- * in an SQL <tt>DELETE</tt> and <tt>update()</tt> or <tt>merge()</tt> in an SQL <tt>UPDATE</tt>.
+ * in an SQL <tt>DELETE</tt> and <tt>update()</tt> or <tt>merge()</tt> in an SQL <tt>UPDATE</tt>.
* Changes to <i>persistent</i> instances are detected at flush time and also result in an SQL
* <tt>UPDATE</tt>. <tt>saveOrUpdate()</tt> and <tt>replicate()</tt> result in either an
* <tt>INSERT</tt> or an <tt>UPDATE</tt>.<br>
@@ -79,59 +79,78 @@
* 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 Session getSession(EntityMode entityMode);
/**
- * Force the <tt>Session</tt> to flush. Must be called at the end of a
+ * Force this session to flush. Must be called at the end of a
* unit of work, before commiting the transaction and closing the
- * session (<tt>Transaction.commit()</tt> calls this method). <i>Flushing</i>
- * is the process of synchronising the underlying persistent store with
- * persistable state held in memory.
+ * session (depending on {@link #setFlushMode flush-mode},
+ * {@link Transaction#commit()} calls this method).
+ * <p/>
+ * <i>Flushing</i> is the process of synchronizing the underlying persistent
+ * store with persistable state held in memory.
*
- * @throws HibernateException
+ * @throws HibernateException Indicates problems flushing the session or
+ * talking to the database.
*/
public void flush() throws HibernateException;
/**
- * 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
- * <tt>FlushMode.NEVER</tt> at the start of the session (in
+ * Set the flush mode for this session.
+ * <p/>
+ * The flush mode determines the points at which the session is flushed.
+ * <i>Flushing</i> is the process of synchronizing the underlying persistent
+ * store with persistable state held in memory.
+ * <p/>
+ * 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
- * @param flushMode the FlushMode
*/
public void setFlushMode(FlushMode flushMode);
+
/**
- * Get the current flush mode.
+ * Get the current flush mode for this session.
*
- * @return FlushMode
+ * @return The flush mode
*/
public FlushMode getFlushMode();
-
+
/**
* Set the cache mode.
+ * <p/>
+ * Cache mode determines the manner in which this session can interact with
+ * the second level cache.
+ *
+ * @param cacheMode The new cache mode.
*/
public void setCacheMode(CacheMode cacheMode);
+
/**
* Get the current cache mode.
+ *
+ * @return The current cache mode.
*/
public CacheMode getCacheMode();
/**
- * Get the <tt>SessionFactory</tt> that created this instance.
+ * Get the session factory which created this session.
+ *
+ * @return The session factory.
* @see SessionFactory
+
*/
public SessionFactory getSessionFactory();
/**
* Get the JDBC connection of this Session.<br>
- * <br>
+ * <br>
* 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
@@ -143,49 +162,53 @@
public Connection connection() throws HibernateException;
/**
- * End the <tt>Session</tt> by disconnecting from the JDBC connection and
- * cleaning up. It is not strictly necessary to <tt>close()</tt> the
- * <tt>Session</tt> but you must at least <tt>disconnect()</tt> it.
+ * 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 <tt>null</tt>
- * @throws HibernateException
+ * @return the connection provided by the application or null.
+ * @throws HibernateException Indicates problems cleaning up.
*/
public Connection close() 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!
+ * Cancel the execution of the current query.
+ * <p/>
+ * 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 cancelQuery() throws HibernateException;
/**
- * Check if the <tt>Session</tt> is still open.
+ * Check if the session is still open.
*
* @return boolean
*/
public boolean isOpen();
/**
- * Check if the <tt>Session</tt> is currently connected.
+ * Check if the session is currently connected.
*
* @return boolean
*/
public boolean isConnected();
-
+
/**
- * Does this <tt>Session</tt> contain any changes which must be
- * synchronized with the database? Would any SQL be executed if
+ * 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 boolean
+ * @return True if the session contains pending changes; false otherwise.
+ * @throws HibernateException could not perform dirtying checking
*/
public boolean isDirty() throws HibernateException;
/**
- * Return the identifier of an entity instance cached by the <tt>Session</tt>, or
- * throw an exception if the instance is transient or associated with a different
- * <tt>Session</tt>.
+ * 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
@@ -193,6 +216,7 @@
* a different session
*/
public Serializable getIdentifier(Object object) throws HibernateException;
+
/**
* Check if this instance is associated with this <tt>Session</tt>.
*
@@ -200,6 +224,7 @@
* @return true if the given instance is associated with this <tt>Session</tt>
*/
public boolean contains(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
@@ -236,8 +261,7 @@
/**
* 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.
+ * assuming that the instance exists.
* <br><br>
* You should not use this method to determine if an instance exists (use <tt>get()</tt>
* instead). Use this only to retrieve an instance that you assume exists, where non-existence
@@ -252,8 +276,7 @@
/**
* 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.
+ * assuming that the instance exists.
* <br><br>
* You should not use this method to determine if an instance exists (use <tt>get()</tt>
* instead). Use this only to retrieve an instance that you assume exists, where non-existence
@@ -277,8 +300,8 @@
public void load(Object object, Serializable id) throws HibernateException;
/**
- * Persist the state of the given detached instance, reusing the current
- * identifier value. This operation cascades to associated instances if
+ * 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 <tt>cascade="replicate"</tt>.
*
* @param object a detached instance of a persistent class
@@ -286,8 +309,8 @@
public void replicate(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
+ * 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 <tt>cascade="replicate"</tt>.
*
* @param object a detached instance of a persistent class
@@ -297,7 +320,7 @@
/**
* Persist the given transient instance, first assigning a generated identifier. (Or
* using the current value of the identifier property if the <tt>assigned</tt>
- * generator is used.) This operation cascades to associated instances if the
+ * generator is used.) This operation cascades to associated instances if the
* association is mapped with <tt>cascade="save-update"</tt>.
*
* @param object a transient instance of a persistent class
@@ -309,7 +332,7 @@
/**
* Persist the given transient instance, first assigning a generated identifier. (Or
* using the current value of the identifier property if the <tt>assigned</tt>
- * generator is used.) This operation cascades to associated instances if the
+ * generator is used.) This operation cascades to associated instances if the
* association is mapped with <tt>cascade="save-update"</tt>.
*
* @param object a transient instance of a persistent class
@@ -319,28 +342,31 @@
public Serializable save(String entityName, Object object) throws HibernateException;
/**
- * Either <tt>save()</tt> or <tt>update()</tt> 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 <tt>unsaved-value</tt> attribute of the identifier property
- * mapping. This operation cascades to associated instances if the association is mapped
+ * 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).
+ * <p/>
+ * This operation cascades to associated instances if the association is mapped
* with <tt>cascade="save-update"</tt>.
*
* @see Session#save(java.lang.Object)
- * @see Session#update(Object object)
+ * @see org.hibernate.classic.Session#update(Object object, Serializable id)
* @param object a transient or detached instance containing new or updated state
* @throws HibernateException
*/
public void saveOrUpdate(Object object) throws HibernateException;
/**
- * Either <tt>save()</tt> or <tt>update()</tt> 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 <tt>unsaved-value</tt> attribute of the identifier property
- * mapping. This operation cascades to associated instances if the association is mapped
+ * 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).
+ * <p/>
+ * This operation cascades to associated instances if the association is mapped
* with <tt>cascade="save-update"</tt>.
*
* @see Session#save(java.lang.Object)
- * @see Session#update(Object object)
+ * @see org.hibernate.classic.Session#update(Object object, Serializable id)
+ * @param entityName The name of the entity
* @param object a transient or detached instance containing new or updated state
* @throws HibernateException
*/
@@ -349,7 +375,7 @@
/**
* 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
+ * an exception is thrown. This operation cascades to associated instances
* if the association is mapped with <tt>cascade="save-update"</tt>.
*
* @param object a detached instance containing updated state
@@ -360,7 +386,7 @@
/**
* 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
+ * an exception is thrown. This operation cascades to associated instances
* if the association is mapped with <tt>cascade="save-update"</tt>.
*
* @param object a detached instance containing updated state
@@ -372,9 +398,9 @@
* 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
+ * 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 <tt>cascade="merge"</tt>.<br>
* <br>
* The semantics of this method are defined by JSR-220.
@@ -383,14 +409,14 @@
* @return an updated persistent instance
*/
public Object merge(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
+ * 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 <tt>cascade="merge"</tt>.<br>
* <br>
* The semantics of this method are defined by JSR-220.
@@ -399,22 +425,22 @@
* @return an updated persistent instance
*/
public Object merge(String entityName, Object object) throws HibernateException;
-
+
/**
- * Make a transient instance persistent. This operation cascades to associated
+ * Make a transient instance persistent. This operation cascades to associated
* instances if the association is mapped with <tt>cascade="persist"</tt>.<br>
* <br>
* The semantics of this method are defined by JSR-220.
- *
+ *
* @param object a transient instance to be made persistent
*/
public void persist(Object object) throws HibernateException;
/**
- * Make a transient instance persistent. This operation cascades to associated
+ * Make a transient instance persistent. This operation cascades to associated
* instances if the association is mapped with <tt>cascade="persist"</tt>.<br>
* <br>
* The semantics of this method are defined by JSR-220.
- *
+ *
* @param object a transient instance to be made persistent
*/
public void persist(String entityName, Object object) throws HibernateException;
@@ -422,8 +448,8 @@
/**
* Remove a persistent instance from the datastore. The argument may be
* an instance associated with the receiving <tt>Session</tt> or a transient
- * instance with an identifier associated with existing persistent state.
- * This operation cascades to associated instances if the association is mapped
+ * instance with an identifier associated with existing persistent state.
+ * This operation cascades to associated instances if the association is mapped
* with <tt>cascade="delete"</tt>.
*
* @param object the instance to be removed
@@ -448,7 +474,7 @@
* Obtain the specified lock level upon the given object. This may be used to
* perform a version check (<tt>LockMode.READ</tt>), to upgrade to a pessimistic
* lock (<tt>LockMode.UPGRADE</tt>), or to simply reassociate a transient instance
- * with a session (<tt>LockMode.NONE</tt>). This operation cascades to associated
+ * with a session (<tt>LockMode.NONE</tt>). This operation cascades to associated
* instances if the association is mapped with <tt>cascade="lock"</tt>.
*
* @param object a persistent or transient instance
@@ -461,7 +487,7 @@
* Obtain the specified lock level upon the given object. This may be used to
* perform a version check (<tt>LockMode.READ</tt>), to upgrade to a pessimistic
* lock (<tt>LockMode.UPGRADE</tt>), or to simply reassociate a transient instance
- * with a session (<tt>LockMode.NONE</tt>). This operation cascades to associated
+ * with a session (<tt>LockMode.NONE</tt>). This operation cascades to associated
* instances if the association is mapped with <tt>cascade="lock"</tt>.
*
* @param object a persistent or transient instance
@@ -519,7 +545,7 @@
* @see Transaction
*/
public Transaction beginTransaction() throws HibernateException;
-
+
/**
* Get the <tt>Transaction</tt> instance associated with this session.
* The class of the returned <tt>Transaction</tt> object is determined by the
@@ -539,7 +565,7 @@
* @return Criteria
*/
public Criteria createCriteria(Class persistentClass);
-
+
/**
* Create a new <tt>Criteria</tt> instance, for the given entity class,
* or a superclass of an entity class, with the given alias.
@@ -548,7 +574,7 @@
* @return Criteria
*/
public Criteria createCriteria(Class persistentClass, String alias);
-
+
/**
* Create a new <tt>Criteria</tt> instance, for the given entity name.
*
@@ -613,8 +639,8 @@
/**
* 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.)
+ * 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
@@ -625,9 +651,8 @@
/**
* 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.
+ * 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
@@ -639,8 +664,8 @@
/**
* 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.)
+ * 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
@@ -651,9 +676,8 @@
/**
* 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.
+ * 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
@@ -663,10 +687,10 @@
*/
public Object get(String entityName, Serializable id, LockMode lockMode) throws HibernateException;
-
+
/**
* Return the entity name for a persistent entity
- *
+ *
* @param object a persistent entity
* @return the entity name
* @throws HibernateException
@@ -695,17 +719,17 @@
* @param filterName The name of the filter to be disabled.
*/
public void disableFilter(String filterName);
-
+
/**
* Get the statistics for this session.
*/
public SessionStatistics getStatistics();
-
+
/**
* 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 setReadOnly(Object entity, boolean readOnly);
More information about the hibernate-commits
mailing list