accumulo-commits mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From els...@apache.org
Subject [2/3] git commit: ACCUMULO-1931 Javadoc for core/data
Date Mon, 16 Dec 2013 19:27:16 GMT
ACCUMULO-1931 Javadoc for core/data

Signed-off-by: Josh Elser <elserj@apache.org>


Project: http://git-wip-us.apache.org/repos/asf/accumulo/repo
Commit: http://git-wip-us.apache.org/repos/asf/accumulo/commit/74c89324
Tree: http://git-wip-us.apache.org/repos/asf/accumulo/tree/74c89324
Diff: http://git-wip-us.apache.org/repos/asf/accumulo/diff/74c89324

Branch: refs/heads/master
Commit: 74c89324772d58970abb30175e1a0dfc045a0ce9
Parents: 75685ce
Author: Bill Havanki <bhavanki@cloudera.com>
Authored: Mon Oct 7 11:35:39 2013 -0400
Committer: Josh Elser <elserj@apache.org>
Committed: Mon Dec 16 13:57:23 2013 -0500

----------------------------------------------------------------------
 .../accumulo/core/data/ArrayByteSequence.java   |  36 ++
 .../apache/accumulo/core/data/ByteSequence.java |  63 +++-
 .../org/apache/accumulo/core/data/Column.java   |  58 +++
 .../apache/accumulo/core/data/ColumnUpdate.java |  49 ++-
 .../accumulo/core/data/ComparableBytes.java     |  16 +
 .../apache/accumulo/core/data/Condition.java    | 128 +++++--
 .../core/data/ConstraintViolationSummary.java   |  21 ++
 .../java/org/apache/accumulo/core/data/Key.java | 297 +++++++++++----
 .../org/apache/accumulo/core/data/KeyValue.java |  15 +
 .../org/apache/accumulo/core/data/Mutation.java | 335 +++++++++++++++-
 .../apache/accumulo/core/data/PartialKey.java   |  15 +
 .../org/apache/accumulo/core/data/Range.java    | 378 ++++++++++---------
 .../org/apache/accumulo/core/data/Value.java    |  76 ++--
 .../data/doc-files/mutation-serialization.html  | 196 ++++++++++
 .../core/util/UnsynchronizedBuffer.java         | 103 ++++-
 15 files changed, 1452 insertions(+), 334 deletions(-)
----------------------------------------------------------------------


http://git-wip-us.apache.org/repos/asf/accumulo/blob/74c89324/core/src/main/java/org/apache/accumulo/core/data/ArrayByteSequence.java
----------------------------------------------------------------------
diff --git a/core/src/main/java/org/apache/accumulo/core/data/ArrayByteSequence.java b/core/src/main/java/org/apache/accumulo/core/data/ArrayByteSequence.java
index eaa61b9..24e5d03 100644
--- a/core/src/main/java/org/apache/accumulo/core/data/ArrayByteSequence.java
+++ b/core/src/main/java/org/apache/accumulo/core/data/ArrayByteSequence.java
@@ -19,6 +19,9 @@ package org.apache.accumulo.core.data;
 import java.io.Serializable;
 import java.nio.ByteBuffer;
 
