incubator-accumulo-commits mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From bil...@apache.org
Subject svn commit: r1202767 - in /incubator/accumulo/branches/1.4/src/core/src/main/java/org/apache/accumulo/core/iterators: Combiner.java LongCombiner.java TypedValueCombiner.java
Date Wed, 16 Nov 2011 16:31:23 GMT
Author: billie
Date: Wed Nov 16 16:31:23 2011
New Revision: 1202767

URL: http://svn.apache.org/viewvc?rev=1202767&view=rev
Log:
ACCUMULO-148 added javadocs for combiner base classes

Modified:
    incubator/accumulo/branches/1.4/src/core/src/main/java/org/apache/accumulo/core/iterators/Combiner.java
    incubator/accumulo/branches/1.4/src/core/src/main/java/org/apache/accumulo/core/iterators/LongCombiner.java
    incubator/accumulo/branches/1.4/src/core/src/main/java/org/apache/accumulo/core/iterators/TypedValueCombiner.java

Modified: incubator/accumulo/branches/1.4/src/core/src/main/java/org/apache/accumulo/core/iterators/Combiner.java
URL: http://svn.apache.org/viewvc/incubator/accumulo/branches/1.4/src/core/src/main/java/org/apache/accumulo/core/iterators/Combiner.java?rev=1202767&r1=1202766&r2=1202767&view=diff
==============================================================================
--- incubator/accumulo/branches/1.4/src/core/src/main/java/org/apache/accumulo/core/iterators/Combiner.java
(original)
+++ incubator/accumulo/branches/1.4/src/core/src/main/java/org/apache/accumulo/core/iterators/Combiner.java
Wed Nov 16 16:31:23 2011
@@ -37,17 +37,33 @@ import org.apache.accumulo.core.iterator
 import org.apache.hadoop.io.Text;
 import org.apache.log4j.Logger;
 
