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:15 UTC
[1/3] ACCUMULO-1931 Javadoc for core/data
Updated Branches:
refs/heads/master 75685ce8b -> 3a2e0a925
http://git-wip-us.apache.org/repos/asf/accumulo/blob/74c89324/core/src/main/java/org/apache/accumulo/core/data/Range.java
----------------------------------------------------------------------
diff --git a/core/src/main/java/org/apache/accumulo/core/data/Range.java b/core/src/main/java/org/apache/accumulo/core/data/Range.java
index 65873c3..adfd17b 100644
--- a/core/src/main/java/org/apache/accumulo/core/data/Range.java
+++ b/core/src/main/java/org/apache/accumulo/core/data/Range.java
@@ -30,10 +30,10 @@ import org.apache.hadoop.io.Text;
import org.apache.hadoop.io.WritableComparable;
/**
- * This class is used to specify a range of Accumulo Keys.
+ * This class is used to specify a range of Accumulo keys.
*
+ * @see Key
*/
-
public class Range implements WritableComparable<Range> {
private Key start;
@@ -46,113 +46,96 @@ public class Range implements WritableComparable<Range> {
/**
* Creates a range that goes from negative to positive infinity
*/
-
public Range() {
this((Key) null, true, (Key) null, true);
}
/**
- * Creates a range from startKey inclusive to endKey inclusive
+ * Creates a range from startKey inclusive to endKey inclusive.
*
- * @param startKey
- * set this to null when negative infinity is needed
- * @param endKey
- * set this to null when positive infinity is needed
+ * @param startKey starting key; set to null for negative infinity
+ * @param endKey ending key; set to null for positive infinity
+ * @throws IllegalArgumentException if end key is before start key
*/
public Range(Key startKey, Key endKey) {
this(startKey, true, endKey, true);
}
/**
- * Creates a range that covers an entire row
+ * Creates a range that covers an entire row.
*
- * @param row
- * set this to null to cover all rows
+ * @param row row to cover; set to null to cover all rows
*/
public Range(CharSequence row) {
this(row, true, row, true);
}
/**
- * Creates a range that covers an entire row
+ * Creates a range that covers an entire row.
*
- * @param row
- * set this to null to cover all rows
+ * @param row row to cover; set to null to cover all rows
*/
public Range(Text row) {
this(row, true, row, true);
}
/**
- * Creates a range from startRow inclusive to endRow inclusive
+ * Creates a range from startRow inclusive to endRow inclusive.
*
- * @param startRow
- * set this to null when negative infinity is needed
- * @param endRow
- * set this to null when positive infinity is needed
+ * @param startRow starting row; set to null for negative infinity
+ * @param endRow ending row; set to null for positive infinity
+ * @throws IllegalArgumentException if end row is before start row
*/
public Range(Text startRow, Text endRow) {
this(startRow, true, endRow, true);
}
/**
- * Creates a range from startRow inclusive to endRow inclusive
+ * Creates a range from startRow inclusive to endRow inclusive.
*
- * @param startRow
- * set this to null when negative infinity is needed
- * @param endRow
- * set this to null when positive infinity is needed
+ * @param startRow starting row; set to null for negative infinity
+ * @param endRow ending row; set to null for positive infinity
+ * @throws IllegalArgumentException if end row is before start row
*/
public Range(CharSequence startRow, CharSequence endRow) {
this(startRow, true, endRow, true);
}
/**
- * Creates a range from startRow to endRow
+ * Creates a range from startRow to endRow.
*
- * @param startRow
- * set this to null when negative infinity is needed
- * @param startRowInclusive
- * determines if the start row is skipped
- * @param endRow
- * set this to null when positive infinity is needed
- * @param endRowInclusive
- * determines if the endRow is included
+ * @param startRow starting row; set to null for negative infinity
+ * @param startRowInclusive true to include start row, false to skip
+ * @param endRow ending row; set to null for positive infinity
+ * @param endRowInclusive true to include start row, false to skip
+ * @throws IllegalArgumentException if end row is before start row
*/
-
public Range(Text startRow, boolean startRowInclusive, Text endRow, boolean endRowInclusive) {
this((startRow == null ? null : (startRowInclusive ? new Key(startRow) : new Key(startRow).followingKey(PartialKey.ROW))), true, (endRow == null ? null
: (endRowInclusive ? new Key(endRow).followingKey(PartialKey.ROW) : new Key(endRow))), false);
}
/**
- * Creates a range from startRow to endRow
+ * Creates a range from startRow to endRow.
*
- * @param startRow
- * set this to null when negative infinity is needed
- * @param startRowInclusive
- * determines if the start row is skipped
- * @param endRow
- * set this to null when positive infinity is needed
- * @param endRowInclusive
- * determines if the endRow is included
+ * @param startRow starting row; set to null for negative infinity
+ * @param startRowInclusive true to include start row, false to skip
+ * @param endRow ending row; set to null for positive infinity
+ * @param endRowInclusive true to include start row, false to skip
+ * @throws IllegalArgumentException if end row is before start row
*/
-
public Range(CharSequence startRow, boolean startRowInclusive, CharSequence endRow, boolean endRowInclusive) {
this(startRow == null ? null : new Text(startRow.toString()), startRowInclusive, endRow == null ? null : new Text(endRow.toString()), endRowInclusive);
}
/**
- * Creates a range from startKey to endKey
+ * Creates a range from startKey to endKey.
*
- * @param startKey
- * set this to null when negative infinity is needed
- * @param startKeyInclusive
- * determines if the ranges includes the start key
- * @param endKey
- * set this to null when infinity is needed
- * @param endKeyInclusive
- * determines if the range includes the end key
+ * @param startKey starting key; set to null for negative infinity
+ * @param startKeyInclusive true to include start key, false to skip
+ * @param endKey ending key; set to null for positive infinity
+ * @param endKeyInclusive true to include start key, false to skip
+ * @throws IllegalArgumentException if end key is before start key
*/
public Range(Key startKey, boolean startKeyInclusive, Key endKey, boolean endKeyInclusive) {
this.start = startKey;
@@ -168,7 +151,9 @@ public class Range implements WritableComparable<Range> {
}
/**
- * Copies a range
+ * Copies a range.
+ *
+ * @param range range to copy
*/
public Range(Range range) {
this(range.start, range.startKeyInclusive, range.infiniteStartKey, range.stop, range.stopKeyInclusive, range.infiniteStopKey);
@@ -233,6 +218,11 @@ public class Range implements WritableComparable<Range> {
this.infiniteStopKey = infiniteStopKey;
}
+ /**
+ * Creates a range from a Thrift range.
+ *
+ * @param trange Thrift range
+ */
public Range(TRange trange) {
this(trange.start == null ? null : new Key(trange.start), trange.startKeyInclusive, trange.infiniteStartKey,
trange.stop == null ? null : new Key(trange.stop), trange.stopKeyInclusive, trange.infiniteStopKey);
@@ -242,7 +232,9 @@ public class Range implements WritableComparable<Range> {
}
/**
- * @return the first key in the range, null if the key is infinite
+ * Gets the start key, or null if the start is negative infinity.
+ *
+ * @return start key
*/
public Key getStartKey() {
if (infiniteStartKey) {
@@ -252,8 +244,9 @@ public class Range implements WritableComparable<Range> {
}
/**
- *
- * @param key
+ * Determines if the given key is before the start key of this range.
+ *
+ * @param key key to check
* @return true if the given key is before the range, otherwise false
*/
public boolean beforeStartKey(Key key) {
@@ -267,9 +260,10 @@ public class Range implements WritableComparable<Range> {
}
/**
- * @return the last key in the range, null if the end key is infinite
+ * Gets the ending key, or null if the end is positive infinity.
+ *
+ * @return ending key
*/
-
public Key getEndKey() {
if (infiniteStopKey) {
return null;
@@ -278,10 +272,11 @@ public class Range implements WritableComparable<Range> {
}
/**
- * @param key
+ * Determines if the given key is after the ending key of this range.
+ *
+ * @param key key to check
* @return true if the given key is after the range, otherwise false
*/
-
public boolean afterEndKey(Key key) {
if (infiniteStopKey)
return false;
@@ -306,14 +301,24 @@ public class Range implements WritableComparable<Range> {
return false;
}
+ /**
+ * Determines if this range equals another.
+ *
+ * @param otherRange range to compare
+ * @return true if ranges are equals, false otherwise
+ * @see #compareTo(Range)
+ */
public boolean equals(Range otherRange) {
return compareTo(otherRange) == 0;
}
/**
- * Compares this range to another range. Compares in the order start key, inclusiveness of start key, end key, inclusiveness of end key. Infinite keys sort
+ * Compares this range to another range. Compares in order: start key, inclusiveness of start key, end key, inclusiveness of end key. Infinite keys sort
* first, and non-infinite keys are compared with {@link Key#compareTo(Key)}. Inclusive sorts before non-inclusive.
+ *
+ * @param o range to compare
+ * @return comparison result
*/
public int compareTo(Range o) {
int comp;
@@ -356,31 +361,31 @@ public class Range implements WritableComparable<Range> {
}
/**
- *
- * @param key
- * @return true if the given key falls within the range
+ * Determines if the given key falls within this range.
+ *
+ * @param key key to consider
+ * @return true if the given key falls within the range, false otherwise
*/
public boolean contains(Key key) {
return !beforeStartKey(key) && !afterEndKey(key);
}
/**
- * Takes a collection on range and merges overlapping and adjacent ranges. For example given the following input
+ * Merges overlapping and adjacent ranges. For example given the following input:
*
* <pre>
* [a,c], (c, d], (g,m), (j,t]
* </pre>
*
- * the following ranges would be returned
+ * the following ranges would be returned:
*
* <pre>
* [a,d], (g,t]
* </pre>
*
- * @param ranges
+ * @param ranges to merge
* @return list of merged ranges
*/
-
public static List<Range> mergeOverlapping(Collection<Range> ranges) {
if (ranges.size() == 0)
return Collections.emptyList();
@@ -447,24 +452,24 @@ public class Range implements WritableComparable<Range> {
* System.out.println(range3.equals(new Range("c", "f")));
* </pre>
*
- * @param range
- * @return the intersection
- * @throws IllegalArgumentException
- * if ranges does not overlap
+ * @param range range to clip to
+ * @return the intersection of this range and the given range
+ * @throws IllegalArgumentException if ranges does not overlap
*/
-
public Range clip(Range range) {
return clip(range, false);
}
/**
- * Same as other clip function except if gives the option to return null of the ranges do not overlap instead of throwing an exception.
+ * Creates a range which represents the intersection of this range and the passed in range. Unlike {@link #clip(Range)},
+ * this method can optionally return null if the ranges do not overlap, instead of throwing an exception. The returnNullIfDisjoint parameter controls this
+ * behavior.
*
+ * @param range range to clip to
+ * @param returnNullIfDisjoint true to return null if ranges are disjoint, false to throw an exception
+ * @return the intersection of this range and the given range, or null if ranges do not overlap and returnNullIfDisjoint is true
+ * @throws IllegalArgumentException if ranges does not overlap and returnNullIfDisjoint is false
* @see Range#clip(Range)
- * @param range
- * @param returnNullIfDisjoint
- * If the ranges do not overlap and true is passed, then null is returned otherwise an exception is thrown.
- * @return the intersection
*/
public Range clip(Range range, boolean returnNullIfDisjoint) {
@@ -509,17 +514,14 @@ public class Range implements WritableComparable<Range> {
}
/**
- * Creates a new range that is bounded by the columns passed in. The stary key in the returned range will have a column >= to the minimum column. The end key
+ * Creates a new range that is bounded by the columns passed in. The start key in the returned range will have a column >= to the minimum column. The end key
* in the returned range will have a column <= the max column.
*
- *
- * @param min
- * @param max
+ * @param min minimum column
+ * @param max maximum column
* @return a column bounded range
- * @throws IllegalArgumentException
- * if min > max
+ * @throws IllegalArgumentException if the minimum column compares greater than the maximum column
*/
-
public Range bound(Column min, Column max) {
if (min.compareTo(max) > 0) {
@@ -631,45 +633,67 @@ public class Range implements WritableComparable<Range> {
out.writeBoolean(stopKeyInclusive);
}
+ /**
+ * Gets whether the start key of this range is inclusive.
+ *
+ * @return true if start key is inclusive
+ */
public boolean isStartKeyInclusive() {
return startKeyInclusive;
}
+ /**
+ * Gets whether the end key of this range is inclusive.
+ *
+ * @return true if end key is inclusive
+ */
public boolean isEndKeyInclusive() {
return stopKeyInclusive;
}
+ /**
+ * Converts this range to Thrift.
+ *
+ * @return Thrift range
+ */
public TRange toThrift() {
return new TRange(start == null ? null : start.toThrift(), stop == null ? null : stop.toThrift(), startKeyInclusive, stopKeyInclusive, infiniteStartKey,
infiniteStopKey);
}
+ /**
+ * Gets whether the start key is negative infinity.
+ *
+ * @return true if start key is negative infinity
+ */
public boolean isInfiniteStartKey() {
return infiniteStartKey;
}
+ /**
+ * Gets whether the end key is positive infinity.
+ *
+ * @return true if end key is positive infinity
+ */
public boolean isInfiniteStopKey() {
return infiniteStopKey;
}
/**
- * Creates a range that covers an exact row Returns the same Range as new Range(row)
+ * Creates a range that covers an exact row. Returns the same Range as
+ * {@link #Range(Text)}.
*
- * @param row
- * all keys in the range will have this row
+ * @param row row to cover; set to null to cover all rows
*/
public static Range exact(Text row) {
return new Range(row);
}
/**
- * Creates a range that covers an exact row and column family
- *
- * @param row
- * all keys in the range will have this row
+ * Creates a range that covers an exact row and column family.
*
- * @param cf
- * all keys in the range will have this column family
+ * @param row row row to cover
+ * @param cf column family to cover
*/
public static Range exact(Text row, Text cf) {
Key startKey = new Key(row, cf);
@@ -677,16 +701,11 @@ public class Range implements WritableComparable<Range> {
}
/**
- * Creates a range that covers an exact row, column family, and column qualifier
+ * Creates a range that covers an exact row, column family, and column qualifier.
*
- * @param row
- * all keys in the range will have this row
- *
- * @param cf
- * all keys in the range will have this column family
- *
- * @param cq
- * all keys in the range will have this column qualifier
+ * @param row row row to cover
+ * @param cf column family to cover
+ * @param cq column qualifier to cover
*/
public static Range exact(Text row, Text cf, Text cq) {
Key startKey = new Key(row, cf, cq);
@@ -694,19 +713,12 @@ public class Range implements WritableComparable<Range> {
}
/**
- * Creates a range that covers an exact row, column family, column qualifier, and visibility
- *
- * @param row
- * all keys in the range will have this row
- *
- * @param cf
- * all keys in the range will have this column family
- *
- * @param cq
- * all keys in the range will have this column qualifier
+ * Creates a range that covers an exact row, column family, column qualifier, and column visibility.
*
- * @param cv
- * all keys in the range will have this column visibility
+ * @param row row row to cover
+ * @param cf column family to cover
+ * @param cq column qualifier to cover
+ * @param cv column visibility to cover
*/
public static Range exact(Text row, Text cf, Text cq, Text cv) {
Key startKey = new Key(row, cf, cq, cv);
@@ -714,22 +726,13 @@ public class Range implements WritableComparable<Range> {
}
/**
- * Creates a range that covers an exact row, column family, column qualifier, visibility, and timestamp
- *
- * @param row
- * all keys in the range will have this row
- *
- * @param cf
- * all keys in the range will have this column family
- *
- * @param cq
- * all keys in the range will have this column qualifier
- *
- * @param cv
- * all keys in the range will have this column visibility
+ * Creates a range that covers an exact row, column family, column qualifier, column visibility, and timestamp.
*
- * @param ts
- * all keys in the range will have this timestamp
+ * @param row row row to cover
+ * @param cf column family to cover
+ * @param cq column qualifier to cover
+ * @param cv column visibility to cover
+ * @param ts timestamp to cover
*/
public static Range exact(Text row, Text cf, Text cq, Text cv, long ts) {
Key startKey = new Key(row, cf, cq, cv, ts);
@@ -737,9 +740,11 @@ public class Range implements WritableComparable<Range> {
}
/**
- * Returns a Text that sorts just after all Texts beginning with a prefix
+ * Returns a Text that sorts just after all Texts beginning with a prefix.
*
- * @param prefix
+ * @param prefix to follow
+ * @return prefix that immediately follows the given prefix when sorted, or
+ * null if no prefix can follow (i.e., the string is all 0xff bytes)
*/
public static Text followingPrefix(Text prefix) {
byte[] prefixBytes = prefix.getBytes();
@@ -761,10 +766,9 @@ public class Range implements WritableComparable<Range> {
}
/**
- * Returns a Range that covers all rows beginning with a prefix
+ * Returns a Range that covers all rows beginning with a prefix.
*
- * @param rowPrefix
- * all keys in the range will have rows that begin with this prefix
+ * @param rowPrefix prefix of rows to cover
*/
public static Range prefix(Text rowPrefix) {
Text fp = followingPrefix(rowPrefix);
@@ -772,13 +776,10 @@ public class Range implements WritableComparable<Range> {
}
/**
- * Returns a Range that covers all column families beginning with a prefix within a given row
+ * Returns a Range that covers all column families beginning with a prefix within a given row.
*
- * @param row
- * all keys in the range will have this row
- *
- * @param cfPrefix
- * all keys in the range will have column families that begin with this prefix
+ * @param row row to cover
+ * @param cfPrefix prefix of column families to cover
*/
public static Range prefix(Text row, Text cfPrefix) {
Text fp = followingPrefix(cfPrefix);
@@ -786,16 +787,11 @@ public class Range implements WritableComparable<Range> {
}
/**
- * Returns a Range that covers all column qualifiers beginning with a prefix within a given row and column family
- *
- * @param row
- * all keys in the range will have this row
+ * Returns a Range that covers all column qualifiers beginning with a prefix within a given row and column family.
*
- * @param cf
- * all keys in the range will have this column family
- *
- * @param cqPrefix
- * all keys in the range will have column qualifiers that begin with this prefix
+ * @param row row to cover
+ * @param cf column family to cover
+ * @param cqPrefix prefix of column qualifiers to cover
*/
public static Range prefix(Text row, Text cf, Text cqPrefix) {
Text fp = followingPrefix(cqPrefix);
@@ -803,19 +799,12 @@ public class Range implements WritableComparable<Range> {
}
/**
- * Returns a Range that covers all column visibilities beginning with a prefix within a given row, column family, and column qualifier
- *
- * @param row
- * all keys in the range will have this row
+ * Returns a Range that covers all column visibilities beginning with a prefix within a given row, column family, and column qualifier.
*
- * @param cf
- * all keys in the range will have this column family
- *
- * @param cq
- * all keys in the range will have this column qualifier
- *
- * @param cvPrefix
- * all keys in the range will have column visibilities that begin with this prefix
+ * @param row row to cover
+ * @param cf column family to cover
+ * @param cq column qualifier to cover
+ * @param cvPrefix prefix of column visibilities to cover
*/
public static Range prefix(Text row, Text cf, Text cq, Text cvPrefix) {
Text fp = followingPrefix(cvPrefix);
@@ -824,81 +813,104 @@ public class Range implements WritableComparable<Range> {
}
/**
- * Creates a range that covers an exact row
+ * Creates a range that covers an exact row.
*
- * @see Range#exact(Text)
+ * @param row row to cover; set to null to cover all rows
+ * @see #exact(Text)
*/
public static Range exact(CharSequence row) {
return Range.exact(new Text(row.toString()));
}
/**
- * Creates a range that covers an exact row and column family
+ * Creates a range that covers an exact row and column family.
*
- * @see Range#exact(Text, Text)
+ * @param row row row to cover
+ * @param cf column family to cover
+ * @see #exact(Text, Text)
*/
public static Range exact(CharSequence row, CharSequence cf) {
return Range.exact(new Text(row.toString()), new Text(cf.toString()));
}
/**
- * Creates a range that covers an exact row, column family, and column qualifier
+ * Creates a range that covers an exact row, column family, and column qualifier.
*
- * @see Range#exact(Text, Text, Text)
+ * @param row row row to cover
+ * @param cf column family to cover
+ * @param cq column qualifier to cover
+ * @see #exact(Text, Text, Text)
*/
public static Range exact(CharSequence row, CharSequence cf, CharSequence cq) {
return Range.exact(new Text(row.toString()), new Text(cf.toString()), new Text(cq.toString()));
}
/**
- * Creates a range that covers an exact row, column family, column qualifier, and visibility
+ * Creates a range that covers an exact row, column family, column qualifier, and column visibility.
*
- * @see Range#exact(Text, Text, Text, Text)
+ * @param row row row to cover
+ * @param cf column family to cover
+ * @param cq column qualifier to cover
+ * @param cv column visibility to cover
+ * @see #exact(Text, Text, Text, Text)
*/
public static Range exact(CharSequence row, CharSequence cf, CharSequence cq, CharSequence cv) {
return Range.exact(new Text(row.toString()), new Text(cf.toString()), new Text(cq.toString()), new Text(cv.toString()));
}
/**
- * Creates a range that covers an exact row, column family, column qualifier, visibility, and timestamp
+ * Creates a range that covers an exact row, column family, column qualifier, column visibility, and timestamp.
*
- * @see Range#exact(Text, Text, Text, Text, long)
+ * @param row row row to cover
+ * @param cf column family to cover
+ * @param cq column qualifier to cover
+ * @param cv column visibility to cover
+ * @param ts timestamp to cover
+ * @see #exact(Text, Text, Text, Text, long)
*/
public static Range exact(CharSequence row, CharSequence cf, CharSequence cq, CharSequence cv, long ts) {
return Range.exact(new Text(row.toString()), new Text(cf.toString()), new Text(cq.toString()), new Text(cv.toString()), ts);
}
-
/**
- * Returns a Range that covers all rows beginning with a prefix
+ * Returns a Range that covers all rows beginning with a prefix.
*
- * @see Range#prefix(Text)
+ * @param rowPrefix prefix of rows to cover
+ * @see #prefix(Text)
*/
public static Range prefix(CharSequence rowPrefix) {
return Range.prefix(new Text(rowPrefix.toString()));
}
/**
- * Returns a Range that covers all column families beginning with a prefix within a given row
+ * Returns a Range that covers all column families beginning with a prefix within a given row.
*
- * @see Range#prefix(Text, Text)
+ * @param row row to cover
+ * @param cfPrefix prefix of column families to cover
+ * @see #prefix(Text, Text)
*/
public static Range prefix(CharSequence row, CharSequence cfPrefix) {
return Range.prefix(new Text(row.toString()), new Text(cfPrefix.toString()));
}
/**
- * Returns a Range that covers all column qualifiers beginning with a prefix within a given row and column family
+ * Returns a Range that covers all column qualifiers beginning with a prefix within a given row and column family.
*
- * @see Range#prefix(Text, Text, Text)
+ * @param row row to cover
+ * @param cf column family to cover
+ * @param cqPrefix prefix of column qualifiers to cover
+ * @see #prefix(Text, Text, Text)
*/
public static Range prefix(CharSequence row, CharSequence cf, CharSequence cqPrefix) {
return Range.prefix(new Text(row.toString()), new Text(cf.toString()), new Text(cqPrefix.toString()));
}
-
/**
- * Returns a Range that covers all column visibilities beginning with a prefix within a given row, column family, and column qualifier
+ * Returns a Range that covers all column visibilities beginning with a prefix within a given row, column family, and column qualifier.
*
- * @see Range#prefix(Text, Text, Text, Text)
+ * @param row row to cover
+ * @param cf column family to cover
+ * @param cq column qualifier to cover
+ * @param cvPrefix prefix of column visibilities to cover
+ * @see #prefix(Text, Text, Text, Text)
*/
public static Range prefix(CharSequence row, CharSequence cf, CharSequence cq, CharSequence cvPrefix) {
return Range.prefix(new Text(row.toString()), new Text(cf.toString()), new Text(cq.toString()), new Text(cvPrefix.toString()));
http://git-wip-us.apache.org/repos/asf/accumulo/blob/74c89324/core/src/main/java/org/apache/accumulo/core/data/Value.java
----------------------------------------------------------------------
diff --git a/core/src/main/java/org/apache/accumulo/core/data/Value.java b/core/src/main/java/org/apache/accumulo/core/data/Value.java
index 39ebbd0..ec07411 100644
--- a/core/src/main/java/org/apache/accumulo/core/data/Value.java
+++ b/core/src/main/java/org/apache/accumulo/core/data/Value.java
@@ -32,42 +32,59 @@ import org.apache.hadoop.io.WritableComparator;
/**
* A byte sequence that is usable as a key or value. Based on {@link org.apache.hadoop.io.BytesWritable} only this class is NOT resizable and DOES NOT
- * distinguish between the size of the sequence and the current capacity as {@link org.apache.hadoop.io.BytesWritable} does. Hence its comparatively
+ * distinguish between the size of the sequence and the current capacity as {@link org.apache.hadoop.io.BytesWritable} does. Hence it is comparatively
* 'immutable'.
*/
public class Value implements WritableComparable<Object> {
protected byte[] value;
/**
- * Create a zero-size sequence.
+ * Creates a zero-size sequence.
*/
public Value() {
super();
}
/**
- * Create a Value using the byte array as the initial value.
+ * Creates a Value using a byte array as the initial value. The given byte
+ * array is used directly as the backing array, so later changes made to the
+ * array reflect into the new Value.
*
- * @param bytes
- * This array becomes the backing storage for the object.
+ * @param bytes bytes of value
*/
-
public Value(byte[] bytes) {
this(bytes, false);
}
+ /**
+ * Creates a Value using the bytes in a buffer as the initial value. Makes
+ * a defensive copy.
+ *
+ * @param bytes bytes of value
+ */
public Value(ByteBuffer bytes) {
this(toBytes(bytes), false);
}
/**
* @deprecated A copy of the bytes in the buffer is always made. Use {@link #Value(ByteBuffer)} instead.
+ *
+ * @param bytes bytes of value
+ * @param copy false to use the backing array of the buffer directly as the
+ * backing array, true to force a copy
*/
@Deprecated
public Value(ByteBuffer bytes, boolean copy) {
this(toBytes(bytes), false);
}
+ /**
+ * Creates a Value using a byte array as the initial value.
+ *
+ * @param bytes bytes of value
+ * @param copy false to use the given byte array directly as the backing
+ * array, true to force a copy
+ */
public Value(byte[] bytes, boolean copy) {
if (!copy) {
this.value = bytes;
@@ -79,24 +96,22 @@ public class Value implements WritableComparable<Object> {
}
/**
- * Set the new Value to a copy of the contents of the passed <code>ibw</code>.
+ * Creates a new Value based on another.
*
- * @param ibw
- * the value to set this Value to.
+ * @param ibw original Value
*/
public Value(final Value ibw) {
this(ibw.get(), 0, ibw.getSize());
}
/**
- * Set the value to a copy of the given byte range
+ * Creates a Value based on a range in a byte array. A copy of the bytes is
+ * always made.
*
- * @param newData
- * the new values to copy in
- * @param offset
- * the offset in newData to start at
- * @param length
- * the number of bytes to copy
+ * @param newData byte array containing value bytes
+ * @param offset the offset in newData to start with for valye bytes
+ * @param length the number of bytes in the value
+ * @throws IndexOutOfBoundsException if offset or length are invalid
*/
public Value(final byte[] newData, final int offset, final int length) {
this.value = new byte[length];
@@ -104,9 +119,11 @@ public class Value implements WritableComparable<Object> {
}
/**
- * Get the data from the BytesWritable.
+ * Gets the byte data of this value.
*
- * @return The data is only valid between 0 and getSize() - 1.
+ * @return value bytes
+ * @throws IllegalStateException if this object is uninitialized because it
+ * was not read correctly from a data stream
*/
public byte[] get() {
if (this.value == null) {
@@ -116,17 +133,20 @@ public class Value implements WritableComparable<Object> {
}
/**
- * @param b
- * Use passed bytes as backing array for this instance.
+ * Sets the byte data of this value. The given byte array is used directly as
+ * the backing array, so later changes made to the array reflect into this
+ * Value.
+ *
+ * @param b bytes of value
*/
public void set(final byte[] b) {
this.value = b;
}
/**
- *
- * @param b
- * copy bytes
+ * Sets the byte data of this value. The given byte array is copied.
+ *
+ * @param b bytes of value
*/
public void copy(byte[] b) {
this.value = new byte[b.length];
@@ -134,7 +154,11 @@ public class Value implements WritableComparable<Object> {
}
/**
- * @return the current size of the buffer.
+ * Gets the size of this value.
+ *
+ * @return size in bytes
+ * @throws IllegalStateException if this object is uninitialized because it
+ * was not read correctly from a data stream
*/
public int getSize() {
if (this.value == null) {
@@ -222,6 +246,10 @@ public class Value implements WritableComparable<Object> {
}
/**
+ * Converts a list of byte arrays to a two-dimensional array.
+ *
+ * @param array list of byte arrays
+ * @return two-dimensional byte array containing one given byte array per row
*/
public static byte[][] toArray(final List<byte[]> array) {
// List#toArray doesn't work on lists of byte [].
http://git-wip-us.apache.org/repos/asf/accumulo/blob/74c89324/core/src/main/java/org/apache/accumulo/core/data/doc-files/mutation-serialization.html
----------------------------------------------------------------------
diff --git a/core/src/main/java/org/apache/accumulo/core/data/doc-files/mutation-serialization.html b/core/src/main/java/org/apache/accumulo/core/data/doc-files/mutation-serialization.html
new file mode 100644
index 0000000..d4d5ed3
--- /dev/null
+++ b/core/src/main/java/org/apache/accumulo/core/data/doc-files/mutation-serialization.html
@@ -0,0 +1,196 @@
+<html>
+<head>
+ <title>Serialization Formats for Mutation</title>
+<!--
+ Licensed to the Apache Software Foundation (ASF) under one or more
+ contributor license agreements. See the NOTICE file distributed with
+ this work for additional information regarding copyright ownership.
+ The ASF licenses this file to You under the Apache License, Version 2.0
+ (the "License"); you may not use this file except in compliance with
+ the License. You may obtain a copy of the License at
+
+ http://www.apache.org/licenses/LICENSE-2.0
+
+ Unless required by applicable law or agreed to in writing, software
+ distributed under the License is distributed on an "AS IS" BASIS,
+ WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ See the License for the specific language governing permissions and
+ limitations under the License.
+-->
+</head>
+<body>
+ <p>
+ The <code>Mutation</code> class supports two serialization formats.
+ While it only currently serializes to the newer version 2 format, it
+ can read both version 1 and version 2 serialized forms.
+ </p>
+
+ <h2>Version 1 Format</h2>
+ <p>
+ Mutation data serialized in the version 1 format has the following
+ layout.
+ </p>
+ <table>
+ <tr>
+ <th>data location</th>
+ <th>description</th>
+ </tr>
+ <tr>
+ <td>bytes 0 through 3</td>
+ <td>4-byte integer for length of row ID</td>
+ </tr>
+ <tr>
+ <td>next <i>n</i> bytes</td>
+ <td>row ID</td>
+ </tr>
+ <tr>
+ <td>next integer</td>
+ <td>data length</td>
+ </tr>
+ <tr>
+ <td>next <i>n</i> bytes</td>
+ <td>data (see below)</td>
+ </tr>
+ <tr>
+ <td>next integer</td>
+ <td>number of entries</td>
+ </tr>
+ <tr>
+ <td>next boolean</td>
+ <td>values present flag</td>
+ </tr>
+ <tr>
+ <td>next integer</td>
+ <td>number of values (only if values present flag is set)</td>
+ </tr>
+ <tr>
+ <td>next <i>n</i> sets of integers and byte arrays</td>
+ <td><i>n</i> value lengths and value data bytes (only if values
+ present flag is set)</td>
+ </tr>
+ </table>
+ <p>
+ The "data" block noted above has the following layout for each entry.
+ </p>
+ <table>
+ <tr>
+ <td>first integer and byte array</td>
+ <td>column family length and bytes</td>
+ </tr>
+ <tr>
+ <td>next integer and byte array</td>
+ <td>column qualifier length and bytes</td>
+ </tr>
+ <tr>
+ <td>next integer and byte array</td>
+ <td>column visibility length and bytes</td>
+ </tr>
+ <tr>
+ <td>next boolean</td>
+ <td>has timestamp flag</td>
+ </tr>
+ <tr>
+ <td>next long</td>
+ <td>timestamp</td>
+ </tr>
+ <tr>
+ <td>next boolean</td>
+ <td>deleted flag</td>
+ </tr>
+ <tr>
+ <td>next integer</td>
+ <td>value length; if negative, value bytes are the same as those
+ for already-read value (-length - 1)</td>
+ </tr>
+ <tr>
+ <td>next <i>n</i> bytes</td>
+ <td>value bytes (only if value length is non-negative)</td>
+ </tr>
+ </table>
+
+ <h2>Version 2 Format</h2>
+ <p>
+ Mutation data serialized in the version 2 format has the following
+ layout. This format uses variable length encoding for integers and
+ longs.
+ </p>
+ <table>
+ <tr>
+ <th>data location</th>
+ <th>description</th>
+ </tr>
+ <tr>
+ <td>byte 0</td>
+ <td>control byte: top bit = 1 for version 2; bottom bit =
+ values present flag</td>
+ </tr>
+ <tr>
+ <td>next integer
+ <td>length of row ID</td>
+ </tr>
+ <tr>
+ <td>next <i>n</i> bytes</td>
+ <td>row ID</td>
+ </tr>
+ <tr>
+ <td>next integer</td>
+ <td>data length</td>
+ </tr>
+ <tr>
+ <td>next <i>n</i> bytes</td>
+ <td>data (see below)</td>
+ </tr>
+ <tr>
+ <td>next integer</td>
+ <td>number of entries</td>
+ </tr>
+ <tr>
+ <td>next integer</td>
+ <td>number of values (only if values present flag is set)</td>
+ </tr>
+ <tr>
+ <td>next <i>n</i> sets of integers and byte arrays</td>
+ <td><i>n</i> value lengths and value data bytes (only if values
+ present flag is set)</td>
+ </tr>
+ </table>
+ <p>
+ The "data" block noted above has the following layout for each entry.
+ </p>
+ <table>
+ <tr>
+ <td>first long and byte array</td>
+ <td>column family length and bytes</td>
+ </tr>
+ <tr>
+ <td>next long and byte array</td>
+ <td>column qualifier length and bytes</td>
+ </tr>
+ <tr>
+ <td>next long and byte array</td>
+ <td>column visibility length and bytes</td>
+ </tr>
+ <tr>
+ <td>next boolean</td>
+ <td>has timestamp flag</td>
+ </tr>
+ <tr>
+ <td>next long</td>
+ <td>timestamp (only present if timestamp flag is set)</td>
+ </tr>
+ <tr>
+ <td>next boolean</td>
+ <td>deleted flag</td>
+ </tr>
+ <tr>
+ <td>next long</td>
+ <td>value length; if negative, value bytes are the same as those
+ for already-read value (-length - 1)</td>
+ </tr>
+ <tr>
+ <td>next <i>n</i> bytes</td>
+ <td>value bytes (only if value length is non-negative)</td>
+ </tr>
+ </table>
+</body>
+</html>
http://git-wip-us.apache.org/repos/asf/accumulo/blob/74c89324/core/src/main/java/org/apache/accumulo/core/util/UnsynchronizedBuffer.java
----------------------------------------------------------------------
diff --git a/core/src/main/java/org/apache/accumulo/core/util/UnsynchronizedBuffer.java b/core/src/main/java/org/apache/accumulo/core/util/UnsynchronizedBuffer.java
index b640581..36aa473 100644
--- a/core/src/main/java/org/apache/accumulo/core/util/UnsynchronizedBuffer.java
+++ b/core/src/main/java/org/apache/accumulo/core/util/UnsynchronizedBuffer.java
@@ -21,20 +21,32 @@ import java.nio.ByteBuffer;
import org.apache.hadoop.io.WritableUtils;
/**
- *
+ * A utility class for reading and writing bytes to byte buffers without
+ * synchronization.
*/
public class UnsynchronizedBuffer {
// created this little class instead of using ByteArrayOutput stream and DataOutputStream
// because both are synchronized... lots of small syncs slow things down
+ /**
+ * A byte buffer writer.
+ */
public static class Writer {
int offset = 0;
byte data[];
+ /**
+ * Creates a new writer.
+ */
public Writer() {
data = new byte[64];
}
+ /**
+ * Creates a new writer.
+ *
+ * @param initialCapacity initial byte capacity
+ */
public Writer(int initialCapacity) {
data = new byte[initialCapacity];
}
@@ -50,12 +62,25 @@ public class UnsynchronizedBuffer {
}
+ /**
+ * Adds bytes to this writer's buffer.
+ *
+ * @param bytes byte array
+ * @param off offset into array to start copying bytes
+ * @param length number of bytes to add
+ * @throws IndexOutOfBoundsException if off or length are invalid
+ */
public void add(byte[] bytes, int off, int length) {
reserve(length);
System.arraycopy(bytes, off, data, offset, length);
offset += length;
}
+ /**
+ * Adds a Boolean value to this writer's buffer.
+ *
+ * @param b Boolean value
+ */
public void add(boolean b) {
reserve(1);
if (b)
@@ -64,20 +89,46 @@ public class UnsynchronizedBuffer {
data[offset++] = 0;
}
+ /**
+ * Gets (a copy of) the contents of this writer's buffer.
+ *
+ * @return byte buffer contents
+ */
public byte[] toArray() {
byte ret[] = new byte[offset];
System.arraycopy(data, 0, ret, 0, offset);
return ret;
}
+ /**
+ * Gets a <code>ByteBuffer</code> wrapped around this writer's buffer.
+ *
+ * @return byte buffer
+ */
public ByteBuffer toByteBuffer() {
return ByteBuffer.wrap(data, 0, offset);
}
+ /**
+ * Adds an integer value to this writer's buffer. The integer is encoded as
+ * a variable-length list of bytes. See {@link #writeVLong(long)} for a
+ * description of the encoding.
+ *
+ * @param i integer value
+ */
public void writeVInt(int i) {
writeVLong(i);
}
+ /**
+ * Adds a long value to this writer's buffer. The long is encoded as
+ * a variable-length list of bytes. For a description of the encoding
+ * scheme, see <code>WritableUtils.writeVLong()</code> in the Hadoop
+ * API.
+ * [<a href="http://hadoop.apache.org/docs/stable/api/org/apache/hadoop/io/WritableUtils.html#writeVLong%28java.io.DataOutput,%20long%29">link</a>]
+ *
+ * @param i long value
+ */
public void writeVLong(long i) {
reserve(9);
if (i >= -112 && i <= 127) {
@@ -109,14 +160,27 @@ public class UnsynchronizedBuffer {
}
}
+ /**
+ * A byte buffer reader.
+ */
public static class Reader {
int offset;
byte data[];
+ /**
+ * Creates a new reader.
+ *
+ * @param b bytes to read
+ */
public Reader(byte b[]) {
this.data = b;
}
+ /**
+ * Creates a new reader.
+ *
+ * @param buffer byte buffer containing bytes to read
+ */
public Reader(ByteBuffer buffer) {
if (buffer.hasArray()) {
offset = buffer.arrayOffset();
@@ -127,28 +191,60 @@ public class UnsynchronizedBuffer {
}
}
+ /**
+ * Reads an integer value from this reader's buffer.
+ *
+ * @return integer value
+ */
public int readInt() {
return (data[offset++] << 24) + ((data[offset++] & 255) << 16) + ((data[offset++] & 255) << 8) + ((data[offset++] & 255) << 0);
}
+ /**
+ * Reads a long value from this reader's buffer.
+ *
+ * @return long value
+ */
public long readLong() {
return (((long) data[offset++] << 56) + ((long) (data[offset++] & 255) << 48) + ((long) (data[offset++] & 255) << 40)
+ ((long) (data[offset++] & 255) << 32) + ((long) (data[offset++] & 255) << 24) + ((data[offset++] & 255) << 16) + ((data[offset++] & 255) << 8) + ((data[offset++] & 255) << 0));
}
+ /**
+ * Reads bytes from this reader's buffer, filling the given byte array.
+ *
+ * @param b byte array to fill
+ */
public void readBytes(byte b[]) {
System.arraycopy(data, offset, b, 0, b.length);
offset += b.length;
}
+ /**
+ * Reads a Boolean value from this reader's buffer.
+ *
+ * @return Boolean value
+ */
public boolean readBoolean() {
return (data[offset++] == 1);
}
+ /**
+ * Reads an integer value from this reader's buffer, assuming the integer
+ * was encoded as a variable-length list of bytes.
+ *
+ * @return integer value
+ */
public int readVInt() {
return (int) readVLong();
}
+ /**
+ * Reads a long value from this reader's buffer, assuming the long
+ * was encoded as a variable-length list of bytes.
+ *
+ * @return long value
+ */
public long readVLong() {
byte firstByte = data[offset++];
int len = WritableUtils.decodeVIntSize(firstByte);
@@ -167,7 +263,10 @@ public class UnsynchronizedBuffer {
/**
* Determines what next array size should be by rounding up to next power of two.
- *
+ *
+ * @param i current array size
+ * @return next array size
+ * @throws IllegalArgumentException if i is negative
*/
public static int nextArraySize(int i) {
if (i < 0)
[2/3] git commit: ACCUMULO-1931 Javadoc for core/data
Posted by el...@apache.org.
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;
}
[3/3] git commit: ACCUMULO-1974 Javadoc for core/conf.
Posted by el...@apache.org.
ACCUMULO-1974 Javadoc for core/conf.
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/3a2e0a92
Tree: http://git-wip-us.apache.org/repos/asf/accumulo/tree/3a2e0a92
Diff: http://git-wip-us.apache.org/repos/asf/accumulo/diff/3a2e0a92
Branch: refs/heads/master
Commit: 3a2e0a925002a2cb8e408791a7f0d2a0fa2f4c96
Parents: 74c8932
Author: Bill Havanki <bh...@cloudera.com>
Authored: Fri Dec 6 13:52:02 2013 -0500
Committer: Josh Elser <el...@apache.org>
Committed: Mon Dec 16 14:15:48 2013 -0500
----------------------------------------------------------------------
.../core/conf/AccumuloConfiguration.java | 176 ++++++++++++++++++-
.../accumulo/core/conf/ConfigSanityCheck.java | 13 ++
.../accumulo/core/conf/ConfigurationCopy.java | 29 +++
.../core/conf/DefaultConfiguration.java | 21 ++-
.../org/apache/accumulo/core/conf/Property.java | 124 ++++++++++++-
.../apache/accumulo/core/conf/PropertyType.java | 14 ++
.../accumulo/core/conf/SiteConfiguration.java | 35 +++-
7 files changed, 399 insertions(+), 13 deletions(-)
----------------------------------------------------------------------
http://git-wip-us.apache.org/repos/asf/accumulo/blob/3a2e0a92/core/src/main/java/org/apache/accumulo/core/conf/AccumuloConfiguration.java
----------------------------------------------------------------------
diff --git a/core/src/main/java/org/apache/accumulo/core/conf/AccumuloConfiguration.java b/core/src/main/java/org/apache/accumulo/core/conf/AccumuloConfiguration.java
index 3aed8c1..b3b82d3 100644
--- a/core/src/main/java/org/apache/accumulo/core/conf/AccumuloConfiguration.java
+++ b/core/src/main/java/org/apache/accumulo/core/conf/AccumuloConfiguration.java
@@ -30,12 +30,27 @@ import org.apache.accumulo.core.client.impl.Tables;
import org.apache.accumulo.start.classloader.vfs.AccumuloVFSClassLoader;
import org.apache.log4j.Logger;
+/**
+ * A configuration object.
+ */
public abstract class AccumuloConfiguration implements Iterable<Entry<String,String>> {
+ /**
+ * A filter for properties, based on key.
+ */
public static interface PropertyFilter {
+ /**
+ * Determines whether to accept a property based on its key.
+ *
+ * @param key property key
+ * @return true to accept property (pass filter)
+ */
boolean accept(String key);
}
+ /**
+ * A filter that accepts all properties.
+ */
public static class AllFilter implements PropertyFilter {
@Override
public boolean accept(String key) {
@@ -43,10 +58,18 @@ public abstract class AccumuloConfiguration implements Iterable<Entry<String,Str
}
}
+ /**
+ * A filter that accepts properties whose keys begin with a prefix.
+ */
public static class PrefixFilter implements PropertyFilter {
private String prefix;
+ /**
+ * Creates a new filter.
+ *
+ * @param prefix prefix of property keys to accept
+ */
public PrefixFilter(String prefix) {
this.prefix = prefix;
}
@@ -59,10 +82,30 @@ public abstract class AccumuloConfiguration implements Iterable<Entry<String,Str
private static final Logger log = Logger.getLogger(AccumuloConfiguration.class);
+ /**
+ * Gets a property value from this configuration.
+ *
+ * @param property property to get
+ * @return property value
+ */
public abstract String get(Property property);
+ /**
+ * Returns property key/value pairs in this configuration. The pairs include
+ * those defined in this configuration which pass the given filter, and those
+ * supplied from the parent configuration which are not included from here.
+ *
+ * @param props properties object to populate
+ * @param filter filter for accepting properties from this configuration
+ */
public abstract void getProperties(Map<String,String> props, PropertyFilter filter);
+ /**
+ * Returns an iterator over property key/value pairs in this configuration.
+ * Some implementations may elect to omit properties.
+ *
+ * @return iterator over properties
+ */
@Override
public Iterator<Entry<String,String>> iterator() {
TreeMap<String,String> entries = new TreeMap<String,String>();
@@ -80,11 +123,11 @@ public abstract class AccumuloConfiguration implements Iterable<Entry<String,Str
}
/**
- * This method returns all properties in a map of string->string under the given prefix property.
- *
- * @param property
- * the prefix property, and must be of type PropertyType.PREFIX
- * @return a map of strings to strings of the resulting properties
+ * Gets all properties under the given prefix in this configuration.
+ *
+ * @param property prefix property, must be of type PropertyType.PREFIX
+ * @return a map of property keys to values
+ * @throws IllegalArgumentException if property is not a prefix
*/
public Map<String,String> getAllPropertiesWithPrefix(Property property) {
checkType(property, PropertyType.PREFIX);
@@ -94,6 +137,15 @@ public abstract class AccumuloConfiguration implements Iterable<Entry<String,Str
return propMap;
}
+ /**
+ * Gets a property of type {@link PropertyType#MEMORY}, interpreting the
+ * value properly.
+ *
+ * @param property property to get
+ * @return property value
+ * @throws IllegalArgumentException if the property is of the wrong type
+ * @see #getMemoryInBytes(String)
+ */
public long getMemoryInBytes(Property property) {
checkType(property, PropertyType.MEMORY);
@@ -101,6 +153,14 @@ public abstract class AccumuloConfiguration implements Iterable<Entry<String,Str
return getMemoryInBytes(memString);
}
+ /**
+ * Interprets a string specifying a memory size. A memory size is specified
+ * as a long integer followed by an optional B (bytes), K (KB), M (MB), or
+ * G (GB).
+ *
+ * @param str string value
+ * @return interpreted memory size
+ */
static public long getMemoryInBytes(String str) {
int multiplier = 0;
switch (str.charAt(str.length() - 1)) {
@@ -117,12 +177,30 @@ public abstract class AccumuloConfiguration implements Iterable<Entry<String,Str
}
}
+ /**
+ * Gets a property of type {@link PropertyType#TIMEDURATION}, interpreting the
+ * value properly.
+ *
+ * @param property property to get
+ * @return property value
+ * @throws IllegalArgumentException if the property is of the wrong type
+ * @see #getTimeInMillis(String)
+ */
public long getTimeInMillis(Property property) {
checkType(property, PropertyType.TIMEDURATION);
return getTimeInMillis(get(property));
}
+ /**
+ * Interprets a string specifying a time duration. A time duration is
+ * specified as a long integer followed by an optional d (days), h (hours),
+ * m (minutes), s (seconds), or ms (milliseconds). A value without a unit
+ * is interpreted as seconds.
+ *
+ * @param str string value
+ * @return interpreted time duration in milliseconds
+ */
static public long getTimeInMillis(String str) {
int multiplier = 1;
switch (str.charAt(str.length() - 1)) {
@@ -143,23 +221,56 @@ public abstract class AccumuloConfiguration implements Iterable<Entry<String,Str
}
}
+ /**
+ * Gets a property of type {@link PropertyType#BOOLEAN}, interpreting the
+ * value properly (using <code>Boolean.parseBoolean()</code>).
+ *
+ * @param property property to get
+ * @return property value
+ * @throws IllegalArgumentException if the property is of the wrong type
+ */
public boolean getBoolean(Property property) {
checkType(property, PropertyType.BOOLEAN);
return Boolean.parseBoolean(get(property));
}
+ /**
+ * Gets a property of type {@link PropertyType#FRACTION}, interpreting the
+ * value properly.
+ *
+ * @param property property to get
+ * @return property value
+ * @throws IllegalArgumentException if the property is of the wrong type
+ * @see #getFraction(String)
+ */
public double getFraction(Property property) {
checkType(property, PropertyType.FRACTION);
return getFraction(get(property));
}
+ /**
+ * Interprets a string specifying a fraction. A fraction is specified as a
+ * double. An optional % at the end signifies a percentage.
+ *
+ * @param str string value
+ * @return interpreted fraction as a decimal value
+ */
public double getFraction(String str) {
if (str.charAt(str.length() - 1) == '%')
return Double.parseDouble(str.substring(0, str.length() - 1)) / 100.0;
return Double.parseDouble(str);
}
+ /**
+ * Gets a property of type {@link PropertyType#PORT}, interpreting the
+ * value properly (as an integer within the range of non-privileged ports).
+ *
+ * @param property property to get
+ * @return property value
+ * @throws IllegalArgumentException if the property is of the wrong type
+ * @see #getTimeInMillis(String)
+ */
public int getPort(Property property) {
checkType(property, PropertyType.PORT);
@@ -174,6 +285,15 @@ public abstract class AccumuloConfiguration implements Iterable<Entry<String,Str
return port;
}
+ /**
+ * Gets a property of type {@link PropertyType#COUNT}, interpreting the
+ * value properly (as an integer).
+ *
+ * @param property property to get
+ * @return property value
+ * @throws IllegalArgumentException if the property is of the wrong type
+ * @see #getTimeInMillis(String)
+ */
public int getCount(Property property) {
checkType(property, PropertyType.COUNT);
@@ -181,6 +301,15 @@ public abstract class AccumuloConfiguration implements Iterable<Entry<String,Str
return Integer.parseInt(countString);
}
+ /**
+ * Gets a property of type {@link PropertyType#PATH}, interpreting the
+ * value properly, replacing supported environment variables.
+ *
+ * @param property property to get
+ * @return property value
+ * @throws IllegalArgumentException if the property is of the wrong type
+ * @see Constants#PATH_PROPERTY_ENV_VARS
+ */
public String getPath(Property property) {
checkType(property, PropertyType.PATH);
@@ -196,13 +325,21 @@ public abstract class AccumuloConfiguration implements Iterable<Entry<String,Str
return pathString;
}
+ /**
+ * Gets the default configuration.
+ *
+ * @return default configuration
+ * @see DefaultConfiguration#getInstance()
+ */
public static synchronized DefaultConfiguration getDefaultConfiguration() {
return DefaultConfiguration.getInstance();
}
/**
- * Only here for Shell option-free start-up
- *
+ * Gets a site configuration parented by a default configuration. Only here
+ * for shell option-free start-up.
+ *
+ * @return configuration
* @deprecated not for client use
*/
@Deprecated
@@ -210,11 +347,27 @@ public abstract class AccumuloConfiguration implements Iterable<Entry<String,Str
return SiteConfiguration.getInstance(getDefaultConfiguration());
}
+ /**
+ * Gets the configuration specific to a table.
+ *
+ * @param conn connector (used to find table name)
+ * @param tableId table ID
+ * @return configuration containing table properties
+ * @throws TableNotFoundException if the table is not found
+ * @throws AccumuloException if there is a problem communicating to Accumulo
+ */
public static AccumuloConfiguration getTableConfiguration(Connector conn, String tableId) throws TableNotFoundException, AccumuloException {
String tableName = Tables.getTableName(conn.getInstance(), tableId);
return new ConfigurationCopy(conn.tableOperations().getProperties(tableName));
}
+ /**
+ * Gets the maximum number of files per tablet from this configuration.
+ *
+ * @return maximum number of files per tablet
+ * @see Property#TABLE_FILE_MAX
+ * @see Property#TSERV_SCAN_MAX_OPENFILES
+ */
public int getMaxFilesPerTablet() {
int maxFilesPerTablet = getCount(Property.TABLE_FILE_MAX);
if (maxFilesPerTablet <= 0) {
@@ -228,6 +381,15 @@ public abstract class AccumuloConfiguration implements Iterable<Entry<String,Str
// overridden in ZooConfiguration
public void invalidateCache() {}
+ /**
+ * Creates a new instance of a class specified in a configuration property.
+ *
+ * @param property property specifying class name
+ * @param base base class of type
+ * @param defaultInstance instance to use if creation fails
+ * @return new class instance, or default instance if creation failed
+ * @see AccumuloVFSClassLoader
+ */
public <T> T instantiateClassProperty(Property property, Class<T> base, T defaultInstance) {
String clazzName = get(property);
T instance = null;
http://git-wip-us.apache.org/repos/asf/accumulo/blob/3a2e0a92/core/src/main/java/org/apache/accumulo/core/conf/ConfigSanityCheck.java
----------------------------------------------------------------------
diff --git a/core/src/main/java/org/apache/accumulo/core/conf/ConfigSanityCheck.java b/core/src/main/java/org/apache/accumulo/core/conf/ConfigSanityCheck.java
index 6724670..82c6dc9 100644
--- a/core/src/main/java/org/apache/accumulo/core/conf/ConfigSanityCheck.java
+++ b/core/src/main/java/org/apache/accumulo/core/conf/ConfigSanityCheck.java
@@ -20,11 +20,24 @@ import java.util.Map.Entry;
import org.apache.log4j.Logger;
+/**
+ * A utility class for validating {@link AccumuloConfiguration} instances.
+ */
public class ConfigSanityCheck {
private static final Logger log = Logger.getLogger(ConfigSanityCheck.class);
private static final String PREFIX = "BAD CONFIG ";
+ /**
+ * Validates the given configuration. A valid configuration contains only
+ * valid properties (i.e., defined or otherwise valid) that are not prefixes
+ * and whose values are formatted correctly for their property types. A valid
+ * configuration also contains a value for property
+ * {@link Property#INSTANCE_ZK_TIMEOUT} within a valid range.
+ *
+ * @param acuconf configuration
+ * @throws RuntimeException if the configuration fails validation
+ */
public static void validate(AccumuloConfiguration acuconf) {
for (Entry<String,String> entry : acuconf) {
String key = entry.getKey();
http://git-wip-us.apache.org/repos/asf/accumulo/blob/3a2e0a92/core/src/main/java/org/apache/accumulo/core/conf/ConfigurationCopy.java
----------------------------------------------------------------------
diff --git a/core/src/main/java/org/apache/accumulo/core/conf/ConfigurationCopy.java b/core/src/main/java/org/apache/accumulo/core/conf/ConfigurationCopy.java
index 756a97b..2b1945d 100644
--- a/core/src/main/java/org/apache/accumulo/core/conf/ConfigurationCopy.java
+++ b/core/src/main/java/org/apache/accumulo/core/conf/ConfigurationCopy.java
@@ -21,19 +21,36 @@ import java.util.HashMap;
import java.util.Map;
import java.util.Map.Entry;
+/**
+ * An {@link AccumuloConfiguration} which holds a flat copy of properties
+ * defined in another configuration
+ */
public class ConfigurationCopy extends AccumuloConfiguration {
final Map<String,String> copy = Collections.synchronizedMap(new HashMap<String,String>());
+ /**
+ * Creates a new configuration.
+ *
+ * @param config configuration property key/value pairs to copy
+ */
public ConfigurationCopy(Map<String,String> config) {
this(config.entrySet());
}
+ /**
+ * Creates a new configuration.
+ *
+ * @param config configuration property iterable to use for copying
+ */
public ConfigurationCopy(Iterable<Entry<String,String>> config) {
for (Entry<String,String> entry : config) {
copy.put(entry.getKey(), entry.getValue());
}
}
+ /**
+ * Creates a new empty configuration.
+ */
public ConfigurationCopy() {
this(new HashMap<String,String>());
}
@@ -52,10 +69,22 @@ public class ConfigurationCopy extends AccumuloConfiguration {
}
}
+ /**
+ * Sets a property in this configuration.
+ *
+ * @param prop property to set
+ * @param value property value
+ */
public void set(Property prop, String value) {
copy.put(prop.getKey(), value);
}
+ /**
+ * Sets a property in this configuration.
+ *
+ * @param key key of property to set
+ * @param value property value
+ */
public void set(String key, String value) {
copy.put(key, value);
}
http://git-wip-us.apache.org/repos/asf/accumulo/blob/3a2e0a92/core/src/main/java/org/apache/accumulo/core/conf/DefaultConfiguration.java
----------------------------------------------------------------------
diff --git a/core/src/main/java/org/apache/accumulo/core/conf/DefaultConfiguration.java b/core/src/main/java/org/apache/accumulo/core/conf/DefaultConfiguration.java
index cfc660e..81b7991 100644
--- a/core/src/main/java/org/apache/accumulo/core/conf/DefaultConfiguration.java
+++ b/core/src/main/java/org/apache/accumulo/core/conf/DefaultConfiguration.java
@@ -28,11 +28,21 @@ import java.util.TreeMap;
import org.apache.log4j.Logger;
+/**
+ * An {@link AccumuloConfiguration} that contains only default values for
+ * properties. This class is a singleton.
+ */
public class DefaultConfiguration extends AccumuloConfiguration {
private static DefaultConfiguration instance = null;
private static Logger log = Logger.getLogger(DefaultConfiguration.class);
private Map<String,String> resolvedProps = null;
+ /**
+ * Gets an instance of this class.
+ *
+ * @return default configuration
+ * @throws RuntimeException if the default configuration is invalid
+ */
synchronized public static DefaultConfiguration getInstance() {
if (instance == null) {
instance = new DefaultConfiguration();
@@ -64,6 +74,11 @@ public class DefaultConfiguration extends AccumuloConfiguration {
props.put(entry.getKey(), entry.getValue());
}
+ /**
+ * Generates HTML documentation on the default configuration.
+ *
+ * @param doc stream to write HTML to
+ */
protected static void generateDocumentation(PrintStream doc) {
// read static content from resources and output
InputStream data = DefaultConfiguration.class.getResourceAsStream("config.html");
@@ -184,7 +199,11 @@ public class DefaultConfiguration extends AccumuloConfiguration {
}
/*
- * Generate documentation for conf/accumulo-site.xml file usage
+ * Generates documentation for conf/accumulo-site.xml file usage. Arguments
+ * are: "--generate-doc", file to write to.
+ *
+ * @param args command-line arguments
+ * @throws IllegalArgumentException if args is invalid
*/
public static void main(String[] args) throws FileNotFoundException {
if (args.length == 2 && args[0].equals("--generate-doc")) {
http://git-wip-us.apache.org/repos/asf/accumulo/blob/3a2e0a92/core/src/main/java/org/apache/accumulo/core/conf/Property.java
----------------------------------------------------------------------
diff --git a/core/src/main/java/org/apache/accumulo/core/conf/Property.java b/core/src/main/java/org/apache/accumulo/core/conf/Property.java
index 2ab3a20..1801a28 100644
--- a/core/src/main/java/org/apache/accumulo/core/conf/Property.java
+++ b/core/src/main/java/org/apache/accumulo/core/conf/Property.java
@@ -435,14 +435,32 @@ public enum Property {
return this.key;
}
+ /**
+ * Gets the key (string) for this property.
+ *
+ * @return keuy
+ */
public String getKey() {
return this.key;
}
+ /**
+ * Gets the default value for this property exactly as provided in its
+ * definition (i.e., without interpolation or conversion to absolute paths).
+ *
+ * @return raw default value
+ */
public String getRawDefaultValue() {
return this.defaultValue;
}
+ /**
+ * Gets the default value for this property. System properties are
+ * interpolated into the value if necessary.
+ *
+ * @return default value
+ * @see Interpolated
+ */
public String getDefaultValue() {
if (isInterpolated()) {
PropertiesConfiguration pconf = new PropertiesConfiguration();
@@ -458,10 +476,20 @@ public enum Property {
}
}
+ /**
+ * Gets the type of this property.
+ *
+ * @return property type
+ */
public PropertyType getType() {
return this.type;
}
+ /**
+ * Gets the description of this property.
+ *
+ * @return description
+ */
public String getDescription() {
return this.description;
}
@@ -470,18 +498,44 @@ public enum Property {
return hasAnnotation(Interpolated.class) || hasPrefixWithAnnotation(getKey(), Interpolated.class);
}
+ /**
+ * Checks if this property is experimental.
+ *
+ * @return true if this property is experimental
+ * @see Experimental
+ */
public boolean isExperimental() {
return hasAnnotation(Experimental.class) || hasPrefixWithAnnotation(getKey(), Experimental.class);
}
+ /**
+ * Checks if this property is deprecated.
+ *
+ * @return true if this property is deprecated
+ */
public boolean isDeprecated() {
return hasAnnotation(Deprecated.class) || hasPrefixWithAnnotation(getKey(), Deprecated.class);
}
+ /**
+ * Checks if this property is sensitive.
+ *
+ * @return true if this property is sensitive
+ * @see Sensitive
+ */
public boolean isSensitive() {
return hasAnnotation(Sensitive.class) || hasPrefixWithAnnotation(getKey(), Sensitive.class);
}
+ /**
+ * Checks if a property with the given key is sensitive. The key must be for
+ * a valid property, and must either itself be annotated as sensitive or have
+ * a prefix annotated as sensitive.
+ *
+ * @param key property key
+ * @return true if property is sensitive
+ * @see Sensitive
+ */
public static boolean isSensitive(String key) {
return hasPrefixWithAnnotation(key, Sensitive.class);
}
@@ -529,6 +583,14 @@ public enum Property {
return false;
}
+ /**
+ * Checks if the given property key is valid. A valid property key is either
+ * equal to the key of some defined property or has a prefix matching some
+ * prefix defined in this class.
+ *
+ * @param key property key
+ * @return true if key is valid (recognized, or has a recognized prefix)
+ */
public synchronized static boolean isValidPropertyKey(String key) {
if (validProperties == null) {
validProperties = new HashSet<String>();
@@ -546,6 +608,17 @@ public enum Property {
return validProperties.contains(key) || isKeyValidlyPrefixed(key);
}
+ /**
+ * Checks if the given property key is for a valid table property. A valid
+ * table property key is either equal to the key of some defined table
+ * property (which each start with {@link #TABLE_PREFIX}) or has a prefix
+ * matching {@link #TABLE_CONSTRAINT_PREFIX}, {@link #TABLE_ITERATOR_PREFIX},
+ * or {@link #TABLE_LOCALITY_GROUP_PREFIX}.
+ *
+ * @param key property key
+ * @return true if key is valid for a table property (recognized, or has a
+ * recognized prefix)
+ */
public synchronized static boolean isValidTablePropertyKey(String key) {
if (validTableProperties == null) {
validTableProperties = new HashSet<String>();
@@ -564,14 +637,35 @@ public enum Property {
private static final EnumSet<Property> fixedProperties = EnumSet.of(Property.TSERV_CLIENTPORT, Property.TSERV_NATIVEMAP_ENABLED,
Property.TSERV_SCAN_MAX_OPENFILES, Property.MASTER_CLIENTPORT, Property.GC_PORT);
+ /**
+ * Checks if the given property may be changed via Zookeeper, but not
+ * recognized until the restart of some relevant daemon.
+ *
+ * @param key property key
+ * @return true if property may be changed via Zookeeper but only heeded upon
+ * some restart
+ */
public static boolean isFixedZooPropertyKey(Property key) {
return fixedProperties.contains(key);
}
+ /**
+ * Gets the set of "fixed" valid Zookeeper properties.
+ *
+ * @return fixed Zookeeper properties
+ * @see #isFixedZooPropertyKey(Property)
+ */
public static Set<Property> getFixedProperties() {
return fixedProperties;
}
+ /**
+ * Checks if the given property key is valid for a property that may be
+ * changed via Zookeeper.
+ *
+ * @param key property key
+ * @return true if key's property may be changed via Zookeeper
+ */
public static boolean isValidZooPropertyKey(String key) {
// white list prefixes
return key.startsWith(Property.TABLE_PREFIX.getKey()) || key.startsWith(Property.TSERV_PREFIX.getKey()) || key.startsWith(Property.LOGGER_PREFIX.getKey())
@@ -580,6 +674,12 @@ public enum Property {
|| key.startsWith(Property.TABLE_COMPACTION_STRATEGY_PREFIX.getKey());
}
+ /**
+ * Gets a {@link Property} instance with the given key.
+ *
+ * @param key property key
+ * @return property, or null if not found
+ */
public static Property getPropertyByKey(String key) {
for (Property prop : Property.values())
if (prop.getKey().equals(key))
@@ -588,7 +688,9 @@ public enum Property {
}
/**
- * @return true if this is a property whose value is expected to be a java class
+ * Checks if this property is expected to have a Java class as a value.
+ *
+ * @return true if this is property is a class property
*/
public static boolean isClassProperty(String key) {
return (key.startsWith(Property.TABLE_CONSTRAINT_PREFIX.getKey()) && key.substring(Property.TABLE_CONSTRAINT_PREFIX.getKey().length()).split("\\.").length == 1)
@@ -599,6 +701,16 @@ public enum Property {
// This is not a cache for loaded classes, just a way to avoid spamming the debug log
static Map<String,Class<?>> loaded = Collections.synchronizedMap(new HashMap<String,Class<?>>());
+ /**
+ * Creates a new instance of a class specified in a configuration property.
+ *
+ * @param conf configuration containing property
+ * @param property property specifying class name
+ * @param base base class of type
+ * @param defaultInstance instance to use if creation fails
+ * @return new class instance, or default instance if creation failed
+ * @see AccumuloVFSClassLoader
+ */
public static <T> T createInstanceFromPropertyName(AccumuloConfiguration conf, Property property, Class<T> base, T defaultInstance) {
String clazzName = conf.get(property);
T instance = null;
@@ -619,6 +731,16 @@ public enum Property {
return instance;
}
+ /**
+ * Collects together properties from the given configuration pertaining to
+ * compaction strategies. The relevant properties all begin with the prefix
+ * in {@link #TABLE_COMPACTION_STRATEGY_PREFIX}. In the returned map, the
+ * prefix is removed from each property's key.
+ *
+ * @param tableConf configuration
+ * @return map of compaction strategy property keys and values, with the
+ * detection prefix removed from each key
+ */
public static Map<String,String> getCompactionStrategyOptions(AccumuloConfiguration tableConf) {
Map<String,String> longNames = tableConf.getAllPropertiesWithPrefix(Property.TABLE_COMPACTION_STRATEGY_PREFIX);
Map<String,String> result = new HashMap<String,String>();
http://git-wip-us.apache.org/repos/asf/accumulo/blob/3a2e0a92/core/src/main/java/org/apache/accumulo/core/conf/PropertyType.java
----------------------------------------------------------------------
diff --git a/core/src/main/java/org/apache/accumulo/core/conf/PropertyType.java b/core/src/main/java/org/apache/accumulo/core/conf/PropertyType.java
index 688b186..304ccc5 100644
--- a/core/src/main/java/org/apache/accumulo/core/conf/PropertyType.java
+++ b/core/src/main/java/org/apache/accumulo/core/conf/PropertyType.java
@@ -21,6 +21,10 @@ import java.util.regex.Pattern;
import org.apache.accumulo.core.Constants;
import org.apache.hadoop.fs.Path;
+/**
+ * Types of {@link Property} values. Each type has a short name, a description,
+ * and a regex which valid values match. All of these fields are optional.
+ */
public enum PropertyType {
PREFIX(null, null, null),
@@ -82,10 +86,20 @@ public enum PropertyType {
return shortname;
}
+ /**
+ * Gets the description of this type.
+ *
+ * @return description
+ */
String getFormatDescription() {
return format;
}
+ /**
+ * Checks if the given value is valid for this type.
+ *
+ * @return true if value is valid or null, or if this type has no regex
+ */
public boolean isValidFormat(String value) {
return (regex == null && value == null) ? true : regex.matcher(value).matches();
}
http://git-wip-us.apache.org/repos/asf/accumulo/blob/3a2e0a92/core/src/main/java/org/apache/accumulo/core/conf/SiteConfiguration.java
----------------------------------------------------------------------
diff --git a/core/src/main/java/org/apache/accumulo/core/conf/SiteConfiguration.java b/core/src/main/java/org/apache/accumulo/core/conf/SiteConfiguration.java
index 8f1f72a..ad9597c 100644
--- a/core/src/main/java/org/apache/accumulo/core/conf/SiteConfiguration.java
+++ b/core/src/main/java/org/apache/accumulo/core/conf/SiteConfiguration.java
@@ -22,6 +22,17 @@ import java.util.Map.Entry;
import org.apache.hadoop.conf.Configuration;
import org.apache.log4j.Logger;
+/**
+ * An {@link AccumuloConfiguration} which loads properties from an XML file,
+ * usually accumulo-site.xml. This implementation supports defaulting undefined
+ * property values to a parent configuration's definitions.
+ * <p>
+ * The system property "org.apache.accumulo.config.file" can be used to specify
+ * the location of the XML configuration file on the classpath. If the system
+ * property is not defined, it defaults to "accumulo-site.xml".
+ * <p>
+ * This class is a singleton.
+ */
public class SiteConfiguration extends AccumuloConfiguration {
private static final Logger log = Logger.getLogger(SiteConfiguration.class);
@@ -34,6 +45,13 @@ public class SiteConfiguration extends AccumuloConfiguration {
SiteConfiguration.parent = parent;
}
+ /**
+ * Gets an instance of this class. A new instance is only created on the first
+ * call, and so the parent configuration cannot be changed later.
+ *
+ * @param parent parent (default) configuration
+ * @throws RuntimeException if the configuration is invalid
+ */
synchronized public static SiteConfiguration getInstance(AccumuloConfiguration parent) {
if (instance == null) {
instance = new SiteConfiguration(parent);
@@ -79,7 +97,8 @@ public class SiteConfiguration extends AccumuloConfiguration {
}
/**
- * method here to support testing, do not call
+ * Clears the configuration properties in this configuration (but not the
+ * parent). This method supports testing and should not be called.
*/
public void clear() {
getXmlConfig().clear();
@@ -87,7 +106,9 @@ public class SiteConfiguration extends AccumuloConfiguration {
/**
- * method here to support testing, do not call
+ * Clears the configuration properties in this configuration (but not the
+ * parent) and nulls it. This method supports testing and should not be
+ * called.
*/
public synchronized void clearAndNull() {
if (xmlConfig != null) {
@@ -97,14 +118,20 @@ public class SiteConfiguration extends AccumuloConfiguration {
}
/**
- * method here to support testing, do not call
+ * Sets a property. This method supports testing and should not be called.
+ *
+ * @param property property to set
+ * @param value property value
*/
public void set(Property property, String value) {
set(property.getKey(), value);
}
/**
- * method here to support testing, do not call
+ * Sets a property. This method supports testing and should not be called.
+ *
+ * @param key key of property to set
+ * @param value property value
*/
public void set(String key, String value) {
getXmlConfig().set(key, value);