accumulo-commits mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From ktur...@apache.org
Subject svn commit: r1298165 - in /incubator/accumulo/trunk: ./ src/core/src/main/java/org/apache/accumulo/core/client/mapreduce/ src/core/src/main/java/org/apache/accumulo/core/data/
Date Wed, 07 Mar 2012 22:22:58 GMT
Author: kturner
Date: Wed Mar  7 22:22:57 2012
New Revision: 1298165

URL: http://svn.apache.org/viewvc?rev=1298165&view=rev
Log:
ACCUMULO-411 Added more javadoc to public API (merged from 1.4)

Modified:
    incubator/accumulo/trunk/   (props changed)
    incubator/accumulo/trunk/src/core/src/main/java/org/apache/accumulo/core/client/mapreduce/InputFormatBase.java
    incubator/accumulo/trunk/src/core/src/main/java/org/apache/accumulo/core/data/Key.java
    incubator/accumulo/trunk/src/core/src/main/java/org/apache/accumulo/core/data/Mutation.java
    incubator/accumulo/trunk/src/core/src/main/java/org/apache/accumulo/core/data/Range.java

Propchange: incubator/accumulo/trunk/
------------------------------------------------------------------------------
--- svn:mergeinfo (original)
+++ svn:mergeinfo Wed Mar  7 22:22:57 2012
@@ -1,3 +1,3 @@
 /incubator/accumulo/branches/1.3:1190280,1190413,1190420,1190427,1190500,1195622,1195625,1195629,1195635,1196044,1196054,1196057,1196071-1196072,1196106,1197066,1198935,1199383,1203683,1204625,1205547,1205880,1206169,1208031,1209124,1209526,1209532,1209539,1209541,1209587,1209657,1210518,1210571,1210596,1210598,1213424,1214320,1225006,1227215,1227231,1227611,1228195,1230180,1230736,1231043,1236873,1245632
 /incubator/accumulo/branches/1.3.5rc:1209938
-/incubator/accumulo/branches/1.4:1201902-1298088
+/incubator/accumulo/branches/1.4:1201902-1298163

Modified: incubator/accumulo/trunk/src/core/src/main/java/org/apache/accumulo/core/client/mapreduce/InputFormatBase.java
URL: http://svn.apache.org/viewvc/incubator/accumulo/trunk/src/core/src/main/java/org/apache/accumulo/core/client/mapreduce/InputFormatBase.java?rev=1298165&r1=1298164&r2=1298165&view=diff
==============================================================================
--- incubator/accumulo/trunk/src/core/src/main/java/org/apache/accumulo/core/client/mapreduce/InputFormatBase.java
(original)
+++ incubator/accumulo/trunk/src/core/src/main/java/org/apache/accumulo/core/client/mapreduce/InputFormatBase.java
Wed Mar  7 22:22:57 2012
@@ -277,18 +277,23 @@ public abstract class InputFormatBase<K,
   }
   
   /**
+   * <p>
    * Enable reading offline tables. This will make the map reduce job directly read the tables
files. If the table is not offline, then the job will fail. If
    * the table comes online during the map reduce job, its likely that the job will fail.
    * 
+   * <p>
    * To use this option, the map reduce user will need access to read the accumulo directory
in HDFS.
    * 
+   * <p>
    * Reading the offline table will create the scan time iterator stack in the map process.
So any iterators that are configured for the table will need to be
    * on the mappers classpath. The accumulo-site.xml may need to be on the mappers classpath
if HDFS or the accumlo directory in HDFS are non-standard.
    * 
+   * <p>
    * One way to use this feature is to clone a table, take the clone offline, and use the
clone as the input table for a map reduce job. If you plan to map
    * reduce over the data many times, it may be better to the compact the table, clone it,
take it offline, and use the clone for all map reduce jobs. The
    * reason to do this is that compaction will reduce each tablet in the table to one file,
and its faster to read from one file.
    * 
+   * <p>
    * There are two possible advantages to reading a tables file directly out of HDFS. First,
you may see better read performance. Second, it will support
    * speculative execution better. When reading an online table speculative execution can
put more load on an already slow tablet server.
    * 

Modified: incubator/accumulo/trunk/src/core/src/main/java/org/apache/accumulo/core/data/Key.java
URL: http://svn.apache.org/viewvc/incubator/accumulo/trunk/src/core/src/main/java/org/apache/accumulo/core/data/Key.java?rev=1298165&r1=1298164&r2=1298165&view=diff
==============================================================================
--- incubator/accumulo/trunk/src/core/src/main/java/org/apache/accumulo/core/data/Key.java
(original)
+++ incubator/accumulo/trunk/src/core/src/main/java/org/apache/accumulo/core/data/Key.java
Wed Mar  7 22:22:57 2012
@@ -17,8 +17,10 @@
 package org.apache.accumulo.core.data;
 
 /**
- * This class is used to group together all the info that goes into a key in 
- * the mapfiles
+ * This is the Key used to store and access individual values in Accumulo.  A Key is a tuple
composed of a row, column family, column qualifier, 
+ * column visibility, timestamp, and delete marker.
+ * 
+ * Keys are comparable and therefore have a sorted order.  
  * 
  */
 
