/*
 * Hibernate, Relational Persistence for Idiomatic Java
 *
 * License: GNU Lesser General Public License (LGPL), version 2.1 or later.
 * See the lgpl.txt file in the root directory or <http://www.gnu.org/licenses/lgpl-2.1.html>.
 */
package org.hibernate.engine.spi;

import java.io.Serializable;
import java.sql.Connection;
import java.util.Iterator;
import java.util.List;
import java.util.UUID;
import javax.persistence.FlushModeType;

import org.hibernate.CacheMode;
import org.hibernate.Criteria;
import org.hibernate.FlushMode;
import org.hibernate.HibernateException;
import org.hibernate.Interceptor;
import org.hibernate.ScrollMode;
import org.hibernate.SharedSessionContract;
import org.hibernate.Transaction;
import org.hibernate.cache.spi.CacheTransactionSynchronization;
import org.hibernate.cfg.Environment;
import org.hibernate.collection.spi.PersistentCollection;
import org.hibernate.engine.jdbc.LobCreationContext;
import org.hibernate.engine.jdbc.spi.JdbcCoordinator;
import org.hibernate.engine.jdbc.spi.JdbcServices;
import org.hibernate.engine.query.spi.sql.NativeSQLQuerySpecification;
import org.hibernate.internal.util.config.ConfigurationHelper;
import org.hibernate.loader.custom.CustomQuery;
import org.hibernate.persister.entity.EntityPersister;
import org.hibernate.query.spi.QueryProducerImplementor;
import org.hibernate.query.spi.ScrollableResultsImplementor;
import org.hibernate.resource.jdbc.spi.JdbcSessionOwner;
import org.hibernate.resource.transaction.spi.TransactionCoordinator;
import org.hibernate.resource.transaction.spi.TransactionCoordinatorBuilder.Options;
import org.hibernate.type.descriptor.WrapperOptions;