+/**
+ * An implementation of {@link ByteSequence} that uses a backing byte array.
+ */
 public class ArrayByteSequence extends ByteSequence implements Serializable {
   
   private static final long serialVersionUID = 1L;
@@ -27,12 +30,30 @@ public class ArrayByteSequence extends ByteSequence implements Serializable {
   protected int offset;
   protected int length;
   
+  /**
+   * Creates a new sequence. The given byte array is used directly as the
+   * backing array, so later changes made to the array reflect into the new
+   * sequence.
+   *
+   * @param data byte data
+   */
   public ArrayByteSequence(byte data[]) {
     this.data = data;
     this.offset = 0;
     this.length = data.length;
   }
   
+  /**
+   * Creates a new sequence from a subsequence of the given byte array. The
+   * given byte array is used directly as the backing array, so later changes
+   * made to the (relevant portion of the) array reflect into the new sequence.
+   *
+   * @param data byte data
+   * @param offset starting offset in byte array (inclusive)
+   * @param length number of bytes to include in sequence
+   * @throws IllegalArgumentException if the offset or length are out of bounds
+   * for the given byte array
+   */
   public ArrayByteSequence(byte data[], int offset, int length) {
     
     if (offset < 0 || offset > data.length || length < 0 || (offset + length) > data.length) {
@@ -45,10 +66,25 @@ public class ArrayByteSequence extends ByteSequence implements Serializable {
     
   }
   
+  /**
+   * Creates a new sequence from the given string. The bytes are determined from
+   * the string using the default platform encoding.
+   *
+   * @param s string to represent as bytes
+   */
   public ArrayByteSequence(String s) {
     this(s.getBytes());
   }
   
+  /**
+   * Creates a new sequence based on a byte buffer. If the byte buffer has an
+   * array, that array (and the buffer's offset and limit) are used; otherwise,
+   * a new backing array is created and a relative bulk get is performed to
+   * transfer the buffer's contents (starting at its current position and
+   * not beyond its limit).
+   *
+   * @param buffer byte buffer
+   */
   public ArrayByteSequence(ByteBuffer buffer) {
     if (buffer.hasArray()) {
       this.data = buffer.array();

http://git-wip-us.apache.org/repos/asf/accumulo/blob/74c89324/core/src/main/java/org/apache/accumulo/core/data/ByteSequence.java
----------------------------------------------------------------------
diff --git a/core/src/main/java/org/apache/accumulo/core/data/ByteSequence.java b/core/src/main/java/org/apache/accumulo/core/data/ByteSequence.java
index 4dc921c..196cb11 100644
--- a/core/src/main/java/org/apache/accumulo/core/data/ByteSequence.java
+++ b/core/src/main/java/org/apache/accumulo/core/data/ByteSequence.java
@@ -18,23 +18,77 @@ package org.apache.accumulo.core.data;
 
 import org.apache.hadoop.io.WritableComparator;
 
+/**
+ * A sequence of bytes.
+ */
 public abstract class ByteSequence implements Comparable<ByteSequence> {
   
+  /**
+   * Gets a byte within this sequence.
+   *
+   * @param i index into sequence
+   * @return byte
+   * @throws IllegalArgumentException if i is out of range
+   */
   public abstract byte byteAt(int i);
   
+  /**
+   * Gets the length of this sequence.
+   *
+   * @return sequence length
+   */
   public abstract int length();
   
+  /**
+   * Returns a portion of this sequence.
+   *
+   * @param start index of subsequence start (inclusive)
+   * @param end index of subsequence end (exclusive)
+   */
   public abstract ByteSequence subSequence(int start, int end);
   
-  // may copy data
+  /**
+   * Returns a byte array containing the bytes in this sequence. This method
+   * may copy the sequence data or may return a backing byte array directly.
+   *
+   * @return byte array
+   */
   public abstract byte[] toArray();
   
+  /**
+   * Determines whether this sequence is backed by a byte array.
+   *
+   * @return true if sequence is backed by a byte array
+   */
   public abstract boolean isBackedByArray();
   
+  /**
+   * Gets the backing byte array for this sequence.
+   *
+   * @return byte array
+   */
   public abstract byte[] getBackingArray();
   
+  /**
+   * Gets the offset for this sequence. This value represents the starting
+   * point for the sequence in the backing array, if there is one.
+   *
+   * @return offset (inclusive)
+   */
   public abstract int offset();
   
+  /**
+   * Compares the two given byte sequences, byte by byte, returning a negative,
+   * zero, or positive result if the first sequence is less than, equal to, or
+   * greater than the second. The comparison is performed starting with the
+   * first byte of each sequence, and proceeds until a pair of bytes differs,
+   * or one sequence runs out of byte (is shorter). A shorter sequence is
+   * considered less than a longer one.
+   *
+   * @param bs1 first byte sequence to compare
+   * @param bs2 second byte sequence to compare
+   * @return comparison result
+   */
   public static int compareBytes(ByteSequence bs1, ByteSequence bs2) {
     
     int minLen = Math.min(bs1.length(), bs2.length());
@@ -51,6 +105,13 @@ public abstract class ByteSequence implements Comparable<ByteSequence> {
     return bs1.length() - bs2.length();
   }
   
+  /**
+   * Compares this byte sequence to another.
+   *
+   * @param obs byte sequence to compare
+   * @return comparison result
+   * @see #compareBytes(ByteSequence, ByteSequence)
+   */
   public int compareTo(ByteSequence obs) {
     if (isBackedByArray() && obs.isBackedByArray()) {
       return WritableComparator.compareBytes(getBackingArray(), offset(), length(), obs.getBackingArray(), obs.offset(), obs.length());

http://git-wip-us.apache.org/repos/asf/accumulo/blob/74c89324/core/src/main/java/org/apache/accumulo/core/data/Column.java
----------------------------------------------------------------------
diff --git a/core/src/main/java/org/apache/accumulo/core/data/Column.java b/core/src/main/java/org/apache/accumulo/core/data/Column.java
index a56c01d..91c4ed2 100644
--- a/core/src/main/java/org/apache/accumulo/core/data/Column.java
+++ b/core/src/main/java/org/apache/accumulo/core/data/Column.java
@@ -27,6 +27,9 @@ import org.apache.accumulo.core.data.thrift.TColumn;
 import org.apache.hadoop.io.WritableComparable;
 import org.apache.hadoop.io.WritableComparator;
 
+/**
+ * A column, specified by family, qualifier, and visibility.
+ */
 public class Column implements WritableComparable<Column> {
   
   static private int compareBytes(byte[] a, byte[] b) {
@@ -39,6 +42,13 @@ public class Column implements WritableComparable<Column> {
     return WritableComparator.compareBytes(a, 0, a.length, b, 0, b.length);
   }
   
+  /**
+   * Compares this column to another. Column families are compared first, then
+   * qualifiers, then visibilities.
+   *
+   * @param that column to compare
+   * @return comparison result
+   */
   public int compareTo(Column that) {
     int result;
     result = compareBytes(this.columnFamily, that.columnFamily);
@@ -107,8 +117,18 @@ public class Column implements WritableComparable<Column> {
   public byte[] columnQualifier;
   public byte[] columnVisibility;
   
+  /**
+   * Creates a new blank column.
+   */
   public Column() {}
   
+  /**
+  * Creates a new column.
+  *
+  * @param columnFamily family
+  * @param columnQualifier qualifier
+  * @param columnVisibility visibility
+  */
   public Column(byte[] columnFamily, byte[] columnQualifier, byte[] columnVisibility) {
     this();
     this.columnFamily = columnFamily;
@@ -116,6 +136,11 @@ public class Column implements WritableComparable<Column> {
     this.columnVisibility = columnVisibility;
   }
   
+  /**
+   * Creates a new column.
+   *
+   * @param tcol Thrift column
+   */
   public Column(TColumn tcol) {
     this(toBytes(tcol.columnFamily), toBytes(tcol.columnQualifier), toBytes(tcol.columnVisibility));
   }
@@ -129,6 +154,12 @@ public class Column implements WritableComparable<Column> {
     return false;
   }
   
+  /**
+   * Checks if this column equals another.
+   *
+   * @param that column to compare
+   * @return true if this column equals that, false otherwise
+   */
   public boolean equals(Column that) {
     return this.compareTo(that) == 0;
   }
@@ -145,23 +176,50 @@ public class Column implements WritableComparable<Column> {
     return hash(columnFamily) + hash(columnQualifier) + hash(columnVisibility);
   }
   
+  /**
+   * Gets the column family. Not a defensive copy.
+   *
+   * @return family
+   */
   public byte[] getColumnFamily() {
     return columnFamily;
   }
   
+  /**
+   * Gets the column qualifier. Not a defensive copy.
+   *
+   * @return qualifier
+   */
   public byte[] getColumnQualifier() {
     return columnQualifier;
   }
   
+  /**
+   * Gets the column visibility. Not a defensive copy.
+   *
+   * @return visibility
+   */
   public byte[] getColumnVisibility() {
     return columnVisibility;
   }
   
+  /**
+   * Gets a string representation of this column. The family, qualifier, and
+   * visibility are interpreted as strings using the platform default encoding;
+   * nulls are interpreted as empty strings.
+   *
+   * @return string form of column
+   */
   public String toString() {
     return new String(columnFamily == null ? new byte[0] : columnFamily) + ":" + new String(columnQualifier == null ? new byte[0] : columnQualifier) + ":"
         + new String(columnVisibility == null ? new byte[0] : columnVisibility);
   }
   
+  /**
+   * Converts this column to Thrift.
+   *
+   * @return Thrift column
+   */
   public TColumn toThrift() {
     return new TColumn(columnFamily == null ? null : ByteBuffer.wrap(columnFamily), columnQualifier == null ? null : ByteBuffer.wrap(columnQualifier),
         columnVisibility == null ? null : ByteBuffer.wrap(columnVisibility));

http://git-wip-us.apache.org/repos/asf/accumulo/blob/74c89324/core/src/main/java/org/apache/accumulo/core/data/ColumnUpdate.java
----------------------------------------------------------------------
diff --git a/core/src/main/java/org/apache/accumulo/core/data/ColumnUpdate.java b/core/src/main/java/org/apache/accumulo/core/data/ColumnUpdate.java
index 641ca3a..35e33bd 100644
--- a/core/src/main/java/org/apache/accumulo/core/data/ColumnUpdate.java
+++ b/core/src/main/java/org/apache/accumulo/core/data/ColumnUpdate.java
@@ -19,10 +19,9 @@ package org.apache.accumulo.core.data;
 import java.util.Arrays;
 
 /**
- * A single column and value pair within a mutation
+ * A single column and value pair within a {@link Mutation}.
  * 
  */
-
 public class ColumnUpdate {
   
   private byte[] columnFamily;
@@ -33,6 +32,17 @@ public class ColumnUpdate {
   private byte[] val;
   private boolean deleted;
   
+  /**
+   * Creates a new column update.
+   *
+   * @param cf column family
+   * @param cq column qualifier
+   * @param cv column visibility
+   * @param hasts true if the update specifies a timestamp
+   * @param ts timestamp
+   * @param deleted delete marker
+   * @param val cell value
+   */
   public ColumnUpdate(byte[] cf, byte[] cq, byte[] cv, boolean hasts, long ts, boolean deleted, byte[] val) {
     this.columnFamily = cf;
     this.columnQualifier = cq;
@@ -43,34 +53,65 @@ public class ColumnUpdate {
     this.val = val;
   }
   
+  /**
+   * Gets whether this update specifies a timestamp.
+   *
+   * @return true if this update specifies a timestamp
+   */
   public boolean hasTimestamp() {
     return hasTimestamp;
   }
   
   /**
-   * Returns the column
-   * 
+   * Gets the column family for this update. Not a defensive copy.
+   *
+   * @return column family
    */
   public byte[] getColumnFamily() {
     return columnFamily;
   }
   
+  /**
+   * Gets the column qualifier for this update. Not a defensive copy.
+   *
+   * @return column qualifier
+   */
   public byte[] getColumnQualifier() {
     return columnQualifier;
   }
   
+  /**
+   * Gets the column visibility for this update.
+   *
+   * @return column visibility
+   */
   public byte[] getColumnVisibility() {
     return columnVisibility;
   }
   
+  /**
+   * Gets the timestamp for this update.
+   *
+   * @return timestamp
+   */
   public long getTimestamp() {
     return this.timestamp;
   }
   
+  /**
+   * Gets the delete marker for this update.
+   *
+   * @return delete marker
+   */
   public boolean isDeleted() {
     return this.deleted;
   }
   
+  /**
+   * Gets the cell value for this update.
+   *
+   * @return cell value
+   */
   public byte[] getValue() {
     return this.val;
   }

http://git-wip-us.apache.org/repos/asf/accumulo/blob/74c89324/core/src/main/java/org/apache/accumulo/core/data/ComparableBytes.java
----------------------------------------------------------------------
diff --git a/core/src/main/java/org/apache/accumulo/core/data/ComparableBytes.java b/core/src/main/java/org/apache/accumulo/core/data/ComparableBytes.java
index ce61844..6bdc7e6 100644
--- a/core/src/main/java/org/apache/accumulo/core/data/ComparableBytes.java
+++ b/core/src/main/java/org/apache/accumulo/core/data/ComparableBytes.java
@@ -18,14 +18,30 @@ package org.apache.accumulo.core.data;
 
 import org.apache.hadoop.io.BinaryComparable;
 
+/**
+ * An array of bytes wrapped so as to extend Hadoop's
+ * <code>BinaryComparable</code> class.
+ */
 public class ComparableBytes extends BinaryComparable {
   
   public byte[] data;
   
+  /**
+   * Creates a new byte wrapper. The given byte array is used directly as a
+   * backing array, so later changes made to the array reflect into the new
+   * object.
+   *
+   * @param b bytes to wrap
+   */
   public ComparableBytes(byte[] b) {
     this.data = b;
   }
   
+  /**
+   * Gets the wrapped bytes in this object.
+   *
+   * @return bytes
+   */
   public byte[] getBytes() {
     return data;
   }

http://git-wip-us.apache.org/repos/asf/accumulo/blob/74c89324/core/src/main/java/org/apache/accumulo/core/data/Condition.java
----------------------------------------------------------------------
diff --git a/core/src/main/java/org/apache/accumulo/core/data/Condition.java b/core/src/main/java/org/apache/accumulo/core/data/Condition.java
index fc8f2bf..8af0e82 100644
--- a/core/src/main/java/org/apache/accumulo/core/data/Condition.java
+++ b/core/src/main/java/org/apache/accumulo/core/data/Condition.java
@@ -41,6 +41,15 @@ public class Condition {
   private static final ByteSequence EMPTY = new ArrayByteSequence(new byte[0]);
   
 
+  /**
+   * Creates a new condition. The initial column value and timestamp are null,
+   * and the initial column visibility is empty. Characters in the column family
+   * and column qualifier are encoded as bytes in the condition using UTF-8.
+   *
+   * @param cf column family
+   * @param cq column qualifier
+   * @throws IllegalArgumentException if any argument is null
+   */
   public Condition(CharSequence cf, CharSequence cq) {
     ArgumentChecker.notNull(cf, cq);
     this.cf = new ArrayByteSequence(cf.toString().getBytes(Constants.UTF8));
@@ -48,6 +57,14 @@ public class Condition {
     this.cv = EMPTY;
   }
   
+  /**
+   * Creates a new condition. The initial column value and timestamp are null,
+   * and the initial column visibility is empty.
+   *
+   * @param cf column family
+   * @param cq column qualifier
+   * @throws IllegalArgumentException if any argument is null
+   */
   public Condition(byte[] cf, byte[] cq) {
     ArgumentChecker.notNull(cf, cq);
     this.cf = new ArrayByteSequence(cf);
@@ -55,6 +72,14 @@ public class Condition {
     this.cv = EMPTY;
   }
 
+  /**
+   * Creates a new condition. The initial column value and timestamp are null,
+   * and the initial column visibility is empty.
+   *
+   * @param cf column family
+   * @param cq column qualifier
+   * @throws IllegalArgumentException if any argument is null
+   */
   public Condition(Text cf, Text cq) {
     ArgumentChecker.notNull(cf, cq);
     this.cf = new ArrayByteSequence(cf.getBytes(), 0, cf.getLength());
@@ -62,6 +87,14 @@ public class Condition {
     this.cv = EMPTY;
   }
 
+  /**
+   * Creates a new condition. The initial column value and timestamp are null,
+   * and the initial column visibility is empty.
+   *
+   * @param cf column family
+   * @param cq column qualifier
+   * @throws IllegalArgumentException if any argument is null
+   */
   public Condition(ByteSequence cf, ByteSequence cq) {
     ArgumentChecker.notNull(cf, cq);
     this.cf = cf;
@@ -69,37 +102,53 @@ public class Condition {
     this.cv = EMPTY;
   }
 
+  /**
+   * Gets the column family of this condition.
+   *
+   * @return column family
+   */
   public ByteSequence getFamily() {
     return cf;
   }
   
+  /**
+   * Gets the column qualifier of this condition.
+   *
+   * @return column qualifier
+   */
   public ByteSequence getQualifier() {
     return cq;
   }
 
   /**
    * Sets the version for the column to check. If this is not set then the latest column will be checked, unless iterators do something different.
-   * 
-   * @param ts
-   * @return returns this
+   *
+   * @param ts timestamp
+   * @return this condition
    */
-
   public Condition setTimestamp(long ts) {
     this.ts = ts;
     return this;
   }
   
+  /**
+   * Gets the timestamp of this condition.
+   *
+   * @return timestamp
+   */
   public Long getTimestamp() {
     return ts;
   }
 
   /**
-   * see {@link #setValue(byte[])}
+   * This method sets the expected value of a column. In order for the condition to pass the column must exist and have this value. If a value is not set, then
+   * the column must be absent for the condition to pass. The passed-in character sequence is encoded as UTF-8.
+   * See {@link #setValue(byte[])}.
    * 
-   * @param value
-   * @return returns this
+   * @param value value
+   * @return this condition
+   * @throws IllegalArgumentException if value is null
    */
-
   public Condition setValue(CharSequence value) {
     ArgumentChecker.notNull(value);
     this.val = new ArrayByteSequence(value.toString().getBytes(Constants.UTF8));
@@ -107,13 +156,13 @@ public class Condition {
   }
 
   /**
-   * This method sets the expected value of a column. Inorder for the condition to pass the column must exist and have this value. If a value is not set, then
+   * This method sets the expected value of a column. In order for the condition to pass the column must exist and have this value. If a value is not set, then
    * the column must be absent for the condition to pass.
    * 
-   * @param value
-   * @return returns this
+   * @param value value
+   * @return this condition
+   * @throws IllegalArgumentException if value is null
    */
-
   public Condition setValue(byte[] value) {
     ArgumentChecker.notNull(value);
     this.val = new ArrayByteSequence(value);
@@ -121,12 +170,14 @@ public class Condition {
   }
   
   /**
-   * see {@link #setValue(byte[])}
-   * 
-   * @param value
-   * @return returns this
+   * This method sets the expected value of a column. In order for the condition to pass the column must exist and have this value. If a value is not set, then
+   * the column must be absent for the condition to pass.
+   * See {@link #setValue(byte[])}.
+   *
+   * @param value value
+   * @return this condition
+   * @throws IllegalArgumentException if value is null
    */
-
   public Condition setValue(Text value) {
     ArgumentChecker.notNull(value);
     this.val = new ArrayByteSequence(value.getBytes(), 0, value.getLength());
@@ -134,35 +185,46 @@ public class Condition {
   }
   
   /**
-   * see {@link #setValue(byte[])}
-   * 
-   * @param value
-   * @return returns this
+   * This method sets the expected value of a column. In order for the condition to pass the column must exist and have this value. If a value is not set, then
+   * the column must be absent for the condition to pass.
+   * See {@link #setValue(byte[])}.
+   *
+   * @param value value
+   * @return this condition
+   * @throws IllegalArgumentException if value is null
    */
-
   public Condition setValue(ByteSequence value) {
     ArgumentChecker.notNull(value);
     this.val = value;
     return this;
   }
 
+  /**
+   * Gets the value of this condition.
+   *
+   * @return value
+   */
   public ByteSequence getValue() {
     return val;
   }
 
   /**
    * Sets the visibility for the column to check. If not set it defaults to empty visibility.
-   * 
-   * @param cv
-   * @return returns this
+   *
+   * @param cv column visibility
+   * @throws IllegalArgumentException if cv is null
    */
-
   public Condition setVisibility(ColumnVisibility cv) {
     ArgumentChecker.notNull(cv);
     this.cv = new ArrayByteSequence(cv.getExpression());
     return this;
   }
 
+  /**
+   * Gets the column visibility of this condition.
+   *
+   * @return column visibility
+   */
   public ByteSequence getVisibility() {
     return cv;
   }
@@ -172,11 +234,12 @@ public class Condition {
    * its possible to test other conditions, besides equality and absence, like less than. On the server side the iterators will be seeked using a range that
    * covers only the family, qualifier, and visibility (if the timestamp is set then it will be used to narrow the range). Value equality will be tested using
    * the first entry returned by the iterator stack.
-   * 
-   * @param iterators
-   * @return returns this
+   *
+   * @param iterators iterators
+   * @return this condition
+   * @throws IllegalArgumentException if iterators or any of its elements are null,
+   * or if any two iterators share the same name or priority
    */
-
   public Condition setIterators(IteratorSetting... iterators) {
     ArgumentChecker.notNull(iterators);
     
@@ -196,6 +259,11 @@ public class Condition {
     return this;
   }
 
+  /**
+   * Gets the iterators for this condition.
+   *
+   * @return iterators
+   */
   public IteratorSetting[] getIterators() {
     return iterators;
   }

http://git-wip-us.apache.org/repos/asf/accumulo/blob/74c89324/core/src/main/java/org/apache/accumulo/core/data/ConstraintViolationSummary.java
----------------------------------------------------------------------
diff --git a/core/src/main/java/org/apache/accumulo/core/data/ConstraintViolationSummary.java b/core/src/main/java/org/apache/accumulo/core/data/ConstraintViolationSummary.java
index 2929bc6..d081a8a 100644
--- a/core/src/main/java/org/apache/accumulo/core/data/ConstraintViolationSummary.java
+++ b/core/src/main/java/org/apache/accumulo/core/data/ConstraintViolationSummary.java
@@ -18,6 +18,9 @@ package org.apache.accumulo.core.data;
 
 import org.apache.accumulo.core.data.thrift.TConstraintViolationSummary;
 
+/**
+ * A summary of constraint violations across some number of mutations.
+ */
 public class ConstraintViolationSummary {
   
   public String constrainClass;
@@ -25,6 +28,14 @@ public class ConstraintViolationSummary {
   public String violationDescription;
   public long numberOfViolatingMutations;
   
+  /**
+   * Creates a new summary.
+   *
+   * @param constrainClass
+   * @param violationCode
+   * @param violationDescription
+   * @param numberOfViolatingMutations
+   */
   public ConstraintViolationSummary(String constrainClass, short violationCode, String violationDescription, long numberOfViolatingMutations) {
     this.constrainClass = constrainClass;
     this.violationCode = violationCode;
@@ -32,6 +43,11 @@ public class ConstraintViolationSummary {
     this.numberOfViolatingMutations = numberOfViolatingMutations;
   }
   
+  /**
+   * Creates a new summary from Thrift.
+   *
+   * @param tcvs Thrift summary
+   */
   public ConstraintViolationSummary(TConstraintViolationSummary tcvs) {
     this(tcvs.constrainClass, tcvs.violationCode, tcvs.violationDescription, tcvs.numberOfViolatingMutations);
   }
@@ -87,6 +103,11 @@ public class ConstraintViolationSummary {
     return sb.toString();
   }
   
+  /**
+   * Converts this summary to Thrift.
+   *
+   * @return Thrift summary
+   */
   public TConstraintViolationSummary toThrift() {
     return new TConstraintViolationSummary(this.constrainClass, violationCode, violationDescription, numberOfViolatingMutations);
   }

http://git-wip-us.apache.org/repos/asf/accumulo/blob/74c89324/core/src/main/java/org/apache/accumulo/core/data/Key.java
----------------------------------------------------------------------
diff --git a/core/src/main/java/org/apache/accumulo/core/data/Key.java b/core/src/main/java/org/apache/accumulo/core/data/Key.java
index de9e22d..6d899b7 100644
--- a/core/src/main/java/org/apache/accumulo/core/data/Key.java
+++ b/core/src/main/java/org/apache/accumulo/core/data/Key.java
@@ -98,6 +98,8 @@ public class Key implements WritableComparable<Key>, Cloneable {
   /**
    * Creates a key with the specified row, empty column family, empty column qualifier, empty column visibility, timestamp {@link Long#MAX_VALUE}, and delete
    * marker false.
+   *
+   * @param row row ID
    */
   public Key(Text row) {
     init(row.getBytes(), 0, row.getLength(), EMPTY_BYTES, 0, 0, EMPTY_BYTES, 0, 0, EMPTY_BYTES, 0, 0, Long.MAX_VALUE, false, true);
@@ -106,24 +108,74 @@ public class Key implements WritableComparable<Key>, Cloneable {
   /**
    * Creates a key with the specified row, empty column family, empty column qualifier, empty column visibility, the specified timestamp, and delete marker
    * false.
+   *
+   * @param row row ID
+   * @param ts timestamp
    */
   public Key(Text row, long ts) {
     this(row);
     timestamp = ts;
   }
   
+  /**
+   * Creates a key. The delete marker defaults to false.
+   *
+   * @param row bytes containing row ID
+   * @param rOff offset into row where key's row ID begins (inclusive)
+   * @param rLen length of row ID in row
+   * @param cf bytes containing column family
+   * @param cfOff offset into cf where key's column family begins (inclusive)
+   * @param cfLen length of column family in cf
+   * @param cq bytes containing column qualifier
+   * @param cqOff offset into cq where key's column qualifier begins (inclusive)
+   * @param cqLen length of column qualifier in cq
+   * @param cv bytes containing column visibility
+   * @param cvOff offset into cv where key's column visibility begins (inclusive)
+   * @param cvLen length of column visibility in cv
+   * @param ts timestamp
+   */
   public Key(byte row[], int rOff, int rLen, byte cf[], int cfOff, int cfLen, byte cq[], int cqOff, int cqLen, byte cv[], int cvOff, int cvLen, long ts) {
     init(row, rOff, rLen, cf, cfOff, cfLen, cq, cqOff, cqLen, cv, cvOff, cvLen, ts, false, true);
   }
   
+  /**
+   * Creates a key. The delete marker defaults to false.
+   *
+   * @param row row ID
+   * @param colFamily column family
+   * @param colQualifier column qualifier
+   * @param colVisibility column visibility
+   * @param timestamp timestamp
+   */
   public Key(byte[] row, byte[] colFamily, byte[] colQualifier, byte[] colVisibility, long timestamp) {
     this(row, colFamily, colQualifier, colVisibility, timestamp, false, true);
   }
   
+  /**
+   * Creates a key.
+   *
+   * @param row row ID
+   * @param cf column family
+   * @param cq column qualifier
+   * @param cv column visibility
+   * @param ts timestamp
+   * @param deleted delete marker
+   */
   public Key(byte[] row, byte[] cf, byte[] cq, byte[] cv, long ts, boolean deleted) {
     this(row, cf, cq, cv, ts, deleted, true);
   }
   
+  /**
+   * Creates a key.
+   *
+   * @param row row ID
+   * @param cf column family
+   * @param cq column qualifier
+   * @param cv column visibility
+   * @param ts timestamp
+   * @param deleted delete marker
+   * @param copy if true, forces copy of byte array values into key
+   */
   public Key(byte[] row, byte[] cf, byte[] cq, byte[] cv, long ts, boolean deleted, boolean copy) {
     init(row, 0, row.length, cf, 0, cf.length, cq, 0, cq.length, cv, 0, cv.length, ts, deleted, copy);
   }
@@ -284,6 +336,11 @@ public class Key implements WritableComparable<Key>, Cloneable {
     set(other);
   }
   
+  /**
+   * Creates a key from Thrift.
+   *
+   * @param tkey Thrift key
+   */
   public Key(TKey tkey) {
     this.row = toBytes(tkey.row);
     this.colFamily = toBytes(tkey.colFamily);
@@ -294,88 +351,83 @@ public class Key implements WritableComparable<Key>, Cloneable {
   }
   
   /**
-   * This method gives users control over allocation of Text objects by copying into the passed in text.
+   * Writes the row ID into the given <code>Text</code>. 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
+   * @param r <code>Text</code> object to copy into
+   * @return the <code>Text</code> 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.
+   * Returns the row ID as a byte sequence. This method returns a pointer to the
+   * key's internal data and does not copy it.
    * 
-   * @return ByteSequence that points to the internal key row data.
+   * @return ByteSequence that points to the internal key row ID data
    */
-  
   public ByteSequence getRowData() {
     return new ArrayByteSequence(row);
   }
   
   /**
-   * This method allocates a Text object and copies into it.
+   * Gets the row ID as a <code>Text</code> object.
    * 
-   * @return Text containing the row field
+   * @return Text containing the row ID
    */
-  
   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.
+   * Compares this key's row ID with another.
    * 
-   * @param r
-   *          row to compare to keys row
+   * @param r row ID to compare
    * @return same as {@link #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.
+   * Returns the column family as a byte sequence. This method returns a pointer to the
+   * key's internal data and does not copy it.
    * 
-   * @return ByteSequence that points to the internal key column family data.
+   * @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.
+   * Writes the column family into the given <code>Text</code>. 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
+   * @param cf <code>Text</code> object to copy into
+   * @return the <code>Text</code> 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.
+   * Gets the column family as a <code>Text</code> object.
    * 
-   * @return Text containing the column family field
+   * @return Text containing the column family
    */
-  
   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.
+   * Compares this key's column family with another.
    * 
-   * @param cf
-   *          column family to compare to keys column family
+   * @param cf column family to compare
    * @return same as {@link #getColumnFamily()}.compareTo(cf)
    */
   
@@ -384,105 +436,120 @@ public class Key implements WritableComparable<Key>, Cloneable {
   }
   
   /**
-   * This method returns a pointer to the keys internal data and does not copy it.
+   * Returns the column qualifier as a byte sequence. This method returns a pointer to the
+   * key's internal data and does not copy it.
    * 
-   * @return ByteSequence that points to the internal key column qualifier data.
+   * @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.
+   * Writes the column qualifier into the given <code>Text</code>. 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
+   * @param cq <code>Text</code> object to copy into
+   * @return the <code>Text</code> 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.
+   * Gets the column qualifier as a <code>Text</code> object.
    * 
-   * @return Text containing the column qualifier field
+   * @return Text containing the column qualifier
    */
-  
   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.
+   * Compares this key's column qualifier with another.
    * 
-   * @param cq
-   *          column family to compare to keys column qualifier
+   * @param cq column qualifier to compare
    * @return same as {@link #getColumnQualifier()}.compareTo(cq)
    */
-  
   public int compareColumnQualifier(Text cq) {
     return WritableComparator.compareBytes(colQualifier, 0, colQualifier.length, cq.getBytes(), 0, cq.getLength());
   }
   
+  /**
+   * Sets the timestamp.
+   *
+   * @param ts timestamp
+   */
   public void setTimestamp(long ts) {
     this.timestamp = ts;
   }
   
+  /**
+   * Gets the timestamp.
+   *
+   * @return timestamp
+   */
   public long getTimestamp() {
     return timestamp;
   }
   
+  /**
+   * Determines if this key is deleted (i.e., has a delete marker = true).
+   *
+   * @return true if key is deleted, false if not
+   */
   public boolean isDeleted() {
     return deleted;
   }
   
+  /**
+   * Sets the delete marker on this key.
+   *
+   * @param deleted delete marker (true to delete)
+   */
   public void setDeleted(boolean deleted) {
     this.deleted = deleted;
   }
   
   /**
-   * This method returns a pointer to the keys internal data and does not copy it.
+   * Returns the column visibility as a byte sequence. This method returns a pointer to the
+   * key's internal data and does not copy it.
    * 
-   * @return ByteSequence that points to the internal key column visibility data.
+   * @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.
+   * Gets the column visibility as a <code>Text</code> object.
    * 
-   * @return Text containing the column visibility field
+   * @return Text containing the column visibility
    */
-  
   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.
+   * Writes the column visibvility into the given <code>Text</code>. 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
+   * @param cv <code>Text</code> object to copy into
+   * @return the <code>Text</code> that was passed in
    */
-  
   public final Text getColumnVisibility(Text cv) {
     cv.set(colVisibility, 0, colVisibility.length);
     return cv;
   }
   
   /**
-   * This method creates a new ColumnVisibility representing the column visibility for this key
-   * 
-   * WARNING: using this method may inhibit performance since a new ColumnVisibility object is created on every call.
+   * Gets the column visibility. <b>WARNING:</b> using this method may inhibit
+   * performance since a new ColumnVisibility object is created on every call.
    * 
-   * @return A new object representing the column visibility field
+   * @return ColumnVisibility representing the column visibility
    * @since 1.5.0
    */
   public final ColumnVisibility getColumnVisibilityParsed() {
@@ -491,6 +558,9 @@ public class Key implements WritableComparable<Key>, Cloneable {
   
   /**
    * Sets this key's row, column family, column qualifier, column visibility, timestamp, and delete marker to be the same as another key's.
+   * This method does not copy data from the other key, but only references to it.
+   *
+   * @param k key to set from
    */
   public void set(Key k) {
     row = k.row;
@@ -548,10 +618,12 @@ public class Key implements WritableComparable<Key>, Cloneable {
   }
   
   /**
-   * Compare part of a key. For example compare just the row and column family, and if those are equal then return true.
+   * Compares part of a key. For example, compares just the row and column family, and if those are equal then return true.
    * 
+   * @param other key to compare to
+   * @param part part of key to compare
+   * @return true if specified parts of keys match, false otherwise
    */
-  
   public boolean equals(Key other, PartialKey part) {
     switch (part) {
       case ROW:
@@ -575,12 +647,19 @@ public class Key implements WritableComparable<Key>, Cloneable {
   }
   
   /**
-   * Compare elements of a key given by a {@link PartialKey}. For example, for {@link PartialKey#ROW_COLFAM}, compare just the row and column family. If the
-   * rows are not equal, return the result of the row comparison; otherwise, return the result of the column family comparison.
+   * Compares elements of a key given by a {@link PartialKey}. The corresponding elements (row, column family, column qualifier, column visibility, timestamp,
+   * and delete marker) are compared in order until unequal elements are found. 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. Lastly, a delete marker of true sorts before a delete marker of false. The result of the first unequal comparison is returned.
+   *
+   * For example, for {@link PartialKey#ROW_COLFAM}, this method compares just the row and column family. If the
+   * row IDs are not equal, return the result of the row comparison; otherwise, returns the result of the column family comparison.
    * 
+   * @param other key to compare to
+   * @param part part of key to compare
+   * @return comparison result
    * @see #compareTo(Key)
    */
-  
   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);
@@ -623,12 +702,12 @@ public class Key implements WritableComparable<Key>, Cloneable {
   }
   
   /**
-   * Compare all elements of a key. The elements (row, column family, column qualifier, column visibility, timestamp, and delete marker) are compared in order
-   * until an unequal element is found. 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. Lastly, a delete marker of true sorts before a delete marker of false.
+   * Compares this key with another.
+   *
+   * @param other key to compare to
+   * @return comparison result
+   * @see #compareTo(Key, PartialKey)
    */
-  
   public int compareTo(Key other) {
     return compareTo(other, PartialKey.ROW_COLFAM_COLQUAL_COLVIS_TIME_DEL);
   }
@@ -640,10 +719,37 @@ public class Key implements WritableComparable<Key>, Cloneable {
         + (int) (timestamp ^ (timestamp >>> 32));
   }
   
+  /**
+   * Returns an ASCII printable string form of the given byte array, treating
+   * the bytes as ASCII characters. See
+   * {@link #appendPrintableString(byte[], int, int, int, StringBuilder)}
+   * for caveats.
+   *
+   * @param ba byte array
+   * @param offset offset to start with in byte array (inclusive)
+   * @param len number of bytes to print
+   * @param maxLen maximum number of bytes to convert to printable form
+   * @return printable string
+   * @see #appendPrintableString(byte[], int, int, int, StringBuilder)
+   */
   public static String toPrintableString(byte ba[], int offset, int len, int maxLen) {
     return appendPrintableString(ba, offset, len, maxLen, new StringBuilder()).toString();
   }
   
+  /**
+   * Appends ASCII printable characters to a string, based on the given byte
+   * array, treating the bytes as ASCII characters. If a byte can be converted
+   * to a ASCII printable character it is appended as is; otherwise, it is
+   * appended as a character code, e.g., %05; for byte value 5. If len > maxlen,
+   * the string includes a "TRUNCATED" note at the end.
+   *
+   * @param ba byte array
+   * @param offset offset to start with in byte array (inclusive)
+   * @param len number of bytes to print
+   * @param maxLen maximum number of bytes to convert to printable form
+   * @param sb <code>StringBuilder</code> to append to
+   * @return given <code>StringBuilder</code>
+   */
   public static StringBuilder appendPrintableString(byte ba[], int offset, int len, int maxLen, StringBuilder sb) {
     int plen = Math.min(len, maxLen);
     
@@ -684,14 +790,19 @@ public class Key implements WritableComparable<Key>, Cloneable {
     return sb.toString();
   }
   
+  /**
+   * Converts this key to a string, not including timestamp or delete marker.
+   *
+   * @return string form of key
+   */
   public String toStringNoTime() {
     return rowColumnStringBuilder().toString();
   }
   
   /**
-   * Returns the sums of the lengths of the row, column family, column qualifier, and visibility.
+   * Returns the sums of the lengths of the row, column family, column qualifier, and column visibility.
    * 
-   * @return row.length + colFamily.length + colQualifier.length + colVisibility.length;
+   * @return sum of key field lengths
    */
   public int getLength() {
     return row.length + colFamily.length + colQualifier.length + colVisibility.length;
@@ -699,6 +810,8 @@ public class Key implements WritableComparable<Key>, Cloneable {
   
   /**
    * Same as {@link #getLength()}.
+   *
+   * @return sum of key field lengths
    */
   public int getSize() {
     return getLength();
@@ -741,10 +854,10 @@ public class Key implements WritableComparable<Key>, Cloneable {
   }
   
   /**
-   * Use this to compress a list of keys before sending them via thrift.
+   * Compresses a list of key/value pairs before sending them via thrift.
    * 
-   * @param param
-   *          a list of key/value pairs
+   * @param param list of key/value pairs
+   * @return list of Thrift key/value pairs
    */
   public static List<TKeyValue> compress(List<? extends KeyValue> param) {
     
@@ -793,11 +906,11 @@ public class Key implements WritableComparable<Key>, Cloneable {
   }
   
   /**
-   * Use this to decompress a list of keys received from thrift.
+   * Decompresses a list of key/value pairs received from thrift. Decompression
+   * occurs in place, in the list.
    * 
-   * @param param
+   * @param param list of Thrift key/value pairs
    */
-  
   public static void decompress(List<TKeyValue> param) {
     for (int i = 1; i < param.size(); i++) {
       TKey prevKey = param.get(i - 1).key;
@@ -818,26 +931,56 @@ public class Key implements WritableComparable<Key>, Cloneable {
     }
   }
   
+  /**
+   * Gets the row ID as a byte array.
+   *
+   * @return row ID
+   */
   byte[] getRowBytes() {
     return row;
   }
   
+  /**
+   * Gets the column family as a byte array.
+   *
+   * @return column family
+   */
   byte[] getColFamily() {
     return colFamily;
   }
   
+  /**
+   * Gets the column qualifier as a byte array.
+   *
+   * @return column qualifier
+   */
   byte[] getColQualifier() {
     return colQualifier;
   }
   
+  /**
+   * Gets the column visibility as a byte array.
+   *
+   * @return column visibility
+   */
   byte[] getColVisibility() {
     return colVisibility;
   }
   
+  /**
+   * Converts this key to Thrift.
+   *
+   * @return Thrift key
+   */
   public TKey toThrift() {
     return new TKey(ByteBuffer.wrap(row), ByteBuffer.wrap(colFamily), ByteBuffer.wrap(colQualifier), ByteBuffer.wrap(colVisibility), timestamp);
   }
   
+  /**
+   * Performs a deep copy of this key.
+   *
+   * @return cloned key
+   */
   @Override
   public Object clone() throws CloneNotSupportedException {
     Key r = (Key) super.clone();

http://git-wip-us.apache.org/repos/asf/accumulo/blob/74c89324/core/src/main/java/org/apache/accumulo/core/data/KeyValue.java
----------------------------------------------------------------------
diff --git a/core/src/main/java/org/apache/accumulo/core/data/KeyValue.java b/core/src/main/java/org/apache/accumulo/core/data/KeyValue.java
index cc48322..ee90b6e 100644
--- a/core/src/main/java/org/apache/accumulo/core/data/KeyValue.java
+++ b/core/src/main/java/org/apache/accumulo/core/data/KeyValue.java
@@ -21,16 +21,31 @@ import static org.apache.accumulo.core.util.ByteBufferUtil.toBytes;
 import java.nio.ByteBuffer;
 import java.util.Map;
 
+/**
+ * A key/value pair. The key and value may not be set after construction.
+ */
 public class KeyValue implements Map.Entry<Key,Value> {
   
   public Key key;
   public byte[] value;
   
+  /**
+   * Creates a new key/value pair.
+   *
+   * @param key key
+   * @param value bytes of value
+   */
   public KeyValue(Key key, byte[] value) {
     this.key = key;
     this.value = value;
   }
   
+  /**
+   * Creates a new key/value pair.
+   *
+   * @param key key
+   * @param value buffer containing bytes of value
+   */
   public KeyValue(Key key, ByteBuffer value) {
     this.key = key;
     this.value = toBytes(value);

http://git-wip-us.apache.org/repos/asf/accumulo/blob/74c89324/core/src/main/java/org/apache/accumulo/core/data/Mutation.java
----------------------------------------------------------------------
diff --git a/core/src/main/java/org/apache/accumulo/core/data/Mutation.java b/core/src/main/java/org/apache/accumulo/core/data/Mutation.java
index 5e281f2..d7f7f58 100644
--- a/core/src/main/java/org/apache/accumulo/core/data/Mutation.java
+++ b/core/src/main/java/org/apache/accumulo/core/data/Mutation.java
@@ -42,20 +42,33 @@ import org.apache.hadoop.io.WritableUtils;
  * 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
+ * When always passing in the same data as a CharSequence/String, it's 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.
- * 
+ * 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 columns/values
+ * that were put into it.
+ * </p>
+ *
+ * <p>
+ * 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. A delete marker effectively hides entries for that row column with a timestamp earlier than the marker's. (The hidden data is eventually
+ * removed during Accumulo garbage collection.)
+ * </p>
  */
-
 public class Mutation implements Writable {
   
+  /**
+   * Internally, this class keeps most mutation data in a byte buffer. If a cell
+   * value put into a mutation exceeds this size, then it is stored in a
+   * separate buffer, and a reference to it is inserted into the main buffer.
+   */
   static final int VALUE_SIZE_COPY_CUTOFF = 1 << 15;
   
+  /**
+   * Formats available for serializing Mutations. The formats are described
+   * in a <a href="doc-files/mutation-serialization.html">separate document</a>.
+   */
   public static enum SERIALIZED_FORMAT {
      VERSION1,
      VERSION2
@@ -81,6 +94,9 @@ public class Mutation implements Writable {
   }
   
   /**
+   * Creates a new mutation. A defensive copy is made.
+   *
+   * @param row row ID
    * @since 1.5.0
    */
   public Mutation(byte[] row) {
@@ -88,6 +104,12 @@ public class Mutation implements Writable {
   }
   
   /**
+   * Creates a new mutation. A defensive copy is made.
+   *
+   * @param row byte array containing row ID
+   * @param start starting index of row ID in byte array
+   * @param length length of row ID in byte array
+   * @throws IndexOutOfBoundsException if start or length is invalid
    * @since 1.5.0
    */
   public Mutation(byte[] row, int start, int length) {
@@ -96,16 +118,34 @@ public class Mutation implements Writable {
     buffer = new UnsynchronizedBuffer.Writer();
   }
   
+  /**
+   * Creates a new mutation. A defensive copy is made.
+   *
+   * @param row row ID
+   */
   public Mutation(Text row) {
     this(row.getBytes(), 0, row.getLength());
   }
   
+  /**
+   * Creates a new mutation.
+   *
+   * @param row row ID
+   */
   public Mutation(CharSequence row) {
     this(new Text(row.toString()));
   }
   
+  /**
+   * Creates a new mutation.
+   */
   public Mutation() {}
   
+  /**
+   * Creates a new mutation from a Thrift mutation.
+   *
+   * @param tmutation Thrift mutation
+   */
   public Mutation(TMutation tmutation) {
     this.row = ByteBufferUtil.toBytes(tmutation.row);
     this.data = ByteBufferUtil.toBytes(tmutation.data);
@@ -113,6 +153,11 @@ public class Mutation implements Writable {
     this.values = ByteBufferUtil.toBytesList(tmutation.values);
   }
   
+  /**
+   * Creates a new mutation by copying another.
+   *
+   * @param m mutation to copy
+   */
   public Mutation(Mutation m) {
     m.serialize();
     this.row = m.row;
@@ -121,6 +166,11 @@ public class Mutation implements Writable {
     this.values = m.values;
   }
   
+  /**
+   * Gets the row ID for this mutation. Not a defensive copy.
+   *
+   * @return row ID
+   */
   public byte[] getRow() {
     return row;
   }
@@ -197,87 +247,264 @@ public class Mutation implements Writable {
     put(new Text(cf.toString()), new Text(cq.toString()), cv, hasts, ts, deleted, new Text(val.toString()));
   }
 
+  /**
+   * Puts a modification in this mutation. Column visibility is empty;
+   * timestamp is not set. All parameters are defensively copied.
+   *
+   * @param columnFamily column family
+   * @param columnQualifier column qualifier
+   * @param value cell value
+   */
   public void put(Text columnFamily, Text columnQualifier, Value value) {
     put(columnFamily, columnQualifier, EMPTY_BYTES, false, 0l, false, value.get());
   }
   
+  /**
+   * Puts a modification in this mutation. Timestamp is not set. All parameters
+   * are defensively copied.
+   *
+   * @param columnFamily column family
+   * @param columnQualifier column qualifier
+   * @param columnVisibility column visibility
+   * @param value cell value
+   */
   public void put(Text columnFamily, Text columnQualifier, ColumnVisibility columnVisibility, Value value) {
     put(columnFamily, columnQualifier, columnVisibility.getExpression(), false, 0l, false, value.get());
   }
   
+  /**
+   * Puts a modification in this mutation. Column visibility is empty. All
+   * appropriate parameters are defensively copied.
+   *
+   * @param columnFamily column family
+   * @param columnQualifier column qualifier
+   * @param timestamp timestamp
+   * @param value cell value
+   */
   public void put(Text columnFamily, Text columnQualifier, long timestamp, Value value) {
     put(columnFamily, columnQualifier, EMPTY_BYTES, true, timestamp, false, value.get());
   }
   
+  /**
+   * Puts a modification in this mutation. All appropriate parameters are
+   * defensively copied.
+   *
+   * @param columnFamily column family
+   * @param columnQualifier column qualifier
+   * @param columnVisibility column visibility
+   * @param timestamp timestamp
+   * @param value cell value
+   */
   public void put(Text columnFamily, Text columnQualifier, ColumnVisibility columnVisibility, long timestamp, Value value) {
     put(columnFamily, columnQualifier, columnVisibility.getExpression(), true, timestamp, false, value.get());
   }
   
+  /**
+   * Puts a deletion in this mutation. Matches empty column visibility;
+   * timestamp is not set. All parameters are defensively copied.
+   *
+   * @param columnFamily column family
+   * @param columnQualifier column qualifier
+   */
   public void putDelete(Text columnFamily, Text columnQualifier) {
     put(columnFamily, columnQualifier, EMPTY_BYTES, false, 0l, true, EMPTY_BYTES);
   }
   
+  /**
+   * Puts a deletion in this mutation. Timestamp is not set. All parameters are
+   * defensively copied.
+   *
+   * @param columnFamily column family
+   * @param columnQualifier column qualifier
+   * @param columnVisibility column visibility
+   */
   public void putDelete(Text columnFamily, Text columnQualifier, ColumnVisibility columnVisibility) {
     put(columnFamily, columnQualifier, columnVisibility.getExpression(), false, 0l, true, EMPTY_BYTES);
   }
   
+  /**
+   * Puts a deletion in this mutation. Matches empty column visibility. All
+   * appropriate parameters are defensively copied.
+   *
+   * @param columnFamily column family
+   * @param columnQualifier column qualifier
+   * @param timestamp timestamp
+   */
   public void putDelete(Text columnFamily, Text columnQualifier, long timestamp) {
     put(columnFamily, columnQualifier, EMPTY_BYTES, true, timestamp, true, EMPTY_BYTES);
   }
   
+  /**
+   * Puts a deletion in this mutation. All appropriate parameters are
+   * defensively copied.
+   *
+   * @param columnFamily column family
+   * @param columnQualifier column qualifier
+   * @param columnVisibility column visibility
+   * @param timestamp timestamp
+   */
   public void putDelete(Text columnFamily, Text columnQualifier, ColumnVisibility columnVisibility, long timestamp) {
     put(columnFamily, columnQualifier, columnVisibility.getExpression(), true, timestamp, true, EMPTY_BYTES);
   }
   
+  /**
+   * Puts a modification in this mutation. Column visibility is empty;
+   * timestamp is not set. All parameters are defensively copied.
+   *
+   * @param columnFamily column family
+   * @param columnQualifier column qualifier
+   */
   public void put(CharSequence columnFamily, CharSequence columnQualifier, Value value) {
     put(columnFamily, columnQualifier, EMPTY_BYTES, false, 0l, false, value.get());
   }
   
+  /**
+   * Puts a modification in this mutation. Timestamp is not set. All parameters
+   * are defensively copied.
+   *
+   * @param columnFamily column family
+   * @param columnQualifier column qualifier
+   * @param columnVisibility column visibility
+   * @param value cell value
+   */
   public void put(CharSequence columnFamily, CharSequence columnQualifier, ColumnVisibility columnVisibility, Value value) {
     put(columnFamily, columnQualifier, columnVisibility.getExpression(), false, 0l, false, value.get());
   }
   
+  /**
+   * Puts a modification in this mutation. Column visibility is empty. All
+   * appropriate parameters are defensively copied.
+   *
+   * @param columnFamily column family
+   * @param columnQualifier column qualifier
+   * @param timestamp timestamp
+   * @param value cell value
+   */
   public void put(CharSequence columnFamily, CharSequence columnQualifier, long timestamp, Value value) {
     put(columnFamily, columnQualifier, EMPTY_BYTES, true, timestamp, false, value.get());
   }
   
+  /**
+   * Puts a modification in this mutation. All appropriate parameters are
+   * defensively copied.
+   *
+   * @param columnFamily column family
+   * @param columnQualifier column qualifier
+   * @param columnVisibility column visibility
+   * @param timestamp timestamp
+   * @param value cell value
+   */
   public void put(CharSequence columnFamily, CharSequence columnQualifier, ColumnVisibility columnVisibility, long timestamp, Value value) {
     put(columnFamily, columnQualifier, columnVisibility.getExpression(), true, timestamp, false, value.get());
   }
   
+  /**
+   * Puts a deletion in this mutation. Matches empty column visibility;
+   * timestamp is not set. All parameters are defensively copied.
+   *
+   * @param columnFamily column family
+   * @param columnQualifier column qualifier
+   */
   public void putDelete(CharSequence columnFamily, CharSequence columnQualifier) {
     put(columnFamily, columnQualifier, EMPTY_BYTES, false, 0l, true, EMPTY_BYTES);
   }
   
+  /**
+   * Puts a deletion in this mutation. Timestamp is not set. All appropriate
+   * parameters are defensively copied.
+   *
+   * @param columnFamily column family
+   * @param columnQualifier column qualifier
+   * @param columnVisibility column visibility
+   */
   public void putDelete(CharSequence columnFamily, CharSequence columnQualifier, ColumnVisibility columnVisibility) {
     put(columnFamily, columnQualifier, columnVisibility.getExpression(), false, 0l, true, EMPTY_BYTES);
   }
   
+  /**
+   * Puts a deletion in this mutation. Matches empty column visibility. All
+   * appropriate parameters are defensively copied.
+   *
+   * @param columnFamily column family
+   * @param columnQualifier column qualifier
+   * @param timestamp timestamp
+   */
   public void putDelete(CharSequence columnFamily, CharSequence columnQualifier, long timestamp) {
     put(columnFamily, columnQualifier, EMPTY_BYTES, true, timestamp, true, EMPTY_BYTES);
   }
   
+  /**
+   * Puts a deletion in this mutation. All appropriate parameters are
+   * defensively copied.
+   *
+   * @param columnFamily column family
+   * @param columnQualifier column qualifier
+   * @param columnVisibility column visibility
+   * @param timestamp timestamp
+   */
   public void putDelete(CharSequence columnFamily, CharSequence columnQualifier, ColumnVisibility columnVisibility, long timestamp) {
     put(columnFamily, columnQualifier, columnVisibility.getExpression(), true, timestamp, true, EMPTY_BYTES);
   }
   
+  /**
+   * Puts a modification in this mutation. Column visibility is empty;
+   * timestamp is not set. All parameters are defensively copied.
+   *
+   * @param columnFamily column family
+   * @param columnQualifier column qualifier
+   * @param value cell value
+   */
   public void put(CharSequence columnFamily, CharSequence columnQualifier, CharSequence value) {
     put(columnFamily, columnQualifier, EMPTY_BYTES, false, 0l, false, value);
   }
   
+  /**
+   * Puts a modification in this mutation. Timestamp is not set. All parameters
+   * are defensively copied.
+   *
+   * @param columnFamily column family
+   * @param columnQualifier column qualifier
+   * @param columnVisibility column visibility
+   * @param value cell value
+   */
   public void put(CharSequence columnFamily, CharSequence columnQualifier, ColumnVisibility columnVisibility, CharSequence value) {
     put(columnFamily, columnQualifier, columnVisibility.getExpression(), false, 0l, false, value);
   }
   
+  /**
+   * Puts a modification in this mutation. Column visibility is empty. All
+   * appropriate parameters are defensively copied.
+   *
+   * @param columnFamily column family
+   * @param columnQualifier column qualifier
+   * @param timestamp timestamp
+   * @param value cell value
+   */
   public void put(CharSequence columnFamily, CharSequence columnQualifier, long timestamp, CharSequence value) {
     put(columnFamily, columnQualifier, EMPTY_BYTES, true, timestamp, false, value);
   }
   
+  /**
+   * Puts a modification in this mutation. All appropriate parameters are
+   * defensively copied.
+   *
+   * @param columnFamily column family
+   * @param columnQualifier column qualifier
+   * @param columnVisibility column visibility
+   * @param timestamp timestamp
+   * @param value cell value
+   */
   public void put(CharSequence columnFamily, CharSequence columnQualifier, ColumnVisibility columnVisibility, long timestamp, CharSequence value) {
     put(columnFamily, columnQualifier, columnVisibility.getExpression(), true, timestamp, false, value);
   }
   
   /**
+   * Puts a modification in this mutation. Column visibility is empty;
+   * timestamp is not set. All parameters are defensively copied.
+   *
+   * @param columnFamily column family
+   * @param columnQualifier column qualifier
+   * @param value cell value
    * @since 1.5.0
    */
   public void put(byte[] columnFamily, byte[] columnQualifier, byte[] value) {
@@ -285,6 +512,13 @@ public class Mutation implements Writable {
   }
   
   /**
+   * Puts a modification in this mutation. Timestamp is not set. All parameters
+   * are defensively copied.
+   *
+   * @param columnFamily column family
+   * @param columnQualifier column qualifier
+   * @param columnVisibility column visibility
+   * @param value cell value
    * @since 1.5.0
    */
   public void put(byte[] columnFamily, byte[] columnQualifier, ColumnVisibility columnVisibility, byte[] value) {
@@ -292,6 +526,13 @@ public class Mutation implements Writable {
   }
   
   /**
+   * Puts a modification in this mutation. Column visibility is empty. All
+   * appropriate parameters are defensively copied.
+   *
+   * @param columnFamily column family
+   * @param columnQualifier column qualifier
+   * @param timestamp timestamp
+   * @param value cell value
    * @since 1.5.0
    */
   public void put(byte[] columnFamily, byte[] columnQualifier, long timestamp, byte[] value) {
@@ -299,6 +540,14 @@ public class Mutation implements Writable {
   }
   
   /**
+   * Puts a modification in this mutation. All appropriate parameters are
+   * defensively copied.
+   *
+   * @param columnFamily column family
+   * @param columnQualifier column qualifier
+   * @param columnVisibility column visibility
+   * @param timestamp timestamp
+   * @param value cell value
    * @since 1.5.0
    */
   public void put(byte[] columnFamily, byte[] columnQualifier, ColumnVisibility columnVisibility, long timestamp, byte[] value) {
@@ -306,6 +555,11 @@ public class Mutation implements Writable {
   }
   
   /**
+   * Puts a deletion in this mutation. Matches empty column visibility;
+   * timestamp is not set. All parameters are defensively copied.
+   *
+   * @param columnFamily column family
+   * @param columnQualifier column qualifier
    * @since 1.5.0
    */
   public void putDelete(byte[] columnFamily, byte[] columnQualifier) {
@@ -313,6 +567,12 @@ public class Mutation implements Writable {
   }
   
   /**
+   * Puts a deletion in this mutation. Timestamp is not set. All parameters are
+   * defensively copied.
+   *
+   * @param columnFamily column family
+   * @param columnQualifier column qualifier
+   * @param columnVisibility column visibility
    * @since 1.5.0
    */
   public void putDelete(byte[] columnFamily, byte[] columnQualifier, ColumnVisibility columnVisibility) {
@@ -320,6 +580,12 @@ public class Mutation implements Writable {
   }
   
   /**
+   * Puts a deletion in this mutation. Matches empty column visibility. All
+   * appropriate parameters are defensively copied.
+   *
+   * @param columnFamily column family
+   * @param columnQualifier column qualifier
+   * @param timestamp timestamp
    * @since 1.5.0
    */
   public void putDelete(byte[] columnFamily, byte[] columnQualifier, long timestamp) {
@@ -327,6 +593,13 @@ public class Mutation implements Writable {
   }
   
   /**
+   * Puts a deletion in this mutation. All appropriate parameters are
+   * defensively copied.
+   *
+   * @param columnFamily column family
+   * @param columnQualifier column qualifier
+   * @param columnVisibility column visibility
+   * @param timestamp timestamp
    * @since 1.5.0
    */
   public void putDelete(byte[] columnFamily, byte[] columnQualifier, ColumnVisibility columnVisibility, long timestamp) {
@@ -353,6 +626,13 @@ public class Mutation implements Writable {
     return bytes;
   }
   
+  /**
+   * Gets the modifications and deletions in this mutation. After calling
+   * this method, further modifications to this mutation are ignored. Changes
+   * made to the returned updates do not affect this mutation.
+   *
+   * @return list of modifications and deletions
+   */
   public List<ColumnUpdate> getUpdates() {
     serialize();
     
@@ -405,6 +685,12 @@ public class Mutation implements Writable {
   
   private int cachedValLens = -1;
   
+  /**
+   * Gets the byte length of all large values stored in this mutation.
+   *
+   * @return length of all large values
+   * @see #VALUE_SIZE_COPY_CUTOFF
+   */
   long getValueLengths() {
     if (values == null)
       return 0;
@@ -421,17 +707,30 @@ public class Mutation implements Writable {
     
   }
   
+  /**
+   * Gets the total number of bytes in this mutation.
+   *
+   * @return length of mutation in bytes
+   */
   public long numBytes() {
     serialize();
     return row.length + data.length + getValueLengths();
   }
   
+  /**
+   * Gets an estimate of the amount of memory used by this mutation. The
+   * estimate includes data sizes and object overhead.
+   *
+   * @return memory usage estimate
+   */
   public long estimatedMemoryUsed() {
     return numBytes() + 238;
   }
   
   /**
-   * @return the number of column value pairs added to the mutation
+   * Gets the number of modifications / deletions in this mutation.
+   *
+   * @return the number of modifications / deletions
    */
   public int size() {
     return entries;
@@ -580,14 +879,14 @@ public class Mutation implements Writable {
   public int hashCode() {
     return toThrift().hashCode();
   }
-
   /**
-   * Checks if this mutation equals another. This method may be removed in a
-   * future API revision in favor of {@link #equals(Object)}. See ACCUMULO-1627
-   * for more information.
+   * Checks if this mutation equals another. Two mutations are equal if they
+   * target the same row and have the same modifications and deletions, in order.
+   * This method may be removed in a  future API revision in favor of
+   * {@link #equals(Object)}. See ACCUMULO-1627 for more information.
    *
-   * @param m mutation
-   * @return true if the given mutation equals this one, false otehrwise
+   * @param m mutation to compare
+   * @return true if this mutation equals the other, false otherwise
    */
   public boolean equals(Mutation m) {
     return this.equals((Object) m);
@@ -613,11 +912,21 @@ public class Mutation implements Writable {
     return false;
   }
   
+  /**
+   * Converts this mutation to Thrift.
+   *
+   * @return Thrift mutation
+   */
   public TMutation toThrift() {
     serialize();
     return new TMutation(java.nio.ByteBuffer.wrap(row), java.nio.ByteBuffer.wrap(data), ByteBufferUtil.toByteBuffers(values), entries);
   }
   
+  /**
+   * Gets the serialization format used to (de)serialize this mutation.
+   *
+   * @return serialization format
+   */
   protected SERIALIZED_FORMAT getSerializedFormat() {
     return this.useOldDeserialize ? SERIALIZED_FORMAT.VERSION1 : SERIALIZED_FORMAT.VERSION2;
   }

http://git-wip-us.apache.org/repos/asf/accumulo/blob/74c89324/core/src/main/java/org/apache/accumulo/core/data/PartialKey.java
----------------------------------------------------------------------
diff --git a/core/src/main/java/org/apache/accumulo/core/data/PartialKey.java b/core/src/main/java/org/apache/accumulo/core/data/PartialKey.java
index 2049881..5636de0 100644
--- a/core/src/main/java/org/apache/accumulo/core/data/PartialKey.java
+++ b/core/src/main/java/org/apache/accumulo/core/data/PartialKey.java
@@ -16,6 +16,9 @@
  */
 package org.apache.accumulo.core.data;
 
+/**
+ * Specifications for part of a {@link Key}.
+ */
 public enum PartialKey {
   ROW(1), ROW_COLFAM(2), ROW_COLFAM_COLQUAL(3), ROW_COLFAM_COLQUAL_COLVIS(4), ROW_COLFAM_COLQUAL_COLVIS_TIME(5),
   //everything with delete flag
@@ -28,6 +31,13 @@ public enum PartialKey {
     this.depth = depth;
   }
   
+  /**
+   * Get a partial key specification by depth of the specification.
+   *
+   * @param depth depth of scope (i.e., number of fields included)
+   * @return partial key
+   * @throws IllegalArgumentException if no partial key has the given depth
+   */
   public static PartialKey getByDepth(int depth) {
     for (PartialKey d : PartialKey.values())
       if (depth == d.depth)
@@ -35,6 +45,11 @@ public enum PartialKey {
     throw new IllegalArgumentException("Invalid legacy depth " + depth);
   }
   
+  /**
+   * Gets the depth of this partial key.
+   *
+   * @return depth
+   */
   public int getDepth() {
     return depth;
   }


Mime
View raw message