package org.apache.lucene.search;

/**
 * Copyright 2004 The Apache Software Foundation
 *
 * Licensed 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.
 */


/**
 * Expert: Compares two ScoreDoc objects for sorting.
 *
 * <p>Created: Feb 3, 2004 9:00:16 AM 
 * 
 * @author  Tim Jones (Nacimiento Software)
 * @since   lucene 1.4
 * @version $Id$
 */
public interface ScoreDocComparator {

	/** Special comparator for sorting hits according to computed relevance (document score). */
	static final ScoreDocComparator RELEVANCE = new ScoreDocComparator() {
		public int compare (ScoreDoc i, ScoreDoc j) {
			if (i.score > j.score) return -1;
			if (i.score < j.score) return 1;
			return 0;
		}
		public int compareReverse (ScoreDoc i, ScoreDoc j) {
			if (i.score < j.score) return -1;
			if (i.score > j.score) return 1;
			return 0;
		}
		public Comparable sortValue (ScoreDoc i) {
			return new Float (i.score);
		}
		public int sortType() {
			return SortField.SCORE;
		}
	};


	/** Special comparator for sorting hits according to index order (document number). */
	static final ScoreDocComparator INDEXORDER = new ScoreDocComparator() {
		public int compare (ScoreDoc i, ScoreDoc j) {
			if (i.doc < j.doc) return -1;
			if (i.doc > j.doc) return 1;
			return 0;
		}
		public int compareReverse (ScoreDoc i, ScoreDoc j) {
			if (i.doc > j.doc) return -1;
			if (i.doc < j.doc) return 1;
			return 0;
		}
		public Comparable sortValue (ScoreDoc i) {
			return new Integer (i.doc);
		}
		public int sortType() {
			return SortField.DOC;
		}
	};


	/**
	 * Compares two ScoreDoc objects and returns a result indicating their
	 * sort order.
	 * @param i First ScoreDoc
	 * @param j Second ScoreDoc
	 * @return <code>-1</code> if <code>i</code> should come before <code>j</code><br><code>1</code> if <code>i</code> should come after <code>j</code><br><code>0</code> if they are equal
	 * @see java.util.Comparator
	 */
	int compare (ScoreDoc i, ScoreDoc j);


	/**
	 * Compares two ScoreDoc objects and returns a result indicating their
	 * sort order in reverse.
	 * @param i First ScoreDoc
	 * @param j Second ScoreDoc
	 * @return <code>-1</code> if <code>i</code> should come before <code>j</code><br><code>1</code> if <code>i</code> should come after <code>j</code><br><code>0</code> if they are equal
	 * @see java.util.Comparator
	 */
	int compareReverse (ScoreDoc i, ScoreDoc j);


	/**
	 * Returns the value used to sort the given document.  The
	 * object returned must implement the java.io.Serializable
	 * interface.
	 * @param i Document
	 * @return Serializable object
	 */
	Comparable sortValue (ScoreDoc i);


	/**
	 * Returns the type of sort.
	 * @return One of the constants in SortField.
	 * @see SortField
	 */
	int sortType();
}
@@ -2638,33 +2638,33 @@
 /code%3E if %3Ccode%3E
-i
+j
 %3C/code%3E should c
@@ -2672,33 +2672,33 @@
 me before %3Ccode%3E
-j
+i
 %3C/code%3E%3Cbr%3E%3Ccode
@@ -2708,33 +2708,33 @@
 /code%3E if %3Ccode%3E
-i
+j
 %3C/code%3E should c
@@ -2741,33 +2741,33 @@
 ome after %3Ccode%3E
-j
+i
 %3C/code%3E%3Cbr%3E%3Ccode
@@ -3148,16 +3148,276 @@
 of sort.
+  Should return %3Ccode%3ESortField.SCORE%3C/code%3E, %3Ccode%3ESortField.DOC%3C/code%3E, %3Ccode%3ESortField.STRING%3C/code%3E, %3Ccode%3ESortField.INTEGER%3C/code%3E, %0A%09 * %3Ccode%3ESortField.FLOAT%3C/code%3E or %3Ccode%3ESortField.CUSTOM%3C/code%3E.  It is not valid to return %3Ccode%3ESortField.AUTO%3C/code%3E.
 %0A%09 * @re

fix javadocs