@@ -231,53 +233,137 @@ public class Key implements WritableComp
     this.deleted = false;
   }
   
+  /**
+   * This method gives users control over allocation of Text objects by copying into the
passed in text.
+   * 
+   * @param r
+   *          the key's row will be copied into this Text
+   * @return the Text that was passed in
+   */
+
   public Text getRow(Text r) {
     r.set(row, 0, row.length);
     return r;
   }
   
+  /**
+   * This method returns a pointer to the keys internal data and does not copy it.
+   * 
+   * @return ByteSequence that points to the internal key row data.
+   */
+
   public ByteSequence getRowData() {
     return new ArrayByteSequence(row);
   }
   
+  /**
+   * This method allocates a Text object and copies into it.
+   * 
+   * @return Text containing the row field
+   */
+
   public Text getRow() {
     return getRow(new Text());
   }
   
+  /**
+   * Efficiently compare the the row of a key w/o allocating a text object and copying the
row into it.
+   * 
+   * @param r
+   *          row to compare to keys row
+   * @return same as getRow().compareTo(r)
+   */
+
   public int compareRow(Text r) {
     return WritableComparator.compareBytes(row, 0, row.length, r.getBytes(), 0, r.getLength());
   }
   
+  /**
+   * This method returns a pointer to the keys internal data and does not copy it.
+   * 
+   * @return ByteSequence that points to the internal key column family data.
+   */
+
   public ByteSequence getColumnFamilyData() {
     return new ArrayByteSequence(colFamily);
   }
   
+  /**
+   * This method gives users control over allocation of Text objects by copying into the
passed in text.
+   * 
+   * @param cf
+   *          the key's column family will be copied into this Text
+   * @return the Text that was passed in
+   */
+
   public Text getColumnFamily(Text cf) {
     cf.set(colFamily, 0, colFamily.length);
     return cf;
   }
   
+  /**
+   * This method allocates a Text object and copies into it.
+   * 
+   * @return Text containing the column family field
+   */
+
   public Text getColumnFamily() {
     return getColumnFamily(new Text());
   }
   
+  /**
+   * Efficiently compare the the column family of a key w/o allocating a text object and
copying the column qualifier into it.
+   * 
+   * @param cf
+   *          column family to compare to keys column family
+   * @return same as getColumnFamily().compareTo(cf)
+   */
+
   public int compareColumnFamily(Text cf) {
     return WritableComparator.compareBytes(colFamily, 0, colFamily.length, cf.getBytes(),
0, cf.getLength());
   }
   
+  /**
+   * This method returns a pointer to the keys internal data and does not copy it.
+   * 
+   * @return ByteSequence that points to the internal key column qualifier data.
+   */
+
   public ByteSequence getColumnQualifierData() {
     return new ArrayByteSequence(colQualifier);
   }
   
+  /**
+   * This method gives users control over allocation of Text objects by copying into the
passed in text.
+   * 
+   * @param cq
+   *          the key's column qualifier will be copied into this Text
+   * @return the Text that was passed in
+   */
+
   public Text getColumnQualifier(Text cq) {
     cq.set(colQualifier, 0, colQualifier.length);
     return cq;
   }
   
+  /**
+   * This method allocates a Text object and copies into it.
+   * 
+   * @return Text containing the column qualifier field
+   */
+
   public Text getColumnQualifier() {
     return getColumnQualifier(new Text());
   }
   
+  /**
+   * Efficiently compare the the column qualifier of a key w/o allocating a text object and
copying the column qualifier into it.
+   * 
+   * @param cq
+   *          column family to compare to keys column qualifier
+   * @return same as compareColumnQualifier().compareTo(cq)
+   */
+
   public int compareColumnQualifier(Text cq) {
     return WritableComparator.compareBytes(colQualifier, 0, colQualifier.length, cq.getBytes(),
0, cq.getLength());
   }
