Author: jgray
Date: Thu Jul 23 16:20:52 2009
New Revision: 797132
URL: http://svn.apache.org/viewvc?rev=797132&view=rev
Log:
HBASE-1688 Improve javadocs in Result and KeyValue
Modified:
hadoop/hbase/trunk/CHANGES.txt
hadoop/hbase/trunk/src/java/org/apache/hadoop/hbase/KeyValue.java
hadoop/hbase/trunk/src/java/org/apache/hadoop/hbase/client/Result.java
Modified: hadoop/hbase/trunk/CHANGES.txt
URL:
http://svn.apache.org/viewvc/hadoop/hbase/trunk/CHANGES.txt?rev=797132&r1=797131&r2=797132&view=diff
==============================================================================
--- hadoop/hbase/trunk/CHANGES.txt (original)
+++ hadoop/hbase/trunk/CHANGES.txt Thu Jul 23 16:20:52 2009
@@ -503,6 +503,7 @@
HBASE-1609 We wait on leases to expire before regionserver goes down.
Rather, just let client fail
HBASE-1655 Usability improvements to HTablePool (Ken Weiner via jgray)
+ HBASE-1688 Improve javadocs in Result and KeyValue
OPTIMIZATIONS
HBASE-1412 Change values for delete column and column family in KeyValue
Modified: hadoop/hbase/trunk/src/java/org/apache/hadoop/hbase/KeyValue.java
URL:
http://svn.apache.org/viewvc/hadoop/hbase/trunk/src/java/org/apache/hadoop/hbase/KeyValue.java?rev=797132&r1=797131&r2=797132&view=diff
==============================================================================
--- hadoop/hbase/trunk/src/java/org/apache/hadoop/hbase/KeyValue.java (original)
+++ hadoop/hbase/trunk/src/java/org/apache/hadoop/hbase/KeyValue.java Thu Jul
23 16:20:52 2009
@@ -33,8 +33,15 @@
import org.apache.hadoop.io.Writable;
/**
- * An HBase Key/Value. Instances of this class are immutable. They are not
- * comparable but Comparators are provided Comparators change with context,
+ * An HBase Key/Value.
+ *
+ * <p>If being used client-side, the primary methods to access individual
fields
+ * are {...@link #getRow()}, {...@link #getFamily()}, {...@link
#getQualifier()},
+ * {...@link #getTimestamp()}, and {...@link #getValue()}. These methods
allocate new
+ * byte arrays and return copies so they should be avoided server-side.
+ *
+ * <p>Instances of this class are immutable. They are not
+ * comparable but Comparators are provided. Comparators change with context,
* whether user table or a catalog table comparison context. Its
* important that you use the appropriate comparator comparing rows in
* particular. There are Comparators for KeyValue instances and then for
@@ -860,7 +867,11 @@
//---------------------------------------------------------------------------
/**
- * @return Copy of the key portion only. Used compacting and testing.
+ * Do not use unless you have to. Used internally for compacting and
testing.
+ *
+ * Use {...@link #getRow()}, {...@link #getFamily()}, {...@link
#getQualifier()}, and
+ * {...@link #getValue()} if accessing a KeyValue client-side.
+ * @return Copy of the key portion only.
*/
public byte [] getKey() {
int keylength = getKeyLength();
@@ -883,8 +894,11 @@
}
/**
- * Do not use this unless you have to.
- * Use {...@link #getBuffer()} with appropriate offsets and lengths instead.
+ * Primarily for use client-side. Returns the row of this KeyValue in a new
+ * byte array.<p>
+ *
+ * If server-side, use {...@link #getBuffer()} with appropriate offsets and
+ * lengths instead.
* @return Row in a new byte array.
*/
public byte [] getRow() {
@@ -896,6 +910,7 @@
}
/**
+ *
* @return Timestamp
*/
public long getTimestamp() {
@@ -941,8 +956,11 @@
}
/**
- * Do not use this unless you have to.
- * Use {...@link #getBuffer()} with appropriate offsets and lengths instead.
+ * Primarily for use client-side. Returns the column of this KeyValue in the
+ * deprecated format: <i>family:qualifier</i>, and in a new byte array.<p>
+ *
+ * If server-side, use {...@link #getBuffer()} with appropriate offsets and
+ * lengths instead.
* @return Returns column. Makes a copy. Inserts delimiter.
*/
public byte [] getColumn() {
@@ -957,8 +975,11 @@
}
/**
- * Do not use this unless you have to.
- * Use {...@link #getBuffer()} with appropriate offsets and lengths instead.
+ * Primarily for use client-side. Returns the family of this KeyValue in a
+ * new byte array.<p>
+ *
+ * If server-side, use {...@link #getBuffer()} with appropriate offsets and
+ * lengths instead.
* @return Returns family. Makes a copy.
*/
public byte [] getFamily() {
@@ -970,7 +991,11 @@
}
/**
- * Do not use this unless you have to.
+ * Primarily for use client-side. Returns the column qualifier of this
+ * KeyValue in a new byte array.<p>
+ *
+ * If server-side, use {...@link #getBuffer()} with appropriate offsets and
+ * lengths instead.
* Use {...@link #getBuffer()} with appropriate offsets and lengths instead.
* @return Returns qualifier. Makes a copy.
*/
Modified: hadoop/hbase/trunk/src/java/org/apache/hadoop/hbase/client/Result.java
URL:
http://svn.apache.org/viewvc/hadoop/hbase/trunk/src/java/org/apache/hadoop/hbase/client/Result.java?rev=797132&r1=797131&r2=797132&view=diff
==============================================================================
--- hadoop/hbase/trunk/src/java/org/apache/hadoop/hbase/client/Result.java
(original)
+++ hadoop/hbase/trunk/src/java/org/apache/hadoop/hbase/client/Result.java Thu
Jul 23 16:20:52 2009
@@ -38,8 +38,29 @@
import org.apache.hadoop.io.Writable;
/**
- * Single row result of a {...@link Get} or {...@link Scan} query.
- * Backed by array of KeyValues.
+ * Single row result of a {...@link Get} or {...@link Scan} query.<p>
+ *
+ * Convenience methods are available that return various {...@link Map}
+ * structures and values directly.<p>
+ *
+ * To get a complete mapping of all cells in the Result, which can include
+ * multiple families and multiple versions, use {...@link #getMap()}.<p>
+ *
+ * To get a mapping of each family to its columns (qualifiers and values),
+ * including only the latest version of each, use {...@link
#getNoVersionMap()}.
+ *
+ * To get a mapping of qualifiers to latest values for an individual family
use
+ * {...@link #getFamilyMap(byte[])}.<p>
+ *
+ * To get the latest value for a specific family and qualifier use {...@link
#getValue(byte[], byte[])}.
+ *
+ * A Result is backed by an array of {...@link KeyValue} objects, each
representing
+ * an HBase cell defined by the row, family, qualifier, timestamp, and
value.<p>
+ *
+ * The underlying {...@link KeyValue} objects can be accessed through the
methods
+ * {...@link #sorted()} and {...@link #list()}. Each KeyValue can then be
accessed
+ * through {...@link KeyValue#getRow()}, {...@link KeyValue#getFamily()},
{...@link KeyValue#getQualifier()},
+ * {...@link KeyValue#getTimestamp()}, and {...@link KeyValue#getValue()}.
*/
public class Result implements Writable {
private KeyValue [] kvs = null;
