001: /*
002: * Copyright 2004-2006 the original author or authors.
003: *
004: * Licensed under the Apache License, Version 2.0 (the "License");
005: * you may not use this file except in compliance with the License.
006: * You may obtain a copy of the License at
007: *
008: * http://www.apache.org/licenses/LICENSE-2.0
009: *
010: * Unless required by applicable law or agreed to in writing, software
011: * distributed under the License is distributed on an "AS IS" BASIS,
012: * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
013: * See the License for the specific language governing permissions and
014: * limitations under the License.
015: */
016:
017: package org.compass.core;
018:
019: import org.compass.core.util.Parameter;
020:
021: /**
022: * An object representing a Compass query. The query is created using the
023: * {@link org.compass.core.CompassQueryBuilder}, and used to get the
024: * matching {@link org.compass.core.CompassHits}.
025: * <p>
026: * The query be sorted as well using one of the <code>addSort</code>
027: * operations. Note that adding sorting is only applicable for the query that
028: * will execute the {@link #hits()} operation.
029: *
030: * @author kimchy
031: */
032: public interface CompassQuery {
033:
034: /**
035: * An extension to the {@link CompassQuery} interface. Handles special span
036: * queries.
037: *
038: * @author kimchy
039: */
040: public static interface CompassSpanQuery extends CompassQuery {
041:
042: }
043:
044: /**
045: * Used to set the sort direction for the query.
046: *
047: * @author kimchy
048: */
049: public static final class SortDirection extends Parameter {
050:
051: private static final long serialVersionUID = -1186862896088594504L;
052:
053: private SortDirection(String name) {
054: super (name);
055: }
056:
057: /**
058: * The default sort direction, which is descending for relevance type
059: * and increasing for all the rest.
060: */
061: public static final SortDirection AUTO = new SortDirection(
062: "AUTO");
063:
064: /**
065: * The reverse order of the <code>AUTO</code> order.
066: */
067: public static final SortDirection REVERSE = new SortDirection(
068: "REVERSE");
069:
070: }
071:
072: /**
073: * Used to define the type of the property that will be sorted. Note that
074: * <code>INT</code> has the lowest memorty requirements and
075: * <code>STRING</code> the most.
076: *
077: * @author kimchy
078: */
079: public static final class SortPropertyType extends Parameter {
080:
081: private static final long serialVersionUID = -7244219805458198332L;
082:
083: private SortPropertyType(String name) {
084: super (name);
085: }
086:
087: /**
088: * Guess type of sort based on proeprty contents. A regular expression
089: * is used to look at the first term indexed for the proeprty and
090: * determine if it represents an integer number, a floating point
091: * number, or just arbitrary string characters.
092: */
093: public static final SortPropertyType AUTO = new SortPropertyType(
094: "AUTO");
095:
096: /**
097: * Sort using term values as Strings. Sort values are String and lower
098: * values are at the front.
099: */
100: public static final SortPropertyType STRING = new SortPropertyType(
101: "STRING");
102:
103: /**
104: * Sort using term values as encoded Integers. Sort values are Integer
105: * and lower values are at the front.
106: */
107: public static final SortPropertyType INT = new SortPropertyType(
108: "INT");
109:
110: /**
111: * Sort using term values as encoded Floats. Sort values are Float and
112: * lower values are at the front.
113: */
114: public static final SortPropertyType FLOAT = new SortPropertyType(
115: "FLOAT");
116: }
117:
118: /**
119: * Implicit types that the hits can be sorted by.
120: *
121: * @author kimchy
122: */
123: public static final class SortImplicitType extends Parameter {
124:
125: private static final long serialVersionUID = -6280976433851973161L;
126:
127: private SortImplicitType(String name) {
128: super (name);
129: }
130:
131: /**
132: * Sort by resource score (relevancy). Sort values are Float and higher
133: * values are at the front.
134: */
135: public static final SortImplicitType SCORE = new SortImplicitType(
136: "SCORE");
137:
138: /**
139: * Sort by document number (index order). Sort values are Integer and
140: * lower values are at the front. Note, that if an updated occurs, the
141: * document number will be higher.
142: */
143: public static final SortImplicitType DOC = new SortImplicitType(
144: "DOC");
145: }
146:
147: /**
148: * Sets the boost for this query to <code>boost</code>. Hits matching
149: * this query will (in addition to the normal weightings) have their score
150: * multiplied by <code>boost</code>.
151: */
152: CompassQuery setBoost(float boost);
153:
154: /**
155: * Adds sorting on the given property name. The type of sorting will be
156: * identified automatically (though it is preferable to specify it in
157: * advance using the {@link #addSort(String,SortPropertyType)}.
158: * <p>
159: * Note that the property must be <code>UN_TOKENIZED</code>, and stored.
160: * <p>
161: * Note, that the sort option will only work on the outer most query (i.e.
162: * the one that the <code>hits</code> is called on).
163: *
164: * @param propertyName The property name that will be sorted.
165: */
166: CompassQuery addSort(String propertyName);
167:
168: /**
169: * Adds sorting on the given property name. The type of sorting will be
170: * identified automatically (though it is preferable to specify it in
171: * advance using the {@link #addSort(String,SortPropertyType)}.
172: * <p>
173: * Note that the property must be <code>UN_TOKENIZED</code>, and stored.
174: * <p>
175: * Note, that the sort option will only work on the outer most query (i.e.
176: * the one that the <code>hits</code> is called on).
177: *
178: * @param propertyName The property name that will be sorted.
179: * @param direction The direction for the sorting.
180: * @return the query
181: */
182: CompassQuery addSort(String propertyName, SortDirection direction);
183:
184: /**
185: * Adds sorting on the given property name, and using the given property
186: * type. Note that <code>INT</code> has the lowest memorty requirements
187: * and <code>STRING</code> the most.
188: * <p>
189: * Note that the property must be <code>UN_TOKENIZED</code>, and stored.
190: * <p>
191: * Note, that the sort option will only work on the outer most query (i.e.
192: * the one that the <code>hits</code> is called on).
193: *
194: * @param propertyName The property name that will be sorted.
195: * @param type The type of the propert.
196: * @return the query
197: */
198: CompassQuery addSort(String propertyName, SortPropertyType type);
199:
200: /**
201: * Adds sorting on the given property name, and using the given property
202: * type. Note that <code>INT</code> has the lowest memorty requirements
203: * and <code>STRING</code> the most.
204: * <p>
205: * Note that the property must be <code>UN_TOKENIZED</code>, and stored.
206: * <p>
207: * Note, that the sort option will only work on the outer most query (i.e.
208: * the one that the <code>hits</code> is called on).
209: *
210: * @param propertyName The property name that will be sorted.
211: * @param type The type of the propert.
212: * @param direction The direction of the sorting.
213: * @return the query
214: */
215: CompassQuery addSort(String propertyName, SortPropertyType type,
216: SortDirection direction);
217:
218: /**
219: * Adds sorting on implicit types, which are not direct properties values.
220: * <p>
221: * Note, that the sort option will only work on the outer most query (i.e.
222: * the one that the <code>hits</code> is called on).
223: *
224: * @param implicitType The implicit type to add sorting on.
225: */
226: CompassQuery addSort(SortImplicitType implicitType);
227:
228: /**
229: * Adds sorting on implicit types, which are not direct properties values.
230: * <p>
231: * Note, that the sort option will only work on the outer most query (i.e.
232: * the one that the <code>hits</code> is called on).
233: *
234: * @param implicitType The implicit type to add sorting on.
235: * @param direction The direction of the sorting.
236: */
237: CompassQuery addSort(SortImplicitType implicitType,
238: SortDirection direction);
239:
240: /**
241: * Narrows down the query to be executed only against the given sub indexes.
242: * If set to <code>null</code>, will use all sub indexes.
243: *
244: * @param subIndexes sub indexes the query will be executed against
245: * @return The query
246: */
247: CompassQuery setSubIndexes(String... subIndexes);
248:
249: /**
250: * Narrows down the query to be executed only against the given aliases.
251: * If set to <code>null</code>, will use all aliases.
252: *
253: * @param aliases aliases the query will be executed against
254: * @return th query
255: */
256: CompassQuery setAliases(String... aliases);
257:
258: /**
259: * Narrows down the query to be executed only against the given types.
260: * Internally will translate the classes to the relevant <b>root</b>
261: * aliases and call {@link #setAliases(String[])}.
262: *
263: * @param types class types the query will be executed against
264: * @return the query
265: */
266: CompassQuery setTypes(Class... types);
267:
268: /**
269: * Sets a filter to the query. Please see {@link CompassQueryFilterBuilder}.
270: *
271: * @param filter The filter for the query
272: * @return the query
273: */
274: CompassQuery setFilter(CompassQueryFilter filter);
275:
276: /**
277: * Returns the filter set using {@link #setFilter(CompassQueryFilter)}. <code>null</code>
278: * if none is set.
279: *
280: * @return The filter set using {@link #setFilter(CompassQueryFilter)}
281: */
282: CompassQueryFilter getFilter();
283:
284: /**
285: * Causes the query to be rewritten before executed to search.
286: */
287: CompassQuery rewrite();
288:
289: /**
290: * Returns the suggested query (based on spell check). If spell check is disabled
291: * the same query is returned.
292: *
293: * <p>In order to know if the query was actually replaced with a suggested one, call
294: * {@link CompassQuery#isSuggested()}.
295: */
296: CompassQuery getSuggestedQuery();
297:
298: /**
299: * Returns <code>true</code> if this is a suggested query. For example, when performing
300: * a search query with spell check enabled, then it will return <code>true</code> if the
301: * query was modified to correct some spelling mistakes.
302: */
303: boolean isSuggested();
304:
305: /**
306: * Performs the search and returns the hits that match the qeury.
307: */
308: CompassHits hits() throws CompassException;
309:
310: /**
311: * Returns the count of hits that match this query. Note, this will be faster than
312: * {@link CompassHitsOperations#length()}.
313: */
314: long count();
315:
316: /**
317: * Clones the given query.
318: */
319: Object clone() throws CloneNotSupportedException;
320: }
|