Sort


1   package org.apache.lucene.search;
2   
3   /**
4    * Copyright 2004 The Apache Software Foundation
5    *
6    * Licensed under the Apache License, Version 2.0 (the "License");
7    * you may not use this file except in compliance with the License.
8    * You may obtain a copy of the License at
9    *
10   *     http://www.apache.org/licenses/LICENSE-2.0
11   *
12   * Unless required by applicable law or agreed to in writing, software
13   * distributed under the License is distributed on an "AS IS" BASIS,
14   * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
15   * See the License for the specific language governing permissions and
16   * limitations under the License.
17   */
18  
19  import java.io.Serializable  ;
20  
21  
22  /**
23   * Encapsulates sort criteria for returned hits.
24   *
25   * <p>The fields used to determine sort order must be carefully chosen.
26   * Documents must contain a single term in such a field,
27   * and the value of the term should indicate the document's relative position in
28   * a given sort order.  The field must be indexed, but should not be tokenized,
29   * and does not need to be stored (unless you happen to want it back with the
30   * rest of your document data).  In other words:
31   *
32   * <p><code>document.add (new Field ("byNumber", Integer.toString(x), Field.Store.NO, Field.Index.UN_TOKENIZED));</code></p>
33   * 
34   *
35   * <p><h3>Valid Types of Values</h3>
36   *
37   * <p>There are three possible kinds of term values which may be put into
38   * sorting fields: Integers, Floats, or Strings.  Unless
39   * {@link SortField SortField} objects are specified, the type of value
40   * in the field is determined by parsing the first term in the field.
41   *
42   * <p>Integer term values should contain only digits and an optional
43   * preceeding negative sign.  Values must be base 10 and in the range
44   * <code>Integer.MIN_VALUE</code> and <code>Integer.MAX_VALUE</code> inclusive.
45   * Documents which should appear first in the sort
46   * should have low value integers, later documents high values
47   * (i.e. the documents should be numbered <code>1..n</code> where
48   * <code>1</code> is the first and <code>n</code> the last).
49   *
50   * <p>Float term values should conform to values accepted by
51   * {@link Float Float.valueOf(String)} (except that <code>NaN</code>
52   * and <code>Infinity</code> are not supported).
53   * Documents which should appear first in the sort
54   * should have low values, later documents high values.
55   *
56   * <p>String term values can contain any valid String, but should
57   * not be tokenized.  The values are sorted according to their
58   * {@link Comparable natural order}.  Note that using this type
59   * of term value has higher memory requirements than the other
60   * two types.
61   *
62   * <p><h3>Object Reuse</h3>
63   *
64   * <p>One of these objects can be
65   * used multiple times and the sort order changed between usages.
66   *
67   * <p>This class is thread safe.
68   *
69   * <p><h3>Memory Usage</h3>
70   *
71   * <p>Sorting uses of caches of term values maintained by the
72   * internal HitQueue(s).  The cache is static and contains an integer
73   * or float array of length <code>IndexReader.maxDoc()</code> for each field
74   * name for which a sort is performed.  In other words, the size of the
75   * cache in bytes is:
76   *
77   * <p><code>4 * IndexReader.maxDoc() * (# of different fields actually used to sort)</code>
78   *
79   * <p>For String fields, the cache is larger: in addition to the
80   * above array, the value of every term in the field is kept in memory.
81   * If there are many unique terms in the field, this could
82   * be quite large.
83   *
84   * <p>Note that the size of the cache is not affected by how many
85   * fields are in the index and <i>might</i> be used to sort - only by
86   * the ones actually used to sort a result set.
87   *
88   * <p>The cache is cleared each time a new <code>IndexReader</code> is
89   * passed in, or if the value returned by <code>maxDoc()</code>
90   * changes for the current IndexReader.  This class is not set up to
91   * be able to efficiently sort hits from more than one index
92   * simultaneously.
93   *
94   * <p>Created: Feb 12, 2004 10:53:57 AM
95   *
96   * @author  Tim Jones (Nacimiento Software)
97   * @since   lucene 1.4
98   * @version $Id: Sort.java 150618 2004-10-18 22:36:54Z dnaber $
99   */
100 public class Sort
101 implements Serializable   {
102 
103   /**
104    * Represents sorting by computed relevance. Using this sort criteria returns
105    * the same results as calling
106    * {@link Searcher#search(Query) Searcher#search()}without a sort criteria,
107    * only with slightly more overhead.
108    */
109   public static final Sort RELEVANCE = new Sort();
110 
111   /** Represents sorting by index order. */
112   public static final Sort INDEXORDER = new Sort(SortField.FIELD_DOC);
113 
114   // internal representation of the sort criteria
115   SortField[] fields;
116 
117   /**
118    * Sorts by computed relevance. This is the same sort criteria as calling
119    * {@link Searcher#search(Query) Searcher#search()}without a sort criteria,
120    * only with slightly more overhead.
121    */
122   public Sort() {
123     this(new SortField[] { SortField.FIELD_SCORE, 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), SortField.FIELD_DOC };
183     fields = nfields;
184   }
185 
186   /** Sets the sort to the terms in each field in succession. */
187   public void setSort(String  [] fieldnames) {
188     final int n = fieldnames.length;
189     SortField[] nfields = new SortField[n];
190     for (int i = 0; i < n; ++i) {
191       nfields[i] = new SortField(fieldnames[i], SortField.AUTO);
192     }
193     fields = nfields;
194   }
195 
196   /** Sets the sort to the given criteria. */
197   public void setSort(SortField field) {
198     this.fields = new SortField[] { field };
199   }
200 
201   /** Sets the sort to the given criteria in succession. */
202   public void setSort(SortField[] fields) {
203     this.fields = fields;
204   }
205   
206   /**
207    * Representation of the sort criteria.
208    * @return Array of SortField objects used in this sort criteria
209    */
210   public SortField[] getSort() {
211     return fields;
212   }
213 
214   public String   toString() {
215     StringBuffer   buffer = new StringBuffer  ();
216 
217     for (int i = 0; i < fields.length; i++) {
218       buffer.append(fields[i].toString());
219       if ((i+1) < fields.length)
220         buffer.append(',');
221     }
222 
223     return buffer.toString();
224   }
225 }
226
A to Z: JavaDoc & Examples Daily Java News & Articles Open Source Projects Open Source Codes Free Computer Books Remove Frame
Popular Tags