SortField.java
001 package gate.creole.annic.apache.lucene.search;
002 
003 /**
004  * Copyright 2004 The Apache Software Foundation
005  *
006  * Licensed under the Apache License, Version 2.0 (the "License");
007  * you may not use this file except in compliance with the License.
008  * You may obtain a copy of the License at
009  *
010  *     http://www.apache.org/licenses/LICENSE-2.0
011  *
012  * Unless required by applicable law or agreed to in writing, software
013  * distributed under the License is distributed on an "AS IS" BASIS,
014  * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
015  * See the License for the specific language governing permissions and
016  * limitations under the License.
017  */
018 
019 import java.io.Serializable;
020 import java.util.Locale;
021 
022 /**
023  * Stores information about how to sort documents by terms in an individual
024  * field.  Fields must be indexed in order to sort by them.
025  *
026  <p>Created: Feb 11, 2004 1:25:29 PM
027  *
028  @author  Tim Jones (Nacimiento Software)
029  @since   lucene 1.4
030  @version $Id: SortField.java 529 2004-10-05 11:55:26Z niraj $
031  @see Sort
032  */
033 @SuppressWarnings("serial")
034 public class SortField
035 implements Serializable {
036 
037   /** Sort by document score (relevancy).  Sort values are Float and higher
038    * values are at the front. */
039   public static final int SCORE = 0;
040 
041   /** Sort by document number (index order).  Sort values are Integer and lower
042    * values are at the front. */
043   public static final int DOC = 1;
044 
045   /** Guess type of sort based on field contents.  A regular expression is used
046    * to look at the first term indexed for the field and determine if it
047    * represents an integer number, a floating point number, or just arbitrary
048    * string characters. */
049   public static final int AUTO = 2;
050 
051   /** Sort using term values as Strings.  Sort values are String and lower
052    * values are at the front. */
053   public static final int STRING = 3;
054 
055   /** Sort using term values as encoded Integers.  Sort values are Integer and
056    * lower values are at the front. */
057   public static final int INT = 4;
058 
059   /** Sort using term values as encoded Floats.  Sort values are Float and
060    * lower values are at the front. */
061   public static final int FLOAT = 5;
062 
063   /** Sort using a custom Comparator.  Sort values are any Comparable and
064    * sorting is done according to natural order. */
065   public static final int CUSTOM = 9;
066 
067   // IMPLEMENTATION NOTE: the FieldCache.STRING_INDEX is in the same "namespace"
068   // as the above static int values.  Any new values must not have the same value
069   // as FieldCache.STRING_INDEX.
070 
071 
072   /** Represents sorting by document score (relevancy). */
073   public static final SortField FIELD_SCORE = new SortField (null, SCORE);
074 
075   /** Represents sorting by document number (index order). */
076   public static final SortField FIELD_DOC = new SortField (null, DOC);
077 
078 
079   private String field;
080   private int type = AUTO;  // defaults to determining type dynamically
081   private Locale locale;    // defaults to "natural order" (no Locale)
082   boolean reverse = false;  // defaults to natural order
083   private SortComparatorSource factory;
084 
085   /** Creates a sort by terms in the given field where the type of term value
086    * is determined dynamically ({@link #AUTO AUTO}).
087    @param field Name of field to sort by, cannot be <code>null</code>.
088    */
089   public SortField (String field) {
090     this.field = field.intern();
091   }
092 
093   /** Creates a sort, possibly in reverse, by terms in the given field where
094    * the type of term value is determined dynamically ({@link #AUTO AUTO}).
095    @param field Name of field to sort by, cannot be <code>null</code>.
096    @param reverse True if natural order should be reversed.
097    */
098   public SortField (String field, boolean reverse) {
099     this.field = field.intern();
100     this.reverse = reverse;
101   }
102 
103   /** Creates a sort by terms in the given field with the type of term
104    * values explicitly given.
105    @param field  Name of field to sort by.  Can be <code>null</code> if
106    *               <code>type</code> is SCORE or DOC.
107    @param type   Type of values in the terms.
108    */
109   public SortField (String field, int type) {
110     this.field = (field != null? field.intern() : field;
111     this.type = type;
112   }
113 
114   /** Creates a sort, possibly in reverse, by terms in the given field with the
115    * type of term values explicitly given.
116    @param field  Name of field to sort by.  Can be <code>null</code> if
117    *               <code>type</code> is SCORE or DOC.
118    @param type   Type of values in the terms.
119    @param reverse True if natural order should be reversed.
120    */
121   public SortField (String field, int type, boolean reverse) {
122     this.field = (field != null? field.intern() : field;
123     this.type = type;
124     this.reverse = reverse;
125   }
126 
127   /** Creates a sort by terms in the given field sorted
128    * according to the given locale.
129    @param field  Name of field to sort by, cannot be <code>null</code>.
130    @param locale Locale of values in the field.
131    */
132   public SortField (String field, Locale locale) {
133     this.field = field.intern();
134     this.type = STRING;
135     this.locale = locale;
136   }
137 
138   /** Creates a sort, possibly in reverse, by terms in the given field sorted
139    * according to the given locale.
140    @param field  Name of field to sort by, cannot be <code>null</code>.
141    @param locale Locale of values in the field.
142    */
143   public SortField (String field, Locale locale, boolean reverse) {
144     this.field = field.intern();
145     this.type = STRING;
146     this.locale = locale;
147     this.reverse = reverse;
148   }
149 
150   /** Creates a sort with a custom comparison function.
151    @param field Name of field to sort by; cannot be <code>null</code>.
152    @param comparator Returns a comparator for sorting hits.
153    */
154   public SortField (String field, SortComparatorSource comparator) {
155     this.field = (field != null? field.intern() : field;
156     this.type = CUSTOM;
157     this.factory = comparator;
158   }
159 
160   /** Creates a sort, possibly in reverse, with a custom comparison function.
161    @param field Name of field to sort by; cannot be <code>null</code>.
162    @param comparator Returns a comparator for sorting hits.
163    @param reverse True if natural order should be reversed.
164    */
165   public SortField (String field, SortComparatorSource comparator, boolean reverse) {
166     this.field = (field != null? field.intern() : field;
167     this.type = CUSTOM;
168     this.reverse = reverse;
169     this.factory = comparator;
170   }
171 
172   /** Returns the name of the field.  Could return <code>null</code>
173    * if the sort is by SCORE or DOC.
174    @return Name of field, possibly <code>null</code>.
175    */
176   public String getField() {
177     return field;
178   }
179 
180   /** Returns the type of contents in the field.
181    @return One of the constants SCORE, DOC, AUTO, STRING, INT or FLOAT.
182    */
183   public int getType() {
184     return type;
185   }
186 
187   /** Returns the Locale by which term values are interpreted.
188    * May return <code>null</code> if no Locale was specified.
189    @return Locale, or <code>null</code>.
190    */
191   public Locale getLocale() {
192     return locale;
193   }
194 
195   /** Returns whether the sort should be reversed.
196    @return  True if natural order should be reversed.
197    */
198   public boolean getReverse() {
199     return reverse;
200   }
201 
202   public SortComparatorSource getFactory() {
203     return factory;
204   }
205 
206   @Override
207   public String toString() {
208     StringBuffer buffer = new StringBuffer();
209     switch (type) {
210       case SCORE: buffer.append("<score>");
211                   break;
212 
213       case DOC: buffer.append("<doc>");
214                 break;
215 
216       case CUSTOM: buffer.append ("<custom:\"" + field + "\": "
217                                                + factory + ">");
218                 break;
219 
220       default: buffer.append("\"" + field + "\"");
221                break;
222     }
223 
224     if (locale != nullbuffer.append ("("+locale+")");
225     if (reversebuffer.append('!');
226 
227     return buffer.toString();
228   }
229 }