001: /**
002: * Copyright (C) 2001 Yasna.com. All rights reserved.
003: *
004: * ===================================================================
005: * The Apache Software License, Version 1.1
006: *
007: * Redistribution and use in source and binary forms, with or without
008: * modification, are permitted provided that the following conditions
009: * are met:
010: *
011: * 1. Redistributions of source code must retain the above copyright
012: * notice, this list of conditions and the following disclaimer.
013: *
014: * 2. Redistributions in binary form must reproduce the above copyright
015: * notice, this list of conditions and the following disclaimer in
016: * the documentation and/or other materials provided with the
017: * distribution.
018: *
019: * 3. The end-user documentation included with the redistribution,
020: * if any, must include the following acknowledgment:
021: * "This product includes software developed by
022: * Yasna.com (http://www.yasna.com)."
023: * Alternately, this acknowledgment may appear in the software itself,
024: * if and wherever such third-party acknowledgments normally appear.
025: *
026: * 4. The names "Yazd" and "Yasna.com" must not be used to
027: * endorse or promote products derived from this software without
028: * prior written permission. For written permission, please
029: * contact yazd@yasna.com.
030: *
031: * 5. Products derived from this software may not be called "Yazd",
032: * nor may "Yazd" appear in their name, without prior written
033: * permission of Yasna.com.
034: *
035: * THIS SOFTWARE IS PROVIDED ``AS IS'' AND ANY EXPRESSED OR IMPLIED
036: * WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES
037: * OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
038: * DISCLAIMED. IN NO EVENT SHALL YASNA.COM OR
039: * ITS CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
040: * SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
041: * LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF
042: * USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND
043: * ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
044: * OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT
045: * OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
046: * SUCH DAMAGE.
047: * ====================================================================
048: *
049: * This software consists of voluntary contributions made by many
050: * individuals on behalf of Yasna.com. For more information
051: * on Yasna.com, please see <http://www.yasna.com>.
052: */
053:
054: /**
055: * Copyright (C) 2000 CoolServlets.com. All rights reserved.
056: *
057: * ===================================================================
058: * The Apache Software License, Version 1.1
059: *
060: * Redistribution and use in source and binary forms, with or without
061: * modification, are permitted provided that the following conditions
062: * are met:
063: *
064: * 1. Redistributions of source code must retain the above copyright
065: * notice, this list of conditions and the following disclaimer.
066: *
067: * 2. Redistributions in binary form must reproduce the above copyright
068: * notice, this list of conditions and the following disclaimer in
069: * the documentation and/or other materials provided with the
070: * distribution.
071: *
072: * 3. The end-user documentation included with the redistribution,
073: * if any, must include the following acknowledgment:
074: * "This product includes software developed by
075: * CoolServlets.com (http://www.coolservlets.com)."
076: * Alternately, this acknowledgment may appear in the software itself,
077: * if and wherever such third-party acknowledgments normally appear.
078: *
079: * 4. The names "Jive" and "CoolServlets.com" must not be used to
080: * endorse or promote products derived from this software without
081: * prior written permission. For written permission, please
082: * contact webmaster@coolservlets.com.
083: *
084: * 5. Products derived from this software may not be called "Jive",
085: * nor may "Jive" appear in their name, without prior written
086: * permission of CoolServlets.com.
087: *
088: * THIS SOFTWARE IS PROVIDED ``AS IS'' AND ANY EXPRESSED OR IMPLIED
089: * WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES
090: * OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
091: * DISCLAIMED. IN NO EVENT SHALL COOLSERVLETS.COM OR
092: * ITS CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
093: * SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
094: * LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF
095: * USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND
096: * ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
097: * OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT
098: * OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
099: * SUCH DAMAGE.
100: * ====================================================================
101: *
102: * This software consists of voluntary contributions made by many
103: * individuals on behalf of CoolServlets.com. For more information
104: * on CoolServlets.com, please see <http://www.coolservlets.com>.
105: */package com.Yasna.forum;
106:
107: import java.util.Date;
108: import java.util.Iterator;
109:
110: /**
111: * Encapsulates a search for content in a forum. Use the factory method
112: * forum.createQuery() to get a handle on a Query object. From there, set
113: * the properties that you're interested in searching on. For example, to
114: * search a forum for "Yazd is cool", you would use the following code:<p>
115: *
116: * <pre>
117: * Query query = forum.createQuery();
118: * query.setQueryString("Yazd is cool");
119: * Iterator iter = query.results();
120: * while (iter.hasNext()) {
121: * ForumMessage message = (ForumMessage)iter.nextElement();
122: * //print results...
123: * }
124: * </pre><p>
125: *
126: * All search properties are optional. You can mix and match them depending on
127: * what kind of query you'd like to perform.<p>
128: *
129: * You can also use the filter methods to restrict searches to messages
130: * from a particular user, messages between a date range, or messages in a
131: * particular thread.
132: */
133: public interface Query {
134:
135: /**
136: * Returns the query string for the Query object. The query string is a
137: * set of keywords that should be searched on. Currently only "and" keyword
138: * searches are supported -- that is, only results that contain every
139: * keyword will be returned. In general, keywords should be seperated by
140: * spaces. However, other delimiter characters are legal and will be
141: * ignored.
142: * <p>
143: * If the query string has not been set, this method will return null.
144: *
145: * @return the Query query string.
146: */
147: public String getQueryString();
148:
149: /**
150: * Sets the query string for the Query object. The query string is a
151: * set of keywords that should be searched on. Currently only "and" keyword
152: * searches are supported -- that is, only results that contain every
153: * keyword will be returned. In general, keywords should be seperated by
154: * spaces. However, other delimiter characters are legal and will be
155: * ignored.
156: *
157: * @param queryString a new query string.
158: */
159: public void setQueryString(String queryString);
160:
161: /**
162: * Returns the latest date for search results. For example, the "before date"
163: * can be used to search for messages modified more than 1 month ago.
164: * <p>
165: * If the "before date" has not been set, this method will return null.
166: *
167: * @return the upder date boundary for search results.
168: */
169: public Date getBeforeDate();
170:
171: /**
172: * Sets the latest date for search results. For example, the "before date"
173: * can be used to search for messages modified more than 1 month ago.
174: *
175: * @param beforeDate an upper date boundary for search results.
176: */
177: public void setBeforeDate(Date beforeDate);
178:
179: /**
180: * Returns the earliest date for search results. For example, the "after date"
181: * can be used to search for messages modified within the last week.<p>
182: *
183: * If the "after date" has not been set, this method will return null.
184: *
185: * @return the lower date boundary for search results.
186: */
187: public Date getAfterDate();
188:
189: /**
190: * Sets the earliest date for search results. For example, the "after date"
191: * can be used to search for messages modified within the last week.
192: *
193: * @param afterDate a lower date boundary for search results.
194: */
195: public void setAfterDate(Date afterDate);
196:
197: /**
198: * Returns the user that query results are restricted to. If the query
199: * is not restricted to messages posted by a certain user, this method will
200: * return null.
201: *
202: * @return the message that results are restricted to.
203: */
204: public User getFilteredUser();
205:
206: /**
207: * Restricts the query results to messages posted by a specified user.
208: *
209: * @param user a User to restrict query results to.
210: */
211: public void filterOnUser(User user);
212:
213: /**
214: * Returns the thread that query results are restricted to. If the query
215: * is not restricted to messages in a certain thread, this method will
216: * return null.
217: *
218: * @return the thread that results are restricted to.
219: */
220: public ForumThread getFilteredThread();
221:
222: /**
223: * Restricts the querty results to messages posted in a specified thread.
224: *
225: * @param thread the ForumThread to restrict query results to.
226: */
227: public void filterOnThread(ForumThread thread);
228:
229: /**
230: * Returns the total number of results of the query.
231: *
232: * @return the number of results of the query.
233: */
234: public int resultCount();
235:
236: /**
237: * Returns the results of the Query as an Iterator of ForumMessage objects.
238: *
239: * @return the result of the query as an Iterator.
240: */
241: public Iterator results();
242:
243: /**
244: * Returns the results of the Query as an Iterator of ForumMessage objects.
245: * The startIndex and numResults paramaters are used to look at a certain
246: * range of the results. For example, the first twenty results, the second
247: * twenty results, etc. This is useful for user interface with multiple
248: * pages of results.<p>
249: *
250: * If startIndex or numResults does not fall within the range of results,
251: * the number of messages returned may be smaller than expected. For
252: * example, suppose a query has a total of 17 results. If startIndex
253: * is 0 and numResults is 25, only 17 results can be returned.
254: *
255: * @param startIndex the index in the results that the iterator will start at.
256: * @param numResuls the max number of results that should be returned.
257: * @return the result of the query as an Iterator.
258: */
259: public Iterator results(int startIndex, int numResults);
260: }
|