You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@lucene.apache.org by rm...@apache.org on 2014/03/06 20:04:41 UTC
svn commit: r1575008 - in
/lucene/dev/branches/lucene5493/lucene/misc/src/java/org/apache/lucene/index/sorter:
BlockJoinComparatorSource.java EarlyTerminatingSortingCollector.java
SortingMergePolicy.java
Author: rmuir
Date: Thu Mar 6 19:04:40 2014
New Revision: 1575008
URL: http://svn.apache.org/r1575008
Log:
LUCENE-5493: javadocs cleanups
Modified:
lucene/dev/branches/lucene5493/lucene/misc/src/java/org/apache/lucene/index/sorter/BlockJoinComparatorSource.java
lucene/dev/branches/lucene5493/lucene/misc/src/java/org/apache/lucene/index/sorter/EarlyTerminatingSortingCollector.java
lucene/dev/branches/lucene5493/lucene/misc/src/java/org/apache/lucene/index/sorter/SortingMergePolicy.java
Modified: lucene/dev/branches/lucene5493/lucene/misc/src/java/org/apache/lucene/index/sorter/BlockJoinComparatorSource.java
URL: http://svn.apache.org/viewvc/lucene/dev/branches/lucene5493/lucene/misc/src/java/org/apache/lucene/index/sorter/BlockJoinComparatorSource.java?rev=1575008&r1=1575007&r2=1575008&view=diff
==============================================================================
--- lucene/dev/branches/lucene5493/lucene/misc/src/java/org/apache/lucene/index/sorter/BlockJoinComparatorSource.java (original)
+++ lucene/dev/branches/lucene5493/lucene/misc/src/java/org/apache/lucene/index/sorter/BlockJoinComparatorSource.java Thu Mar 6 19:04:40 2014
@@ -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.FixedBitSe
/**
* Helper class to sort readers that contain blocks of documents.
* <p>
- * 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:
* <ul>
- * <li>Cannot yet be used with IndexSearcher.searchAfter
- * <li>Filling sort value fields is not yet supported.
+ * <li>Cannot yet be used with {@link IndexSearcher#searchAfter(ScoreDoc, Query, int, Sort) IndexSearcher.searchAfter}
+ * <li>Filling sort field values is not yet supported.
* </ul>
- * 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 e
@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
Modified: lucene/dev/branches/lucene5493/lucene/misc/src/java/org/apache/lucene/index/sorter/EarlyTerminatingSortingCollector.java
URL: http://svn.apache.org/viewvc/lucene/dev/branches/lucene5493/lucene/misc/src/java/org/apache/lucene/index/sorter/EarlyTerminatingSortingCollector.java?rev=1575008&r1=1575007&r2=1575008&view=diff
==============================================================================
--- lucene/dev/branches/lucene5493/lucene/misc/src/java/org/apache/lucene/index/sorter/EarlyTerminatingSortingCollector.java (original)
+++ lucene/dev/branches/lucene5493/lucene/misc/src/java/org/apache/lucene/index/sorter/EarlyTerminatingSortingCollector.java Thu Mar 6 19:04:40 2014
@@ -34,41 +34,43 @@ import org.apache.lucene.search.TotalHit
* {@link Sort}.
*
* <p>
- * <b>NOTE:</b> the {@link Collector} detects sorted segments according to
+ * <b>NOTE:</b> 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}.
* <p>
- * <b>NOTE</b>: If you wrap a {@link TopDocsCollector} that sorts in the same
- * order as the index order, the returned {@link TopDocsCollector#topDocs()}
+ * <b>NOTE</b>: 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.
* <p>
- * <b>NOTE</b>: 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
+ * <b>NOTE</b>: This {@code Collector} uses {@link Sort#toString()} to detect
+ * whether a segment was sorted with the same {@code Sort}. This has
* two implications:
* <ul>
* <li>if a custom comparator is not implemented correctly and returns
* different identifiers for equivalent instances, this collector will not
* detect sorted segments,</li>
* <li>if you suddenly change the {@link IndexWriter}'s
- * {@link SortingMergePolicy} to sort according to another criterion and if both
- * the old and the new {@link Sort}s have the same identifier, this
- * {@link Collector} will incorrectly detect sorted segments.</li>
+ * {@code SortingMergePolicy} to sort according to another criterion and if both
+ * the old and the new {@code Sort}s have the same identifier, this
+ * {@code Collector} will incorrectly detect sorted segments.</li>
* </ul>
*
* @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;
Modified: lucene/dev/branches/lucene5493/lucene/misc/src/java/org/apache/lucene/index/sorter/SortingMergePolicy.java
URL: http://svn.apache.org/viewvc/lucene/dev/branches/lucene5493/lucene/misc/src/java/org/apache/lucene/index/sorter/SortingMergePolicy.java?rev=1575008&r1=1575007&r2=1575008&view=diff
==============================================================================
--- lucene/dev/branches/lucene5493/lucene/misc/src/java/org/apache/lucene/index/sorter/SortingMergePolicy.java (original)
+++ lucene/dev/branches/lucene5493/lucene/misc/src/java/org/apache/lucene/index/sorter/SortingMergePolicy.java Thu Mar 6 19:04:40 2014
@@ -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.Mon
* 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.
- * <p><b>NOTE</b>: Never use this {@link MergePolicy} if you rely on
- * {@link IndexWriter#addDocuments(Iterable, org.apache.lucene.analysis.Analyzer)}
+ * <p><b>NOTE</b>: 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.
- * <p><b>NOTE</b>: 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.
+ * <p><b>NOTE</b>: 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 ex
}
- /** 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 ex
final Sorter sorter;
final Sort sort;
- /** Create a new {@link MergePolicy} that sorts documents with <code>sort</code>. */
+ /** 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);