org.apache.hadoop.hbase
Class HTable

java.lang.Object
  extended by 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


Copyright © 2006 The Apache Software Foundation