/*
 * Hibernate Search, full-text search for your domain model
 *
 * 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.search.engine.integration.impl;

import java.util.Map;
import java.util.Properties;
import java.util.Set;

import org.hibernate.search.analyzer.spi.ScopedAnalyzerReference;
import org.hibernate.search.cfg.spi.SearchConfiguration;
import org.hibernate.search.engine.impl.AnalyzerRegistry;
import org.hibernate.search.engine.impl.FilterDef;
import org.hibernate.search.engine.spi.DocumentBuilderContainedEntity;
import org.hibernate.search.engine.spi.EntityIndexBinding;
import org.hibernate.search.engine.spi.TimingSource;
import org.hibernate.search.filter.FilterCachingStrategy;
import org.hibernate.search.indexes.impl.IndexManagerHolder;
import org.hibernate.search.indexes.spi.IndexManagerType;
import org.hibernate.search.query.DatabaseRetrievalMethod;
import org.hibernate.search.query.ObjectLookupMethod;
import org.hibernate.search.query.engine.spi.HSQuery;
import org.hibernate.search.spi.InstanceInitializer;
import org.hibernate.search.spi.SearchIntegrator;
import org.hibernate.search.stat.spi.StatisticsImplementor;

/**
 * Interface which gives access to runtime configuration. Intended to be used by Search components.
 *
 * @author Emmanuel Bernard
 * @author Hardy Ferentschik
 * @author Sanne Grinovero
 */
public interface ExtendedSearchIntegrator extends SearchIntegrator {

	/**
	 * Returns a map of all known entity index binding (indexed entities) keyed against the indexed type
	 *
	 * @return a map of all known entity index binding (indexed entities) keyed against the indexed type. The empty
	 * map is returned if there are no indexed types.
	 */
	Map<Class<?>, EntityIndexBinding> getIndexBindings();

	DocumentBuilderContainedEntity getDocumentBuilderContainedEntity(Class<?> entityType);

	FilterCachingStrategy getFilterCachingStrategy();

	FilterDef getFilterDefinition(String name);

	int getFilterCacheBitResultsSize();

	/**
	 * Given a set of target entities, return the set of configured subtypes.
	 * <p>
	 * "Configured" types are types that Hibernate Search was instructed to take into consideration,
	 * i.e. types returned by {@link SearchConfiguration#getClassMappings()}.
	 *
	 * @param classes an array of types
	 * @return the set of configured subtypes
	 */
	Set<Class<?>> getConfiguredTypesPolymorphic(Class<?>[] classes);

	/**
	 * Given a set of target entities, return the set of configured subtypes that are indexed.
	 * <p>
	 * "Configured" types are types that Hibernate Search was instructed to take into consideration,
	 * i.e. types returned by {@link SearchConfiguration#getClassMappings()}.
	 * <p>
	 * "Indexed" types are configured types that happened to be annotated with {@code @Indexed},
	 * or similarly configured through a programmatic mapping.
	 * <p>
	 * Note: the fact that a given type is configured or indexed doesn't mean that its subtypes are, too.
	 * Each type must be configured explicitly.
	 *
	 * @param classes an array of types
	 * @return the set of configured subtypes that are indexed
	 */
	Set<Class<?>> getIndexedTypesPolymorphic(Class<?>[] classes);

	/**
	 * @return {@code true} if JMX is enabled
	 */
	boolean isJMXEnabled();

	/**
	 * Retrieve the statistics implementor instance for this factory.
	 *
	 * @return The statistics implementor.
	 */
	StatisticsImplementor getStatisticsImplementor();

	/**
	 * @return {@code true} if we are allowed to inspect entity state to skip some indexing operations.
	 * Can be disabled to get pre-3.4 behavior which always rebuilds the document.
	 */
	boolean isDirtyChecksEnabled();

	/**
	 * @return Returns the {@code IndexManagerHolder} which gives access to all index managers known to this factory
	 */
	IndexManagerHolder getIndexManagerHolder();

	/**
	 * @return an instance of {@code InstanceInitializer} for class/object initialization.
	 */
	InstanceInitializer getInstanceInitializer();

	/**
	 * @return the globally configured TimingSource, which we use to implement timeouts during query execution.
	 */
	TimingSource getTimingSource();

	/**
	 * @return the configuration properties for this factory
	 */
	Properties getConfigurationProperties();

	/**
	 * Returns the default {@code DatabaseRetrievalMethod}.
	 *
	 * This is either the system default or the default specified via the configuration property
	 * {@link org.hibernate.search.cfg.Environment#DATABASE_RETRIEVAL_METHOD}.
	 *
	 * @return returns the default {@code DatabaseRetrievalMethod}.
	 */
	DatabaseRetrievalMethod getDefaultDatabaseRetrievalMethod();

	/**
	 * Returns the default {@code ObjectLookupMethod}.
	 *
	 * This is either the system default or the default specified via the configuration property
	 * {@link org.hibernate.search.cfg.Environment#OBJECT_LOOKUP_METHOD}.
	 *
	 * @return returns the default {@code OBJECT_LOOKUP_METHOD}.
	 */
	ObjectLookupMethod getDefaultObjectLookupMethod();

	/**
	 * @return whether index uninverting should be done when running queries with sorts not covered by the configured sortable
	 * fields. If not allowed, an exception will be raised in this situation.
	 */
	boolean isIndexUninvertingAllowed();

	/**
	 * Returns a map of all known entity index binding (indexed entities) keyed against the indexed type
	 *
	 * @return a map of all known entity index binding (indexed entities) keyed against the indexed type. The empty
	 * map is returned if there are no indexed types.
	 */
	Map<IndexManagerType, AnalyzerRegistry> getAnalyzerRegistries();

	/**
	 * Retrieve the analyzer registry for a given index manager type.
	 *
	 * @param indexManagerType the index manager type for which to retrieve the registry
	 *
	 * @return The corresponding analyzer registry
	 *
	 * @throws org.hibernate.search.exception.SearchException if the index manager type is unknown
	 */
	AnalyzerRegistry getAnalyzerRegistry(IndexManagerType indexManagerType);

	/**
	 * Retrieve the scoped analyzer reference for a given class.
	 *
	 * @param clazz The class for which to retrieve the analyzer.
	 *
	 * @return The scoped analyzer for the specified class.
	 *
	 * @throws java.lang.IllegalArgumentException in case {@code clazz == null} or the specified
	 * class is not an indexed entity.
	 */
	ScopedAnalyzerReference getAnalyzerReference(Class<?> clazz);

	/**
	 * Return an Hibernate Search query object.
	 * This method does NOT support non-Lucene backends (e.g. Elasticsearch).
	 *
	 * @return an Hibernate Search query object
	 */
	HSQuery createLuceneBasedHSQuery();
}