Query


1   /**
2    * Copyright (C) 2001 Yasna.com. All rights reserved.
3    *
4    * ===================================================================
5    * The Apache Software License, Version 1.1
6    *
7    * Redistribution and use in source and binary forms, with or without
8    * modification, are permitted provided that the following conditions
9    * are met:
10   *
11   * 1. Redistributions of source code must retain the above copyright
12   *    notice, this list of conditions and the following disclaimer.
13   *
14   * 2. Redistributions in binary form must reproduce the above copyright
15   *    notice, this list of conditions and the following disclaimer in
16   *    the documentation and/or other materials provided with the
17   *    distribution.
18   *
19   * 3. The end-user documentation included with the redistribution,
20   *    if any, must include the following acknowledgment:
21   *       "This product includes software developed by
22   *        Yasna.com (http://www.yasna.com)."
23   *    Alternately, this acknowledgment may appear in the software itself,
24   *    if and wherever such third-party acknowledgments normally appear.
25   *
26   * 4. The names "Yazd" and "Yasna.com" must not be used to
27   *    endorse or promote products derived from this software without
28   *    prior written permission. For written permission, please
29   *    contact yazd@yasna.com.
30   *
31   * 5. Products derived from this software may not be called "Yazd",
32   *    nor may "Yazd" appear in their name, without prior written
33   *    permission of Yasna.com.
34   *
35   * THIS SOFTWARE IS PROVIDED ``AS IS'' AND ANY EXPRESSED OR IMPLIED
36   * WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES
37   * OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
38   * DISCLAIMED.  IN NO EVENT SHALL YASNA.COM OR
39   * ITS CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
40   * SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
41   * LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF
42   * USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND
43   * ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
44   * OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT
45   * OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
46   * SUCH DAMAGE.
47   * ====================================================================
48   *
49   * This software consists of voluntary contributions made by many
50   * individuals on behalf of Yasna.com. For more information
51   * on Yasna.com, please see <http://www.yasna.com>.
52   */
53  
54  /**
55   * Copyright (C) 2000 CoolServlets.com. All rights reserved.
56   *
57   * ===================================================================
58   * The Apache Software License, Version 1.1
59   *
60   * Redistribution and use in source and binary forms, with or without
61   * modification, are permitted provided that the following conditions
62   * are met:
63   *
64   * 1. Redistributions of source code must retain the above copyright
65   *    notice, this list of conditions and the following disclaimer.
66   *
67   * 2. Redistributions in binary form must reproduce the above copyright
68   *    notice, this list of conditions and the following disclaimer in
69   *    the documentation and/or other materials provided with the
70   *    distribution.
71   *
72   * 3. The end-user documentation included with the redistribution,
73   *    if any, must include the following acknowledgment:
74   *       "This product includes software developed by
75   *        CoolServlets.com (http://www.coolservlets.com)."
76   *    Alternately, this acknowledgment may appear in the software itself,
77   *    if and wherever such third-party acknowledgments normally appear.
78   *
79   * 4. The names "Jive" and "CoolServlets.com" must not be used to
80   *    endorse or promote products derived from this software without
81   *    prior written permission. For written permission, please
82   *    contact webmaster@coolservlets.com.
83   *
84   * 5. Products derived from this software may not be called "Jive",
85   *    nor may "Jive" appear in their name, without prior written
86   *    permission of CoolServlets.com.
87   *
88   * THIS SOFTWARE IS PROVIDED ``AS IS'' AND ANY EXPRESSED OR IMPLIED
89   * WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES
90   * OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
91   * DISCLAIMED.  IN NO EVENT SHALL COOLSERVLETS.COM OR
92   * ITS CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
93   * SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
94   * LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF
95   * USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND
96   * ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
97   * OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT
98   * OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
99   * 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  */
106 
107 package com.Yasna.forum;
108 
109 import java.util.Date  ;
110 import java.util.Iterator  ;
111 
112 /**
113  * Encapsulates a search for content in a forum. Use the factory method
114  * forum.createQuery() to get a handle on a Query object. From there, set
115  * the properties that you're interested in searching on. For example, to
116  * search a forum for "Yazd is cool", you would use the following code:<p>
117  *
118  * <pre>
119  * Query query = forum.createQuery();
120  * query.setQueryString("Yazd is cool");
121  * Iterator iter = query.results();
122  * while (iter.hasNext()) {
123  *     ForumMessage message = (ForumMessage)iter.nextElement();
124  *     //print results...
125  * }
126  * </pre><p>
127  *
128  * All search properties are optional. You can mix and match them depending on
129  * what kind of query you'd like to perform.<p>
130  *
131  * You can also use the filter methods to restrict searches to messages
132  * from a particular user, messages between a date range, or messages in a
133  * particular thread.
134  */
135 public interface Query {
136 
137     /**
138      * Returns the query string for the Query object. The query string is a
139      * set of keywords that should be searched on. Currently only "and" keyword
140      * searches are supported -- that is, only results that contain every
141      * keyword will be returned. In general, keywords should be seperated by
142      * spaces. However, other delimiter characters are legal and will be
143      * ignored.
144      * <p>
145      * If the query string has not been set, this method will return null.
146      *
147      * @return the Query query string.
148      */
149     public String   getQueryString();
150 
151     /**
152      * Sets the query string for the Query object. The query string is a
153      * set of keywords that should be searched on. Currently only "and" keyword
154      * searches are supported -- that is, only results that contain every
155      * keyword will be returned. In general, keywords should be seperated by
156      * spaces. However, other delimiter characters are legal and will be
157      * ignored.
158      *
159      * @param queryString a new query string.
160      */
161     public void setQueryString(String   queryString);
162 
163     /**
164      * Returns the latest date for search results. For example, the "before date"
165      * can be used to search for messages modified more than 1 month ago.
166      * <p>
167      * If the "before date" has not been set, this method will return null.
168      *
169      * @return the upder date boundary for search results.
170      */
171     public Date   getBeforeDate();
172 
173     /**
174      * Sets the latest date for search results. For example, the "before date"
175      * can be used to search for messages modified more than 1 month ago.
176      *
177      * @param beforeDate an upper date boundary for search results.
178      */
179     public void setBeforeDate(Date   beforeDate);
180 
181     /**
182      * Returns the earliest date for search results. For example, the "after date"
183      * can be used to search for messages modified within the last week.<p>
184      *
185      * If the "after date" has not been set, this method will return null.
186      *
187      * @return the lower date boundary for search results.
188      */
189     public Date   getAfterDate();
190 
191     /**
192      * Sets the earliest date for search results. For example, the "after date"
193      * can be used to search for messages modified within the last week.
194      *
195      * @param afterDate a lower date boundary for search results.
196      */
197     public void setAfterDate(Date   afterDate);
198 
199     /**
200      * Returns the user that query results are restricted to. If the query
201      * is not restricted to messages posted by a certain user, this method will
202      * return null.
203      *
204      * @return the message that results are restricted to.
205      */
206     public User getFilteredUser();
207 
208     /**
209      * Restricts the query results to messages posted by a specified user.
210      *
211      * @param user a User to restrict query results to.
212      */
213     public void filterOnUser(User user);
214 
215     /**
216      * Returns the thread that query results are restricted to. If the query
217      * is not restricted to messages in a certain thread, this method will
218      * return null.
219      *
220      * @return the thread that results are restricted to.
221      */
222     public ForumThread getFilteredThread();
223 
224     /**
225      * Restricts the querty results to messages posted in a specified thread.
226      *
227      * @param thread the ForumThread to restrict query results to.
228      */
229     public void filterOnThread(ForumThread thread);
230 
231     /**
232      * Returns the total number of results of the query.
233      *
234      * @return the number of results of the query.
235      */
236     public int resultCount();
237 
238     /**
239      * Returns the results of the Query as an Iterator of ForumMessage objects.
240      *
241      * @return the result of the query as an Iterator.
242      */
243     public Iterator   results();
244 
245     /**
246      * Returns the results of the Query as an Iterator of ForumMessage objects.
247      * The startIndex and numResults paramaters are used to look at a certain
248      * range of the results. For example, the first twenty results, the second
249      * twenty results, etc. This is useful for user interface with multiple
250      * pages of results.<p>
251      *
252      * If startIndex or numResults does not fall within the range of results,
253      * the number of messages returned may be smaller than expected. For
254      * example, suppose a query has a total of 17 results. If startIndex
255      * is 0 and numResults is 25, only 17 results can be returned.
256      *
257      * @param startIndex the index in the results that the iterator will start at.
258      * @param numResuls the max number of results that should be returned.
259      * @return the result of the query as an Iterator.
260      */
261     public Iterator   results(int startIndex, int numResults);
262 }
263
A to Z: JavaDoc & Examples Daily Java News & Articles Open Source Projects Open Source Codes Free Computer Books Remove Frame
Popular Tags