001: package org.apache.lucene.search;
002:
003: /**
004: * Licensed to the Apache Software Foundation (ASF) under one or more
005: * contributor license agreements. See the NOTICE file distributed with
006: * this work for additional information regarding copyright ownership.
007: * The ASF licenses this file to You under the Apache License, Version 2.0
008: * (the "License"); you may not use this file except in compliance with
009: * the License. You may obtain a copy of the License at
010: *
011: * http://www.apache.org/licenses/LICENSE-2.0
012: *
013: * Unless required by applicable law or agreed to in writing, software
014: * distributed under the License is distributed on an "AS IS" BASIS,
015: * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
016: * See the License for the specific language governing permissions and
017: * limitations under the License.
018: */
019:
020: import java.io.Serializable;
021:
022: /**
023: * Encapsulates sort criteria for returned hits.
024: *
025: * <p>The fields used to determine sort order must be carefully chosen.
026: * Documents must contain a single term in such a field,
027: * and the value of the term should indicate the document's relative position in
028: * a given sort order. The field must be indexed, but should not be tokenized,
029: * and does not need to be stored (unless you happen to want it back with the
030: * rest of your document data). In other words:
031: *
032: * <p><code>document.add (new Field ("byNumber", Integer.toString(x), Field.Store.NO, Field.Index.UN_TOKENIZED));</code></p>
033: *
034: *
035: * <p><h3>Valid Types of Values</h3>
036: *
037: * <p>There are four possible kinds of term values which may be put into
038: * sorting fields: Integers, Longs, Floats, or Strings. Unless
039: * {@link SortField SortField} objects are specified, the type of value
040: * in the field is determined by parsing the first term in the field.
041: *
042: * <p>Integer term values should contain only digits and an optional
043: * preceding negative sign. Values must be base 10 and in the range
044: * <code>Integer.MIN_VALUE</code> and <code>Integer.MAX_VALUE</code> inclusive.
045: * Documents which should appear first in the sort
046: * should have low value integers, later documents high values
047: * (i.e. the documents should be numbered <code>1..n</code> where
048: * <code>1</code> is the first and <code>n</code> the last).
049: *
050: * <p>Long term values should contain only digits and an optional
051: * preceding negative sign. Values must be base 10 and in the range
052: * <code>Long.MIN_VALUE</code> and <code>Long.MAX_VALUE</code> inclusive.
053: * Documents which should appear first in the sort
054: * should have low value integers, later documents high values.
055: *
056: * <p>Float term values should conform to values accepted by
057: * {@link Float Float.valueOf(String)} (except that <code>NaN</code>
058: * and <code>Infinity</code> are not supported).
059: * Documents which should appear first in the sort
060: * should have low values, later documents high values.
061: *
062: * <p>String term values can contain any valid String, but should
063: * not be tokenized. The values are sorted according to their
064: * {@link Comparable natural order}. Note that using this type
065: * of term value has higher memory requirements than the other
066: * two types.
067: *
068: * <p><h3>Object Reuse</h3>
069: *
070: * <p>One of these objects can be
071: * used multiple times and the sort order changed between usages.
072: *
073: * <p>This class is thread safe.
074: *
075: * <p><h3>Memory Usage</h3>
076: *
077: * <p>Sorting uses of caches of term values maintained by the
078: * internal HitQueue(s). The cache is static and contains an integer
079: * or float array of length <code>IndexReader.maxDoc()</code> for each field
080: * name for which a sort is performed. In other words, the size of the
081: * cache in bytes is:
082: *
083: * <p><code>4 * IndexReader.maxDoc() * (# of different fields actually used to sort)</code>
084: *
085: * <p>For String fields, the cache is larger: in addition to the
086: * above array, the value of every term in the field is kept in memory.
087: * If there are many unique terms in the field, this could
088: * be quite large.
089: *
090: * <p>Note that the size of the cache is not affected by how many
091: * fields are in the index and <i>might</i> be used to sort - only by
092: * the ones actually used to sort a result set.
093: *
094: * <p>Created: Feb 12, 2004 10:53:57 AM
095: *
096: * @author Tim Jones (Nacimiento Software)
097: * @since lucene 1.4
098: * @version $Id: Sort.java 598376 2007-11-26 18:45:39Z dnaber $
099: */
100: public class Sort implements Serializable {
101:
102: /**
103: * Represents sorting by computed relevance. Using this sort criteria returns
104: * the same results as calling
105: * {@link Searcher#search(Query) Searcher#search()}without a sort criteria,
106: * only with slightly more overhead.
107: */
108: public static final Sort RELEVANCE = new Sort();
109:
110: /** Represents sorting by index order. */
111: public static final Sort INDEXORDER = new Sort(SortField.FIELD_DOC);
112:
113: // internal representation of the sort criteria
114: SortField[] fields;
115:
116: /**
117: * Sorts by computed relevance. This is the same sort criteria as calling
118: * {@link Searcher#search(Query) Searcher#search()}without a sort criteria,
119: * only with slightly more overhead.
120: */
121: public Sort() {
122: this (new SortField[] { SortField.FIELD_SCORE,
123: SortField.FIELD_DOC });
124: }
125:
126: /**
127: * Sorts by the terms in <code>field</code> then by index order (document
128: * number). The type of value in <code>field</code> is determined
129: * automatically.
130: *
131: * @see SortField#AUTO
132: */
133: public Sort(String field) {
134: setSort(field, false);
135: }
136:
137: /**
138: * Sorts possibly in reverse by the terms in <code>field</code> then by
139: * index order (document number). The type of value in <code>field</code> is
140: * determined automatically.
141: *
142: * @see SortField#AUTO
143: */
144: public Sort(String field, boolean reverse) {
145: setSort(field, reverse);
146: }
147:
148: /**
149: * Sorts in succession by the terms in each field. The type of value in
150: * <code>field</code> is determined automatically.
151: *
152: * @see SortField#AUTO
153: */
154: public Sort(String[] fields) {
155: setSort(fields);
156: }
157:
158: /** Sorts by the criteria in the given SortField. */
159: public Sort(SortField field) {
160: setSort(field);
161: }
162:
163: /** Sorts in succession by the criteria in each SortField. */
164: public Sort(SortField[] fields) {
165: setSort(fields);
166: }
167:
168: /**
169: * Sets the sort to the terms in <code>field</code> then by index order
170: * (document number).
171: */
172: public final void setSort(String field) {
173: setSort(field, false);
174: }
175:
176: /**
177: * Sets the sort to the terms in <code>field</code> possibly in reverse,
178: * then by index order (document number).
179: */
180: public void setSort(String field, boolean reverse) {
181: SortField[] nfields = new SortField[] {
182: new SortField(field, SortField.AUTO, reverse),
183: SortField.FIELD_DOC };
184: fields = nfields;
185: }
186:
187: /** Sets the sort to the terms in each field in succession. */
188: public void setSort(String[] fieldnames) {
189: final int n = fieldnames.length;
190: SortField[] nfields = new SortField[n];
191: for (int i = 0; i < n; ++i) {
192: nfields[i] = new SortField(fieldnames[i], SortField.AUTO);
193: }
194: fields = nfields;
195: }
196:
197: /** Sets the sort to the given criteria. */
198: public void setSort(SortField field) {
199: this .fields = new SortField[] { field };
200: }
201:
202: /** Sets the sort to the given criteria in succession. */
203: public void setSort(SortField[] fields) {
204: this .fields = fields;
205: }
206:
207: /**
208: * Representation of the sort criteria.
209: * @return Array of SortField objects used in this sort criteria
210: */
211: public SortField[] getSort() {
212: return fields;
213: }
214:
215: public String toString() {
216: StringBuffer buffer = new StringBuffer();
217:
218: for (int i = 0; i < fields.length; i++) {
219: buffer.append(fields[i].toString());
220: if ((i + 1) < fields.length)
221: buffer.append(',');
222: }
223:
224: return buffer.toString();
225: }
226: }
|