You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@accumulo.apache.org by el...@apache.org on 2013/12/16 20:27:16 UTC
[2/3] git commit: ACCUMULO-1931 Javadoc for core/data
ACCUMULO-1931 Javadoc for core/data
Signed-off-by: Josh Elser <el...@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 <bh...@cloudera.com>
Authored: Mon Oct 7 11:35:39 2013 -0400
Committer: Josh Elser <el...@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;
}