org.apache.kudu.client

Class AsyncKuduScanner

java.lang.Object

org.apache.kudu.client.AsyncKuduScanner

@InterfaceAudience.Public
 @InterfaceStability.Unstable
public final class AsyncKuduScanner
extends Object

Creates a scanner to read data from Kudu.

This class is not synchronized as it's expected to be used from a single thread at a time. It's rarely (if ever?) useful to scan concurrently from a shared scanner using multiple threads. If you want to optimize large table scans using extra parallelism, create a few scanners through the KuduScanToken API. Or use MapReduce.

There's no method in this class to explicitly open the scanner. It will open itself automatically when you start scanning by calling nextRows(). Also, the scanner will automatically call close() when it reaches the end key. If, however, you would like to stop scanning before reaching the end key, you must call close() before disposing of the scanner. Note that it's always safe to call close() on a scanner.

A AsyncKuduScanner is not re-usable. Should you want to scan the same rows or the same table again, you must create a new one.

A note on passing byte arrays in argument

None of the method that receive a byte[] in argument will copy it. For more info, please refer to the documentation of KuduRpc.

A note on passing Strings in argument

All strings are assumed to use the platform's default charset.

Nested Class Summary

Nested Classes

Modifier and Type	Class and Description
static class	AsyncKuduScanner.AsyncKuduScannerBuilder A Builder class to build AsyncKuduScanner.
static class	AsyncKuduScanner.ReadMode The possible read modes for scanners.
static class	AsyncKuduScanner.RowDataFormat Expected row data format in scanner result set.

Method Summary

Modifier and Type	Method and Description
com.stumbleupon.async.Deferred<RowResultIterator>	close() Closes this scanner (don't forget to call this when you're done with it!).
long	getBatchSizeBytes() Returns the maximum number of bytes returned by the scanner, on each batch.
boolean	getCacheBlocks() Returns if this scanner was configured to cache data blocks or not.
long	getKeepAlivePeriodMs()
long	getLimit() Returns the maximum number of rows that this scanner was configured to return.
Schema	getProjectionSchema() Returns the projection schema of this scanner.
AsyncKuduScanner.ReadMode	getReadMode() Returns the ReadMode for this scanner.
ResourceMetrics	getResourceMetrics() Returns the ResourceMetrics for this scanner.
long	getScanRequestTimeout() Returns the scan request timeout for this scanner.
boolean	hasMoreRows() Tells if the last rpc returned that there might be more rows to scan.
boolean	isClosed()
com.stumbleupon.async.Deferred<Void>	keepAlive() Keep the current remote scanner alive.
com.stumbleupon.async.Deferred<RowResultIterator>	nextRows() Scans a number of rows.
void	setReuseRowResult(boolean reuseRowResult) If set to true, the RowResult object returned by the RowResultIterator will be reused with each call to Iterator.next().
void	setRowDataFormat(AsyncKuduScanner.RowDataFormat rowDataFormat) Optionally set expected row data format.
String	toString()

Methods inherited from class java.lang.Object

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

Method Detail

getLimit

public long getLimit()

Returns the maximum number of rows that this scanner was configured to return.

Returns:

a long representing the maximum number of rows that can be returned

hasMoreRows

public boolean hasMoreRows()

Tells if the last rpc returned that there might be more rows to scan.

Returns:

true if there might be more data to scan, else false

getCacheBlocks

public boolean getCacheBlocks()

Returns if this scanner was configured to cache data blocks or not.

Returns:

true if this scanner will cache blocks, else else.

getBatchSizeBytes

public long getBatchSizeBytes()

Returns the maximum number of bytes returned by the scanner, on each batch.

Returns:

a long representing the maximum number of bytes that a scanner can receive at once from a tablet server

getReadMode

public AsyncKuduScanner.ReadMode getReadMode()

Returns the ReadMode for this scanner.

Returns:

the configured read mode for this scanner

getScanRequestTimeout

public long getScanRequestTimeout()

Returns the scan request timeout for this scanner.

Returns:

the scan request timeout, in milliseconds

getProjectionSchema

public Schema getProjectionSchema()

Returns the projection schema of this scanner. If specific columns were not specified during scanner creation, the table schema is returned.

Returns:

the projection schema for this scanner

getKeepAlivePeriodMs

public long getKeepAlivePeriodMs()

getResourceMetrics

public ResourceMetrics getResourceMetrics()

Returns the ResourceMetrics for this scanner. These metrics are updated with each batch of rows returned from the server.

Returns:

the resource metrics for this scanner

setReuseRowResult

public void setReuseRowResult(boolean reuseRowResult)

If set to true, the RowResult object returned by the RowResultIterator will be reused with each call to Iterator.next(). This can be a useful optimization to reduce the number of objects created. Note: DO NOT use this if the RowResult is stored between calls to next(). Enabling this optimization means that a call to next() mutates the previously returned RowResult. Accessing the previously returned RowResult after a call to next(), by storing all RowResults in a collection and accessing them later for example, will lead to all of the stored RowResults being mutated as per the data in the last RowResult returned.

setRowDataFormat

public void setRowDataFormat(AsyncKuduScanner.RowDataFormat rowDataFormat)

Optionally set expected row data format.

Parameters:

rowDataFormat - Row data format to be expected.

nextRows

public com.stumbleupon.async.Deferred<RowResultIterator> nextRows()

Scans a number of rows.

Once this method returns null once (which indicates that this Scanner is done scanning), calling it again leads to an undefined behavior.

Returns:

a deferred list of rows.

isClosed

public boolean isClosed()

Returns:

true if the scanner has been closed.

close

public com.stumbleupon.async.Deferred<RowResultIterator> close()

Closes this scanner (don't forget to call this when you're done with it!).

Closing a scanner already closed has no effect. The deferred returned will be called back immediately.

Returns:

A deferred object that indicates the completion of the request. The Object can be null, a RowResultIterator if there was data left in the scanner, or an Exception.

toString

public String toString()

Overrides:

toString in class Object

keepAlive

public com.stumbleupon.async.Deferred<Void> keepAlive()

Keep the current remote scanner alive.

Keep the current remote scanner alive on the Tablet server for an additional time-to-live. This is useful if the interval in between nextRows() calls is big enough that the remote scanner might be garbage collected. The scanner time-to-live can be configured on the tablet server via the --scanner_ttl_ms configuration flag and has a default of 60 seconds.

This does not invalidate any previously fetched results.

Note that an error returned by this method should not be taken as indication that the scan has failed. Subsequent calls to nextRows() might still be successful, particularly if the scanner is configured to be fault tolerant.

Returns:

A deferred object that indicates the completion of the request.

Throws:

IllegalStateException - if the scanner is already closed.