| package org.apache.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.IOException; |
| import java.io.Serializable; |
| import java.util.Locale; |
| |
| import org.apache.lucene.util.StringHelper; |
| |
| /** |
| * Stores information about how to sort documents by terms in an individual |
| * field. Fields must be indexed in order to sort by them. |
| * |
| * <p>Created: Feb 11, 2004 1:25:29 PM |
| * |
| * @since lucene 1.4 |
| * @see Sort |
| */ |
| public class SortField |
| implements Serializable { |
| |
| /** Sort by document score (relevance). Sort values are Float and higher |
| * values are at the front. */ |
| public static final int SCORE = 0; |
| |
| /** Sort by document number (index order). Sort values are Integer and lower |
| * values are at the front. */ |
| public static final int DOC = 1; |
| |
| // reserved, in Lucene 2.9, there was a constant: AUTO = 2; |
| |
| /** Sort using term values as Strings. Sort values are String and lower |
| * values are at the front. */ |
| public static final int STRING = 3; |
| |
| /** Sort using term values as encoded Integers. Sort values are Integer and |
| * lower values are at the front. */ |
| public static final int INT = 4; |
| |
| /** Sort using term values as encoded Floats. Sort values are Float and |
| * lower values are at the front. */ |
| public static final int FLOAT = 5; |
| |
| /** Sort using term values as encoded Longs. Sort values are Long and |
| * lower values are at the front. */ |
| public static final int LONG = 6; |
| |
| /** Sort using term values as encoded Doubles. Sort values are Double and |
| * lower values are at the front. */ |
| public static final int DOUBLE = 7; |
| |
| /** Sort using term values as encoded Shorts. Sort values are Short and |
| * lower values are at the front. */ |
| public static final int SHORT = 8; |
| |
| /** Sort using a custom Comparator. Sort values are any Comparable and |
| * sorting is done according to natural order. */ |
| public static final int CUSTOM = 9; |
| |
| /** Sort using term values as encoded Bytes. Sort values are Byte and |
| * lower values are at the front. */ |
| public static final int BYTE = 10; |
| |
| /** Sort using term values as Strings, but comparing by |
| * value (using String.compareTo) for all comparisons. |
| * This is typically slower than {@link #STRING}, which |
| * uses ordinals to do the sorting. */ |
| public static final int STRING_VAL = 11; |
| |
| // IMPLEMENTATION NOTE: the FieldCache.STRING_INDEX is in the same "namespace" |
| // as the above static int values. Any new values must not have the same value |
| // as FieldCache.STRING_INDEX. |
| |
| /** Represents sorting by document score (relevance). */ |
| public static final SortField FIELD_SCORE = new SortField(null, SCORE); |
| |
| /** Represents sorting by document number (index order). */ |
| public static final SortField FIELD_DOC = new SortField(null, DOC); |
| |
| private String field; |
| private int type; // defaults to determining type dynamically |
| private Locale locale; // defaults to "natural order" (no Locale) |
| boolean reverse = false; // defaults to natural order |
| private FieldCache.Parser parser; |
| |
| // Used for CUSTOM sort |
| private FieldComparatorSource comparatorSource; |
| |
| private Object missingValue; |
| |
| /** Creates a sort by terms in the given field with the type of term |
| * values explicitly given. |
| * @param field Name of field to sort by. Can be <code>null</code> if |
| * <code>type</code> is SCORE or DOC. |
| * @param type Type of values in the terms. |
| */ |
| public SortField(String field, int type) { |
| initFieldType(field, type); |
| } |
| |
| /** Creates a sort, possibly in reverse, by terms in the given field with the |
| * type of term values explicitly given. |
| * @param field Name of field to sort by. Can be <code>null</code> if |
| * <code>type</code> is SCORE or DOC. |
| * @param type Type of values in the terms. |
| * @param reverse True if natural order should be reversed. |
| */ |
| public SortField(String field, int type, boolean reverse) { |
| initFieldType(field, type); |
| this.reverse = reverse; |
| } |
| |
| /** Creates a sort by terms in the given field, parsed |
| * to numeric values using a custom {@link FieldCache.Parser}. |
| * @param field Name of field to sort by. Must not be null. |
| * @param parser Instance of a {@link FieldCache.Parser}, |
| * which must subclass one of the existing numeric |
| * parsers from {@link FieldCache}. Sort type is inferred |
| * by testing which numeric parser the parser subclasses. |
| * @throws IllegalArgumentException if the parser fails to |
| * subclass an existing numeric parser, or field is null |
| */ |
| public SortField(String field, FieldCache.Parser parser) { |
| this(field, parser, false); |
| } |
| |
| /** Creates a sort, possibly in reverse, by terms in the given field, parsed |
| * to numeric values using a custom {@link FieldCache.Parser}. |
| * @param field Name of field to sort by. Must not be null. |
| * @param parser Instance of a {@link FieldCache.Parser}, |
| * which must subclass one of the existing numeric |
| * parsers from {@link FieldCache}. Sort type is inferred |
| * by testing which numeric parser the parser subclasses. |
| * @param reverse True if natural order should be reversed. |
| * @throws IllegalArgumentException if the parser fails to |
| * subclass an existing numeric parser, or field is null |
| */ |
| public SortField(String field, FieldCache.Parser parser, boolean reverse) { |
| if (parser instanceof FieldCache.IntParser) initFieldType(field, INT); |
| else if (parser instanceof FieldCache.FloatParser) initFieldType(field, FLOAT); |
| else if (parser instanceof FieldCache.ShortParser) initFieldType(field, SHORT); |
| else if (parser instanceof FieldCache.ByteParser) initFieldType(field, BYTE); |
| else if (parser instanceof FieldCache.LongParser) initFieldType(field, LONG); |
| else if (parser instanceof FieldCache.DoubleParser) initFieldType(field, DOUBLE); |
| else |
| throw new IllegalArgumentException("Parser instance does not subclass existing numeric parser from FieldCache (got " + parser + ")"); |
| |
| this.reverse = reverse; |
| this.parser = parser; |
| } |
| |
| /** Creates a sort by terms in the given field sorted |
| * according to the given locale. |
| * @param field Name of field to sort by, cannot be <code>null</code>. |
| * @param locale Locale of values in the field. |
| */ |
| public SortField (String field, Locale locale) { |
| initFieldType(field, STRING); |
| this.locale = locale; |
| } |
| |
| /** Creates a sort, possibly in reverse, by terms in the given field sorted |
| * according to the given locale. |
| * @param field Name of field to sort by, cannot be <code>null</code>. |
| * @param locale Locale of values in the field. |
| */ |
| public SortField (String field, Locale locale, boolean reverse) { |
| initFieldType(field, STRING); |
| this.locale = locale; |
| this.reverse = reverse; |
| } |
| |
| /** Creates a sort with a custom comparison function. |
| * @param field Name of field to sort by; cannot be <code>null</code>. |
| * @param comparator Returns a comparator for sorting hits. |
| */ |
| public SortField(String field, FieldComparatorSource comparator) { |
| initFieldType(field, CUSTOM); |
| this.comparatorSource = comparator; |
| } |
| |
| /** Creates a sort, possibly in reverse, with a custom comparison function. |
| * @param field Name of field to sort by; cannot be <code>null</code>. |
| * @param comparator Returns a comparator for sorting hits. |
| * @param reverse True if natural order should be reversed. |
| */ |
| public SortField(String field, FieldComparatorSource comparator, boolean reverse) { |
| initFieldType(field, CUSTOM); |
| this.reverse = reverse; |
| this.comparatorSource = comparator; |
| } |
| |
| /** Set a default sorting value for documents which lacks one */ |
| public SortField setMissingValue(Object missingValue) { |
| if (type != BYTE && type != SHORT && type != INT && type != FLOAT && type != LONG && type != DOUBLE) { |
| throw new IllegalArgumentException( "Missing value only works for numeric types" ); |
| } |
| this.missingValue = missingValue; |
| |
| return this; |
| } |
| |
| // Sets field & type, and ensures field is not NULL unless |
| // type is SCORE or DOC |
| private void initFieldType(String field, int type) { |
| this.type = type; |
| if (field == null) { |
| if (type != SCORE && type != DOC) |
| throw new IllegalArgumentException("field can only be null when type is SCORE or DOC"); |
| } else { |
| this.field = StringHelper.intern(field); |
| } |
| } |
| |
| /** Returns the name of the field. Could return <code>null</code> |
| * if the sort is by SCORE or DOC. |
| * @return Name of field, possibly <code>null</code>. |
| */ |
| public String getField() { |
| return field; |
| } |
| |
| /** Returns the type of contents in the field. |
| * @return One of the constants SCORE, DOC, STRING, INT or FLOAT. |
| */ |
| public int getType() { |
| return type; |
| } |
| |
| /** Returns the Locale by which term values are interpreted. |
| * May return <code>null</code> if no Locale was specified. |
| * @return Locale, or <code>null</code>. |
| */ |
| public Locale getLocale() { |
| return locale; |
| } |
| |
| /** Returns the instance of a {@link FieldCache} parser that fits to the given sort type. |
| * May return <code>null</code> if no parser was specified. Sorting is using the default parser then. |
| * @return An instance of a {@link FieldCache} parser, or <code>null</code>. |
| */ |
| public FieldCache.Parser getParser() { |
| return parser; |
| } |
| |
| /** Returns whether the sort should be reversed. |
| * @return True if natural order should be reversed. |
| */ |
| public boolean getReverse() { |
| return reverse; |
| } |
| |
| /** Returns the {@link FieldComparatorSource} used for |
| * custom sorting |
| */ |
| public FieldComparatorSource getComparatorSource() { |
| return comparatorSource; |
| } |
| |
| @Override |
| public String toString() { |
| StringBuilder buffer = new StringBuilder(); |
| switch (type) { |
| case SCORE: |
| buffer.append("<score>"); |
| break; |
| |
| case DOC: |
| buffer.append("<doc>"); |
| break; |
| |
| case STRING: |
| buffer.append("<string: \"").append(field).append("\">"); |
| break; |
| |
| case STRING_VAL: |
| buffer.append("<string_val: \"").append(field).append("\">"); |
| break; |
| |
| case BYTE: |
| buffer.append("<byte: \"").append(field).append("\">"); |
| break; |
| |
| case SHORT: |
| buffer.append("<short: \"").append(field).append("\">"); |
| break; |
| |
| case INT: |
| buffer.append("<int: \"").append(field).append("\">"); |
| break; |
| |
| case LONG: |
| buffer.append("<long: \"").append(field).append("\">"); |
| break; |
| |
| case FLOAT: |
| buffer.append("<float: \"").append(field).append("\">"); |
| break; |
| |
| case DOUBLE: |
| buffer.append("<double: \"").append(field).append("\">"); |
| break; |
| |
| case CUSTOM: |
| buffer.append("<custom:\"").append(field).append("\": ").append(comparatorSource).append('>'); |
| break; |
| |
| default: |
| buffer.append("<???: \"").append(field).append("\">"); |
| break; |
| } |
| |
| if (locale != null) buffer.append('(').append(locale).append(')'); |
| if (parser != null) buffer.append('(').append(parser).append(')'); |
| if (reverse) buffer.append('!'); |
| |
| return buffer.toString(); |
| } |
| |
| /** Returns true if <code>o</code> is equal to this. If a |
| * {@link FieldComparatorSource} or {@link |
| * FieldCache.Parser} was provided, it must properly |
| * implement equals (unless a singleton is always used). */ |
| @Override |
| public boolean equals(Object o) { |
| if (this == o) return true; |
| if (!(o instanceof SortField)) return false; |
| final SortField other = (SortField)o; |
| return ( |
| other.field == this.field // field is always interned |
| && other.type == this.type |
| && other.reverse == this.reverse |
| && (other.locale == null ? this.locale == null : other.locale.equals(this.locale)) |
| && (other.comparatorSource == null ? this.comparatorSource == null : other.comparatorSource.equals(this.comparatorSource)) |
| && (other.parser == null ? this.parser == null : other.parser.equals(this.parser)) |
| ); |
| } |
| |
| /** Returns true if <code>o</code> is equal to this. If a |
| * {@link FieldComparatorSource} or {@link |
| * FieldCache.Parser} was provided, it must properly |
| * implement hashCode (unless a singleton is always |
| * used). */ |
| @Override |
| public int hashCode() { |
| int hash=type^0x346565dd + Boolean.valueOf(reverse).hashCode()^0xaf5998bb; |
| if (field != null) hash += field.hashCode()^0xff5685dd; |
| if (locale != null) hash += locale.hashCode()^0x08150815; |
| if (comparatorSource != null) hash += comparatorSource.hashCode(); |
| if (parser != null) hash += parser.hashCode()^0x3aaf56ff; |
| return hash; |
| } |
| |
| // field must be interned after reading from stream |
| private void readObject(java.io.ObjectInputStream in) throws java.io.IOException, ClassNotFoundException { |
| in.defaultReadObject(); |
| if (field != null) |
| field = StringHelper.intern(field); |
| } |
| |
| /** Returns the {@link FieldComparator} to use for |
| * sorting. |
| * |
| * @lucene.experimental |
| * |
| * @param numHits number of top hits the queue will store |
| * @param sortPos position of this SortField within {@link |
| * Sort}. The comparator is primary if sortPos==0, |
| * secondary if sortPos==1, etc. Some comparators can |
| * optimize themselves when they are the primary sort. |
| * @return {@link FieldComparator} to use when sorting |
| */ |
| public FieldComparator getComparator(final int numHits, final int sortPos) throws IOException { |
| |
| if (locale != null) { |
| // TODO: it'd be nice to allow FieldCache.getStringIndex |
| // to optionally accept a Locale so sorting could then use |
| // the faster StringComparator impls |
| return new FieldComparator.StringComparatorLocale(numHits, field, locale); |
| } |
| |
| switch (type) { |
| case SortField.SCORE: |
| return new FieldComparator.RelevanceComparator(numHits); |
| |
| case SortField.DOC: |
| return new FieldComparator.DocComparator(numHits); |
| |
| case SortField.INT: |
| return new FieldComparator.IntComparator(numHits, field, parser, (Integer) missingValue); |
| |
| case SortField.FLOAT: |
| return new FieldComparator.FloatComparator(numHits, field, parser, (Float) missingValue); |
| |
| case SortField.LONG: |
| return new FieldComparator.LongComparator(numHits, field, parser, (Long) missingValue); |
| |
| case SortField.DOUBLE: |
| return new FieldComparator.DoubleComparator(numHits, field, parser, (Double) missingValue); |
| |
| case SortField.BYTE: |
| return new FieldComparator.ByteComparator(numHits, field, parser, (Byte) missingValue); |
| |
| case SortField.SHORT: |
| return new FieldComparator.ShortComparator(numHits, field, parser, (Short) missingValue); |
| |
| case SortField.CUSTOM: |
| assert comparatorSource != null; |
| return comparatorSource.newComparator(field, numHits, sortPos, reverse); |
| |
| case SortField.STRING: |
| return new FieldComparator.StringOrdValComparator(numHits, field, sortPos, reverse); |
| |
| case SortField.STRING_VAL: |
| return new FieldComparator.StringValComparator(numHits, field); |
| |
| default: |
| throw new IllegalStateException("Illegal sort type: " + type); |
| } |
| } |
| } |