org.apache.hadoop.hbase
Class HTable

java.lang.Object
  org.apache.hadoop.hbase.HTable

All Implemented Interfaces:

HConstants

public class HTable
extends Object
implements HConstants

Used to communicate with a single HBase table

Nested Class Summary

protected class

HTable.ClientScanner Implements the scanner interface for the HBase client.

Field Summary

protected AtomicReference<BatchUpdate>	batch
protected boolean	closed
protected HConnection	connection
protected org.apache.commons.logging.Log	LOG
protected int	numRetries
protected long	pause
protected Random	rand
protected boolean	tableDoesNotExist
protected Text	tableName

Fields inherited from interface org.apache.hadoop.hbase.HConstants

ALL_META_COLUMNS, ALL_VERSIONS, COL_REGIONINFO, COL_REGIONINFO_ARRAY, COL_SERVER, COL_SPLITA, COL_SPLITB, COL_STARTCODE, COLUMN_FAMILY, COLUMN_FAMILY_ARRAY, COLUMN_FAMILY_STR, DEFAULT_HBASE_DIR, DEFAULT_HOST, DEFAULT_MASTER_ADDRESS, DEFAULT_MASTER_INFOPORT, DEFAULT_MASTER_PORT, DEFAULT_MAX_FILE_SIZE, DEFAULT_REGION_SERVER_CLASS, DEFAULT_REGIONSERVER_ADDRESS, DEFAULT_REGIONSERVER_INFOPORT, EMPTY_START_ROW, EMPTY_TEXT, FILE_SYSTEM_VERSION, HBASE_DIR, HREGION_LOGDIR_NAME, HREGION_OLDLOGFILE_NAME, LATEST_TIMESTAMP, MASTER_ADDRESS, META_TABLE_NAME, REGION_SERVER_CLASS, REGIONSERVER_ADDRESS, ROOT_TABLE_NAME, THREAD_WAKE_FREQUENCY, UTF8_ENCODING, VERSION_FILE_NAME

Constructor Summary

HTable(HBaseConfiguration conf, Text tableName)
Creates an object to access a HBase table

Method Summary

void	abort(long lockid) Abort a row mutation.
void	abortBatch(long lockid) Deprecated. Batch operations are now the default. abortBatch is now implemented by @see abort(long)
protected void	checkClosed()
void	checkUpdateInProgress() Verifies that no update is in progress
void	close() Releases resources associated with this table.
void	commit(long lockid) Finalize a row mutation.
void	commit(long lockid, long timestamp) Finalize a row mutation and release any resources associated with the update.
void	commitBatch(long lockid) Deprecated. Batch operations are now the default. commitBatch(long) is now implemented by @see commit(long)
void	commitBatch(long lockid, long timestamp) Deprecated. Batch operations are now the default. commitBatch(long, long) is now implemented by @see commit(long, long)
void	delete(long lockid, Text column) Delete the value for a column.
void	deleteAll(Text row) Completely delete the row's cells.
void	deleteAll(Text row, long ts) Completely delete the row's cells of the same timestamp or older.
void	deleteAll(Text row, Text column) Delete all cells that match the passed row and column.
void	deleteAll(Text row, Text column, long ts) Delete all cells that match the passed row and column and whose timestamp is equal-to or older than the passed timestamp.
void	deleteFamily(Text row, Text family) Delete all cells for a row with matching column family at all timestamps.
void	deleteFamily(Text row, Text family, long timestamp) Delete all cells for a row with matching column family with timestamps less than or equal to timestamp.
byte[]	get(Text row, Text column) Get a single value for the specified row and column
byte[][]	get(Text row, Text column, int numVersions) Get the specified number of versions of the specified row and column
byte[][]	get(Text row, Text column, long timestamp, int numVersions) Get the specified number of versions of the specified row and column with the specified timestamp.
HConnection	getConnection()
HTableDescriptor	getMetadata()
SortedMap<Text,byte[]>	getRow(Text row) Get all the data for the specified row at the latest timestamp
SortedMap<Text,byte[]>	getRow(Text row, long ts) Get all the data for the specified row at a specified timestamp
Text[]	getStartKeys() Gets the starting row key for every region in the currently open table
Text	getTableName()
HScannerInterface	obtainScanner(Text[] columns, Text startRow) Get a scanner on the current table starting at the specified row.
HScannerInterface	obtainScanner(Text[] columns, Text startRow, long timestamp) Get a scanner on the current table starting at the specified row.
HScannerInterface	obtainScanner(Text[] columns, Text startRow, long timestamp, RowFilterInterface filter) Get a scanner on the current table starting at the specified row.
HScannerInterface	obtainScanner(Text[] columns, Text startRow, RowFilterInterface filter) Get a scanner on the current table starting at the specified row.
HScannerInterface	obtainScanner(Text[] columns, Text startRow, Text stopRow) Get a scanner on the current table starting at the specified row and ending just before stopRow.
HScannerInterface	obtainScanner(Text[] columns, Text startRow, Text stopRow, long timestamp) Get a scanner on the current table starting at the specified row and ending just before stopRow.
void	put(long lockid, Text column, byte[] val) Update a value for the specified column.
void	put(long lockid, Text column, Writable val) Update a value for the specified column.
void	renewLease(long lockid) Deprecated. Batch updates are now the default. Consequently this method does nothing.
long	startBatchUpdate(Text row) Deprecated. Batch operations are now the default. startBatchUpdate is now implemented by @see startUpdate(Text)
long	startUpdate(Text row) Start an atomic row insertion/update.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Detail

