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 2013/01/25 19:58:00 UTC
svn commit: r1438647 - in
/lucene/dev/branches/lucene4547/lucene/core/src/java/org/apache/lucene/codecs:
DocValuesConsumer.java DocValuesFormat.java NormsFormat.java
lucene42/package.html
Author: rmuir
Date: Fri Jan 25 18:57:59 2013
New Revision: 1438647
URL: http://svn.apache.org/viewvc?rev=1438647&view=rev
Log:
javadocs
Modified:
lucene/dev/branches/lucene4547/lucene/core/src/java/org/apache/lucene/codecs/DocValuesConsumer.java
lucene/dev/branches/lucene4547/lucene/core/src/java/org/apache/lucene/codecs/DocValuesFormat.java
lucene/dev/branches/lucene4547/lucene/core/src/java/org/apache/lucene/codecs/NormsFormat.java
lucene/dev/branches/lucene4547/lucene/core/src/java/org/apache/lucene/codecs/lucene42/package.html
Modified: lucene/dev/branches/lucene4547/lucene/core/src/java/org/apache/lucene/codecs/DocValuesConsumer.java
URL: http://svn.apache.org/viewvc/lucene/dev/branches/lucene4547/lucene/core/src/java/org/apache/lucene/codecs/DocValuesConsumer.java?rev=1438647&r1=1438646&r2=1438647&view=diff
==============================================================================
--- lucene/dev/branches/lucene4547/lucene/core/src/java/org/apache/lucene/codecs/DocValuesConsumer.java (original)
+++ lucene/dev/branches/lucene4547/lucene/core/src/java/org/apache/lucene/codecs/DocValuesConsumer.java Fri Jan 25 18:57:59 2013
@@ -29,22 +29,67 @@ import org.apache.lucene.index.BinaryDoc
import org.apache.lucene.index.FieldInfo;
import org.apache.lucene.index.MergeState;
import org.apache.lucene.index.NumericDocValues;
+import org.apache.lucene.index.SegmentWriteState;
import org.apache.lucene.index.SortedDocValues;
import org.apache.lucene.util.Bits;
import org.apache.lucene.util.BytesRef;
import org.apache.lucene.util.FixedBitSet;
import org.apache.lucene.util.PriorityQueue;
-// prototype streaming DV api
+/**
+ * Abstract API that consumes numeric, binary and
+ * sorted docvalues. Concrete implementations of this
+ * actually do "something" with the docvalues (write it into
+ * the index in a specific format).
+ * <p>
+ * The lifecycle is:
+ * <ol>
+ * <li>DocValuesConsumer is created by
+ * {@link DocValuesFormat#fieldsConsumer(SegmentWriteState)} or
+ * {@link NormsFormat#normsConsumer(SegmentWriteState)}.
+ * <li>{@link #addNumericField}, {@link #addBinaryField},
+ * or {@link #addSortedField} are called for each Numeric,
+ * Binary, or Sorted docvalues field. The API is a "pull" rather
+ * than "push", and the implementation is free to iterate over the
+ * values multiple times ({@link Iterable#iterator()}).
+ * <li>After all fields are added, the consumer is {@link #close}d.
+ * </ol>
+ *
+ * @lucene.experimental
+ */
public abstract class DocValuesConsumer implements Closeable {
+ /**
+ * Writes numeric docvalues for a field.
+ * @param field field information
+ * @param values Iterable of numeric values (one for each document).
+ * @throws IOException if an I/O error occurred.
+ */
public abstract void addNumericField(FieldInfo field, Iterable<Number> values) throws IOException;
+ /**
+ * Writes binary docvalues for a field.
+ * @param field field information
+ * @param values Iterable of binary values (one for each document).
+ * @throws IOException if an I/O error occurred.
+ */
public abstract void addBinaryField(FieldInfo field, Iterable<BytesRef> values) throws IOException;
+ /**
+ * Writes pre-sorted binary docvalues for a field.
+ * @param field field information
+ * @param values Iterable of binary values in sorted order (deduplicated).
+ * @param docToOrd Iterable of ordinals (one for each document).
+ * @throws IOException if an I/O error occurred.
+ */
public abstract void addSortedField(FieldInfo field, Iterable<BytesRef> values, Iterable<Number> docToOrd) throws IOException;
- // dead simple impl: codec can optimize
+ /**
+ * Merges the numeric docvalues from <code>toMerge</code>.
+ * <p>
+ * The default implementation calls {@link #addNumericField}, passing
+ * an Iterable that merges and filters deleted documents on the fly.
+ */
public void mergeNumericField(FieldInfo fieldInfo, final MergeState mergeState, final List<NumericDocValues> toMerge) throws IOException {
addNumericField(fieldInfo,
@@ -113,7 +158,12 @@ public abstract class DocValuesConsumer
});
}
- // dead simple impl: codec can optimize
+ /**
+ * Merges the binary docvalues from <code>toMerge</code>.
+ * <p>
+ * The default implementation calls {@link #addBinaryField}, passing
+ * an Iterable that merges and filters deleted documents on the fly.
+ */
public void mergeBinaryField(FieldInfo fieldInfo, final MergeState mergeState, final List<BinaryDocValues> toMerge) throws IOException {
addBinaryField(fieldInfo,
@@ -319,6 +369,12 @@ public abstract class DocValuesConsumer
*/
}
+ /**
+ * Merges the sorted docvalues from <code>toMerge</code>.
+ * <p>
+ * The default implementation calls {@link #addSortedField}, passing
+ * an Iterable that merges ordinals and values and filters deleted documents .
+ */
public void mergeSortedField(FieldInfo fieldInfo, final MergeState mergeState, List<SortedDocValues> toMerge) throws IOException {
final SortedBytesMerger merger = new SortedBytesMerger();
Modified: lucene/dev/branches/lucene4547/lucene/core/src/java/org/apache/lucene/codecs/DocValuesFormat.java
URL: http://svn.apache.org/viewvc/lucene/dev/branches/lucene4547/lucene/core/src/java/org/apache/lucene/codecs/DocValuesFormat.java?rev=1438647&r1=1438646&r2=1438647&view=diff
==============================================================================
--- lucene/dev/branches/lucene4547/lucene/core/src/java/org/apache/lucene/codecs/DocValuesFormat.java (original)
+++ lucene/dev/branches/lucene4547/lucene/core/src/java/org/apache/lucene/codecs/DocValuesFormat.java Fri Jan 25 18:57:59 2013
@@ -18,12 +18,26 @@ package org.apache.lucene.codecs;
*/
import java.io.IOException;
+import java.util.ServiceLoader;
import java.util.Set;
import org.apache.lucene.index.SegmentReadState;
import org.apache.lucene.index.SegmentWriteState;
import org.apache.lucene.util.NamedSPILoader;
+/**
+ * Encodes/decodes per-document values.
+ * <p>
+ * Note, when extending this class, the name ({@link #getName}) may
+ * written into the index in certain configurations. In order for the segment
+ * to be read, the name must resolve to your implementation via {@link #forName(String)}.
+ * This method uses Java's
+ * {@link ServiceLoader Service Provider Interface} (SPI) to resolve format names.
+ * <p>
+ * If you implement your own format, make sure that it has a no-arg constructor
+ * so SPI can load it.
+ * @see ServiceLoader
+ * @lucene.experimental */
public abstract class DocValuesFormat implements NamedSPILoader.NamedSPI {
private static final NamedSPILoader<DocValuesFormat> loader =
Modified: lucene/dev/branches/lucene4547/lucene/core/src/java/org/apache/lucene/codecs/NormsFormat.java
URL: http://svn.apache.org/viewvc/lucene/dev/branches/lucene4547/lucene/core/src/java/org/apache/lucene/codecs/NormsFormat.java?rev=1438647&r1=1438646&r2=1438647&view=diff
==============================================================================
--- lucene/dev/branches/lucene4547/lucene/core/src/java/org/apache/lucene/codecs/NormsFormat.java (original)
+++ lucene/dev/branches/lucene4547/lucene/core/src/java/org/apache/lucene/codecs/NormsFormat.java Fri Jan 25 18:57:59 2013
@@ -23,7 +23,7 @@ import org.apache.lucene.index.SegmentRe
import org.apache.lucene.index.SegmentWriteState;
/**
- * format for normalization factors
+ * Encodes/decodes per-document score normalization values.
*/
public abstract class NormsFormat {
/** Sole constructor. (For invocation by subclass
Modified: lucene/dev/branches/lucene4547/lucene/core/src/java/org/apache/lucene/codecs/lucene42/package.html
URL: http://svn.apache.org/viewvc/lucene/dev/branches/lucene4547/lucene/core/src/java/org/apache/lucene/codecs/lucene42/package.html?rev=1438647&r1=1438646&r2=1438647&view=diff
==============================================================================
--- lucene/dev/branches/lucene4547/lucene/core/src/java/org/apache/lucene/codecs/lucene42/package.html (original)
+++ lucene/dev/branches/lucene4547/lucene/core/src/java/org/apache/lucene/codecs/lucene42/package.html Fri Jan 25 18:57:59 2013
@@ -143,7 +143,7 @@ its numbering.</p>
what files it uses,
</li>
<li>
-{@link org.apache.lucene.codecs.lucene40.Lucene40FieldInfosFormat Field names}.
+{@link org.apache.lucene.codecs.lucene42.Lucene42FieldInfosFormat Field names}.
This contains the set of field names used in the index.
</li>
<li>
@@ -249,7 +249,7 @@ file.</td>
systems that frequently run out of file handles.</td>
</tr>
<tr>
-<td>{@link org.apache.lucene.codecs.lucene40.Lucene40FieldInfosFormat Fields}</td>
+<td>{@link org.apache.lucene.codecs.lucene42.Lucene42FieldInfosFormat Fields}</td>
<td>.fnm</td>
<td>Stores information about the fields</td>
</tr>