@@ -298,14 +384,34 @@ public class Key implements WritableComp
     this.deleted = deleted;
   }
   
+  /**
+   * This method returns a pointer to the keys internal data and does not copy it.
+   * 
+   * @return ByteSequence that points to the internal key column visibility data.
+   */
+
   public ByteSequence getColumnVisibilityData() {
     return new ArrayByteSequence(colVisibility);
   }
   
+  /**
+   * This method allocates a Text object and copies into it.
+   * 
+   * @return Text containing the column visibility field
+   */
+
   public final Text getColumnVisibility() {
     return getColumnVisibility(new Text());
   }
   
+  /**
+   * This method gives users control over allocation of Text objects by copying into the
passed in text.
+   * 
+   * @param cv
+   *          the key's column visibility will be copied into this Text
+   * @return the Text that was passed in
+   */
+
   public final Text getColumnVisibility(Text cv) {
     cv.set(colVisibility, 0, colVisibility.length);
     return cv;
@@ -366,6 +472,11 @@ public class Key implements WritableComp
     out.writeBoolean(deleted);
   }
   
+  /**
+   * Compare part of a key. For example compare just the row and column family, and if those
are equal then return true.
+   * 
+   */
+
   public boolean equals(Key other, PartialKey part) {
     switch (part) {
       case ROW:
@@ -388,6 +499,11 @@ public class Key implements WritableComp
     }
   }
   
