//$Id: SessionImplementor.java,v 1.8 2002/12/07 09:05:41 oneovthafew Exp $
package cirrus.hibernate.engine;

import java.sql.SQLException;
import java.util.Iterator;
import java.util.List;
import java.util.Map;
import java.io.Serializable;

import cirrus.hibernate.persister.ClassPersister;
import cirrus.hibernate.type.Type;
import cirrus.hibernate.HibernateException;
import cirrus.hibernate.LockMode;
import cirrus.hibernate.MappingException;
import cirrus.hibernate.ScrollableResults;
import cirrus.hibernate.Session;
import cirrus.hibernate.collections.PersistentCollection;
import cirrus.hibernate.collections.ArrayHolder;
import cirrus.hibernate.impl.CollectionPersister;
import cirrus.hibernate.impl.QueryImpl;

/** 
 * Defines the internal contract between the <tt>Session</tt> and other parts of
 * Hibernate such as implementors of <tt>Type</tt> or <tt>ClassPersister</tt>.
 * @see cirrus.hibernate.Session
 * @see cirrus.hibernate.impl.SessionImpl
 */
public interface SessionImplementor extends Session {
		
	/**
	 * Get the post-flush identifier of the collection (during a flush)
	 */
	public Serializable getCurrentID(PersistentCollection collection);
	/**
	 * Get the pre-flush identifier of the collection
	 */
	public Serializable getLoadedID(PersistentCollection collection);
	/**
	 * Get the snapshot of the pre-flush collection state
	 */
	public Serializable getSnapshot(PersistentCollection collection);
	
	/**
	 * Get the <tt>PersistentCollection</tt> object for an array
	 */
	public ArrayHolder getArrayHolder(Object array);	
	/**
	 * Register a <tt>PersistentCollection</tt> object for an array
	 */
	public void addArrayHolder(ArrayHolder holder);
	/**
	 * Register an uninitialized <tt>PersistentCollection</tt> that will be lazily initializable
	 */
	public void addUninitializedCollection(PersistentCollection collection, CollectionPersister persister, Serializable id);
	/**
	 * Register an initialized <tt>PersistentCollection</tt>
	 */
	public void addInitializedCollection(PersistentCollection collection, CollectionPersister persister, Serializable id) throws HibernateException;
	/**
	 * Set the "shallow dirty" status of the collection. Called when the collection detects that the 
	 * client is modifying it
	 */
	public void dirty(PersistentCollection collection);
	/**
	 * Initialize the collection (if not already initialized)
	 */
	public void initialize(PersistentCollection collection, boolean writing) throws HibernateException, SQLException;
	/**
	 * Is this the readonly end of a bidirectional association?
	 */
	public boolean isCollectionReadOnly(PersistentCollection collection);
	
	/**
	 * Load an instance without checking if it was deleted. If it does not exist, throw an exception.
	 * This method may create a new proxy or return an existing proxy.
	 */
	public Object internalLoad(Class persistentClass, Serializable id) throws SQLException, HibernateException;
	/**
	 * Load an instance without checking if it was deleted. If it does not exist, return <tt>null</tt>.
	 * Do not create a proxy (but do return any existing proxy).
	 */
	public Object internalLoadOneToOne(Class persistentClass, Serializable id) throws SQLException, HibernateException;
	/**
	 * Load an instance immediately. Do not return a proxy.
	 */
	public Object immediateLoad(Class persistentClass, Serializable id) throws SQLException, HibernateException;
		
	/**
	 * System time before the start of the transaction
	 */
	public long getTimestamp();
	/**
	 * Get the creating <tt>SessionFactoryImplementor</tt>
	 */
	public SessionFactoryImplementor getFactory();
	/**
	 * Get the prepared statement <tt>Batcher</tt> for this session
	 */
	public Batcher getBatcher();
	
	/**
	 * After actually inserting a row, record the fact that the instance exists on the database
	 * (needed for identity-column key generation)
	 */
	public void postInsert(Object object);
	/**
	 * After actually deleting a row, record the fact that the instance no longer exists on the 
	 * database (needed for identity-column key generation)
	 */
	public void postDelete(Object object);
		
	/**
	 * Execute a <tt>find()</tt> query
	 */
	public List find(String query, Object[] values, Type[] types, QueryImpl.RowSelection selection, Map namedParams) throws SQLException, HibernateException;	
	/**
	 * Execute an <tt>iterate()</tt> query
	 */
	public Iterator iterate(String query, Object[] values, Type[] types, QueryImpl.RowSelection selection, Map namedParams) throws SQLException, HibernateException;
	/**
	 * Execute a <tt>scroll()</tt> query
	 */
	public ScrollableResults scroll(String query, Object[] values, Type[] types, QueryImpl.RowSelection selection, Map namedParams) throws SQLException, HibernateException;
	
	/**
	 * Execute a filter
	 */
	public List filter(Object collection, String filter, Object[] values, Type[] types, QueryImpl.RowSelection selection, Map namedParams) throws SQLException, HibernateException;
	/**
	 * Iterate a filter
	 */
	public Iterator iterateFilter(Object collection, String filter, Object[] values, Type[] types, QueryImpl.RowSelection selection, Map namedParams) throws SQLException, HibernateException;
	/**
	 * Get the <tt>ClassPersister</tt> for an object
	 */
	public ClassPersister getPersister(Object object) throws MappingException;

	/**
	 * Add an uninitialized instance of an entity class, as a placeholder to ensure object identity.
	 * Must be called before <tt>postHydrate()</tt>.
	 */
	public void addUninitializedEntity(Key key, Object object, LockMode lockMode);
	/**
	 * Register the "hydrated" state of an entity instance, after the first step of 2-phase loading
	 */
	public void postHydrate(ClassPersister persister, Serializable id, Object[] values, Object object, LockMode lockMode) throws HibernateException;
	/**
	 * Perform the second step of 2-phase load (ie. fully initialize the entity instance)
	 */
	public void initializeEntity(Object object) throws HibernateException, SQLException;
	
	/**
	 * Get the entity instance associated with the given <tt>Key</tt>
	 */
	public Object getEntity(Key key);
	/**
	 * Return the existing proxy associated with the given <tt>Key</tt>, or the 
	 * second argument (the entity associated with the key) if no proxy exists.
	 */
	public Object proxyFor(ClassPersister persister, Key key, Object impl) throws HibernateException;
	
	/**
	 * Notify the session that the transaction completed, so we no longer 
	 * own the old locks. (Also we should release cache softlocks.)
	 */
	public void afterTransactionCompletion();
	
	/**
	 * Return the identifier of the persistent object, or null if transient
	 */
	public Serializable getID(Object obj);
	
}