Defines the internal contract shared between Session and StatelessSession as used by other parts of Hibernate (such as Type, EntityPersister and CollectionPersister implementors A Session, through this interface and SharedSessionContractImplementor, implements:

    
 JdbcSessionOwner to drive the behavior of a "JDBC session". Can therefor be used to construct a JdbcCoordinator, which (for now) models a "JDBC session" 
    
 Options to drive the creation of the TransactionCoordinator delegate. This allows it to be passed along to TransactionCoordinatorBuilder.buildTransactionCoordinator 
    
 LobCreationContext to act as the context for JDBC LOB instance creation 
    
 WrapperOptions to fulfill the behavior needed while binding/extracting values to/from JDBC as part of the Type contracts 

Author:
Gavin King, Steve Ebersole/**
 * Defines the internal contract shared between {@link org.hibernate.Session} and
 * {@link org.hibernate.StatelessSession} as used by other parts of Hibernate (such as
 * {@link org.hibernate.type.Type}, {@link EntityPersister} and
 * {@link org.hibernate.persister.collection.CollectionPersister} implementors
 *
 * A Session, through this interface and SharedSessionContractImplementor, implements:<ul>
 *     <li>
 *         {@link org.hibernate.resource.jdbc.spi.JdbcSessionOwner} to drive the behavior of a "JDBC session".
 *         Can therefor be used to construct a JdbcCoordinator, which (for now) models a "JDBC session"
 *     </li>
 *     <li>
 *         {@link Options}
 *         to drive the creation of the {@link TransactionCoordinator} delegate.
 *         This allows it to be passed along to
 *         {@link org.hibernate.resource.transaction.spi.TransactionCoordinatorBuilder#buildTransactionCoordinator}
 *     </li>
 *     <li>
 *         {@link org.hibernate.engine.jdbc.LobCreationContext} to act as the context for JDBC LOB instance creation
 *     </li>
 *     <li>
 *         {@link org.hibernate.type.descriptor.WrapperOptions} to fulfill the behavior needed while
 *         binding/extracting values to/from JDBC as part of the Type contracts
 *     </li>
 * </ul>
 *
 * @author Gavin King
 * @author Steve Ebersole
 */
public interface SharedSessionContractImplementor
		extends SharedSessionContract, JdbcSessionOwner, Options, LobCreationContext, WrapperOptions, QueryProducerImplementor {

	// todo : this is the shared contract between Session and StatelessSession, but it defines methods that StatelessSession does not implement
	//	(it just throws UnsupportedOperationException).  To me it seems like it is better to properly isolate those methods
	//	into just the Session hierarchy.  They include (at least):
	//		1) get/set CacheMode
	//		2) get/set FlushMode
	//		3) get/set (default) read-only
	//		4) #setAutoClear
	//		5) #disableTransactionAutoJoin

	
Get the creating SessionFactoryImplementor
/**
	 * Get the creating <tt>SessionFactoryImplementor</tt>
	 */
	SessionFactoryImplementor getFactory();

	SessionEventListenerManager getEventListenerManager();

	
Get the persistence context for this session
/**
	 * Get the persistence context for this session
	 */
	PersistenceContext getPersistenceContext();

	JdbcCoordinator getJdbcCoordinator();

	JdbcServices getJdbcServices();

	
The multi-tenancy tenant identifier, if one.
Returns:
The tenant identifier; may be null/**
	 * The multi-tenancy tenant identifier, if one.
	 *
	 * @return The tenant identifier; may be {@code null}
	 */
	String getTenantIdentifier();

	
A UUID associated with each Session.  Useful mainly for logging.
Returns:
The UUID/**
	 * A UUID associated with each Session.  Useful mainly for logging.
	 *
	 * @return The UUID
	 */
	UUID getSessionIdentifier();

	
Checks whether the session is closed. Provided separately from SharedSessionContract.isOpen() as this method does not attempt any JTA synchronization registration, where as SharedSessionContract.isOpen() does; which makes this one nicer to use for most internal purposes. 
Returns:
true if the session is closed; false otherwise./**
	 * Checks whether the session is closed.  Provided separately from
	 * {@link #isOpen()} as this method does not attempt any JTA synchronization
	 * registration, where as {@link #isOpen()} does; which makes this one
	 * nicer to use for most internal purposes.
	 *
	 * @return {@code true} if the session is closed; {@code false} otherwise.
	 */
	boolean isClosed();

	
Checks whether the session is open or is waiting for auto-close
Returns:
true if the session is closed or if it's waiting for auto-close; false otherwise./**
	 * Checks whether the session is open or is waiting for auto-close
	 *
	 * @return {@code true} if the session is closed or if it's waiting for auto-close; {@code false} otherwise.
	 */
	default boolean isOpenOrWaitingForAutoClose() {
		return !isClosed();
	}

	
Performs a check whether the Session is open, and if not:

    
marks current transaction (if one) for rollback only
    
throws an IllegalStateException (JPA defines the exception type)

/**
	 * Performs a check whether the Session is open, and if not:<ul>
	 *     <li>marks current transaction (if one) for rollback only</li>
	 *     <li>throws an IllegalStateException (JPA defines the exception type)</li>
	 * </ul>
	 */
	default void checkOpen() {
		checkOpen( true );
	}

	
Performs a check whether the Session is open, and if not:

    
if markForRollbackIfClosed is true, marks current transaction (if one) for rollback only
    
throws an IllegalStateException (JPA defines the exception type)

/**
	 * Performs a check whether the Session is open, and if not:<ul>
	 *     <li>if {@code markForRollbackIfClosed} is true, marks current transaction (if one) for rollback only</li>
	 *     <li>throws an IllegalStateException (JPA defines the exception type)</li>
	 * </ul>
	 */
	void checkOpen(boolean markForRollbackIfClosed);

	
Marks current transaction (if one) for rollback only
/**
	 * Marks current transaction (if one) for rollback only
	 */
	void markForRollbackOnly();

	
A "timestamp" at or before the start of the current transaction.
API Note:
This "timestamp" need not be related to timestamp in the Java Date/millisecond sense. It just needs to be an incrementing value. See CacheTransactionSynchronization.getCurrentTransactionStartTimestamp()/**
	 * A "timestamp" at or before the start of the current transaction.
	 *
	 * @apiNote This "timestamp" need not be related to timestamp in the Java Date/millisecond
	 * sense.  It just needs to be an incrementing value.  See
	 * {@link CacheTransactionSynchronization#getCurrentTransactionStartTimestamp()}
	 */
	long getTransactionStartTimestamp();

	
Deprecated:
(since 5.3) Use/**
	 * @deprecated (since 5.3) Use
	 */
	@Deprecated
	default long getTimestamp() {
		return getTransactionStartTimestamp();
	}

	
The current CacheTransactionContext associated with the Session. This may return null when the Session is not currently part of a transaction. /**
	 * The current CacheTransactionContext associated with the Session.  This may
	 * return {@code null} when the Session is not currently part of a transaction.
	 */
	CacheTransactionSynchronization getCacheTransactionSynchronization();

	
Does this Session have an active Hibernate transaction
or is there a JTA transaction in progress?
/**
	 * Does this <tt>Session</tt> have an active Hibernate transaction
	 * or is there a JTA transaction in progress?
	 */
	boolean isTransactionInProgress();

	
Provides access to the underlying transaction or creates a new transaction if
one does not already exist or is active.  This is primarily for internal or
integrator use.
Returns:
the transaction/**
	 * Provides access to the underlying transaction or creates a new transaction if
	 * one does not already exist or is active.  This is primarily for internal or
	 * integrator use.
	 *
	 * @return the transaction
     */
	Transaction accessTransaction();

	
Hide the changing requirements of entity key creation
Params:
id – The entity id
persister – The entity persister
Returns:
The entity key/**
	 * Hide the changing requirements of entity key creation
	 *
	 * @param id The entity id
	 * @param persister The entity persister
	 *
	 * @return The entity key
	 */
	EntityKey generateEntityKey(Serializable id, EntityPersister persister);

	
Retrieves the interceptor currently in use by this event source.
Returns:
The interceptor./**
	 * Retrieves the interceptor currently in use by this event source.
	 *
	 * @return The interceptor.
	 */
	Interceptor getInterceptor();

	
Enable/disable automatic cache clearing from after transaction
completion (for EJB3)
/**
	 * Enable/disable automatic cache clearing from after transaction
	 * completion (for EJB3)
	 */
	void setAutoClear(boolean enabled);

	
Initialize the collection (if not already initialized)
/**
	 * Initialize the collection (if not already initialized)
	 */
	void initializeCollection(PersistentCollection collection, boolean writing)
			throws HibernateException;

	
Load an instance without checking if it was deleted.

When nullable is disabled this method may create a new proxy or
return an existing proxy; if it does not exist, throw an exception.

When nullable is enabled, the method does not create new proxies
(but might return an existing proxy); if it does not exist, return
null.

When eager is enabled, the object is eagerly fetched
/**
	 * Load an instance without checking if it was deleted.
	 * <p/>
	 * When <tt>nullable</tt> is disabled this method may create a new proxy or
	 * return an existing proxy; if it does not exist, throw an exception.
	 * <p/>
	 * When <tt>nullable</tt> is enabled, the method does not create new proxies
	 * (but might return an existing proxy); if it does not exist, return
	 * <tt>null</tt>.
	 * <p/>
	 * When <tt>eager</tt> is enabled, the object is eagerly fetched
	 */
	Object internalLoad(String entityName, Serializable id, boolean eager, boolean nullable)
			throws HibernateException;

	
Load an instance immediately. This method is only called when lazily initializing a proxy.
Do not return the proxy.
/**
	 * Load an instance immediately. This method is only called when lazily initializing a proxy.
	 * Do not return the proxy.
	 */
	Object immediateLoad(String entityName, Serializable id) throws HibernateException;

	
Execute a find() query
/**
	 * Execute a <tt>find()</tt> query
	 */
	List list(String query, QueryParameters queryParameters) throws HibernateException;

	
Execute an iterate() query
/**
	 * Execute an <tt>iterate()</tt> query
	 */
	Iterator iterate(String query, QueryParameters queryParameters) throws HibernateException;

	
Execute a scroll() query
/**
	 * Execute a <tt>scroll()</tt> query
	 */
	ScrollableResultsImplementor scroll(String query, QueryParameters queryParameters) throws HibernateException;

	
Execute a criteria query
/**
	 * Execute a criteria query
	 */
	ScrollableResultsImplementor scroll(Criteria criteria, ScrollMode scrollMode);

	
Execute a criteria query
/**
	 * Execute a criteria query
	 */
	List list(Criteria criteria);

	
Execute a filter
/**
	 * Execute a filter
	 */
	List listFilter(Object collection, String filter, QueryParameters queryParameters) throws HibernateException;

	
Iterate a filter
/**
	 * Iterate a filter
	 */
	Iterator iterateFilter(Object collection, String filter, QueryParameters queryParameters)
			throws HibernateException;

	
Get the EntityPersister for any instance
Params:
entityName – optional entity name
object – the entity instance/**
	 * Get the <tt>EntityPersister</tt> for any instance
	 *
	 * @param entityName optional entity name
	 * @param object the entity instance
	 */
	EntityPersister getEntityPersister(String entityName, Object object) throws HibernateException;

	
Get the entity instance associated with the given Key,
calling the Interceptor if necessary
/**
	 * Get the entity instance associated with the given <tt>Key</tt>,
	 * calling the Interceptor if necessary
	 */
	Object getEntityUsingInterceptor(EntityKey key) throws HibernateException;

	
Return the identifier of the persistent object, or null if
not associated with the session
/**
	 * Return the identifier of the persistent object, or null if
	 * not associated with the session
	 */
	Serializable getContextEntityIdentifier(Object object);

	
The best guess entity name for an entity not in an association
/**
	 * The best guess entity name for an entity not in an association
	 */
	String bestGuessEntityName(Object object);

	
The guessed entity name for an entity not in an association
/**
	 * The guessed entity name for an entity not in an association
	 */
	String guessEntityName(Object entity) throws HibernateException;

	
Instantiate the entity class, initializing with the given identifier
/**
	 * Instantiate the entity class, initializing with the given identifier
	 */
	Object instantiate(String entityName, Serializable id) throws HibernateException;

	
Execute an SQL Query
/**
	 * Execute an SQL Query
	 */
	List listCustomQuery(CustomQuery customQuery, QueryParameters queryParameters)
			throws HibernateException;

	
Execute an SQL Query
/**
	 * Execute an SQL Query
	 */
	ScrollableResultsImplementor scrollCustomQuery(CustomQuery customQuery, QueryParameters queryParameters)
			throws HibernateException;

	
Execute a native SQL query, and return the results as a fully built list.
Params:
spec – The specification of the native SQL query to execute.
queryParameters – The parameters by which to perform the execution.
Throws:
HibernateException – 
Returns:
The result list./**
	 * Execute a native SQL query, and return the results as a fully built list.
	 *
	 * @param spec The specification of the native SQL query to execute.
	 * @param queryParameters The parameters by which to perform the execution.
	 *
	 * @return The result list.
	 *
	 * @throws HibernateException
	 */
	List list(NativeSQLQuerySpecification spec, QueryParameters queryParameters)
			throws HibernateException;

	
Execute a native SQL query, and return the results as a scrollable result.
Params:
spec – The specification of the native SQL query to execute.
queryParameters – The parameters by which to perform the execution.
Throws:
HibernateException – 
Returns:
The resulting scrollable result./**
	 * Execute a native SQL query, and return the results as a scrollable result.
	 *
	 * @param spec The specification of the native SQL query to execute.
	 * @param queryParameters The parameters by which to perform the execution.
	 *
	 * @return The resulting scrollable result.
	 *
	 * @throws HibernateException
	 */
	ScrollableResultsImplementor scroll(NativeSQLQuerySpecification spec, QueryParameters queryParameters);

	int getDontFlushFromFind();

	
Execute a HQL update or delete query
/**
	 * Execute a HQL update or delete query
	 */
	int executeUpdate(String query, QueryParameters queryParameters) throws HibernateException;

	
Execute a native SQL update or delete query
/**
	 * Execute a native SQL update or delete query
	 */
	int executeNativeUpdate(NativeSQLQuerySpecification specification, QueryParameters queryParameters)
			throws HibernateException;


	CacheMode getCacheMode();

	void setCacheMode(CacheMode cm);

	
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). 
Params:
flushMode – the new flush mode
Deprecated:
(since 5.2) use setHibernateFlushMode(FlushMode) instead/**
	 * 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
	 *
	 * @deprecated (since 5.2) use {@link #setHibernateFlushMode(FlushMode)} instead
	 */
	@Deprecated
	void setFlushMode(FlushMode flushMode);

	
Get the flush mode for this session.
 For users of the Hibernate native APIs, we've had to rename this method as defined by Hibernate historically because the JPA contract defines a method of the same name, but returning the JPA FlushModeType rather than Hibernate's FlushMode. For the former behavior, use getHibernateFlushMode() instead. 
Returns:
The FlushModeType in effect for this Session./**
	 * Get the flush mode for this session.
	 * <p/>
	 * For users of the Hibernate native APIs, we've had to rename this method
	 * as defined by Hibernate historically because the JPA contract defines a method of the same
	 * name, but returning the JPA {@link FlushModeType} rather than Hibernate's {@link FlushMode}.  For
	 * the former behavior, use {@link #getHibernateFlushMode()} instead.
	 *
	 * @return The FlushModeType in effect for this Session.
	 */
	FlushModeType getFlushMode();

	
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). 
Params:
flushMode – the new flush mode/**
	 * 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
	 */
	void setHibernateFlushMode(FlushMode flushMode);

	
