001/*
002 * file CqHitSet.java
003 *
004 * Licensed Materials - Property of IBM
005 * Restricted Materials of IBM 
006 *
007 * com.ibm.rational.wvcm.stp.cq.CqHitSet
008 *
009 * (C) Copyright IBM Corporation 2008.  All Rights Reserved.
010 * Note to U.S. Government Users Restricted Rights:  Use, duplication or 
011 * disclosure restricted by GSA ADP  Schedule Contract with IBM Corp.
012 */
013
014package com.ibm.rational.wvcm.stp.cq;
015
016import java.util.Iterator;
017
018import javax.wvcm.WvcmException;
019
020import com.ibm.rational.wvcm.stp.StpReleasable;
021
022/**
023 * The interface to the results of a CqUserDb.doFullTextSearch invocation.
024 * 
025 * A CqHitSet is an Iterable, but each invocation of its iterator() method does
026 * not restart the iteration. It just continues from the last read hit. That is
027 * CqHitSet.iterator() simply returns the CqHitSet object. It is provided to
028 * allow the use of CqHitSet objects in the Java 5 for-each construct.
029 * 
030 * @see CqUserDb#doFullTextSearch(com.ibm.rational.wvcm.stp.cq.CqUserDb.SearchFilter, long[])
031 */
032public interface CqHitSet extends StpReleasable, Iterator<CqHit>,
033                Iterable<CqHit>
034{
035    /**
036     * @return The total number of hits found by the search. In most cases this
037     *         number is only an approximation and can be used only to give an
038     *         indication of the magnitude of the hit set.
039     */
040    long totalHits();
041
042    /**
043     * @return The search string composed from the filter content and used by 
044     * the search engine to generate this hit set.
045     */
046    String expandedSearchString();
047
048    /**
049     * @return Amongst all hits found by the search, the ordinal position of the
050     *         hit to be returned by the next call to Iterator.next(). This
051     *         value can exceed totalHits() while there are still hits
052     *         available. All hits have been returned only when hasNext() and
053     *         hasMore() both return <b>false</b>.
054     */
055    long nextIndex();
056
057    /**
058     * @return The number of hits currently on the client that can be accessed
059     *         by Iterator.next(). This value resets after each interaction with
060     *         the server and thus is not monotonic.
061     */
062    long size();
063
064    /**
065     * Indicates whether or not the server has more data to provide via the
066     * doGetMore() method.
067     * 
068     * @return <b>true</b> if the server has more hit data that it could send
069     *         to the client.
070     */
071    boolean hasMore();
072
073    /**
074     * Requests the server to forward the next set of hits to the client.
075     * Successful execution of this method flushes the current content of the
076     * CqHitSet iterator and resets it to the first hit of the new set,
077     * adjusting the nextIndex and size fields accordingly.
078     * 
079     * @param maxSetSize The maximum number of hits the client will accept in
080     *            the next set. If zero, the number of hits requested will be
081     *            the same as previously request.
082     * 
083     * @return <b>true</b> if more hits were obtained from the server; <b>false</b>
084     *         if there were none left on the server.
085     * @throws WvcmException If the server had indicated it had more hits, but
086     *             the attempt to get those hits from the server failed.
087     */
088    boolean doGetMore(long maxSetSize) throws WvcmException;
089
090    /**
091     * Sets whether or not more hits are automatically requested from the server
092     * when those currently on the client run out.
093     * 
094     * @param autoGetMore If <b>false</b>, Iterator.hasNext() will return
095     *            <b>false</b> and Iterator.next() will throw an exception when
096     *            size() returns 0 (i.e. after the last hit on the client has
097     *            been returned by the Iterator.next() function). This is the
098     *            initial, default behavior of any result set.
099     *            <p>
100     *            If <b>true</b>, Iterator.hasNext() or Iterator.next() will
101     *            automatically call doGetMore() when there are no more hits on
102     *            the client. In this mode the last specified value for the hit
103     *            set size is used in the implicit call of doGetMore().
104     */
105    void setAutoGetMore(boolean autoGetMore);
106}