+  /**
+   * Compare part of a key. For example compare just the row and column family, and if those
are equal then return 0.
+   * 
+   */
+
   public int compareTo(Key other, PartialKey part) {
     // check for matching row
     int result = WritableComparator.compareBytes(row, 0, row.length, other.row, 0, other.row.length);
@@ -430,7 +546,9 @@ public class Key implements WritableComp
   }
   
   /**
-   * determines the order of keys in the MapFiles we must then just make sure that *'s are
not ever stored
+   * Compare the elements of a key starting with the row. If the row is equal, then compare
the column family, etc. The row, column family, column qualifier,
+   * and column visibility are compared lexographically and sorted ascending. The timestamps
are compared numerically and sorted descending so that the most
+   * recent data comes first. Last when delete is compared, true come first and false after.
    */
   
   public int compareTo(Key other) {

Modified: incubator/accumulo/trunk/src/core/src/main/java/org/apache/accumulo/core/data/Mutation.java
URL: http://svn.apache.org/viewvc/incubator/accumulo/trunk/src/core/src/main/java/org/apache/accumulo/core/data/Mutation.java?rev=1298165&r1=1298164&r2=1298165&view=diff
==============================================================================
--- incubator/accumulo/trunk/src/core/src/main/java/org/apache/accumulo/core/data/Mutation.java
(original)
+++ incubator/accumulo/trunk/src/core/src/main/java/org/apache/accumulo/core/data/Mutation.java
Wed Mar  7 22:22:57 2012
@@ -32,14 +32,23 @@ import org.apache.hadoop.io.Text;
 import org.apache.hadoop.io.Writable;
 
 /**
- * Mutation represents an action that manipulates a row in a table
+ * <p>
+ * Mutation represents an action that manipulates a row in a table. A mutation holds a list
of column/value pairs that represent an atomic set of modifications
+ * to make to a row.
  * 
+ * <p>
  * Convenience methods which takes columns and value as CharSequence (String implements CharSequence)
are provided. CharSequence is converted to UTF-8 by
  * constructing a new Text object.
  * 
+ * <p>
  * When always passing in the same data as a CharSequence/String, its probably more efficient
to call the Text put methods. This way the data is only encoded
  * once and only one Text object is created.
  * 
+ * <p>
+ * All of the put methods append data to the mutation, they do not overwrite anything that
was previously put. The mutation holds a list of all column/values
+ * that were put into it. The putDelete() methods do not remove something that was previously
added to the mutation, rather they indicate that Accumulo should
+ * insert a delete marker for that row column.
+ * 
  */
 
 public class Mutation implements Writable {

Modified: incubator/accumulo/trunk/src/core/src/main/java/org/apache/accumulo/core/data/Range.java
URL: http://svn.apache.org/viewvc/incubator/accumulo/trunk/src/core/src/main/java/org/apache/accumulo/core/data/Range.java?rev=1298165&r1=1298164&r2=1298165&view=diff
==============================================================================
--- incubator/accumulo/trunk/src/core/src/main/java/org/apache/accumulo/core/data/Range.java
(original)
+++ incubator/accumulo/trunk/src/core/src/main/java/org/apache/accumulo/core/data/Range.java
Wed Mar  7 22:22:57 2012
@@ -28,6 +28,11 @@ import org.apache.accumulo.core.data.thr
 import org.apache.hadoop.io.Text;
 import org.apache.hadoop.io.WritableComparable;
 
+/**
+ * This class is used to specify a range of Accumulo Keys.
+ * 
+ */
+
 public class Range implements WritableComparable<Range> {
   
   private Key start;
@@ -193,6 +198,11 @@ public class Range implements WritableCo
     return start;
   }
   
+  /**
+   * 
+   * @param key
+   * @return true of the given key is before the range, otherwise false
+   */
   public boolean beforeStartKey(Key key) {
     if (infiniteStartKey) {
       return false;
@@ -203,6 +213,10 @@ public class Range implements WritableCo
     return key.compareTo(start) <= 0;
   }
   
+  /**
+   * @return the last key in the range, null if the end key is infinite
+   */
+
   public Key getEndKey() {
     if (infiniteStopKey) {
       return null;
@@ -210,6 +224,11 @@ public class Range implements WritableCo
     return stop;
   }
   
+  /**
+   * @param key
+   * @return true if the given key is after the range, otherwise false
+   */
+
   public boolean afterEndKey(Key key) {
     if (infiniteStopKey)
       return false;
@@ -279,10 +298,32 @@ public class Range implements WritableCo
     return comp;
   }
   
+  /**
+   * 
+   * @param key
+   * @return true if the given key falls within the range
+   */
   public boolean contains(Key key) {
     return !beforeStartKey(key) && !afterEndKey(key);
   }
   
+  /**
+   * Takes a collection on range and merges overlapping and adjacent ranges. For example
given the following input
+   * 
+   * <pre>
+   * [a,c], (c, d], (g,m), (j,t]
+   * </pre>
+   * 
+   * the following ranges would be returned
+   * 
+   * <pre>
+   * [a,d], (g,t]
+   * </pre>
+   * 
+   * @param ranges
+   * @return list of merged ranges
+   */
+
   public static List<Range> mergeOverlapping(Collection<Range> ranges) {
     if (ranges.size() == 0)
       return Collections.emptyList();
@@ -339,10 +380,36 @@ public class Range implements WritableCo
     return ret;
   }
   
+  /**
+   * Creates a range which represents the intersection of this range and the passed in range.
The following example will print true.
+   * 
+   * <pre>
+   * Range range1 = new Range(&quot;a&quot;, &quot;f&quot;);
+   * Range range2 = new Range(&quot;c&quot;, &quot;n&quot;);
+   * Range range3 = range1.clip(range2);
+   * System.out.println(range3.equals(new Range(&quot;c&quot;, &quot;f&quot;)));
+   * </pre>
+   * 
+   * @param range
+   * @return the intersection
+   * @throws IllegalArgumentException
+   *           if ranges does not overlap
+   */
+
   public Range clip(Range range) {
     return clip(range, false);
   }
   
+  /**
+   * Same as other clip function except if gives the option to return null of the ranges
do not overlap instead of throwing an exception.
+   * 
+   * @see Range#clip(Range)
+   * @param range
+   * @param returnNullIfDisjoint
+   *          If the ranges do not overlap and true is passed, then null is returned otherwise
an exception is thrown.
+   * @return the intersection
+   */
+
   public Range clip(Range range, boolean returnNullIfDisjoint) {
     
     Key sk = range.getStartKey();
@@ -384,6 +451,18 @@ public class Range implements WritableCo
     return new Range(sk, ski, ek, eki);
   }
   
+  /**
+   * Creates a new range that is bounded by the columns passed in. The stary key in the returned
range will have a column >= to the minimum column. The end key
+   * in the returned range will have a column <= the max column.
+   * 
+   * 
+   * @param min
+   * @param max
+   * @return a column bounded range
+   * @throws IllegalArgumentException
+   *           if min > max
+   */
+
   public Range bound(Column min, Column max) {
     
     if (min.compareTo(max) > 0) {



Mime
View raw message