-@SuppressWarnings("deprecation")
+/*
+ * A SortedKeyValueIterator that combines the Values for different versions of a Key into
a single Value.
+ * Combiner will replace one or more versions of a Key and their Values with the most recent
Key and a Value which is the result of the reduce method.
+ * 
+ * Subclasses must implement a reduce method:
+ *   public Value reduce(Key key, Iterator<Value> iter);
+ * 
+ * This reduce method will be passed the most recent Key and an iterator over the Values
for all non-deleted versions of that Key.
+ */
 public abstract class Combiner extends WrappingIterator implements OptionDescriber {
   static final Logger log = Logger.getLogger(Combiner.class);
   public static final String COLUMN_PREFIX = "column:";
   
+  /*
+   * A Java Iterator that iterates over the Values for a given Key from a source SortedKeyValueIterator.
+   */
   public static class ValueIterator implements Iterator<Value> {
     Key topKey;
     SortedKeyValueIterator<Key,Value> source;
     boolean hasNext;
     
-    ValueIterator(SortedKeyValueIterator<Key,Value> source) {
+    /*
+     * Constructs an iterator over Values whose Keys are versions of the current topKey of
the source SortedKeyValueIterator.
+     * 
+     * @param source The SortedKeyValueIterator<Key,Value> from which to read data.
+     */
+    public ValueIterator(SortedKeyValueIterator<Key,Value> source) {
       this.source = source;
       topKey = source.getTopKey();
       hasNext = _hasNext();
@@ -57,11 +73,21 @@ public abstract class Combiner extends W
       return source.hasTop() && !source.getTopKey().isDeleted() && topKey.equals(source.getTopKey(),
PartialKey.ROW_COLFAM_COLQUAL_COLVIS);
     }
     
+    /*
+     * @return <tt>true</tt> if there is another Value
+     * 
+     * @see java.util.Iterator#hasNext()
+     */
     @Override
     public boolean hasNext() {
       return hasNext;
     }
     
+    /*
+     * @return the next Value
+     * 
+     * @see java.util.Iterator#next()
+     */
     @Override
     public Value next() {
       if (!hasNext)
@@ -76,6 +102,11 @@ public abstract class Combiner extends W
       return topValue;
     }
     
+    /*
+     * unsupported
+     * 
+     * @see java.util.Iterator#remove()
+     */
     @Override
     public void remove() {
       throw new UnsupportedOperationException();
@@ -120,6 +151,11 @@ public abstract class Combiner extends W
   
   private Key workKey = new Key();
   
+  /*
+   * Sets the topKey and topValue based on the top key of the source. If the column of the
source top key is in the set of combiners, or if there are no columns
+   * in the set of combiners, topKey will be the top key of the source and topValue will
be the result of the reduce method. Otherwise, topKey and topValue will
+   * be null.
+   */
   private void findTop() throws IOException {
     // check if aggregation is needed
     if (super.hasTop()) {
@@ -138,8 +174,7 @@ public abstract class Combiner extends W
   
   @Override
   public void seek(Range range, Collection<ByteSequence> columnFamilies, boolean inclusive)
throws IOException {
-    // do not want to seek to the middle of a value that should be
-    // combined...
+    // do not want to seek to the middle of a value that should be combined...
     
     Range seekRange = IteratorUtil.maximizeStartKeyTimeStamp(range);
     
@@ -149,8 +184,7 @@ public abstract class Combiner extends W
     if (range.getStartKey() != null) {
       while (hasTop() && getTopKey().equals(range.getStartKey(), PartialKey.ROW_COLFAM_COLQUAL_COLVIS)
           && getTopKey().getTimestamp() > range.getStartKey().getTimestamp())
{
-        // the value has a more recent time stamp, so
-        // pass it up
+        // the value has a more recent time stamp, so pass it up
         // log.debug("skipping "+getTopKey());
         next();
       }
@@ -161,6 +195,15 @@ public abstract class Combiner extends W
     }
   }
   
+  /*
+   * Reduces a list of Values into a single Value.
+   * 
+   * @param key The most recent version of the Key being reduced.
+   * 
+   * @param iter An iterator over the Values for different versions of the key.
+   * 
+   * @return The combined Value.
+   */
   public abstract Value reduce(Key key, Iterator<Value> iter);
   
   private ColumnSet combiners;
@@ -188,6 +231,15 @@ public abstract class Combiner extends W
     return true;
   }
   
+  /*
+   * Adds a column (colf and colq) to an IteratorSetting.
+   * 
+   * @param colf The column family.
+   * 
+   * @param colq The column qualifier (<tt>null</tt> if unspecified).
+   * 
+   * @param is The IteratorSetting to which to add the column parameter.
+   */
   public static void addColumn(Text colf, Text colq, IteratorSetting is) {
     String column = PerColumnIteratorConfig.encodeColumns(colf, colq);
     is.addOption(COLUMN_PREFIX + column, "");

Modified: incubator/accumulo/branches/1.4/src/core/src/main/java/org/apache/accumulo/core/iterators/LongCombiner.java
URL: http://svn.apache.org/viewvc/incubator/accumulo/branches/1.4/src/core/src/main/java/org/apache/accumulo/core/iterators/LongCombiner.java?rev=1202767&r1=1202766&r2=1202767&view=diff
==============================================================================
--- incubator/accumulo/branches/1.4/src/core/src/main/java/org/apache/accumulo/core/iterators/LongCombiner.java
(original)
+++ incubator/accumulo/branches/1.4/src/core/src/main/java/org/apache/accumulo/core/iterators/LongCombiner.java
Wed Nov 16 16:31:23 2011
@@ -27,6 +27,17 @@ import org.apache.accumulo.core.data.Key
 import org.apache.accumulo.core.data.Value;
 import org.apache.hadoop.io.WritableUtils;
 
+/*
+ * A TypedValueCombiner that translates each Value to a Long before reducing, then encodes
the reduced Long back to a Value.
+ * 
+ * Subclasses must implement a typedReduce method:
+ *   public Long typedReduce(Key key, Iterator<Long> iter);
+ * 
+ * This typedReduce method will be passed the most recent Key and an iterator over the Values
(translated to Longs) for all non-deleted versions of that Key.
+ * 
+ * A required option for this Combiner is "type" which indicates which type of Encoder to
use to encode and decode Longs into Values.  Supported types are
+ * VARNUM, LONG, and STRING which indicate the VarNumEncoder, LongEncoder, and StringEncoder
respectively.
+ */
 public abstract class LongCombiner extends TypedValueCombiner<Long> {
   public static final String TYPE = "type";
   
@@ -75,6 +86,9 @@ public abstract class LongCombiner exten
     return true;
   }
   
+  /*
+   * An Encoder that uses a variable-length encoding for Longs. It uses WritableUtils.writeVLong
and WritableUtils.readVLong for encoding and decoding.
+   */
   public static class VarNumEncoder implements Encoder<Long> {
     @Override
     public byte[] encode(Long v) {
@@ -101,6 +115,9 @@ public abstract class LongCombiner exten
     }
   }
   
+  /*
+   * An Encoder that uses an 8-byte encoding for Longs.
+   */
   public static class LongEncoder implements Encoder<Long> {
     @Override
     public byte[] encode(Long l) {
@@ -129,6 +146,9 @@ public abstract class LongCombiner exten
     }
   }
   
+  /*
+   * An Encoder that uses a String representation of Longs. It uses Long.toString and Long.parseLong
for encoding and decoding.
+   */
   public static class StringEncoder implements Encoder<Long> {
     @Override
     public byte[] encode(Long v) {

Modified: incubator/accumulo/branches/1.4/src/core/src/main/java/org/apache/accumulo/core/iterators/TypedValueCombiner.java
URL: http://svn.apache.org/viewvc/incubator/accumulo/branches/1.4/src/core/src/main/java/org/apache/accumulo/core/iterators/TypedValueCombiner.java?rev=1202767&r1=1202766&r2=1202767&view=diff
==============================================================================
--- incubator/accumulo/branches/1.4/src/core/src/main/java/org/apache/accumulo/core/iterators/TypedValueCombiner.java
(original)
+++ incubator/accumulo/branches/1.4/src/core/src/main/java/org/apache/accumulo/core/iterators/TypedValueCombiner.java
Wed Nov 16 16:31:23 2011
@@ -23,16 +23,32 @@ import org.apache.accumulo.core.data.Key
 import org.apache.accumulo.core.data.Value;
 
 /*
- * Subclasses should implement a switch on the "type" variable 
- * in their reduce method.
+ * A Combiner that decodes each Value to type V before reducing, then encodes the result
of typedReduce back to Value.
+ * 
+ * Subclasses must implement a typedReduce method:
+ *   public V typedReduce(Key key, Iterator<V> iter);
+ * 
+ * This typedReduce method will be passed the most recent Key and an iterator over the Values
(translated to Vs) for all non-deleted versions of that Key.
+ *
+ * Subclasses may implement a switch on the "type" variable to choose an Encoder in their
init method.
  */
 public abstract class TypedValueCombiner<V> extends Combiner {
   protected Encoder<V> encoder;
   
+  /*
+   * A Java Iterator that translates an Iterator<Value> to an Iterator<V> using
the decode method of an Encoder.
+   */
   private static class VIterator<V> implements Iterator<V> {
     private Iterator<Value> source;
     private Encoder<V> encoder;
     
+    /*
+     * Constructs an Iterator<V> from an Iterator<Value>
+     * 
+     * @param iter The source iterator
+     * 
+     * @param encoder The Encoder whose decode method is used to translate from Value to
V
+     */
     VIterator(Iterator<Value> iter, Encoder<V> encoder) {
       this.source = iter;
       this.encoder = encoder;
@@ -56,6 +72,9 @@ public abstract class TypedValueCombiner
     }
   }
   
+  /*
+   * An interface for translating from byte[] to V and back.
+   */
   public static interface Encoder<V> {
     public byte[] encode(V v);
     
@@ -67,5 +86,14 @@ public abstract class TypedValueCombiner
     return new Value(encoder.encode(typedReduce(key, new VIterator<V>(iter, encoder))));
   }
   
+  /*
+   * Reduces a list of V into a single V.
+   * 
+   * @param key The most recent version of the Key being reduced.
+   * 
+   * @param iter An iterator over the V for different versions of the key.
+   * 
+   * @return The combined V.
+   */
   public abstract V typedReduce(Key key, Iterator<V> iter);
 }



Mime
View raw message