HBASE-2490 Improve the javadoc of the client API for HTable

git-svn-id: https://svn.apache.org/repos/asf/hadoop/hbase/trunk@938220 13f79535-47bb-0310-9956-ffa450edef68
This commit is contained in:
Michael Stack 2010-04-26 20:17:20 +00:00
parent 5bab1bdcfb
commit e37f4ecef9
3 changed files with 201 additions and 258 deletions

View File

@ -529,6 +529,8 @@ Release 0.21.0 - Unreleased
HBASE-1892 [performance] make hbase splits run faster
HBASE-2456 deleteChangedReaderObserver spitting warnings after HBASE-2248
HBASE-2452 Fix our Maven dependencies (Lars Francke via Stack)
HBASE-2490 Improve the javadoc of the client API for HTable
(Benoit Sigoure via Stack)
NEW FEATURES
HBASE-1961 HBase EC2 scripts

View File

@ -76,9 +76,9 @@ public class HTable implements HTableInterface {
private long maxScannerResultSize;
/**
* Creates an object to access a HBase table
* Creates an object to access a HBase table.
*
* @param tableName name of the table
* @param tableName Name of the table.
* @throws IOException if a remote or network exception occurs
*/
public HTable(final String tableName)
@ -87,9 +87,9 @@ public class HTable implements HTableInterface {
}
/**
* Creates an object to access a HBase table
* Creates an object to access a HBase table.
*
* @param tableName name of the table
* @param tableName Name of the table.
* @throws IOException if a remote or network exception occurs
*/
public HTable(final byte [] tableName)
@ -98,10 +98,10 @@ public class HTable implements HTableInterface {
}
/**
* Creates an object to access a HBase table
* Creates an object to access a HBase table.
*
* @param conf configuration object
* @param tableName name of the table
* @param conf Configuration object to use.
* @param tableName Name of the table.
* @throws IOException if a remote or network exception occurs
*/
public HTable(Configuration conf, final String tableName)
@ -113,8 +113,8 @@ public class HTable implements HTableInterface {
/**
* Creates an object to access a HBase table.
*
* @param conf configuration object
* @param tableName name of the table
* @param conf Configuration object to use.
* @param tableName Name of the table.
* @throws IOException if a remote or network exception occurs
*/
public HTable(Configuration conf, final byte [] tableName)
@ -174,16 +174,19 @@ public class HTable implements HTableInterface {
private ExecutorService pool;
/**
* @param tableName name of table to check
* @return true if table is on-line
* Tells whether or not a table is enabled or not.
* @param tableName Name of table to check.
* @return {@code true} if table is online.
* @throws IOException if a remote or network exception occurs
*/
public static boolean isTableEnabled(String tableName) throws IOException {
return isTableEnabled(Bytes.toBytes(tableName));
}
/**
* @param tableName name of table to check
* @return true if table is on-line
* Tells whether or not a table is enabled or not.
* @param tableName Name of table to check.
* @return {@code true} if table is online.
* @throws IOException if a remote or network exception occurs
*/
public static boolean isTableEnabled(byte[] tableName) throws IOException {
@ -191,9 +194,10 @@ public class HTable implements HTableInterface {
}
/**
* @param conf HBaseConfiguration object
* @param tableName name of table to check
* @return true if table is on-line
* Tells whether or not a table is enabled or not.
* @param conf The Configuration object to use.
* @param tableName Name of table to check.
* @return {@code true} if table is online.
* @throws IOException if a remote or network exception occurs
*/
public static boolean isTableEnabled(Configuration conf, String tableName)
@ -202,9 +206,10 @@ public class HTable implements HTableInterface {
}
/**
* @param conf HBaseConfiguration object
* @param tableName name of table to check
* @return true if table is on-line
* Tells whether or not a table is enabled or not.
* @param conf The Configuration object to use.
* @param tableName Name of table to check.
* @return {@code true} if table is online.
* @throws IOException if a remote or network exception occurs
*/
public static boolean isTableEnabled(Configuration conf, byte[] tableName)
@ -215,7 +220,7 @@ public class HTable implements HTableInterface {
/**
* Find region location hosting passed row using cached info
* @param row Row to find.
* @return Location of row.
* @return The location of the given row.
* @throws IOException if a remote or network exception occurs
*/
public HRegionLocation getRegionLocation(final String row)
@ -224,9 +229,9 @@ public class HTable implements HTableInterface {
}
/**
* Find region location hosting passed row using cached info
* Finds the region on which the given row is being served.
* @param row Row to find.
* @return Location of row.
* @return Location of the row.
* @throws IOException if a remote or network exception occurs
*/
public HRegionLocation getRegionLocation(final byte [] row)
@ -234,48 +239,52 @@ public class HTable implements HTableInterface {
return connection.getRegionLocation(tableName, row, false);
}
/** @return the table name */
public byte [] getTableName() {
return this.tableName;
}
/**
* Used by unit tests and tools to do low-level manipulations. Not for
* general use.
* <em>INTERNAL</em> Used by unit tests and tools to do low-level
* manipulations.
* @return An HConnection instance.
*/
// TODO(tsuna): Remove this. Unit tests shouldn't require public helpers.
public HConnection getConnection() {
return this.connection;
}
/**
* Get the number of rows for caching that will be passed to scanners
* @return the number of rows for caching
* Gets the number of rows that a scanner will fetch at once.
* <p>
* The default value comes from {@code hbase.client.scanner.caching}.
*/
public int getScannerCaching() {
return scannerCaching;
}
/**
* Set the number of rows for caching that will be passed to scanners
* @param scannerCaching the number of rows for caching
* Sets the number of rows that a scanner will fetch at once.
* <p>
* This will override the value specified by
* {@code hbase.client.scanner.caching}.
* Increasing this value will reduce the amount of work needed each time
* {@code next()} is called on a scanner, at the expense of memory use
* (since more rows will need to be maintained in memory by the scanners).
* @param scannerCaching the number of rows a scanner will fetch at once.
*/
public void setScannerCaching(int scannerCaching) {
this.scannerCaching = scannerCaching;
}
/**
* @return table metadata
* @throws IOException
*/
public HTableDescriptor getTableDescriptor() throws IOException {
return new UnmodifyableHTableDescriptor(
this.connection.getHTableDescriptor(this.tableName));
}
/**
* Gets the starting row key for every region in the currently open table
*
* Gets the starting row key for every region in the currently open table.
* <p>
* This is mainly useful for the MapReduce integration.
* @return Array of region starting row keys
* @throws IOException if a remote or network exception occurs
*/
@ -284,8 +293,9 @@ public class HTable implements HTableInterface {
}
/**
* Gets the ending row key for every region in the currently open table
*
* Gets the ending row key for every region in the currently open table.
* <p>
* This is mainly useful for the MapReduce integration.
* @return Array of region ending row keys
* @throws IOException if a remote or network exception occurs
*/
@ -295,8 +305,9 @@ public class HTable implements HTableInterface {
/**
* Gets the starting and ending row keys for every region in the currently
* open table
*
* open table.
* <p>
* This is mainly useful for the MapReduce integration.
* @return Pair of arrays of region starting and ending row keys
* @throws IOException if a remote or network exception occurs
*/
@ -324,8 +335,9 @@ public class HTable implements HTableInterface {
}
/**
* Get all the regions and their address for this table
*
* Gets all the regions and their address for this table.
* <p>
* This is mainly useful for the MapReduce integration.
* @return A map of HRegionInfo with it's server address
* @throws IOException if a remote or network exception occurs
*/
@ -362,16 +374,6 @@ public class HTable implements HTableInterface {
return regionMap;
}
/**
* Return the row that matches <i>row</i> exactly,
* or the one that immediately preceeds it.
*
* @param row row key
* @param family Column family to look for row in.
* @return map of values
* @throws IOException
* @since 0.20.0
*/
public Result getRowOrBefore(final byte[] row, final byte[] family)
throws IOException {
return connection.getRegionServerWithRetries(
@ -383,42 +385,18 @@ public class HTable implements HTableInterface {
});
}
/**
* Get a scanner on the current table as specified by the {@link Scan} object
*
* @param scan a configured {@link Scan} object
* @return scanner
* @throws IOException
* @since 0.20.0
*/
public ResultScanner getScanner(final Scan scan) throws IOException {
ClientScanner s = new ClientScanner(scan);
s.initialize();
return s;
}
/**
* Get a scanner on the current table as specified by the {@link Scan} object
*
* @param family The column family to scan.
* @return The scanner.
* @throws IOException
* @since 0.20.0
*/
public ResultScanner getScanner(byte [] family) throws IOException {
Scan scan = new Scan();
scan.addFamily(family);
return getScanner(scan);
}
/**
* Get a scanner on the current table as specified by the {@link Scan} object
*
* @param family The column family to scan.
* @param qualifier The column qualifier to scan.
* @return The scanner.
* @throws IOException
* @since 0.20.0
*/
public ResultScanner getScanner(byte [] family, byte [] qualifier)
throws IOException {
Scan scan = new Scan();
@ -426,13 +404,6 @@ public class HTable implements HTableInterface {
return getScanner(scan);
}
/**
* Method for getting data from a row
* @param get the Get to fetch
* @return the result
* @throws IOException
* @since 0.20.0
*/
public Result get(final Get get) throws IOException {
return connection.getRegionServerWithRetries(
new ServerCallable<Result>(connection, tableName, get.getRow()) {
@ -443,13 +414,6 @@ public class HTable implements HTableInterface {
);
}
/**
* Execute a delete
*
* @param delete the delete
* @throws IOException
* @since 0.20.0
*/
public void delete(final Delete delete)
throws IOException {
connection.getRegionServerWithRetries(
@ -462,13 +426,6 @@ public class HTable implements HTableInterface {
);
}
/**
* Bulk commit a List of Deletes to the table.
* @param deletes List of deletes. List is modified by this method. On
* exception holds deletes that were NOT applied.
* @throws IOException
* @since 0.20.1
*/
public void delete(final List<Delete> deletes)
throws IOException {
int last = 0;
@ -479,26 +436,10 @@ public class HTable implements HTableInterface {
}
}
/**
* Commit a Put to the table.
* <p>
* If autoFlush is false, the update is buffered.
* @param put data to put
* @throws IOException
* @since 0.20.0
*/
public void put(final Put put) throws IOException {
doPut(Arrays.asList(put));
}
/**
* Commit a List of Puts to the table.
* <p>
* If autoFlush is false, the update is buffered.
* @param puts list of puts
* @throws IOException if a remote or network exception occurs
* @since 0.20.0
*/
public void put(final List<Put> puts) throws IOException {
doPut(puts);
}
@ -514,37 +455,12 @@ public class HTable implements HTableInterface {
}
}
/**
* Atomically increments a column value. If the column value already exists
* and is not a big-endian long, this could throw an exception.<p>
*
* @param row row
* @param family column family
* @param qualifier column qualifier
* @param amount long amount to increment by
* @return The new value after incrementing
* @throws IOException if a remote or network exception occurs
*/
public long incrementColumnValue(final byte [] row, final byte [] family,
final byte [] qualifier, final long amount)
throws IOException {
return incrementColumnValue(row, family, qualifier, amount, true);
}
/**
* Atomically increments a column value. If the column value already exists
* and is not a big-endian long, this could throw an exception.<p>
*
* Setting writeToWAL to false means that in a fail scenario, you will lose
* any increments that have not been flushed.
* @param row row
* @param family column family
* @param qualifier column qualifier
* @param amount long amount to increment by
* @param writeToWAL true if increment should be applied to WAL, false if not
* @return The new value.
* @throws IOException if a remote or network exception occurs
*/
@SuppressWarnings({"ThrowableInstanceNeverThrown"})
public long incrementColumnValue(final byte [] row, final byte [] family,
final byte [] qualifier, final long amount, final boolean writeToWAL)
@ -572,7 +488,7 @@ public class HTable implements HTableInterface {
/**
* Atomically checks if a row/family/qualifier value match the expectedValue.
* If it does, it adds the put. If value == null, checks for non-existance
* If it does, it adds the put. If value == null, checks for non-existence
* of the value.
*
* @param row to check
@ -619,11 +535,6 @@ public class HTable implements HTableInterface {
);
}
/**
* Commit to the table the buffer of Puts.
* Called automatically in the commit methods when autoFlush is true.
* @throws IOException e
*/
public void flushCommits() throws IOException {
try {
connection.processBatchOfPuts(writeBuffer,
@ -637,11 +548,6 @@ public class HTable implements HTableInterface {
}
}
/**
* Release held resources
*
* @throws IOException
*/
public void close() throws IOException{
flushCommits();
}
@ -662,12 +568,6 @@ public class HTable implements HTableInterface {
}
}
/**
* Obtain a row lock
* @param row The row to lock
* @return rowLock RowLock containing row and lock id
* @throws IOException
*/
public RowLock lockRow(final byte [] row)
throws IOException {
return connection.getRegionServerWithRetries(
@ -681,11 +581,6 @@ public class HTable implements HTableInterface {
);
}
/**
* Release a row lock
* @param rl The row lock to release
* @throws IOException
*/
public void unlockRow(final RowLock rl)
throws IOException {
connection.getRegionServerWithRetries(
@ -699,19 +594,26 @@ public class HTable implements HTableInterface {
);
}
/**
* Get the value of autoFlush. If true, updates will not be buffered
* @return value of autoFlush
*/
public boolean isAutoFlush() {
return autoFlush;
}
/**
* Turning off autoflush will cause operations to be batched for greater
* efficiency in the RPC. Also see @{link #flushCommits}
* Turns 'auto-flush' on or off.
* <p>
* When enabled (default), {@link Put} operations don't get buffered/delayed
* and are immediately executed. This is slower but safer.
* <p>
* Turning this off means that multiple {@link Put}s will be accepted before
* any RPC is actually sent to do the write operations. If the application
* dies before pending writes get flushed to HBase, data will be lost.
* Other side effects may include the fact that the application thinks a
* {@link Put} was executed successfully whereas it was in fact only
* buffered and the operation may fail when attempting to flush all pending
* writes. In that case though, the code will retry the failed {@link Put}
* upon its next attempt to flush the buffer.
*
* @param autoFlush flag
* @param autoFlush Whether or not to enable 'auto-flush'.
* @see #flushCommits
*/
public void setAutoFlush(boolean autoFlush) {
@ -719,19 +621,23 @@ public class HTable implements HTableInterface {
}
/**
* Get the maximum size in bytes of the write buffer for this HTable
* @return the size of the write buffer in bytes
* Returns the maximum size in bytes of the write buffer for this HTable.
* <p>
* The default value comes from the configuration parameter
* {@code hbase.client.write.buffer}.
* @return The size of the write buffer in bytes.
*/
public long getWriteBufferSize() {
return writeBufferSize;
}
/**
* Set the size of the buffer in bytes.
* If the new size is lower than the current size of data in the
* write buffer, the buffer is flushed.
* @param writeBufferSize new write buffer size
* @throws IOException e
* Sets the size of the buffer in bytes.
* <p>
* If the new size is less than the current amount of data in the
* write buffer, the buffer gets flushed.
* @param writeBufferSize The new write buffer size, in bytes.
* @throws IOException if a remote or network exception occurs.
*/
public void setWriteBufferSize(long writeBufferSize) throws IOException {
this.writeBufferSize = writeBufferSize;
@ -741,8 +647,8 @@ public class HTable implements HTableInterface {
}
/**
* Get the write buffer
* @return the current write buffer
* Returns the write buffer.
* @return The current write buffer.
*/
public ArrayList<Put> getWriteBuffer() {
return writeBuffer;

View File

@ -31,6 +31,7 @@ import java.util.List;
* @since 0.21.0
*/
public interface HTableInterface {
/**
* Gets the name of this table.
*
@ -39,17 +40,16 @@ public interface HTableInterface {
byte[] getTableName();
/**
* Gets the configuration of this instance.
*
* @return The configuration.
* Returns the {@link Configuration} object used by this instance.
* <p>
* The reference returned is not a copy, so any change made to it will
* affect this instance.
*/
Configuration getConfiguration();
/**
* Gets the table descriptor for this table.
*
* @return table metadata
* @throws IOException e
* Gets the {@link HTableDescriptor table descriptor} for this table.
* @throws IOException if a remote or network exception occurs.
*/
HTableDescriptor getTableDescriptor() throws IOException;
@ -70,72 +70,84 @@ public interface HTableInterface {
boolean exists(Get get) throws IOException;
/**
* Method for getting data from a row.
* If the row cannot be found an empty Result is returned.
* This can be checked by calling {@link Result#isEmpty()}
*
* @param get the Get to fetch
* @return the result
* @throws IOException e
* Extracts certain cells from a given row.
* @param get The object that specifies what data to fetch and from which row.
* @return The data coming from the specified row, if it exists. If the row
* specified doesn't exist, the {@link Result} instance returned won't
* contain any {@link KeyValue}, as indicated by {@link Result#isEmpty()}.
* @throws IOException if a remote or network exception occurs.
* @since 0.20.0
*/
Result get(Get get) throws IOException;
/**
* Return the row that matches <i>row</i> and <i>family</i> exactly, or the
* one that immediately precedes it.
* Return the row that matches <i>row</i> exactly,
* or the one that immediately precedes it.
*
* @param row row key
* @param family Column family to look for row in
* @return map of values
* @throws IOException e
* @param row A row key.
* @param family Column family to include in the {@link Result}.
* @throws IOException if a remote or network exception occurs.
* @since 0.20.0
*/
Result getRowOrBefore(byte[] row, byte[] family) throws IOException;
/**
* Get a scanner on the current table as specified by the {@link Scan} object.
* Returns a scanner on the current table as specified by the {@link Scan}
* object.
*
* @param scan a configured {@link Scan} object
* @return the scanner
* @throws IOException e
* @param scan A configured {@link Scan} object.
* @return A scanner.
* @throws IOException if a remote or network exception occurs.
* @since 0.20.0
*/
ResultScanner getScanner(Scan scan) throws IOException;
/**
* Get a scanner on the current table as specified by the {@link Scan} object.
* Gets a scanner on the current table for the given family.
*
* @param family the column family to scan
* @return the scanner
* @throws IOException e
* @param family The column family to scan.
* @return A scanner.
* @throws IOException if a remote or network exception occurs.
* @since 0.20.0
*/
ResultScanner getScanner(byte[] family) throws IOException;
/**
* Get a scanner on the current table as specified by the {@link Scan} object.
* Gets a scanner on the current table for the given family and qualifier.
*
* @param family the column family to scan
* @param qualifier the column qualifier to scan
* @return The scanner
* @throws IOException e
* @param family The column family to scan.
* @param qualifier The column qualifier to scan.
* @return A scanner.
* @throws IOException if a remote or network exception occurs.
* @since 0.20.0
*/
ResultScanner getScanner(byte[] family, byte[] qualifier) throws IOException;
/**
* Commit a Put to the table.
* Puts some data in the table.
* <p>
* If autoFlush is false, the update is buffered.
*
* @param put data
* @throws IOException e
* If {@link #isAutoFlush isAutoFlush} is false, the update is buffered
* until the internal buffer is full.
* @param put The data to put.
* @throws IOException if a remote or network exception occurs.
* @since 0.20.0
*/
void put(Put put) throws IOException;
/**
* Commit a List of Puts to the table.
* Puts some data in the table, in batch.
* <p>
* If autoFlush is false, the update is buffered.
*
* @param puts list of puts
* @throws IOException e
* If {@link #isAutoFlush isAutoFlush} is false, the update is buffered
* until the internal buffer is full.
* @param puts The list of mutations to apply. The list gets modified by this
* method (in particular it gets re-ordered, so the order in which the elements
* are inserted in the list gives no guarantee as to the order in which the
* {@link Put}s are executed).
* @throws IOException if a remote or network exception occurs. In that case
* the {@code puts} argument will contain the {@link Put} instances that
* have not be successfully applied.
* @since 0.20.0
*/
void put(List<Put> puts) throws IOException;
@ -156,33 +168,40 @@ public interface HTableInterface {
byte[] value, Put put) throws IOException;
/**
* Deletes as specified by the delete.
* Deletes the specified cells/row.
*
* @param delete a delete
* @throws IOException e
* @param delete The object that specifies what to delete.
* @throws IOException if a remote or network exception occurs.
* @since 0.20.0
*/
void delete(Delete delete) throws IOException;
/**
* Bulk commit a List of Deletes to the table.
* @param deletes List of deletes. List is modified by this method.
* On exception holds deletes that were NOT applied.
* @throws IOException e
* Deletes the specified cells/rows in bulk.
* @param deletes List of things to delete. List gets modified by this
* method (in particular it gets re-ordered, so the order in which the elements
* are inserted in the list gives no guarantee as to the order in which the
* {@link Delete}s are executed).
* @throws IOException if a remote or network exception occurs. In that case
* the {@code deletes} argument will contain the {@link Delete} instances
* that have not be successfully applied.
* @since 0.20.1
*/
void delete(List<Delete> deletes) throws IOException;
/**
* Atomically increments a column value. If the column value already exists
* and is not a big-endian long, this could throw an exception. If the column
* value does not yet exist it is initialized to <code>amount</code> and
* written to the specified column.
*
* @param row row to increment
* @param family column family
* @param qualifier column qualifier
* @param amount long amount to increment
* @return the new value
* @throws IOException e
* Atomically increments a column value.
* <p>
* Equivalent to {@code {@link #incrementColumnValue(byte[], byte[], byte[],
* long, boolean) incrementColumnValue}(row, family, qualifier, amount,
* <b>true</b>)}
* @param row The row that contains the cell to increment.
* @param family The column family of the cell to increment.
* @param qualifier The column qualifier of the cell to increment.
* @param amount The amount to increment the cell with (or decrement, if the
* amount is negative).
* @return The new value, post increment.
* @throws IOException if a remote or network exception occurs.
*/
long incrementColumnValue(byte[] row, byte[] family, byte[] qualifier,
long amount) throws IOException;
@ -195,52 +214,68 @@ public interface HTableInterface {
*
* <p>Setting writeToWAL to false means that in a fail scenario, you will lose
* any increments that have not been flushed.
* @param row row to increment
* @param family column family
* @param qualifier column qualifier
* @param amount long amount to increment
* @param writeToWAL true if increment should be applied to WAL, false if not
* @return The new value.
* @throws IOException e
* @param row The row that contains the cell to increment.
* @param family The column family of the cell to increment.
* @param qualifier The column qualifier of the cell to increment.
* @param amount The amount to increment the cell with (or decrement, if the
* amount is negative).
* @param writeToWAL if {@code true}, the operation will be applied to the
* Write Ahead Log (WAL). This makes the operation slower but safer, as if
* the call returns successfully, it is guaranteed that the increment will
* be safely persisted. When set to {@code false}, the call may return
* successfully before the increment is safely persisted, so it's possible
* that the increment be lost in the event of a failure happening before the
* operation gets persisted.
* @return The new value, post increment.
* @throws IOException if a remote or network exception occurs.
*/
long incrementColumnValue(byte[] row, byte[] family, byte[] qualifier,
long amount, boolean writeToWAL) throws IOException;
/**
* Get the value of autoFlush. If true, updates will not be buffered.
* Tells whether or not 'auto-flush' is turned on.
*
* @return true if autoFlush is enabled for this table
* @return {@code true} if 'auto-flush' is enabled (default), meaning
* {@link Put} operations don't get buffered/delayed and are immediately
* executed.
*/
boolean isAutoFlush();
/**
* Flushes buffer data. Called automatically when autoFlush is true.
*
* @throws IOException e
* Executes all the buffered {@link Put} operations.
* <p>
* This method gets called once automatically for every {@link Put} or batch
* of {@link Put}s (when {@link #put(List<Put>)} is used) when
* {@link #isAutoFlush} is {@code true}.
* @throws IOException if a remote or network exception occurs.
*/
void flushCommits() throws IOException;
/**
* Releases held resources.
* Releases any resources help or pending changes in internal buffers.
*
* @throws IOException e
* @throws IOException if a remote or network exception occurs.
*/
void close() throws IOException;
/**
* Obtains a row lock.
* Obtains a lock on a row.
*
* @param row the row to lock
* @return rowLock RowLock containing row and lock id
* @throws IOException e
* @param row The row to lock.
* @return A {@link RowLock} containing the row and lock id.
* @throws IOException if a remote or network exception occurs.
* @see RowLock
* @see #unlockRow
*/
RowLock lockRow(byte[] row) throws IOException;
/**
* Releases the row lock.
* Releases a row lock.
*
* @param rl the row lock to release
* @throws IOException e
* @param rl The row lock to release.
* @throws IOException if a remote or network exception occurs.
* @see RowLock
* @see #unlockRow
*/
void unlockRow(RowLock rl) throws IOException;
}