LOG

protected final org.apache.commons.logging.Log LOG

connection

protected final HConnection connection

tableName

protected final Text tableName

pause

protected final long pause

numRetries

protected final int numRetries

rand

protected Random rand

batch

protected AtomicReference<BatchUpdate> batch

tableDoesNotExist

protected volatile boolean tableDoesNotExist

closed

protected volatile boolean closed

Constructor Detail

HTable

public HTable(HBaseConfiguration conf,
              Text tableName)
       throws IOException

Creates an object to access a HBase table

Parameters:

conf - configuration object

tableName - name of the table

Throws:

IOException

Method Detail

checkClosed

protected void checkClosed()

getConnection

public HConnection getConnection()

Returns:

the connection

close

public void close()

Releases resources associated with this table. After calling close(), all other methods will throw an IllegalStateException

checkUpdateInProgress

public void checkUpdateInProgress()

Verifies that no update is in progress

getTableName

public Text getTableName()

Returns:

the table name

getMetadata

public HTableDescriptor getMetadata()
                             throws IOException

Returns:

table metadata

Throws:

IOException

getStartKeys

public Text[] getStartKeys()
                    throws IOException

Gets the starting row key for every region in the currently open table

Returns:

Array of region starting row keys

Throws:

IOException

get

public byte[] get(Text row,
                  Text column)
           throws IOException

Get a single value for the specified row and column

Parameters:

row - row key

column - column name

Returns:

value for specified row/column

Throws:

IOException

get

public byte[][] get(Text row,
                    Text column,
                    int numVersions)
             throws IOException

Get the specified number of versions of the specified row and column

Parameters:

row - - row key

column - - column name

numVersions - - number of versions to retrieve

Returns:

- array byte values

Throws:

IOException

get

public byte[][] get(Text row,
                    Text column,
                    long timestamp,
                    int numVersions)
             throws IOException

Get the specified number of versions of the specified row and column with the specified timestamp.

Parameters:

row - - row key

column - - column name

timestamp - - timestamp

numVersions - - number of versions to retrieve

Returns:

- array of values that match the above criteria

Throws:

IOException

getRow

public SortedMap<Text,byte[]> getRow(Text row)
                              throws IOException

Get all the data for the specified row at the latest timestamp

Parameters:

row - row key

Returns:

Map of columns to values. Map is empty if row does not exist.

Throws:

IOException

getRow

public SortedMap<Text,byte[]> getRow(Text row,
                                     long ts)
                              throws IOException

Get all the data for the specified row at a specified timestamp

Parameters:

row - row key

ts - timestamp

Returns:

Map of columns to values. Map is empty if row does not exist.

Throws:

IOException

obtainScanner

public HScannerInterface obtainScanner(Text[] columns,
                                       Text startRow)
                                throws IOException

Get a scanner on the current table starting at the specified row. Return the specified columns.

Parameters:

columns - columns to scan. If column name is a column family, all columns of the specified column family are returned. Its also possible to pass a regex in the column qualifier. A column qualifier is judged to be a regex if it contains at least one of the following characters: \+|^&*$[]]}{)(.

startRow - starting row in table to scan

Returns:

scanner

Throws:

IOException

obtainScanner

public HScannerInterface obtainScanner(Text[] columns,
                                       Text startRow,
                                       long timestamp)
                                throws IOException

Get a scanner on the current table starting at the specified row. Return the specified columns.

Parameters:

columns - columns to scan. If column name is a column family, all columns of the specified column family are returned. Its also possible to pass a regex in the column qualifier. A column qualifier is judged to be a regex if it contains at least one of the following characters: \+|^&*$[]]}{)(.

startRow - starting row in table to scan

timestamp - only return results whose timestamp <= this value

Returns:

scanner

Throws:

IOException

obtainScanner

public HScannerInterface obtainScanner(Text[] columns,
                                       Text startRow,
                                       RowFilterInterface filter)
                                throws IOException

Get a scanner on the current table starting at the specified row. Return the specified columns.

Parameters:

columns - columns to scan. If column name is a column family, all columns of the specified column family are returned. Its also possible to pass a regex in the column qualifier. A column qualifier is judged to be a regex if it contains at least one of the following characters: \+|^&*$[]]}{)(.

startRow - starting row in table to scan

filter - a row filter using row-key regexp and/or column data filter.

Returns:

scanner

Throws:

IOException

obtainScanner

public HScannerInterface obtainScanner(Text[] columns,
                                       Text startRow,
                                       Text stopRow)
                                throws IOException

Get a scanner on the current table starting at the specified row and ending just before stopRow. Return the specified columns.

Parameters:

columns - columns to scan. If column name is a column family, all columns of the specified column family are returned. Its also possible to pass a regex in the column qualifier. A column qualifier is judged to be a regex if it contains at least one of the following characters: \+|^&*$[]]}{)(.

startRow - starting row in table to scan

stopRow - Row to stop scanning on. Once we hit this row we stop returning values; i.e. we return the row before this one but not the stopRow itself.

Returns:

scanner

Throws:

IOException

obtainScanner

public HScannerInterface obtainScanner(Text[] columns,
                                       Text startRow,
                                       Text stopRow,
                                       long timestamp)
                                throws IOException

Get a scanner on the current table starting at the specified row and ending just before stopRow. Return the specified columns.

Parameters:

columns - columns to scan. If column name is a column family, all columns of the specified column family are returned. Its also possible to pass a regex in the column qualifier. A column qualifier is judged to be a regex if it contains at least one of the following characters: \+|^&*$[]]}{)(.

startRow - starting row in table to scan

stopRow - Row to stop scanning on. Once we hit this row we stop returning values; i.e. we return the row before this one but not the stopRow itself.

timestamp - only return results whose timestamp <= this value

Returns:

scanner

Throws:

IOException

obtainScanner

public HScannerInterface obtainScanner(Text[] columns,
                                       Text startRow,
                                       long timestamp,
                                       RowFilterInterface filter)
                                throws IOException

Get a scanner on the current table starting at the specified row. Return the specified columns.

Parameters:

columns - columns to scan. If column name is a column family, all columns of the specified column family are returned. Its also possible to pass a regex in the column qualifier. A column qualifier is judged to be a regex if it contains at least one of the following characters: \+|^&*$[]]}{)(.

startRow - starting row in table to scan

timestamp - only return results whose timestamp <= this value

filter - a row filter using row-key regexp and/or column data filter.

Returns:

scanner

Throws:

IOException

startBatchUpdate

@Deprecated
public long startBatchUpdate(Text row)

Deprecated. Batch operations are now the default. startBatchUpdate is now implemented by @see startUpdate(Text)

Start a batch of row insertions/updates. No changes are committed until the call to commitBatchUpdate returns. A call to abortBatchUpdate will abandon the entire batch.

Parameters:

row - name of row to be updated

Returns:

lockid to be used in subsequent put, delete and commit calls

abortBatch

@Deprecated
public void abortBatch(long lockid)

Deprecated. Batch operations are now the default. abortBatch is now implemented by @see abort(long)

Abort a batch mutation

Parameters:

lockid - lock id returned by startBatchUpdate

commitBatch

@Deprecated
public void commitBatch(long lockid)
                 throws IOException

Deprecated. Batch operations are now the default. commitBatch(long) is now implemented by @see commit(long)

Finalize a batch mutation

Parameters:

lockid - lock id returned by startBatchUpdate

Throws:

IOException

commitBatch

@Deprecated
public void commitBatch(long lockid,
                                   long timestamp)
                 throws IOException

Deprecated. Batch operations are now the default. commitBatch(long, long) is now implemented by @see commit(long, long)

Finalize a batch mutation

Parameters:

lockid - lock id returned by startBatchUpdate

timestamp - time to associate with all the changes

Throws:

IOException

startUpdate

public long startUpdate(Text row)

Start an atomic row insertion/update. No changes are committed until the call to commit() returns. A call to abort() will abandon any updates in progress.

Example:

 long lockid = table.startUpdate(new Text(article.getName()));
 for (File articleInfo: article.listFiles(new NonDirectories())) {
   String article = null;
   try {
     DataInputStream in = new DataInputStream(new FileInputStream(articleInfo));
     article = in.readUTF();
   } catch (IOException e) {
     // Input error - abandon update
     table.abort(lockid);
     throw e;
   }
   try {
     table.put(lockid, columnName(articleInfo.getName()), article.getBytes());
   } catch (RuntimeException e) {
     // Put failed - abandon update
     table.abort(lockid);
     throw e;
   }
 }
 table.commit(lockid);
 

Parameters:

row - Name of row to start update against. Note, choose row names with care. Rows are sorted lexicographically (comparison is done using Text.compareTo(Object). If your keys are numeric, lexicographic sorting means that 46 sorts AFTER 450 (If you want to use numerics for keys, zero-pad).

Returns:

Row lock id..

See Also:

commit(long), commit(long, long), abort(long)

put

public void put(long lockid,
                Text column,
                byte[] val)

Update a value for the specified column. Runs abort(long) if exception thrown.

Parameters:

lockid - lock id returned from startUpdate

column - column whose value is being set

val - new value for column. Cannot be null.

put

public void put(long lockid,
                Text column,
                Writable val)
         throws IOException

Update a value for the specified column. Runs abort(long) if exception thrown.

Parameters:

lockid - lock id returned from startUpdate

column - column whose value is being set

val - new value for column. Cannot be null.

Throws:

IOException - throws this if the writable can't be converted into a byte array

delete

public void delete(long lockid,
                   Text column)

Delete the value for a column. Deletes the cell whose row/column/commit-timestamp match those of the delete.

Parameters:

lockid - lock id returned from startUpdate

column - name of column whose value is to be deleted

deleteAll

public void deleteAll(Text row,
                      Text column)
               throws IOException

Delete all cells that match the passed row and column.

Parameters:

row - Row to update

column - name of column whose value is to be deleted

Throws:

IOException

deleteAll

public void deleteAll(Text row,
                      Text column,
                      long ts)
               throws IOException

Delete all cells that match the passed row and column and whose timestamp is equal-to or older than the passed timestamp.

Parameters:

row - Row to update

column - name of column whose value is to be deleted

ts - Delete all cells of the same timestamp or older.

Throws:

IOException

deleteAll

public void deleteAll(Text row,
                      long ts)
               throws IOException

Completely delete the row's cells of the same timestamp or older.

Parameters:

row - Key of the row you want to completely delete.

ts - Timestamp of cells to delete

Throws:

IOException

deleteAll

public void deleteAll(Text row)
               throws IOException

Completely delete the row's cells.

Parameters:

row - Key of the row you want to completely delete.

Throws:

IOException

deleteFamily

public void deleteFamily(Text row,
                         Text family,
                         long timestamp)
                  throws IOException

Delete all cells for a row with matching column family with timestamps less than or equal to timestamp.

Parameters:

row - The row to operate on

family - The column family to match

timestamp - Timestamp to match

Throws:

IOException

deleteFamily

public void deleteFamily(Text row,
                         Text family)
                  throws IOException

Delete all cells for a row with matching column family at all timestamps.

Parameters:

row - The row to operate on

family - The column family to match

Throws:

IOException

abort

public void abort(long lockid)

Abort a row mutation. This method should be called only when an update has been started and it is determined that the update should not be committed. Releases resources being held by the update in progress.

Parameters:

lockid - lock id returned from startUpdate

commit

public void commit(long lockid)
            throws IOException

Finalize a row mutation. When this method is specified, we pass the server a value that says use the 'latest' timestamp. If we are doing a put, on the server-side, cells will be given the servers's current timestamp. If the we are commiting deletes, then delete removes the most recently modified cell of stipulated column.

Parameters:

lockid - lock id returned from startUpdate

Throws:

IOException

See Also:

commit(long, long)

commit

public void commit(long lockid,
                   long timestamp)
            throws IOException

Finalize a row mutation and release any resources associated with the update.

Parameters:

lockid - lock id returned from startUpdate

timestamp - time to associate with the change

Throws:

IOException

renewLease

@Deprecated
public void renewLease(long lockid)

Deprecated. Batch updates are now the default. Consequently this method does nothing.

Renew lease on update

Parameters:

lockid - - lock id returned from startUpdate