accumulo-commits mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From els...@apache.org
Subject [1/3] ACCUMULO-1931 Javadoc for core/data
Date Mon, 16 Dec 2013 19:27:15 GMT
Updated Branches:
  refs/heads/master 75685ce8b -> 3a2e0a925


http://git-wip-us.apache.org/repos/asf/accumulo/blob/74c89324/core/src/main/java/org/apache/accumulo/core/data/Range.java
----------------------------------------------------------------------
diff --git a/core/src/main/java/org/apache/accumulo/core/data/Range.java b/core/src/main/java/org/apache/accumulo/core/data/Range.java
index 65873c3..adfd17b 100644
--- a/core/src/main/java/org/apache/accumulo/core/data/Range.java
+++ b/core/src/main/java/org/apache/accumulo/core/data/Range.java
@@ -30,10 +30,10 @@ import org.apache.hadoop.io.Text;
 import org.apache.hadoop.io.WritableComparable;
 
 /**
- * This class is used to specify a range of Accumulo Keys.
+ * This class is used to specify a range of Accumulo keys.
  * 
+ * @see Key
  */
-
 public class Range implements WritableComparable<Range> {
   
   private Key start;
@@ -46,113 +46,96 @@ public class Range implements WritableComparable<Range> {
   /**
    * Creates a range that goes from negative to positive infinity
    */
-  
   public Range() {
     this((Key) null, true, (Key) null, true);
   }
   
   /**
-   * Creates a range from startKey inclusive to endKey inclusive
+   * Creates a range from startKey inclusive to endKey inclusive.
    * 
-   * @param startKey
-   *          set this to null when negative infinity is needed
-   * @param endKey
-   *          set this to null when positive infinity is needed
+   * @param startKey starting key; set to null for negative infinity
+   * @param endKey ending key; set to null for positive infinity
+   * @throws IllegalArgumentException if end key is before start key
    */
   public Range(Key startKey, Key endKey) {
     this(startKey, true, endKey, true);
   }
   
   /**
-   * Creates a range that covers an entire row
+   * Creates a range that covers an entire row.
    * 
-   * @param row
-   *          set this to null to cover all rows
+   * @param row row to cover; set to null to cover all rows
    */
   public Range(CharSequence row) {
     this(row, true, row, true);
   }
   
   /**
-   * Creates a range that covers an entire row
+   * Creates a range that covers an entire row.
    * 
-   * @param row
-   *          set this to null to cover all rows
+   * @param row row to cover; set to null to cover all rows
    */
   public Range(Text row) {
     this(row, true, row, true);
   }
   
   /**
-   * Creates a range from startRow inclusive to endRow inclusive
+   * Creates a range from startRow inclusive to endRow inclusive.
    * 
-   * @param startRow
-   *          set this to null when negative infinity is needed
-   * @param endRow
-   *          set this to null when positive infinity is needed
+   * @param startRow starting row; set to null for negative infinity
+   * @param endRow ending row; set to null for positive infinity
+   * @throws IllegalArgumentException if end row is before start row
    */
   public Range(Text startRow, Text endRow) {
     this(startRow, true, endRow, true);
   }
   
   /**
-   * Creates a range from startRow inclusive to endRow inclusive
+   * Creates a range from startRow inclusive to endRow inclusive.
    * 
-   * @param startRow
-   *          set this to null when negative infinity is needed
-   * @param endRow
-   *          set this to null when positive infinity is needed
+   * @param startRow starting row; set to null for negative infinity
+   * @param endRow ending row; set to null for positive infinity
+   * @throws IllegalArgumentException if end row is before start row
    */
   public Range(CharSequence startRow, CharSequence endRow) {
     this(startRow, true, endRow, true);
   }
   
   /**
-   * Creates a range from startRow to endRow
+   * Creates a range from startRow to endRow.
    * 
-   * @param startRow
-   *          set this to null when negative infinity is needed
-   * @param startRowInclusive
-   *          determines if the start row is skipped
-   * @param endRow
-   *          set this to null when positive infinity is needed
-   * @param endRowInclusive
-   *          determines if the endRow is included
+   * @param startRow starting row; set to null for negative infinity
+   * @param startRowInclusive true to include start row, false to skip
+   * @param endRow ending row; set to null for positive infinity
+   * @param endRowInclusive true to include start row, false to skip
+   * @throws IllegalArgumentException if end row is before start row
    */
-  
   public Range(Text startRow, boolean startRowInclusive, Text endRow, boolean endRowInclusive)
{
     this((startRow == null ? null : (startRowInclusive ? new Key(startRow) : new Key(startRow).followingKey(PartialKey.ROW))),
true, (endRow == null ? null
         : (endRowInclusive ? new Key(endRow).followingKey(PartialKey.ROW) : new Key(endRow))),
false);
   }
   
   /**
-   * Creates a range from startRow to endRow
+   * Creates a range from startRow to endRow.
    * 
-   * @param startRow
-   *          set this to null when negative infinity is needed
-   * @param startRowInclusive
-   *          determines if the start row is skipped
-   * @param endRow
-   *          set this to null when positive infinity is needed
-   * @param endRowInclusive
-   *          determines if the endRow is included
+   * @param startRow starting row; set to null for negative infinity
+   * @param startRowInclusive true to include start row, false to skip
+   * @param endRow ending row; set to null for positive infinity
+   * @param endRowInclusive true to include start row, false to skip
+   * @throws IllegalArgumentException if end row is before start row
    */
-  
   public Range(CharSequence startRow, boolean startRowInclusive, CharSequence endRow, boolean
endRowInclusive) {
     this(startRow == null ? null : new Text(startRow.toString()), startRowInclusive, endRow
== null ? null : new Text(endRow.toString()), endRowInclusive);
   }
   
   /**
-   * Creates a range from startKey to endKey
+   * Creates a range from startKey to endKey.
    * 
-   * @param startKey
-   *          set this to null when negative infinity is needed
-   * @param startKeyInclusive
-   *          determines if the ranges includes the start key
-   * @param endKey
-   *          set this to null when infinity is needed
-   * @param endKeyInclusive
-   *          determines if the range includes the end key
+   * @param startKey starting key; set to null for negative infinity
+   * @param startKeyInclusive true to include start key, false to skip
+   * @param endKey ending key; set to null for positive infinity
+   * @param endKeyInclusive true to include start key, false to skip
+   * @throws IllegalArgumentException if end key is before start key
    */
   public Range(Key startKey, boolean startKeyInclusive, Key endKey, boolean endKeyInclusive)
{
     this.start = startKey;
@@ -168,7 +151,9 @@ public class Range implements WritableComparable<Range> {
   }
   
   /**
-   * Copies a range
+   * Copies a range.
+   *
+   * @param range range to copy
    */
   public Range(Range range) {
     this(range.start, range.startKeyInclusive, range.infiniteStartKey, range.stop, range.stopKeyInclusive,
range.infiniteStopKey);
@@ -233,6 +218,11 @@ public class Range implements WritableComparable<Range> {
     this.infiniteStopKey = infiniteStopKey;
   }
   
+  /**
+   * Creates a range from a Thrift range.
+   *
+   * @param trange Thrift range
+   */
   public Range(TRange trange) {
     this(trange.start == null ? null : new Key(trange.start), trange.startKeyInclusive, trange.infiniteStartKey,
         trange.stop == null ? null : new Key(trange.stop), trange.stopKeyInclusive, trange.infiniteStopKey);
@@ -242,7 +232,9 @@ public class Range implements WritableComparable<Range> {
   }
   
   /**
-   * @return the first key in the range, null if the key is infinite
+   * Gets the start key, or null if the start is negative infinity.
+   *
+   * @return start key
    */
   public Key getStartKey() {
     if (infiniteStartKey) {
@@ -252,8 +244,9 @@ public class Range implements WritableComparable<Range> {
   }
   
   /**
-   * 
-   * @param key
+   * Determines if the given key is before the start key of this range.
+   *
+   * @param key key to check
    * @return true if the given key is before the range, otherwise false
    */
   public boolean beforeStartKey(Key key) {
@@ -267,9 +260,10 @@ public class Range implements WritableComparable<Range> {
   }
   
   /**
-   * @return the last key in the range, null if the end key is infinite
+   * Gets the ending key, or null if the end is positive infinity.
+   *
+   * @return ending key
    */
-  
   public Key getEndKey() {
     if (infiniteStopKey) {
       return null;
@@ -278,10 +272,11 @@ public class Range implements WritableComparable<Range> {
   }
   
   /**
-   * @param key
+   * Determines if the given key is after the ending key of this range.
+   *
+   * @param key key to check
    * @return true if the given key is after the range, otherwise false
    */
-  
   public boolean afterEndKey(Key key) {
     if (infiniteStopKey)
       return false;
@@ -306,14 +301,24 @@ public class Range implements WritableComparable<Range> {
     return false;
   }
   
+  /**
+   * Determines if this range equals another.
+   *
+   * @param otherRange range to compare
+   * @return true if ranges are equals, false otherwise
+   * @see #compareTo(Range)
+   */
   public boolean equals(Range otherRange) {
     
     return compareTo(otherRange) == 0;
   }
   
   /**
-   * Compares this range to another range. Compares in the order start key, inclusiveness
of start key, end key, inclusiveness of end key. Infinite keys sort
+   * Compares this range to another range. Compares in order: start key, inclusiveness of
start key, end key, inclusiveness of end key. Infinite keys sort
    * first, and non-infinite keys are compared with {@link Key#compareTo(Key)}. Inclusive
sorts before non-inclusive.
+   *
+   * @param o range to compare
+   * @return comparison result
    */
   public int compareTo(Range o) {
     int comp;
@@ -356,31 +361,31 @@ public class Range implements WritableComparable<Range> {
   }
   
   /**
-   * 
-   * @param key
-   * @return true if the given key falls within the range
+   * Determines if the given key falls within this range.
+   *
+   * @param key key to consider
+   * @return true if the given key falls within the range, false otherwise
    */
   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
+   * 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
+   * the following ranges would be returned:
    * 
    * <pre>
    * [a,d], (g,t]
    * </pre>
    * 
-   * @param ranges
+   * @param ranges to merge
    * @return list of merged ranges
    */
-  
   public static List<Range> mergeOverlapping(Collection<Range> ranges) {
     if (ranges.size() == 0)
       return Collections.emptyList();
@@ -447,24 +452,24 @@ public class Range implements WritableComparable<Range> {
    * 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
+   * @param range range to clip to
+   * @return the intersection of this range and the given range
+   * @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.
+   * Creates a range which represents the intersection of this range and the passed in range.
Unlike {@link #clip(Range)},
+   * this method can optionally return null if the ranges do not overlap, instead of throwing
an exception. The returnNullIfDisjoint parameter controls this
+   * behavior.
    * 
+   * @param range range to clip to
+   * @param returnNullIfDisjoint true to return null if ranges are disjoint, false to throw
an exception
+   * @return the intersection of this range and the given range, or null if ranges do not
overlap and returnNullIfDisjoint is true
+   * @throws IllegalArgumentException if ranges does not overlap and returnNullIfDisjoint
is false
    * @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) {
@@ -509,17 +514,14 @@ public class Range implements WritableComparable<Range> {
   }
   
   /**
-   * 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
+   * Creates a new range that is bounded by the columns passed in. The start 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
+   * @param min minimum column
+   * @param max maximum column
    * @return a column bounded range
-   * @throws IllegalArgumentException
-   *           if min > max
+   * @throws IllegalArgumentException if the minimum column compares greater than the maximum
column
    */
-  
   public Range bound(Column min, Column max) {
     
     if (min.compareTo(max) > 0) {
@@ -631,45 +633,67 @@ public class Range implements WritableComparable<Range> {
     out.writeBoolean(stopKeyInclusive);
   }
   
+  /**
+   * Gets whether the start key of this range is inclusive.
+   *
+   * @return true if start key is inclusive
+   */
   public boolean isStartKeyInclusive() {
     return startKeyInclusive;
   }
   
+  /**
+   * Gets whether the end key of this range is inclusive.
+   *
+   * @return true if end key is inclusive
+   */
   public boolean isEndKeyInclusive() {
     return stopKeyInclusive;
   }
   
+  /**
+   * Converts this range to Thrift.
+   *
+   * @return Thrift range
+   */
   public TRange toThrift() {
     return new TRange(start == null ? null : start.toThrift(), stop == null ? null : stop.toThrift(),
startKeyInclusive, stopKeyInclusive, infiniteStartKey,
         infiniteStopKey);
   }
   
+  /**
+   * Gets whether the start key is negative infinity.
+   *
+   * @return true if start key is negative infinity
+   */
   public boolean isInfiniteStartKey() {
     return infiniteStartKey;
   }
   
+  /**
+   * Gets whether the end key is positive infinity.
+   *
+   * @return true if end key is positive infinity
+   */
   public boolean isInfiniteStopKey() {
     return infiniteStopKey;
   }
   
   /**
-   * Creates a range that covers an exact row Returns the same Range as new Range(row)
+   * Creates a range that covers an exact row. Returns the same Range as
+   * {@link #Range(Text)}.
    * 
-   * @param row
-   *          all keys in the range will have this row
+   * @param row row to cover; set to null to cover all rows
    */
   public static Range exact(Text row) {
     return new Range(row);
   }
   
   /**
-   * Creates a range that covers an exact row and column family
-   * 
-   * @param row
-   *          all keys in the range will have this row
+   * Creates a range that covers an exact row and column family.
    * 
-   * @param cf
-   *          all keys in the range will have this column family
+   * @param row row row to cover
+   * @param cf column family to cover
    */
   public static Range exact(Text row, Text cf) {
     Key startKey = new Key(row, cf);
@@ -677,16 +701,11 @@ public class Range implements WritableComparable<Range> {
   }
   
   /**
-   * Creates a range that covers an exact row, column family, and column qualifier
+   * Creates a range that covers an exact row, column family, and column qualifier.
    * 
-   * @param row
-   *          all keys in the range will have this row
-   * 
-   * @param cf
-   *          all keys in the range will have this column family
-   * 
-   * @param cq
-   *          all keys in the range will have this column qualifier
+   * @param row row row to cover
+   * @param cf column family to cover
+   * @param cq column qualifier to cover
    */
   public static Range exact(Text row, Text cf, Text cq) {
     Key startKey = new Key(row, cf, cq);
@@ -694,19 +713,12 @@ public class Range implements WritableComparable<Range> {
   }
   
   /**
-   * Creates a range that covers an exact row, column family, column qualifier, and visibility
-   * 
-   * @param row
-   *          all keys in the range will have this row
-   * 
-   * @param cf
-   *          all keys in the range will have this column family
-   * 
-   * @param cq
-   *          all keys in the range will have this column qualifier
+   * Creates a range that covers an exact row, column family, column qualifier, and column
visibility.
    * 
-   * @param cv
-   *          all keys in the range will have this column visibility
+   * @param row row row to cover
+   * @param cf column family to cover
+   * @param cq column qualifier to cover
+   * @param cv column visibility to cover
    */
   public static Range exact(Text row, Text cf, Text cq, Text cv) {
     Key startKey = new Key(row, cf, cq, cv);
@@ -714,22 +726,13 @@ public class Range implements WritableComparable<Range> {
   }
   
   /**
-   * Creates a range that covers an exact row, column family, column qualifier, visibility,
and timestamp
-   * 
-   * @param row
-   *          all keys in the range will have this row
-   * 
-   * @param cf
-   *          all keys in the range will have this column family
-   * 
-   * @param cq
-   *          all keys in the range will have this column qualifier
-   * 
-   * @param cv
-   *          all keys in the range will have this column visibility
+   * Creates a range that covers an exact row, column family, column qualifier, column visibility,
and timestamp.
    * 
-   * @param ts
-   *          all keys in the range will have this timestamp
+   * @param row row row to cover
+   * @param cf column family to cover
+   * @param cq column qualifier to cover
+   * @param cv column visibility to cover
+   * @param ts timestamp to cover
    */
   public static Range exact(Text row, Text cf, Text cq, Text cv, long ts) {
     Key startKey = new Key(row, cf, cq, cv, ts);
@@ -737,9 +740,11 @@ public class Range implements WritableComparable<Range> {
   }
   
   /**
-   * Returns a Text that sorts just after all Texts beginning with a prefix
+   * Returns a Text that sorts just after all Texts beginning with a prefix.
    * 
-   * @param prefix
+   * @param prefix to follow
+   * @return prefix that immediately follows the given prefix when sorted, or
+   * null if no prefix can follow (i.e., the string is all 0xff bytes)
    */
   public static Text followingPrefix(Text prefix) {
     byte[] prefixBytes = prefix.getBytes();
@@ -761,10 +766,9 @@ public class Range implements WritableComparable<Range> {
   }
   
   /**
-   * Returns a Range that covers all rows beginning with a prefix
+   * Returns a Range that covers all rows beginning with a prefix.
    * 
-   * @param rowPrefix
-   *          all keys in the range will have rows that begin with this prefix
+   * @param rowPrefix prefix of rows to cover
    */
   public static Range prefix(Text rowPrefix) {
     Text fp = followingPrefix(rowPrefix);
@@ -772,13 +776,10 @@ public class Range implements WritableComparable<Range> {
   }
   
   /**
-   * Returns a Range that covers all column families beginning with a prefix within a given
row
+   * Returns a Range that covers all column families beginning with a prefix within a given
row.
    * 
-   * @param row
-   *          all keys in the range will have this row
-   * 
-   * @param cfPrefix
-   *          all keys in the range will have column families that begin with this prefix
+   * @param row row to cover
+   * @param cfPrefix prefix of column families to cover
    */
   public static Range prefix(Text row, Text cfPrefix) {
     Text fp = followingPrefix(cfPrefix);
@@ -786,16 +787,11 @@ public class Range implements WritableComparable<Range> {
   }
   
   /**
-   * Returns a Range that covers all column qualifiers beginning with a prefix within a given
row and column family
-   * 
-   * @param row
-   *          all keys in the range will have this row
+   * Returns a Range that covers all column qualifiers beginning with a prefix within a given
row and column family.
    * 
-   * @param cf
-   *          all keys in the range will have this column family
-   * 
-   * @param cqPrefix
-   *          all keys in the range will have column qualifiers that begin with this prefix
+   * @param row row to cover
+   * @param cf column family to cover
+   * @param cqPrefix prefix of column qualifiers to cover
    */
   public static Range prefix(Text row, Text cf, Text cqPrefix) {
     Text fp = followingPrefix(cqPrefix);
@@ -803,19 +799,12 @@ public class Range implements WritableComparable<Range> {
   }
   
   /**
-   * Returns a Range that covers all column visibilities beginning with a prefix within a
given row, column family, and column qualifier
-   * 
-   * @param row
-   *          all keys in the range will have this row
+   * Returns a Range that covers all column visibilities beginning with a prefix within a
given row, column family, and column qualifier.
    * 
-   * @param cf
-   *          all keys in the range will have this column family
-   * 
-   * @param cq
-   *          all keys in the range will have this column qualifier
-   * 
-   * @param cvPrefix
-   *          all keys in the range will have column visibilities that begin with this prefix
+   * @param row row to cover
+   * @param cf column family to cover
+   * @param cq column qualifier to cover
+   * @param cvPrefix prefix of column visibilities to cover
    */
   public static Range prefix(Text row, Text cf, Text cq, Text cvPrefix) {
     Text fp = followingPrefix(cvPrefix);
@@ -824,81 +813,104 @@ public class Range implements WritableComparable<Range> {
   }
   
   /**
-   * Creates a range that covers an exact row
+   * Creates a range that covers an exact row.
    * 
-   * @see Range#exact(Text)
+   * @param row row to cover; set to null to cover all rows
+   * @see #exact(Text)
    */
   public static Range exact(CharSequence row) {
     return Range.exact(new Text(row.toString()));
   }
   
   /**
-   * Creates a range that covers an exact row and column family
+   * Creates a range that covers an exact row and column family.
    * 
-   * @see Range#exact(Text, Text)
+   * @param row row row to cover
+   * @param cf column family to cover
+   * @see #exact(Text, Text)
    */
   public static Range exact(CharSequence row, CharSequence cf) {
     return Range.exact(new Text(row.toString()), new Text(cf.toString()));
   }
   
   /**
-   * Creates a range that covers an exact row, column family, and column qualifier
+   * Creates a range that covers an exact row, column family, and column qualifier.
    * 
-   * @see Range#exact(Text, Text, Text)
+   * @param row row row to cover
+   * @param cf column family to cover
+   * @param cq column qualifier to cover
+   * @see #exact(Text, Text, Text)
    */
   public static Range exact(CharSequence row, CharSequence cf, CharSequence cq) {
     return Range.exact(new Text(row.toString()), new Text(cf.toString()), new Text(cq.toString()));
   }
   
   /**
-   * Creates a range that covers an exact row, column family, column qualifier, and visibility
+   * Creates a range that covers an exact row, column family, column qualifier, and column
visibility.
    * 
-   * @see Range#exact(Text, Text, Text, Text)
+   * @param row row row to cover
+   * @param cf column family to cover
+   * @param cq column qualifier to cover
+   * @param cv column visibility to cover
+   * @see #exact(Text, Text, Text, Text)
    */
   public static Range exact(CharSequence row, CharSequence cf, CharSequence cq, CharSequence
cv) {
     return Range.exact(new Text(row.toString()), new Text(cf.toString()), new Text(cq.toString()),
new Text(cv.toString()));
   }
   
   /**
-   * Creates a range that covers an exact row, column family, column qualifier, visibility,
and timestamp
+   * Creates a range that covers an exact row, column family, column qualifier, column visibility,
and timestamp.
    * 
-   * @see Range#exact(Text, Text, Text, Text, long)
+   * @param row row row to cover
+   * @param cf column family to cover
+   * @param cq column qualifier to cover
+   * @param cv column visibility to cover
+   * @param ts timestamp to cover
+   * @see #exact(Text, Text, Text, Text, long)
    */
   public static Range exact(CharSequence row, CharSequence cf, CharSequence cq, CharSequence
cv, long ts) {
     return Range.exact(new Text(row.toString()), new Text(cf.toString()), new Text(cq.toString()),
new Text(cv.toString()), ts);
   }
-  
   /**
-   * Returns a Range that covers all rows beginning with a prefix
+   * Returns a Range that covers all rows beginning with a prefix.
    * 
-   * @see Range#prefix(Text)
+   * @param rowPrefix prefix of rows to cover
+   * @see #prefix(Text)
    */
   public static Range prefix(CharSequence rowPrefix) {
     return Range.prefix(new Text(rowPrefix.toString()));
   }
   
   /**
-   * Returns a Range that covers all column families beginning with a prefix within a given
row
+   * Returns a Range that covers all column families beginning with a prefix within a given
row.
    * 
-   * @see Range#prefix(Text, Text)
+   * @param row row to cover
+   * @param cfPrefix prefix of column families to cover
+   * @see #prefix(Text, Text)
    */
   public static Range prefix(CharSequence row, CharSequence cfPrefix) {
     return Range.prefix(new Text(row.toString()), new Text(cfPrefix.toString()));
   }
   
   /**
-   * Returns a Range that covers all column qualifiers beginning with a prefix within a given
row and column family
+   * Returns a Range that covers all column qualifiers beginning with a prefix within a given
row and column family.
    * 
-   * @see Range#prefix(Text, Text, Text)
+   * @param row row to cover
+   * @param cf column family to cover
+   * @param cqPrefix prefix of column qualifiers to cover
+   * @see #prefix(Text, Text, Text)
    */
   public static Range prefix(CharSequence row, CharSequence cf, CharSequence cqPrefix) {
     return Range.prefix(new Text(row.toString()), new Text(cf.toString()), new Text(cqPrefix.toString()));
   }
-  
   /**
-   * Returns a Range that covers all column visibilities beginning with a prefix within a
given row, column family, and column qualifier
+   * Returns a Range that covers all column visibilities beginning with a prefix within a
given row, column family, and column qualifier.
    * 
-   * @see Range#prefix(Text, Text, Text, Text)
+   * @param row row to cover
+   * @param cf column family to cover
+   * @param cq column qualifier to cover
+   * @param cvPrefix prefix of column visibilities to cover
+   * @see #prefix(Text, Text, Text, Text)
    */
   public static Range prefix(CharSequence row, CharSequence cf, CharSequence cq, CharSequence
cvPrefix) {
     return Range.prefix(new Text(row.toString()), new Text(cf.toString()), new Text(cq.toString()),
new Text(cvPrefix.toString()));

http://git-wip-us.apache.org/repos/asf/accumulo/blob/74c89324/core/src/main/java/org/apache/accumulo/core/data/Value.java
----------------------------------------------------------------------
diff --git a/core/src/main/java/org/apache/accumulo/core/data/Value.java b/core/src/main/java/org/apache/accumulo/core/data/Value.java
index 39ebbd0..ec07411 100644
--- a/core/src/main/java/org/apache/accumulo/core/data/Value.java
+++ b/core/src/main/java/org/apache/accumulo/core/data/Value.java
@@ -32,42 +32,59 @@ import org.apache.hadoop.io.WritableComparator;
 
 /**
  * A byte sequence that is usable as a key or value. Based on {@link org.apache.hadoop.io.BytesWritable}
only this class is NOT resizable and DOES NOT
- * distinguish between the size of the sequence and the current capacity as {@link org.apache.hadoop.io.BytesWritable}
does. Hence its comparatively
+ * distinguish between the size of the sequence and the current capacity as {@link org.apache.hadoop.io.BytesWritable}
does. Hence it is comparatively
  * 'immutable'.
  */
 public class Value implements WritableComparable<Object> {
   protected byte[] value;
   
   /**
-   * Create a zero-size sequence.
+   * Creates a zero-size sequence.
    */
   public Value() {
     super();
   }
   
   /**
-   * Create a Value using the byte array as the initial value.
+   * Creates a Value using a byte array as the initial value. The given byte
+   * array is used directly as the backing array, so later changes made to the
+   * array reflect into the new Value.
    * 
-   * @param bytes
-   *          This array becomes the backing storage for the object.
+   * @param bytes bytes of value
    */
-  
   public Value(byte[] bytes) {
     this(bytes, false);
   }
   
+  /**
+   * Creates a Value using the bytes in a buffer as the initial value. Makes
+   * a defensive copy.
+   * 
+   * @param bytes bytes of value
+   */
   public Value(ByteBuffer bytes) {
     this(toBytes(bytes), false);
   }
   
   /**
    * @deprecated A copy of the bytes in the buffer is always made. Use {@link #Value(ByteBuffer)}
instead.
+   * 
+   * @param bytes bytes of value
+   * @param copy false to use the backing array of the buffer directly as the
+   * backing array, true to force a copy
    */
   @Deprecated
   public Value(ByteBuffer bytes, boolean copy) {
     this(toBytes(bytes), false);
   }
   
+  /**
+   * Creates a Value using a byte array as the initial value.
+   * 
+   * @param bytes bytes of value
+   * @param copy false to use the given byte array directly as the backing
+   * array, true to force a copy
+   */
   public Value(byte[] bytes, boolean copy) {
     if (!copy) {
       this.value = bytes;
@@ -79,24 +96,22 @@ public class Value implements WritableComparable<Object> {
   }
   
   /**
-   * Set the new Value to a copy of the contents of the passed <code>ibw</code>.
+   * Creates a new Value based on another.
    * 
-   * @param ibw
-   *          the value to set this Value to.
+   * @param ibw original Value
    */
   public Value(final Value ibw) {
     this(ibw.get(), 0, ibw.getSize());
   }
   
   /**
-   * Set the value to a copy of the given byte range
+   * Creates a Value based on a range in a byte array. A copy of the bytes is
+   * always made.
    * 
-   * @param newData
-   *          the new values to copy in
-   * @param offset
-   *          the offset in newData to start at
-   * @param length
-   *          the number of bytes to copy
+   * @param newData byte array containing value bytes
+   * @param offset the offset in newData to start with for valye bytes
+   * @param length the number of bytes in the value
+   * @throws IndexOutOfBoundsException if offset or length are invalid
    */
   public Value(final byte[] newData, final int offset, final int length) {
     this.value = new byte[length];
@@ -104,9 +119,11 @@ public class Value implements WritableComparable<Object> {
   }
   
   /**
-   * Get the data from the BytesWritable.
+   * Gets the byte data of this value.
    * 
-   * @return The data is only valid between 0 and getSize() - 1.
+   * @return value bytes
+   * @throws IllegalStateException if this object is uninitialized because it
+   * was not read correctly from a data stream
    */
   public byte[] get() {
     if (this.value == null) {
@@ -116,17 +133,20 @@ public class Value implements WritableComparable<Object> {
   }
   
   /**
-   * @param b
-   *          Use passed bytes as backing array for this instance.
+   * Sets the byte data of this value. The given byte array is used directly as
+   * the backing array, so later changes made to the array reflect into this
+   * Value.
+   *
+   * @param b bytes of value
    */
   public void set(final byte[] b) {
     this.value = b;
   }
   
   /**
-   * 
-   * @param b
-   *          copy bytes
+   * Sets the byte data of this value. The given byte array is copied.
+   *
+   * @param b bytes of value
    */
   public void copy(byte[] b) {
     this.value = new byte[b.length];
@@ -134,7 +154,11 @@ public class Value implements WritableComparable<Object> {
   }
   
   /**
-   * @return the current size of the buffer.
+   * Gets the size of this value.
+   *
+   * @return size in bytes
+   * @throws IllegalStateException if this object is uninitialized because it
+   * was not read correctly from a data stream
    */
   public int getSize() {
     if (this.value == null) {
@@ -222,6 +246,10 @@ public class Value implements WritableComparable<Object> {
   }
   
   /**
+   * Converts a list of byte arrays to a two-dimensional array.
+   *
+   * @param array list of byte arrays
+   * @return two-dimensional byte array containing one given byte array per row
 	 */
   public static byte[][] toArray(final List<byte[]> array) {
     // List#toArray doesn't work on lists of byte [].

http://git-wip-us.apache.org/repos/asf/accumulo/blob/74c89324/core/src/main/java/org/apache/accumulo/core/data/doc-files/mutation-serialization.html
----------------------------------------------------------------------
diff --git a/core/src/main/java/org/apache/accumulo/core/data/doc-files/mutation-serialization.html
b/core/src/main/java/org/apache/accumulo/core/data/doc-files/mutation-serialization.html
new file mode 100644
index 0000000..d4d5ed3
--- /dev/null
+++ b/core/src/main/java/org/apache/accumulo/core/data/doc-files/mutation-serialization.html
@@ -0,0 +1,196 @@
+<html>
+<head>
+    <title>Serialization Formats for Mutation</title>
+<!--
+ Licensed to the Apache Software Foundation (ASF) under one or more
+ contributor license agreements.  See the NOTICE file distributed with
+ this work for additional information regarding copyright ownership.
+ The ASF licenses this file to You under the Apache License, Version 2.0
+ (the "License"); you may not use this file except in compliance with
+ the License.  You may obtain a copy of the License at
+
+     http://www.apache.org/licenses/LICENSE-2.0
+
+ Unless required by applicable law or agreed to in writing, software
+ distributed under the License is distributed on an "AS IS" BASIS,
+ WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ See the License for the specific language governing permissions and
+ limitations under the License.
+-->
+</head>
+<body>
+    <p>
+        The <code>Mutation</code> class supports two serialization formats.
+        While it only currently serializes to the newer version 2 format, it
+        can read both version 1 and version 2 serialized forms.
+    </p>
+
+    <h2>Version 1 Format</h2>
+    <p>
+        Mutation data serialized in the version 1 format has the following
+        layout.
+    </p>
+    <table>
+        <tr>
+            <th>data location</th>
+            <th>description</th>
+        </tr>
+        <tr>
+            <td>bytes 0 through 3</td>
+            <td>4-byte integer for length of row ID</td>
+        </tr>
+        <tr>
+            <td>next <i>n</i> bytes</td>
+            <td>row ID</td>
+        </tr>
+        <tr>
+            <td>next integer</td>
+            <td>data length</td>
+        </tr>
+        <tr>
+            <td>next <i>n</i> bytes</td>
+            <td>data (see below)</td>
+        </tr>
+        <tr>
+            <td>next integer</td>
+            <td>number of entries</td>
+        </tr>
+        <tr>
+            <td>next boolean</td>
+            <td>values present flag</td>
+        </tr>
+        <tr>
+            <td>next integer</td>
+            <td>number of values (only if values present flag is set)</td>
+        </tr>
+        <tr>
+            <td>next <i>n</i> sets of integers and byte arrays</td>
+            <td><i>n</i> value lengths and value data bytes (only if values
+                present flag is set)</td>
+        </tr>
+    </table>
+    <p>
+        The "data" block noted above has the following layout for each entry.
+    </p>
+    <table>
+        <tr>
+            <td>first integer and byte array</td>
+            <td>column family length and bytes</td>
+        </tr>
+        <tr>
+            <td>next integer and byte array</td>
+            <td>column qualifier length and bytes</td>
+        </tr>
+        <tr>
+            <td>next integer and byte array</td>
+            <td>column visibility length and bytes</td>
+        </tr>
+        <tr>
+            <td>next boolean</td>
+            <td>has timestamp flag</td>
+        </tr>
+        <tr>
+            <td>next long</td>
+            <td>timestamp</td>
+        </tr>
+        <tr>
+            <td>next boolean</td>
+            <td>deleted flag</td>
+        </tr>
+        <tr>
+            <td>next integer</td>
+            <td>value length; if negative, value bytes are the same as those
+                for already-read value (-length - 1)</td>
+        </tr>
+        <tr>
+            <td>next <i>n</i> bytes</td>
+            <td>value bytes (only if value length is non-negative)</td>
+        </tr>
+    </table>
+
+    <h2>Version 2 Format</h2>
+    <p>
+        Mutation data serialized in the version 2 format has the following
+        layout. This format uses variable length encoding for integers and
+        longs.
+    </p>
+    <table>
+        <tr>
+            <th>data location</th>
+            <th>description</th>
+        </tr>
+        <tr>
+            <td>byte 0</td>
+            <td>control byte: top bit = 1 for version 2; bottom bit =
+                values present flag</td>
+        </tr>
+        <tr>
+            <td>next integer
+            <td>length of row ID</td>
+        </tr>
+        <tr>
+            <td>next <i>n</i> bytes</td>
+            <td>row ID</td>
+        </tr>
+        <tr>
+            <td>next integer</td>
+            <td>data length</td>
+        </tr>
+        <tr>
+            <td>next <i>n</i> bytes</td>
+            <td>data (see below)</td>
+        </tr>
+        <tr>
+            <td>next integer</td>
+            <td>number of entries</td>
+        </tr>
+        <tr>
+            <td>next integer</td>
+            <td>number of values (only if values present flag is set)</td>
+        </tr>
+        <tr>
+            <td>next <i>n</i> sets of integers and byte arrays</td>
+            <td><i>n</i> value lengths and value data bytes (only if values
+                present flag is set)</td>
+        </tr>
+    </table>
+    <p>
+        The "data" block noted above has the following layout for each entry.
+    </p>
+    <table>
+        <tr>
+            <td>first long and byte array</td>
+            <td>column family length and bytes</td>
+        </tr>
+        <tr>
+            <td>next long and byte array</td>
+            <td>column qualifier length and bytes</td>
+        </tr>
+        <tr>
+            <td>next long and byte array</td>
+            <td>column visibility length and bytes</td>
+        </tr>
+        <tr>
+            <td>next boolean</td>
+            <td>has timestamp flag</td>
+        </tr>
+        <tr>
+            <td>next long</td>
+            <td>timestamp (only present if timestamp flag is set)</td>
+        </tr>
+        <tr>
+            <td>next boolean</td>
+            <td>deleted flag</td>
+        </tr>
+        <tr>
+            <td>next long</td>
+            <td>value length; if negative, value bytes are the same as those
+                for already-read value (-length - 1)</td>
+        </tr>
+        <tr>
+            <td>next <i>n</i> bytes</td>
+            <td>value bytes (only if value length is non-negative)</td>
+        </tr>
+    </table>
+</body>
+</html>

http://git-wip-us.apache.org/repos/asf/accumulo/blob/74c89324/core/src/main/java/org/apache/accumulo/core/util/UnsynchronizedBuffer.java
----------------------------------------------------------------------
diff --git a/core/src/main/java/org/apache/accumulo/core/util/UnsynchronizedBuffer.java b/core/src/main/java/org/apache/accumulo/core/util/UnsynchronizedBuffer.java
index b640581..36aa473 100644
--- a/core/src/main/java/org/apache/accumulo/core/util/UnsynchronizedBuffer.java
+++ b/core/src/main/java/org/apache/accumulo/core/util/UnsynchronizedBuffer.java
@@ -21,20 +21,32 @@ import java.nio.ByteBuffer;
 import org.apache.hadoop.io.WritableUtils;
 
 /**
- * 
+ * A utility class for reading and writing bytes to byte buffers without
+ * synchronization.
  */
 public class UnsynchronizedBuffer {
   // created this little class instead of using ByteArrayOutput stream and DataOutputStream
   // because both are synchronized... lots of small syncs slow things down
+  /**
+   * A byte buffer writer.
+   */
   public static class Writer {
     
     int offset = 0;
     byte data[];
     
+    /**
+     * Creates a new writer.
+     */
     public Writer() {
       data = new byte[64];
     }
     
+    /**
+     * Creates a new writer.
+     *
+     * @param initialCapacity initial byte capacity
+     */
     public Writer(int initialCapacity) {
       data = new byte[initialCapacity];
     }
@@ -50,12 +62,25 @@ public class UnsynchronizedBuffer {
       
     }
     
+    /**
+     * Adds bytes to this writer's buffer.
+     *
+     * @param bytes byte array
+     * @param off offset into array to start copying bytes
+     * @param length number of bytes to add
+     * @throws IndexOutOfBoundsException if off or length are invalid
+     */
     public void add(byte[] bytes, int off, int length) {
       reserve(length);
       System.arraycopy(bytes, off, data, offset, length);
       offset += length;
     }
     
+    /**
+     * Adds a Boolean value to this writer's buffer.
+     *
+     * @param b Boolean value
+     */
     public void add(boolean b) {
       reserve(1);
       if (b)
@@ -64,20 +89,46 @@ public class UnsynchronizedBuffer {
         data[offset++] = 0;
     }
     
+    /**
+     * Gets (a copy of) the contents of this writer's buffer.
+     *
+     * @return byte buffer contents
+     */
     public byte[] toArray() {
       byte ret[] = new byte[offset];
       System.arraycopy(data, 0, ret, 0, offset);
       return ret;
     }
     
+    /**
+     * Gets a <code>ByteBuffer</code> wrapped around this writer's buffer.
+     *
+     * @return byte buffer
+     */
     public ByteBuffer toByteBuffer() {
       return ByteBuffer.wrap(data, 0, offset);
     }
 
+    /**
+     * Adds an integer value to this writer's buffer. The integer is encoded as
+     * a variable-length list of bytes. See {@link #writeVLong(long)} for a
+     * description of the encoding.
+     *
+     * @param i integer value
+     */
     public void writeVInt(int i) {
       writeVLong(i);
     }
 
+    /**
+     * Adds a long value to this writer's buffer. The long is encoded as
+     * a variable-length list of bytes. For a description of the encoding
+     * scheme, see <code>WritableUtils.writeVLong()</code> in the Hadoop
+     * API.
+     * [<a href="http://hadoop.apache.org/docs/stable/api/org/apache/hadoop/io/WritableUtils.html#writeVLong%28java.io.DataOutput,%20long%29">link</a>]
+     *
+     * @param i long value
+     */
     public void writeVLong(long i) {
       reserve(9);
       if (i >= -112 && i <= 127) {
@@ -109,14 +160,27 @@ public class UnsynchronizedBuffer {
     }
   }
   
+  /**
+   * A byte buffer reader.
+   */
   public static class Reader {
     int offset;
     byte data[];
     
+    /**
+     * Creates a new reader.
+     *
+     * @param b bytes to read
+     */
     public Reader(byte b[]) {
       this.data = b;
     }
     
+    /**
+     * Creates a new reader.
+     *
+     * @param buffer byte buffer containing bytes to read
+     */
     public Reader(ByteBuffer buffer) {
       if (buffer.hasArray()) {
         offset = buffer.arrayOffset();
@@ -127,28 +191,60 @@ public class UnsynchronizedBuffer {
       }
     }
 
+    /**
+     * Reads an integer value from this reader's buffer.
+     *
+     * @return integer value
+     */
     public int readInt() {
       return (data[offset++] << 24) + ((data[offset++] & 255) << 16) + ((data[offset++]
& 255) << 8) + ((data[offset++] & 255) << 0);
     }
     
+    /**
+     * Reads a long value from this reader's buffer.
+     *
+     * @return long value
+     */
     public long readLong() {
       return (((long) data[offset++] << 56) + ((long) (data[offset++] & 255) <<
48) + ((long) (data[offset++] & 255) << 40)
           + ((long) (data[offset++] & 255) << 32) + ((long) (data[offset++] &
255) << 24) + ((data[offset++] & 255) << 16) + ((data[offset++] & 255)
<< 8) + ((data[offset++] & 255) << 0));
     }
     
+    /**
+     * Reads bytes from this reader's buffer, filling the given byte array.
+     *
+     * @param b byte array to fill
+     */
     public void readBytes(byte b[]) {
       System.arraycopy(data, offset, b, 0, b.length);
       offset += b.length;
     }
     
+    /**
+     * Reads a Boolean value from this reader's buffer.
+     *
+     * @return Boolean value
+     */
     public boolean readBoolean() {
       return (data[offset++] == 1);
     }
     
+    /**
+     * Reads an integer value from this reader's buffer, assuming the integer
+     * was encoded as a variable-length list of bytes.
+     *
+     * @return integer value
+     */
     public int readVInt() {
       return (int) readVLong();
     }
 
+    /**
+     * Reads a long value from this reader's buffer, assuming the long
+     * was encoded as a variable-length list of bytes.
+     *
+     * @return long value
+     */
     public long readVLong() {
       byte firstByte = data[offset++];
       int len = WritableUtils.decodeVIntSize(firstByte);
@@ -167,7 +263,10 @@ public class UnsynchronizedBuffer {
 
   /**
    * Determines what next array size should be by rounding up to next power of two.
-   * 
+   *
+   * @param i current array size
+   * @return next array size
+   * @throws IllegalArgumentException if i is negative
    */
   public static int nextArraySize(int i) {
     if (i < 0)


Mime
View raw message