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     * © 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    
014    package com.ibm.rational.wvcm.stp.cq;
015    
016    import java.util.Iterator;
017    
018    import javax.wvcm.WvcmException;
019    
020    import 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     */
032    public 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    }