Return-Path: X-Original-To: apmail-accumulo-commits-archive@www.apache.org Delivered-To: apmail-accumulo-commits-archive@www.apache.org Received: from mail.apache.org (hermes.apache.org [140.211.11.3]) by minotaur.apache.org (Postfix) with SMTP id D4C691080F for ; Mon, 16 Dec 2013 19:27:16 +0000 (UTC) Received: (qmail 3115 invoked by uid 500); 16 Dec 2013 19:27:16 -0000 Delivered-To: apmail-accumulo-commits-archive@accumulo.apache.org Received: (qmail 3018 invoked by uid 500); 16 Dec 2013 19:27:16 -0000 Mailing-List: contact commits-help@accumulo.apache.org; run by ezmlm Precedence: bulk List-Help: List-Unsubscribe: List-Post: List-Id: Reply-To: dev@accumulo.apache.org Delivered-To: mailing list commits@accumulo.apache.org Received: (qmail 2940 invoked by uid 99); 16 Dec 2013 19:27:16 -0000 Received: from tyr.zones.apache.org (HELO tyr.zones.apache.org) (140.211.11.114) by apache.org (qpsmtpd/0.29) with ESMTP; Mon, 16 Dec 2013 19:27:16 +0000 Received: by tyr.zones.apache.org (Postfix, from userid 65534) id E7B8291DE92; Mon, 16 Dec 2013 19:27:15 +0000 (UTC) Content-Type: text/plain; charset="us-ascii" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit From: elserj@apache.org To: commits@accumulo.apache.org Date: Mon, 16 Dec 2013 19:27:16 -0000 Message-Id: <0be2f79f18ea4e80859e3284a8d2d64e@git.apache.org> In-Reply-To: References: X-Mailer: ASF-Git Admin Mailer Subject: [2/3] git commit: ACCUMULO-1931 Javadoc for core/data ACCUMULO-1931 Javadoc for core/data Signed-off-by: Josh Elser 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 Authored: Mon Oct 7 11:35:39 2013 -0400 Committer: Josh Elser 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 { + /** + * 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 { 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 { static private int compareBytes(byte[] a, byte[] b) { @@ -39,6 +42,13 @@ public class Column implements WritableComparable { 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 { 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 { 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 { 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 { 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 + * BinaryComparable 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, 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, 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, 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, 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 Text. 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 Text object to copy into + * @return the Text that was passed in */ - public Text getRow(Text r) { r.set(row, 0, row.length); return r; } /** - * This method returns a pointer to the keys internal data and does not copy it. + * 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 Text 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 Text. 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 Text object to copy into + * @return the Text that was passed in */ - public Text getColumnFamily(Text cf) { cf.set(colFamily, 0, colFamily.length); return cf; } /** - * This method allocates a Text object and copies into it. + * Gets the column family as a Text 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, 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 Text. 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 Text object to copy into + * @return the Text that was passed in */ - public Text getColumnQualifier(Text cq) { cq.set(colQualifier, 0, colQualifier.length); return cq; } /** - * This method allocates a Text object and copies into it. + * Gets the column qualifier as a Text 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 Text 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 Text. This method gives + * users control over allocation of Text objects by copying into the passed in + * text. * - * @param cv - * the key's column visibility will be copied into this Text - * @return the Text that was passed in + * @param cv Text object to copy into + * @return the Text 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. WARNING: 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, 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, 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, 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, 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, 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 StringBuilder to append to + * @return given StringBuilder + */ 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, 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, 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, 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 compress(List param) { @@ -793,11 +906,11 @@ public class Key implements WritableComparable, 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 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, 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 { 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. * *

- * 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. * *

- * 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. + *

+ * + *

+ * 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.) + *

*/ - 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 separate document. + */ 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 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; }