/*
 * 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.jpa.spi;

import java.util.List;
import java.util.Map;
import javax.persistence.LockModeType;
import javax.persistence.PersistenceException;
import javax.persistence.criteria.Selection;

import org.hibernate.HibernateException;
import org.hibernate.LockOptions;
import org.hibernate.StaleStateException;
import org.hibernate.engine.spi.SessionImplementor;
import org.hibernate.jpa.HibernateEntityManager;
import org.hibernate.query.Query;
import org.hibernate.query.criteria.internal.ValueHandlerFactory;
import org.hibernate.type.Type;

Additional internal contracts for the Hibernate EntityManager implementation. 
Author:
Emmanuel Bernard, Steve Ebersole
Deprecated:
(since 5.2) move these methods to SessionImplementor/**
 * Additional internal contracts for the Hibernate {@link javax.persistence.EntityManager} implementation.
 *
 * @author Emmanuel Bernard
 * @author Steve Ebersole
 *
 * @deprecated (since 5.2) move these methods to SessionImplementor
 */
@Deprecated
public interface HibernateEntityManagerImplementor extends HibernateEntityManager, HibernateEntityManagerFactoryAware {
	@Override
	SessionImplementor getSession();

	
Used to ensure the EntityManager is open, throwing IllegalStateException if it is closed. Depending on the value of markForRollbackIfClosed, may also rollback any enlisted-in transaction. This distinction is made across various sections of the spec. Most failed checks should rollback. Section 3.10.7 (per 2.1 spec) lists cases related to calls on related query objects that should not rollback. 
Params:
markForRollbackIfClosed – If the EM is closed, should the transaction (if one) be marked for rollback?
Throws:
IllegalStateException – Thrown if the EM is closed/**
	 * Used to ensure the EntityManager is open, throwing IllegalStateException if it is closed.
	 *
	 * Depending on the value of {@code markForRollbackIfClosed}, may also rollback any enlisted-in transaction.  This
	 * distinction is made across various sections of the spec.  Most failed checks should rollback.  Section
	 * 3.10.7 (per 2.1 spec) lists cases related to calls on related query objects that should not rollback.
	 *
	 * @param markForRollbackIfClosed If the EM is closed, should the transaction (if one) be marked for rollback?
	 *
	 * @throws IllegalStateException Thrown if the EM is closed
	 */
	void checkOpen(boolean markForRollbackIfClosed) throws IllegalStateException;

	
Provides access to whether a transaction is currently in progress.
Returns:
True if a transaction is considered currently in progress; false otherwise./**
	 * Provides access to whether a transaction is currently in progress.
	 *
	 * @return True if a transaction is considered currently in progress; false otherwise.
	 */
	boolean isTransactionInProgress();

	
Used to mark a transaction for rollback only (when that is the JPA spec defined behavior).
/**
	 * Used to mark a transaction for rollback only (when that is the JPA spec defined behavior).
	 */
	void markForRollbackOnly();

	
Convert from JPA 2 LockModeType & properties into LockOptions 
Params:
lockModeType – is the requested lock type
properties – are the lock properties
Returns:
the LockOptions
Deprecated:
(since 5.2) use buildLockOptions(LockModeType, Map<String,Object>) instead/**
	 * Convert from JPA 2 {@link javax.persistence.LockModeType} & properties into {@link org.hibernate.LockOptions}
	 *
	 * @param lockModeType is the requested lock type
	 * @param properties are the lock properties
	 *
	 * @return the LockOptions
	 *
	 * @deprecated (since 5.2) use {@link #buildLockOptions(LockModeType, Map)} instead
	 */
	@Deprecated
	LockOptions getLockRequest(LockModeType lockModeType, Map<String, Object> properties);

	
Given a JPA LockModeType and properties, build a Hibernate LockOptions 
Params:
lockModeType – the requested LockModeType
properties – the lock properties
Returns:
the LockOptions/**
	 * Given a JPA {@link javax.persistence.LockModeType} and properties, build a Hibernate
	 * {@link org.hibernate.LockOptions}
	 *
	 * @param lockModeType the requested LockModeType
	 * @param properties the lock properties
	 *
	 * @return the LockOptions
	 */
	default LockOptions buildLockOptions(LockModeType lockModeType, Map<String, Object> properties) {
		return getLockRequest( lockModeType, properties );
	}

	interface QueryOptions {
		interface ResultMetadataValidator {
			void validate(Type[] returnTypes);
		}

		ResultMetadataValidator getResultMetadataValidator();

		
Get the conversions for the individual tuples in the query results.
Returns:
Value conversions to be applied to the JPA QL results/**
		 * Get the conversions for the individual tuples in the query results.
		 *
		 * @return Value conversions to be applied to the JPA QL results
		 */
		List<ValueHandlerFactory.ValueHandler> getValueHandlers();

		
Get the explicit parameter types.  Generally speaking these would apply to implicit named
parameters.
Returns:
The/**
		 * Get the explicit parameter types.  Generally speaking these would apply to implicit named
		 * parameters.
		 *
		 * @return The
		 */
		Map<String, Class> getNamedParameterExplicitTypes();
	}

	
Used during "compiling" a JPA criteria query.
Params:
jpaqlString – The criteria query rendered as a JPA QL string
resultClass – The result type (the type expected in the result list)
selection – The selection(s)
queryOptions – The options to use to build the query.
Type parameters:
<T> – The query type
Deprecated:
(since 5.2) this method form is used to construct a "compiled" representation of
a JPA Criteria query.  However it assumes the old yucky implementation of "compilation" that
converted the Criteria into a HQL/JPQL string.  In 6.0 that is re-written from scratch to
compile to SQM, and so this method would not be needed in 6.0
Returns:
The typed query/**
	 * Used during "compiling" a JPA criteria query.
	 *
	 * @param jpaqlString The criteria query rendered as a JPA QL string
	 * @param resultClass The result type (the type expected in the result list)
	 * @param selection The selection(s)
	 * @param queryOptions The options to use to build the query.
	 * @param <T> The query type
	 *
	 * @deprecated (since 5.2) this method form is used to construct a "compiled" representation of
	 * a JPA Criteria query.  However it assumes the old yucky implementation of "compilation" that
	 * converted the Criteria into a HQL/JPQL string.  In 6.0 that is re-written from scratch to
	 * compile to SQM, and so this method would not be needed in 6.0
	 *
	 * @return The typed query
	 */
	@Deprecated
	<T> Query<T> createQuery(
			String jpaqlString,
			Class<T> resultClass,
			Selection selection,
			QueryOptions queryOptions);
}