org.trypticon.luceneupgrader.lucene3.internal.lucene.search.Sort Maven / Gradle / Ivy
package org.trypticon.luceneupgrader.lucene3.internal.lucene.search;
/**
* Licensed to the Apache Software Foundation (ASF) under one or more
* contributor license agreements. See the NOTICE file distributed with
* this work for additional information regarding copyright ownership.
* The ASF licenses this file to You under the Apache License, Version 2.0
* (the "License"); you may not use this file except in compliance with
* the License. You may obtain a copy of the License at
*
* http://www.apache.org/licenses/LICENSE-2.0
*
* Unless required by applicable law or agreed to in writing, software
* distributed under the License is distributed on an "AS IS" BASIS,
* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
* See the License for the specific language governing permissions and
* limitations under the License.
*/
import java.io.Serializable;
import java.util.Arrays;
/**
* Encapsulates sort criteria for returned hits.
*
* The fields used to determine sort order must be carefully chosen.
* Documents must contain a single term in such a field,
* and the value of the term should indicate the document's relative position in
* a given sort order. The field must be indexed, but should not be tokenized,
* and does not need to be stored (unless you happen to want it back with the
* rest of your document data). In other words:
*
*
document.add (new Field ("byNumber", Integer.toString(x), Field.Store.NO, Field.Index.NOT_ANALYZED));
*
*
* Valid Types of Values
*
* There are four possible kinds of term values which may be put into
* sorting fields: Integers, Longs, Floats, or Strings. Unless
* {@link SortField SortField} objects are specified, the type of value
* in the field is determined by parsing the first term in the field.
*
*
Integer term values should contain only digits and an optional
* preceding negative sign. Values must be base 10 and in the range
* Integer.MIN_VALUE and Integer.MAX_VALUE inclusive.
* Documents which should appear first in the sort
* should have low value integers, later documents high values
* (i.e. the documents should be numbered 1..n where
* 1 is the first and n the last).
*
*
Long term values should contain only digits and an optional
* preceding negative sign. Values must be base 10 and in the range
* Long.MIN_VALUE and Long.MAX_VALUE inclusive.
* Documents which should appear first in the sort
* should have low value integers, later documents high values.
*
*
Float term values should conform to values accepted by
* {@link Float Float.valueOf(String)} (except that NaN
* and Infinity are not supported).
* Documents which should appear first in the sort
* should have low values, later documents high values.
*
*
String term values can contain any valid String, but should
* not be tokenized. The values are sorted according to their
* {@link Comparable natural order}. Note that using this type
* of term value has higher memory requirements than the other
* two types.
*
*
Object Reuse
*
* One of these objects can be
* used multiple times and the sort order changed between usages.
*
*
This class is thread safe.
*
*
Memory Usage
*
* Sorting uses of caches of term values maintained by the
* internal HitQueue(s). The cache is static and contains an integer
* or float array of length IndexReader.maxDoc() for each field
* name for which a sort is performed. In other words, the size of the
* cache in bytes is:
*
*
4 * IndexReader.maxDoc() * (# of different fields actually used to sort)
*
*
For String fields, the cache is larger: in addition to the
* above array, the value of every term in the field is kept in memory.
* If there are many unique terms in the field, this could
* be quite large.
*
*
Note that the size of the cache is not affected by how many
* fields are in the index and might be used to sort - only by
* the ones actually used to sort a result set.
*
*
Created: Feb 12, 2004 10:53:57 AM
*
* @since lucene 1.4
*/
public class Sort
implements Serializable {
/**
* Represents sorting by computed relevance. Using this sort criteria returns
* the same results as calling
* {@link Searcher#search(Query,int) Searcher#search()}without a sort criteria,
* only with slightly more overhead.
*/
public static final Sort RELEVANCE = new Sort();
/** Represents sorting by index order. */
public static final Sort INDEXORDER = new Sort(SortField.FIELD_DOC);
// internal representation of the sort criteria
SortField[] fields;
/**
* Sorts by computed relevance. This is the same sort criteria as calling
* {@link Searcher#search(Query,int) Searcher#search()}without a sort criteria,
* only with slightly more overhead.
*/
public Sort() {
this(SortField.FIELD_SCORE);
}
/** Sorts by the criteria in the given SortField. */
public Sort(SortField field) {
setSort(field);
}
/** Sorts in succession by the criteria in each SortField. */
public Sort(SortField... fields) {
setSort(fields);
}
/** Sets the sort to the given criteria. */
public void setSort(SortField field) {
this.fields = new SortField[] { field };
}
/** Sets the sort to the given criteria in succession. */
public void setSort(SortField... fields) {
this.fields = fields;
}
/**
* Representation of the sort criteria.
* @return Array of SortField objects used in this sort criteria
*/
public SortField[] getSort() {
return fields;
}
@Override
public String toString() {
StringBuilder buffer = new StringBuilder();
for (int i = 0; i < fields.length; i++) {
buffer.append(fields[i].toString());
if ((i+1) < fields.length)
buffer.append(',');
}
return buffer.toString();
}
/** Returns true if o is equal to this. */
@Override
public boolean equals(Object o) {
if (this == o) return true;
if (!(o instanceof Sort)) return false;
final Sort other = (Sort)o;
return Arrays.equals(this.fields, other.fields);
}
/** Returns a hash code value for this object. */
@Override
public int hashCode() {
return 0x45aaf665 + Arrays.hashCode(fields);
}
}