org.compass.core.CompassHits Maven / Gradle / Ivy

/*
 * Copyright 2004-2009 the original author or authors.
 * 
 * Licensed under the Apache License, Version 2.0 (the "License");
 * you may not use this file except in compliance with the License.
 * You may obtain a copy of the License at
 * 
 *      http://www.apache.org/licenses/LICENSE-2.0
 * 
 * Unless required by applicable law or agreed to in writing, software
 * distributed under the License is distributed on an "AS IS" BASIS,
 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 * See the License for the specific language governing permissions and
 * limitations under the License.
 */

package org.compass.core;

/**
 * Holds hits returned from a search performed by compass. Can be used within a
 * transaction context. For hits to be used outside of a transactional context,
 * the {@link #detach()} and {@link #detach(int, int)} can be used.
 * 
 * Also allows for highlighting using {@link #highlighter(int)}, and any highlighting
 * operation (that returns a single String) will be cached within the
 * hits (and also moved to the detached hits, if {@link #detach(int, int)} is called),
 * and can be used by {@link CompassHitsOperations#highlightedText(int)}.
 *
 * @author kimchy
 */
public interface CompassHits extends CompassHitsOperations {

    /**
     * Detaches a seperate CompassHits, holds all the data. The
     * detached hits preloads all the data, so it can be used outside of a
     * transaction. NOTE: Be carefull when using the method, since it will take
     * LONG time to load a large hits result set.
     *
     * @return A detached hits.
     * @throws CompassException 
     */
    CompassDetachedHits detach() throws CompassException;

    /**
     * Detaches a seperate CompassHits, which starts from the
     * given from parameter, and has the specified size. The detached hits
     * preloads all the data, so it can be used outside of a transaction.
     *
     * @param from The index that the sub hits starts from.
     * @param size The size of the sub hits.
     * @return A detached sub hits.
     * @throws CompassException
     */
    CompassDetachedHits detach(int from, int size) throws CompassException, IllegalArgumentException;

    /**
     * Returns the highlighter that maps the n'th hit.
     * 

     * Note, that any highlighting operation (that returns a single String)
     * will be cached within the hits (and also moved to the detached hits, if
     * {@link #detach(int, int)} is called), and can be used by
     * {@link CompassHitsOperations#highlightedText(int)}.
     *
     * @param n The n'th hit.
     * @return The highlighter.
     * @throws CompassException
     */
    CompassHighlighter highlighter(int n) throws CompassException;

    /**
     * Closes the hits object. Note that it is an optional operation since it
     * will be closed transperantly when the transaction is closed.
     * 
     * It is provided for more controlled resource management
     *
     * @throws CompassException
     */
    void close() throws CompassException;
}