diff --git a/lucene/misc/src/java/org/apache/lucene/index/sorter/BlockJoinComparatorSource.java b/lucene/misc/src/java/org/apache/lucene/index/sorter/BlockJoinComparatorSource.java index 3029bcab656..6d5ff0bdd89 100644 --- a/lucene/misc/src/java/org/apache/lucene/index/sorter/BlockJoinComparatorSource.java +++ b/lucene/misc/src/java/org/apache/lucene/index/sorter/BlockJoinComparatorSource.java @@ -24,6 +24,9 @@ import org.apache.lucene.search.DocIdSet; import org.apache.lucene.search.FieldComparator; import org.apache.lucene.search.FieldComparatorSource; import org.apache.lucene.search.Filter; +import org.apache.lucene.search.IndexSearcher; // javadocs +import org.apache.lucene.search.Query; // javadocs +import org.apache.lucene.search.ScoreDoc; // javadocs import org.apache.lucene.search.Scorer; import org.apache.lucene.search.Sort; import org.apache.lucene.search.SortField; @@ -32,12 +35,12 @@ import org.apache.lucene.util.FixedBitSet; /** * Helper class to sort readers that contain blocks of documents. *

- * Note that this currently has some limitations: + * Note that this class is intended to used with {@link SortingMergePolicy}, + * and for other purposes has some limitations: *

- * Its intended to be used with {@link SortingMergePolicy}. */ // TODO: can/should we clean this thing up (e.g. return a proper sort value) // and move to the join/ module? @@ -160,7 +163,7 @@ public class BlockJoinComparatorSource extends FieldComparatorSource { @Override public Integer value(int slot) { // really our sort "value" is more complex... - throw new UnsupportedOperationException(); + throw new UnsupportedOperationException("filling sort field values is not yet supported"); } @Override diff --git a/lucene/misc/src/java/org/apache/lucene/index/sorter/EarlyTerminatingSortingCollector.java b/lucene/misc/src/java/org/apache/lucene/index/sorter/EarlyTerminatingSortingCollector.java index fa032edc462..23772e18f23 100644 --- a/lucene/misc/src/java/org/apache/lucene/index/sorter/EarlyTerminatingSortingCollector.java +++ b/lucene/misc/src/java/org/apache/lucene/index/sorter/EarlyTerminatingSortingCollector.java @@ -34,41 +34,43 @@ import org.apache.lucene.search.TotalHitCountCollector; * {@link Sort}. * *

- * NOTE: the {@link Collector} detects sorted segments according to + * NOTE: the {@code Collector} detects sorted segments according to * {@link SortingMergePolicy}, so it's best used in conjunction with it. Also, - * it collects up to a specified num docs from each segment, and therefore is - * mostly suitable for use in conjunction with collectors such as + * it collects up to a specified {@code numDocsToCollect} from each segment, + * and therefore is mostly suitable for use in conjunction with collectors such as * {@link TopDocsCollector}, and not e.g. {@link TotalHitCountCollector}. *

- * NOTE: If you wrap a {@link TopDocsCollector} that sorts in the same - * order as the index order, the returned {@link TopDocsCollector#topDocs()} + * NOTE: If you wrap a {@code TopDocsCollector} that sorts in the same + * order as the index order, the returned {@link TopDocsCollector#topDocs() TopDocs} * will be correct. However the total of {@link TopDocsCollector#getTotalHits() * hit count} will be underestimated since not all matching documents will have * been collected. *

- * NOTE: This {@link Collector} uses {@link Sort#toString()} to detect - * whether a segment was sorted with the same {@link Sort} as the one given in - * {@link #EarlyTerminatingSortingCollector(Collector, Sort, int)}. This has + * NOTE: This {@code Collector} uses {@link Sort#toString()} to detect + * whether a segment was sorted with the same {@code Sort}. This has * two implications: *

* * @lucene.experimental */ public class EarlyTerminatingSortingCollector extends Collector { - + /** The wrapped Collector */ protected final Collector in; + /** Sort used to sort the search results */ protected final Sort sort; + /** Number of documents to collect in each segment */ protected final int numDocsToCollect; - + /** Number of documents to collect in the current segment being processed */ protected int segmentTotalCollect; + /** True if the current segment being processed is sorted by {@link #sort} */ protected boolean segmentSorted; private int numCollected; diff --git a/lucene/misc/src/java/org/apache/lucene/index/sorter/SortingMergePolicy.java b/lucene/misc/src/java/org/apache/lucene/index/sorter/SortingMergePolicy.java index 58263407e5d..8b11b689fd9 100644 --- a/lucene/misc/src/java/org/apache/lucene/index/sorter/SortingMergePolicy.java +++ b/lucene/misc/src/java/org/apache/lucene/index/sorter/SortingMergePolicy.java @@ -22,6 +22,7 @@ import java.util.Collections; import java.util.List; import java.util.Map; +import org.apache.lucene.analysis.Analyzer; // javadocs import org.apache.lucene.index.AtomicReader; import org.apache.lucene.index.IndexReader; import org.apache.lucene.index.IndexWriter; @@ -42,14 +43,14 @@ import org.apache.lucene.util.packed.MonotonicAppendingLongBuffer; * before merging them. As a consequence, all segments resulting from a merge * will be sorted while segments resulting from a flush will be in the order * in which documents have been added. - *

NOTE: Never use this {@link MergePolicy} if you rely on - * {@link IndexWriter#addDocuments(Iterable, org.apache.lucene.analysis.Analyzer)} + *

NOTE: Never use this policy if you rely on + * {@link IndexWriter#addDocuments(Iterable, Analyzer) IndexWriter.addDocuments} * to have sequentially-assigned doc IDs, this policy will scatter doc IDs. - *

NOTE: This {@link MergePolicy} should only be used with idempotent - * {@link Sort}s so that the order of segments is predictable. For example, - * using {@link SortingMergePolicy} with {@link Sort#INDEXORDER in reverse} (which is - * not idempotent) will make the order of documents in a segment depend on the - * number of times the segment has been merged. + *

NOTE: This policy should only be used with idempotent {@code Sort}s + * so that the order of segments is predictable. For example, using + * {@link Sort#INDEXORDER} in reverse (which is not idempotent) will make + * the order of documents in a segment depend on the number of times the segment + * has been merged. * @lucene.experimental */ public final class SortingMergePolicy extends MergePolicy { @@ -148,7 +149,7 @@ public final class SortingMergePolicy extends MergePolicy { } - /** Returns true if the given reader is sorted by the given sort. */ + /** Returns {@code true} if the given {@code reader} is sorted by the specified {@code sort}. */ public static boolean isSorted(AtomicReader reader, Sort sort) { if (reader instanceof SegmentReader) { final SegmentReader segReader = (SegmentReader) reader; @@ -175,7 +176,7 @@ public final class SortingMergePolicy extends MergePolicy { final Sorter sorter; final Sort sort; - /** Create a new {@link MergePolicy} that sorts documents with sort. */ + /** Create a new {@code MergePolicy} that sorts documents with the given {@code sort}. */ public SortingMergePolicy(MergePolicy in, Sort sort) { this.in = in; this.sorter = new Sorter(sort);