Get the current flush mode for this session.
Returns:
The flush mode/**
	 * Get the current flush mode for this session.
	 *
	 * @return The flush mode
	 */
	FlushMode getHibernateFlushMode();

	Connection connection();

	void flush();

	boolean isEventSource();

	void afterScrollOperation();

	boolean shouldAutoClose();

	boolean isAutoCloseSessionEnabled();

	default boolean isQueryParametersValidationEnabled(){
		return getFactory().getSessionFactoryOptions().isQueryParametersValidationEnabled();
	}

	
Get the load query influencers associated with this session.
Returns:
the load query influencers associated with this session;
        should never be null./**
	 * Get the load query influencers associated with this session.
	 *
	 * @return the load query influencers associated with this session;
	 *         should never be null.
	 */
	LoadQueryInfluencers getLoadQueryInfluencers();

	ExceptionConverter getExceptionConverter();

	
Get the currently configured JDBC batch size either at the Session-level or SessionFactory-level.
If the Session-level JDBC batch size was not configured, return the SessionFactory-level one.
See Also:
SessionFactoryOptions.getJdbcBatchSize
SessionFactoryBuilder.applyJdbcBatchSize
Returns:
Session-level or or SessionFactory-level JDBC batch size.
Since:
5.2/**
	 * Get the currently configured JDBC batch size either at the Session-level or SessionFactory-level.
	 *
	 * If the Session-level JDBC batch size was not configured, return the SessionFactory-level one.
	 *
	 * @return Session-level or or SessionFactory-level JDBC batch size.
	 *
	 * @since 5.2
	 *
	 * @see org.hibernate.boot.spi.SessionFactoryOptions#getJdbcBatchSize
	 * @see org.hibernate.boot.SessionFactoryBuilder#applyJdbcBatchSize
	 */
	default Integer getConfiguredJdbcBatchSize() {
		final Integer sessionJdbcBatchSize = getJdbcBatchSize();

		return sessionJdbcBatchSize == null ?
			ConfigurationHelper.getInt(
					Environment.STATEMENT_BATCH_SIZE,
					getFactory().getProperties(),
					1
			) :
			sessionJdbcBatchSize;
	}
}