diff --git a/src/java/org/apache/lucene/search/FieldDoc.java b/src/java/org/apache/lucene/search/FieldDoc.java index 2e657e36a93..36b73204e77 100644 --- a/src/java/org/apache/lucene/search/FieldDoc.java +++ b/src/java/org/apache/lucene/search/FieldDoc.java @@ -19,34 +19,45 @@ package org.apache.lucene.search; /** * Expert: A ScoreDoc which also contains information about - * how to sort the referenced document. + * how to sort the referenced document. In addition to the + * document number and score, this object contains an array + * of values for the document from the field(s) used to sort. + * For example, if the sort criteria was to sort by fields + * "a", "b" then "c", the fields object array + * will have three elements, corresponding respectively to + * the term values for the document in fields "a", "b" and "c". + * The class of each element in the array will be either + * Integer, Float or String depending on the type of values + * in the terms of each field. + * + *

Created: Feb 11, 2004 1:23:38 PM * - *

Created: Feb 11, 2004 1:23:38 PM - * * @author Tim Jones (Nacimiento Software) * @since lucene 1.4 * @version $Id$ + * @see ScoreDoc * @see TopFieldDocs */ public class FieldDoc extends ScoreDoc { - /** The values which are used to sort the referenced document. - * The order of these will match the original sort criteria given by an - * Sort object. + /** Expert: The values which are used to sort the referenced document. + * The order of these will match the original sort criteria given by a + * Sort object. Each Object will be either an Integer, Float or String, + * depending on the type of values in the terms of the original field. * @see Sort * @see Searchable#search(Query,Filter,int,Sort) */ public Object[] fields; - /** Creates one of these objects with empty sort information. */ + /** Expert: Creates one of these objects with empty sort information. */ public FieldDoc (int doc, float score) { super (doc, score); } - /** Creates one of these objects with the given sort information. */ + /** Expert: Creates one of these objects with the given sort information. */ public FieldDoc (int doc, float score, Object[] fields) { super (doc, score); this.fields = fields; } -} +} \ No newline at end of file diff --git a/src/java/org/apache/lucene/search/Sort.java b/src/java/org/apache/lucene/search/Sort.java index d436d93c049..c134a553482 100644 --- a/src/java/org/apache/lucene/search/Sort.java +++ b/src/java/org/apache/lucene/search/Sort.java @@ -69,8 +69,28 @@ import java.io.Serializable; * *

Memory Usage

* - * See {@link FieldSortedHitQueue FieldSortedHitQueue} for - * information on the memory requirements of sorting hits. + *

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. + * + *

The cache is cleared each time a new IndexReader is + * passed in, or if the value returned by maxDoc() + * changes for the current IndexReader. This class is not set up to + * be able to efficiently sort hits from more than one index + * simultaneously. * *

Created: Feb 12, 2004 10:53:57 AM * @@ -82,9 +102,9 @@ public class Sort implements Serializable { /** Represents sorting by computed relevance. Using this sort criteria - * returns the same results with slightly more overhead as calling - * Searcher#search() without a sort criteria. */ - public static final Sort RELEVANCE = new Sort (); + * returns the same results as calling {@link Searcher#search(Query) 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); @@ -94,7 +114,7 @@ implements Serializable { /** Sorts by computed relevance. This is the same sort criteria as - * calling Searcher#search() without a sort criteria, only with + * calling {@link Searcher#search(Query) Searcher#search()} without a sort criteria, only with * slightly more overhead. */ public Sort() { this (new SortField[]{SortField.FIELD_SCORE, SortField.FIELD_DOC}); @@ -102,20 +122,30 @@ implements Serializable { /** Sorts by the terms in field then by index order (document - * number). */ + * number). The type of value in field is determined + * automatically. + * @see SortField#AUTO + */ public Sort (String field) { setSort (field, false); } /** Sorts possibly in reverse by the terms in field then by - * index order (document number). */ + * index order (document number). The type of value in field is determined + * automatically. + * @see SortField#AUTO + */ public Sort (String field, boolean reverse) { setSort (field, reverse); } - /** Sorts in succession by the terms in each field. */ + /** Sorts in succession by the terms in each field. + * The type of value in field is determined + * automatically. + * @see SortField#AUTO + */ public Sort (String[] fields) { setSort (fields); } diff --git a/src/java/org/apache/lucene/search/SortField.java b/src/java/org/apache/lucene/search/SortField.java index 1d712643fe1..acede19e389 100644 --- a/src/java/org/apache/lucene/search/SortField.java +++ b/src/java/org/apache/lucene/search/SortField.java @@ -27,6 +27,7 @@ import java.io.Serializable; * @author Tim Jones (Nacimiento Software) * @since lucene 1.4 * @version $Id$ + * @see Sort */ public class SortField implements Serializable {