org.apache.hadoop.hbase.client

Interface BufferedMutator

All Superinterfaces:

AutoCloseable, Closeable

All Known Implementing Classes:

BufferedMutatorImpl

@InterfaceAudience.Public
 @InterfaceStability.Evolving
public interface BufferedMutator
extends Closeable

Used to communicate with a single HBase table similar to Table but meant for batched, asynchronous puts. Obtain an instance from a Connection and call close() afterwards. Customizations can be applied to the BufferedMutator via the BufferedMutatorParams.

Exception handling with asynchronously via the BufferedMutator.ExceptionListener. The default implementation is to throw the exception upon receipt. This behavior can be overridden with a custom implementation, provided as a parameter with BufferedMutatorParams.listener(BufferedMutator.ExceptionListener).

Map/Reduce jobs are good use cases for using BufferedMutator. Map/reduce jobs benefit from batching, but have no natural flush point. BufferedMutator receives the puts from the M/R job and will batch puts based on some heuristic, such as the accumulated size of the puts, and submit batches of puts asynchronously so that the M/R logic can continue without interruption.

BufferedMutator can also be used on more exotic circumstances. Map/Reduce batch jobs will have a single BufferedMutator per thread. A single BufferedMutator can also be effectively used in high volume online systems to batch puts, with the caveat that extreme circumstances, such as JVM or machine failure, may cause some data loss.

NOTE: This class replaces the functionality that used to be available via HTableInterface.setAutoFlush(boolean) set to false.

See also the BufferedMutatorExample in the hbase-examples module.

Since:

1.0.0

See Also:

ConnectionFactory, Connection

Nested Class Summary

Nested Classes

Modifier and Type	Interface and Description
static interface	BufferedMutator.ExceptionListener Listens for asynchronous exceptions on a BufferedMutator.

Method Summary

Modifier and Type	Method and Description
void	close() Performs a flush() and releases any resources held.
void	flush() Executes all the buffered, asynchronous Mutation operations and waits until they are done.
Configuration	getConfiguration() Returns the org.apache.hadoop.conf.Configuration object used by this instance.
TableName	getName() Gets the fully qualified table name instance of the table that this BufferedMutator writes to.
long	getWriteBufferSize() Returns the maximum size in bytes of the write buffer for this HTable.
void	mutate(List<? extends Mutation> mutations) Send some Mutations to the table.
void	mutate(Mutation mutation) Sends a Mutation to the table.

Method Detail

getName

TableName getName()

Gets the fully qualified table name instance of the table that this BufferedMutator writes to.

getConfiguration

Configuration getConfiguration()

Returns the org.apache.hadoop.conf.Configuration object used by this instance.

The reference returned is not a copy, so any change made to it will affect this instance.

mutate

void mutate(Mutation mutation)
     throws IOException

Sends a Mutation to the table. The mutations will be buffered and sent over the wire as part of a batch. Currently only supports Put and Delete mutations.

Parameters:

mutation - The data to send.

Throws:

IOException - if a remote or network exception occurs.

mutate

void mutate(List<? extends Mutation> mutations)
     throws IOException

Send some Mutations to the table. The mutations will be buffered and sent over the wire as part of a batch. There is no guarantee of sending entire content of mutations in a single batch; it will be broken up according to the write buffer capacity.

Parameters:

mutations - The data to send.

Throws:

IOException - if a remote or network exception occurs.

close

void close()
    throws IOException

Performs a flush() and releases any resources held.

Specified by:

close in interface AutoCloseable

Specified by:

close in interface Closeable

Throws:

IOException - if a remote or network exception occurs.

flush

void flush()
    throws IOException

Executes all the buffered, asynchronous Mutation operations and waits until they are done.

Throws:

IOException - if a remote or network exception occurs.

getWriteBufferSize

long getWriteBufferSize()

Returns the maximum size in bytes of the write buffer for this HTable.

The default value comes from the configuration parameter hbase.client.write.buffer.

Returns:

The size of the write buffer in bytes.