Author: stack
Date: Mon Apr 26 20:17:20 2010
New Revision: 938220
URL: http://svn.apache.org/viewvc?rev=938220&view=rev
Log:
HBASE-2490 Improve the javadoc of the client API for HTable
Modified:
hadoop/hbase/trunk/CHANGES.txt
hadoop/hbase/trunk/core/src/main/java/org/apache/hadoop/hbase/client/HTable.java
hadoop/hbase/trunk/core/src/main/java/org/apache/hadoop/hbase/client/HTableInterface.java
Modified: hadoop/hbase/trunk/CHANGES.txt
URL:
http://svn.apache.org/viewvc/hadoop/hbase/trunk/CHANGES.txt?rev=938220&r1=938219&r2=938220&view=diff
==============================================================================
--- hadoop/hbase/trunk/CHANGES.txt (original)
+++ hadoop/hbase/trunk/CHANGES.txt Mon Apr 26 20:17:20 2010
@@ -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
Modified:
hadoop/hbase/trunk/core/src/main/java/org/apache/hadoop/hbase/client/HTable.java
URL:
http://svn.apache.org/viewvc/hadoop/hbase/trunk/core/src/main/java/org/apache/hadoop/hbase/client/HTable.java?rev=938220&r1=938219&r2=938220&view=diff
==============================================================================
---
hadoop/hbase/trunk/core/src/main/java/org/apache/hadoop/hbase/client/HTable.java
(original)
+++
hadoop/hbase/trunk/core/src/main/java/org/apache/hadoop/hbase/client/HTable.java
Mon Apr 26 20:17:20 2010
@@ -76,9 +76,9 @@ public class HTable implements HTableInt
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 HTableInt
}
/**
- * 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 HTableInt
}
/**
- * 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 HTableInt
/**
* 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 HTableInt
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 HTableInt
}
/**
- * @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 HTableInt
}
/**
- * @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 HTableInt
/**
* 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 HTableInt
}
/**
- * 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 HTableInt
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 HTableInt
}
/**
- * 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 HTableInt
/**
* 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 HTableInt
}
/**
- * 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 HTableInt
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 HTableInt
});
}
- /**
- * 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 HTableInt
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 HTableInt
);
}
- /**
- * 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 HTableInt
);
}
- /**
- * 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 HTableInt
}
}
- /**
- * 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 HTableInt
}
}
- /**
- * 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 HTableInt
/**
* 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 HTableInt
);
}
- /**
- * 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 HTableInt
}
}
- /**
- * Release held resources
- *
- * @throws IOException
- */
public void close() throws IOException{
flushCommits();
}
@@ -662,12 +568,6 @@ public class HTable implements HTableInt
}
}
- /**
- * 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 HTableInt
);
}
- /**
- * 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 HTableInt
);
}
- /**
- * 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 HTableInt
}
/**
- * 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 HTableInt
}
/**
- * Get the write buffer
- * @return the current write buffer
+ * Returns the write buffer.
+ * @return The current write buffer.
*/
public ArrayList<Put> getWriteBuffer() {
return writeBuffer;
Modified:
hadoop/hbase/trunk/core/src/main/java/org/apache/hadoop/hbase/client/HTableInterface.java
URL:
http://svn.apache.org/viewvc/hadoop/hbase/trunk/core/src/main/java/org/apache/hadoop/hbase/client/HTableInterface.java?rev=938220&r1=938219&r2=938220&view=diff
==============================================================================
---
hadoop/hbase/trunk/core/src/main/java/org/apache/hadoop/hbase/client/HTableInterface.java
(original)
+++
hadoop/hbase/trunk/core/src/main/java/org/apache/hadoop/hbase/client/HTableInterface.java
Mon Apr 26 20:17:20 2010
@@ -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;
}
