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
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 }