/*
* Hibernate, Relational Persistence for Idiomatic Java
*
* JBoss, Home of Professional Open Source
* Copyright 2011 Red Hat Inc. and/or its affiliates and other contributors
* as indicated by the @authors tag. All rights reserved.
* See the copyright.txt in the distribution for a
* full listing of individual contributors.
*
* This copyrighted material is made available to anyone wishing to use,
* modify, copy, or redistribute it subject to the terms and conditions
* of the GNU Lesser General Public License, v. 2.1.
* This program is distributed in the hope that it will be useful, but WITHOUT A
* WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A
* PARTICULAR PURPOSE. See the GNU Lesser General Public License for more details.
* You should have received a copy of the GNU Lesser General Public License,
* v.2.1 along with this distribution; if not, write to the Free Software
* Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston,
* MA 02110-1301, USA.
*/
package org.hibernate.search.indexes;
import org.apache.lucene.index.IndexReader;
/**
* The {@code IndexReaderAccessor} exposes {@link org.apache.lucene.index.IndexReader}s directly, making it possible to query the Lucene
* indexes directly bypassing Hibernate Search.
* <p>
* The returned IndexReader instances are always read-only and must be closed
* using the {@link #close(IndexReader)} method on this same instance.
* </p>
* <P>
* <b>Note:</b> this API is intended for power users intending to extract information directly.
* </p>
*
* @author Sanne Grinovero <sanne@hibernate.org> (C) 2011 Red Hat Inc.
*/
public interface IndexReaderAccessor {
/**
* Opens an IndexReader on all indexes containing the entities passed as parameter.
* In the simplest case passing a single entity will map to a single index; if the entity
* uses a sharding strategy or if multiple entities using different index names are selected,
* the single IndexReader will act as a MultiReader on the aggregate of these indexes.
* This MultiReader is not filtered by Hibernate Search, so it might contain information
* relevant to different types as well.
* <p>
* The returned IndexReader is read only; writing directly to the index is discouraged. If you
* need to write to the index use the
* {@link org.hibernate.search.spi.SearchFactoryIntegrator#getWorker()} to queue change operations to the backend.
* </p>
* <p>
* The IndexReader should not be closed in other ways except being returned to this instance via
* {@link #close(IndexReader)}.
* </p>
*
* @param entities the entity types for which to return a (multi)reader
* @return an IndexReader containing at least all listed entities
* @throws java.lang.IllegalArgumentException if one of the specified classes is not indexed
*/
IndexReader open(Class<?>... entities);
/**
* Opens an IndexReader on all named indexes.
* A single name can be provided, or multiple. In the case of multiple names it
* still returns a single IndexReader instance, but this will make it possible to run
* queries on the combination of each index.
*
* @param indexNames At least one IndexManager name.
* @return an IndexReader instance.
* @throws org.hibernate.search.SearchException if the index manager to which the named index belongs failed to start
*/
IndexReader open(String... indexNames);
/**
* Closes IndexReader instances obtained using {@link #open(Class...)}
*
* @param indexReader the IndexReader to be closed
*/
void close(IndexReader indexReader);
}