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
This commit is contained in:
Jonathan Gray 2009-07-23 16:20:52 +00:00
parent c186d1eb2e
commit cb6db82e31
3 changed files with 59 additions and 12 deletions

View File

@ -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

View File

@ -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
* 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 @@ 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.
* 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 @@ 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.
* 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 @@ public class KeyValue implements Writable, HeapSize {
}
/**
* 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 @@ 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.
*/

View File

@ -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.
* 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;