You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@accumulo.apache.org by kt...@apache.org on 2012/03/07 23:22:58 UTC
svn commit: r1298165 - in /incubator/accumulo/trunk: ./
src/core/src/main/java/org/apache/accumulo/core/client/mapreduce/
src/core/src/main/java/org/apache/accumulo/core/data/
Author: kturner
Date: Wed Mar 7 22:22:57 2012
New Revision: 1298165
URL: http://svn.apache.org/viewvc?rev=1298165&view=rev
Log:
ACCUMULO-411 Added more javadoc to public API (merged from 1.4)
Modified:
incubator/accumulo/trunk/ (props changed)
incubator/accumulo/trunk/src/core/src/main/java/org/apache/accumulo/core/client/mapreduce/InputFormatBase.java
incubator/accumulo/trunk/src/core/src/main/java/org/apache/accumulo/core/data/Key.java
incubator/accumulo/trunk/src/core/src/main/java/org/apache/accumulo/core/data/Mutation.java
incubator/accumulo/trunk/src/core/src/main/java/org/apache/accumulo/core/data/Range.java
Propchange: incubator/accumulo/trunk/
------------------------------------------------------------------------------
--- svn:mergeinfo (original)
+++ svn:mergeinfo Wed Mar 7 22:22:57 2012
@@ -1,3 +1,3 @@
/incubator/accumulo/branches/1.3:1190280,1190413,1190420,1190427,1190500,1195622,1195625,1195629,1195635,1196044,1196054,1196057,1196071-1196072,1196106,1197066,1198935,1199383,1203683,1204625,1205547,1205880,1206169,1208031,1209124,1209526,1209532,1209539,1209541,1209587,1209657,1210518,1210571,1210596,1210598,1213424,1214320,1225006,1227215,1227231,1227611,1228195,1230180,1230736,1231043,1236873,1245632
/incubator/accumulo/branches/1.3.5rc:1209938
-/incubator/accumulo/branches/1.4:1201902-1298088
+/incubator/accumulo/branches/1.4:1201902-1298163
Modified: incubator/accumulo/trunk/src/core/src/main/java/org/apache/accumulo/core/client/mapreduce/InputFormatBase.java
URL: http://svn.apache.org/viewvc/incubator/accumulo/trunk/src/core/src/main/java/org/apache/accumulo/core/client/mapreduce/InputFormatBase.java?rev=1298165&r1=1298164&r2=1298165&view=diff
==============================================================================
--- incubator/accumulo/trunk/src/core/src/main/java/org/apache/accumulo/core/client/mapreduce/InputFormatBase.java (original)
+++ incubator/accumulo/trunk/src/core/src/main/java/org/apache/accumulo/core/client/mapreduce/InputFormatBase.java Wed Mar 7 22:22:57 2012
@@ -277,18 +277,23 @@ public abstract class InputFormatBase<K,
}
/**
+ * <p>
* Enable reading offline tables. This will make the map reduce job directly read the tables files. If the table is not offline, then the job will fail. If
* the table comes online during the map reduce job, its likely that the job will fail.
*
+ * <p>
* To use this option, the map reduce user will need access to read the accumulo directory in HDFS.
*
+ * <p>
* Reading the offline table will create the scan time iterator stack in the map process. So any iterators that are configured for the table will need to be
* on the mappers classpath. The accumulo-site.xml may need to be on the mappers classpath if HDFS or the accumlo directory in HDFS are non-standard.
*
+ * <p>
* One way to use this feature is to clone a table, take the clone offline, and use the clone as the input table for a map reduce job. If you plan to map
* reduce over the data many times, it may be better to the compact the table, clone it, take it offline, and use the clone for all map reduce jobs. The
* reason to do this is that compaction will reduce each tablet in the table to one file, and its faster to read from one file.
*
+ * <p>
* There are two possible advantages to reading a tables file directly out of HDFS. First, you may see better read performance. Second, it will support
* speculative execution better. When reading an online table speculative execution can put more load on an already slow tablet server.
*
Modified: incubator/accumulo/trunk/src/core/src/main/java/org/apache/accumulo/core/data/Key.java
URL: http://svn.apache.org/viewvc/incubator/accumulo/trunk/src/core/src/main/java/org/apache/accumulo/core/data/Key.java?rev=1298165&r1=1298164&r2=1298165&view=diff
==============================================================================
--- incubator/accumulo/trunk/src/core/src/main/java/org/apache/accumulo/core/data/Key.java (original)
+++ incubator/accumulo/trunk/src/core/src/main/java/org/apache/accumulo/core/data/Key.java Wed Mar 7 22:22:57 2012
@@ -17,8 +17,10 @@
package org.apache.accumulo.core.data;
/**
- * This class is used to group together all the info that goes into a key in
- * the mapfiles
+ * This is the Key used to store and access individual values in Accumulo. A Key is a tuple composed of a row, column family, column qualifier,
+ * column visibility, timestamp, and delete marker.
+ *
+ * Keys are comparable and therefore have a sorted order.
*
*/
@@ -231,53 +233,137 @@ public class Key implements WritableComp
this.deleted = false;
}
+ /**
+ * 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
+ */
+
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.
+ *
+ * @return ByteSequence that points to the internal key row data.
+ */
+
public ByteSequence getRowData() {
return new ArrayByteSequence(row);
}
+ /**
+ * This method allocates a Text object and copies into it.
+ *
+ * @return Text containing the row field
+ */
+
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.
+ *
+ * @param r
+ * row to compare to keys row
+ * @return same as 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.
+ *
+ * @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.
+ *
+ * @param cf
+ * the key's column family will be copied into this Text
+ * @return the Text that was passed in
+ */
+
public Text getColumnFamily(Text cf) {
cf.set(colFamily, 0, colFamily.length);
return cf;
}
+ /**
+ * This method allocates a Text object and copies into it.
+ *
+ * @return Text containing the column family field
+ */
+
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.
+ *
+ * @param cf
+ * column family to compare to keys column family
+ * @return same as getColumnFamily().compareTo(cf)
+ */
+
public int compareColumnFamily(Text cf) {
return WritableComparator.compareBytes(colFamily, 0, colFamily.length, cf.getBytes(), 0, cf.getLength());
}
+ /**
+ * This method returns a pointer to the keys internal data and does not copy it.
+ *
+ * @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.
+ *
+ * @param cq
+ * the key's column qualifier will be copied into this Text
+ * @return the Text that was passed in
+ */
+
public Text getColumnQualifier(Text cq) {
cq.set(colQualifier, 0, colQualifier.length);
return cq;
}
+ /**
+ * This method allocates a Text object and copies into it.
+ *
+ * @return Text containing the column qualifier field
+ */
+
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.
+ *
+ * @param cq
+ * column family to compare to keys column qualifier
+ * @return same as compareColumnQualifier().compareTo(cq)
+ */
+
public int compareColumnQualifier(Text cq) {
return WritableComparator.compareBytes(colQualifier, 0, colQualifier.length, cq.getBytes(), 0, cq.getLength());
}
@@ -298,14 +384,34 @@ public class Key implements WritableComp
this.deleted = deleted;
}
+ /**
+ * This method returns a pointer to the keys internal data and does not copy it.
+ *
+ * @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.
+ *
+ * @return Text containing the column visibility field
+ */
+
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.
+ *
+ * @param cv
+ * the key's column visibility will be copied into this Text
+ * @return the Text that was passed in
+ */
+
public final Text getColumnVisibility(Text cv) {
cv.set(colVisibility, 0, colVisibility.length);
return cv;
@@ -366,6 +472,11 @@ public class Key implements WritableComp
out.writeBoolean(deleted);
}
+ /**
+ * Compare part of a key. For example compare just the row and column family, and if those are equal then return true.
+ *
+ */
+
public boolean equals(Key other, PartialKey part) {
switch (part) {
case ROW:
@@ -388,6 +499,11 @@ public class Key implements WritableComp
}
}
+ /**
+ * Compare part of a key. For example compare just the row and column family, and if those are equal then return 0.
+ *
+ */
+
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);
@@ -430,7 +546,9 @@ public class Key implements WritableComp
}
/**
- * determines the order of keys in the MapFiles we must then just make sure that *'s are not ever stored
+ * Compare the elements of a key starting with the row. 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. Last when delete is compared, true come first and false after.
*/
public int compareTo(Key other) {
Modified: incubator/accumulo/trunk/src/core/src/main/java/org/apache/accumulo/core/data/Mutation.java
URL: http://svn.apache.org/viewvc/incubator/accumulo/trunk/src/core/src/main/java/org/apache/accumulo/core/data/Mutation.java?rev=1298165&r1=1298164&r2=1298165&view=diff
==============================================================================
--- incubator/accumulo/trunk/src/core/src/main/java/org/apache/accumulo/core/data/Mutation.java (original)
+++ incubator/accumulo/trunk/src/core/src/main/java/org/apache/accumulo/core/data/Mutation.java Wed Mar 7 22:22:57 2012
@@ -32,14 +32,23 @@ import org.apache.hadoop.io.Text;
import org.apache.hadoop.io.Writable;
/**
- * Mutation represents an action that manipulates a row in a table
+ * <p>
+ * Mutation represents an action that manipulates a row in a table. A mutation holds a list of column/value pairs that represent an atomic set of modifications
+ * to make to a row.
*
+ * <p>
* Convenience methods which takes columns and value as CharSequence (String implements CharSequence) are provided. CharSequence is converted to UTF-8 by
* 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
* 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.
+ *
*/
public class Mutation implements Writable {
Modified: incubator/accumulo/trunk/src/core/src/main/java/org/apache/accumulo/core/data/Range.java
URL: http://svn.apache.org/viewvc/incubator/accumulo/trunk/src/core/src/main/java/org/apache/accumulo/core/data/Range.java?rev=1298165&r1=1298164&r2=1298165&view=diff
==============================================================================
--- incubator/accumulo/trunk/src/core/src/main/java/org/apache/accumulo/core/data/Range.java (original)
+++ incubator/accumulo/trunk/src/core/src/main/java/org/apache/accumulo/core/data/Range.java Wed Mar 7 22:22:57 2012
@@ -28,6 +28,11 @@ import org.apache.accumulo.core.data.thr
import org.apache.hadoop.io.Text;
import org.apache.hadoop.io.WritableComparable;
+/**
+ * This class is used to specify a range of Accumulo Keys.
+ *
+ */
+
public class Range implements WritableComparable<Range> {
private Key start;
@@ -193,6 +198,11 @@ public class Range implements WritableCo
return start;
}
+ /**
+ *
+ * @param key
+ * @return true of the given key is before the range, otherwise false
+ */
public boolean beforeStartKey(Key key) {
if (infiniteStartKey) {
return false;
@@ -203,6 +213,10 @@ public class Range implements WritableCo
return key.compareTo(start) <= 0;
}
+ /**
+ * @return the last key in the range, null if the end key is infinite
+ */
+
public Key getEndKey() {
if (infiniteStopKey) {
return null;
@@ -210,6 +224,11 @@ public class Range implements WritableCo
return stop;
}
+ /**
+ * @param key
+ * @return true if the given key is after the range, otherwise false
+ */
+
public boolean afterEndKey(Key key) {
if (infiniteStopKey)
return false;
@@ -279,10 +298,32 @@ public class Range implements WritableCo
return comp;
}
+ /**
+ *
+ * @param key
+ * @return true if the given key falls within the range
+ */
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
+ *
+ * <pre>
+ * [a,c], (c, d], (g,m), (j,t]
+ * </pre>
+ *
+ * the following ranges would be returned
+ *
+ * <pre>
+ * [a,d], (g,t]
+ * </pre>
+ *
+ * @param ranges
+ * @return list of merged ranges
+ */
+
public static List<Range> mergeOverlapping(Collection<Range> ranges) {
if (ranges.size() == 0)
return Collections.emptyList();
@@ -339,10 +380,36 @@ public class Range implements WritableCo
return ret;
}
+ /**
+ * Creates a range which represents the intersection of this range and the passed in range. The following example will print true.
+ *
+ * <pre>
+ * Range range1 = new Range("a", "f");
+ * Range range2 = new Range("c", "n");
+ * Range range3 = range1.clip(range2);
+ * System.out.println(range3.equals(new Range("c", "f")));
+ * </pre>
+ *
+ * @param range
+ * @return the intersection
+ * @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.
+ *
+ * @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) {
Key sk = range.getStartKey();
@@ -384,6 +451,18 @@ public class Range implements WritableCo
return new Range(sk, ski, ek, eki);
}
+ /**
+ * 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
+ * in the returned range will have a column <= the max column.
+ *
+ *
+ * @param min
+ * @param max
+ * @return a column bounded range
+ * @throws IllegalArgumentException
+ * if min > max
+ */
+
public Range bound(Column min, Column max) {
if (min.compareTo(max) > 0) {