hbase-commits mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From jg...@apache.org
Subject svn commit: r797132 - in /hadoop/hbase/trunk: CHANGES.txt src/java/org/apache/hadoop/hbase/KeyValue.java src/java/org/apache/hadoop/hbase/client/Result.java
Date Thu, 23 Jul 2009 16:20:53 GMT
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;



Mime
View raw message