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 }