HBASE-1688 Improve javadocs in Result and KeyValue

git-svn-id: https://svn.apache.org/repos/asf/hadoop/hbase/trunk@797132 13f79535-47bb-0310-9956-ffa450edef68

CHANGES.txt

@@ -503,6 +503,7 @@ Release 0.20.0 - Unreleased
    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

src/java/org/apache/hadoop/hbase/KeyValue.java

@@ -33,8 +33,15 @@ import org.apache.hadoop.io.RawComparator;
 import org.apache.hadoop.io.Writable;
 
 /**
- * An HBase Key/Value.  Instances of this class are immutable.  They are not
+ * An HBase Key/Value.
- * comparable but Comparators are provided  Comparators change with context,
+ * 
+ * <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 @@ public class KeyValue implements Writable, HeapSize {
   //---------------------------------------------------------------------------
   
   /**
-   * @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 @@ public class KeyValue implements Writable, HeapSize {
   }
   
   /**
-   * Do not use this unless you have to.
+   * Primarily for use client-side.  Returns the row of this KeyValue in a new
-   * Use {@link #getBuffer()} with appropriate offsets and lengths instead.
+   * 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 @@ public class KeyValue implements Writable, HeapSize {
   }
 
   /**
+   * 
    * @return Timestamp
    */
   public long getTimestamp() {
@@ -941,8 +956,11 @@ public class KeyValue implements Writable, HeapSize {
   }
 
   /**
-   * Do not use this unless you have to.
+   * Primarily for use client-side.  Returns the column of this KeyValue in the
-   * Use {@link #getBuffer()} with appropriate offsets and lengths instead.
+   * 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 @@ public class KeyValue implements Writable, HeapSize {
   }
 
   /**
-   * Do not use this unless you have to.
+   * Primarily for use client-side.  Returns the family of this KeyValue in a 
-   * Use {@link #getBuffer()} with appropriate offsets and lengths instead.
+   * 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 @@ public class KeyValue implements Writable, HeapSize {
   }
 
   /**
-   * 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.
    */

src/java/org/apache/hadoop/hbase/client/Result.java

@@ -38,8 +38,29 @@ import org.apache.hadoop.hbase.util.Bytes;
 import org.apache.hadoop.io.Writable;
 
 /**
- * Single row result of a {@link Get} or {@link Scan} query.
+ * Single row result of a {@link Get} or {@link Scan} query.<p>
- * Backed by array of KeyValues.
+ * 
+ * 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;