org.apache.hadoop.hbase.regionserver

Class ScannerContext

java.lang.Object

org.apache.hadoop.hbase.regionserver.ScannerContext

Direct Known Subclasses:

NoLimitScannerContext

@InterfaceAudience.LimitedPrivate(value="Coprocesssor")
 @InterfaceStability.Evolving
public class ScannerContext
extends Object

ScannerContext instances encapsulate limit tracking AND progress towards those limits during invocations of InternalScanner.next(java.util.List) and InternalScanner.next(java.util.List).

A ScannerContext instance should be updated periodically throughout execution whenever progress towards a limit has been made. Each limit can be checked via the appropriate checkLimit method.

Once a limit has been reached, the scan will stop. The invoker of InternalScanner.next(java.util.List) or InternalScanner.next(java.util.List) can use the appropriate check*Limit methods to see exactly which limits have been reached. Alternatively, checkAnyLimitReached(LimitScope) is provided to see if ANY limit was reached

NoLimitScannerContext.NO_LIMIT is an immutable static definition that can be used whenever a ScannerContext is needed but limits do not need to be enforced.

NOTE: It is important that this class only ever expose setter methods that can be safely skipped when limits should be NOT enforced. This is because of the necessary immutability of the class NoLimitScannerContext. If a setter cannot be safely skipped, the immutable nature of NoLimitScannerContext will lead to incorrect behavior.

Nested Class Summary

Nested Classes

Modifier and Type	Class and Description
static class	ScannerContext.Builder
private static class	ScannerContext.LimitFields The different fields that can be used as limits in calls to InternalScanner.next(java.util.List) and InternalScanner.next(java.util.List)
static class	ScannerContext.LimitScope The various scopes where a limit can be enforced.
static class	ScannerContext.NextState The possible states a scanner may be in following a call to InternalScanner.next(List)
private static class	ScannerContext.ProgressFields

Field Summary

Fields

Modifier and Type	Field and Description
private static boolean	DEFAULT_KEEP_PROGRESS
private static ScannerContext.NextState	DEFAULT_STATE
(package private) boolean	keepProgress Used as an indication to invocations of InternalScanner.next(java.util.List) and InternalScanner.next(java.util.List) that, if true, the progress tracked within this ScannerContext instance should be considered while evaluating the limits.
private Cell	lastPeekedCell
(package private) ScannerContext.LimitFields	limits
(package private) ServerSideScanMetrics	metrics Tracks the relevant server side metrics during scans.
(package private) ScannerContext.ProgressFields	progress A different set of progress fields.
private boolean	returnImmediately
(package private) ScannerContext.NextState	scannerState The state of the scanner after the invocation of InternalScanner.next(java.util.List) or InternalScanner.next(java.util.List).

Constructor Summary

Constructors

Constructor and Description
ScannerContext(boolean keepProgress, ScannerContext.LimitFields limitsToCopy, boolean trackMetrics)

Method Summary

Modifier and Type	Method and Description
(package private) boolean	checkAnyLimitReached(ScannerContext.LimitScope checkerScope)
(package private) boolean	checkBatchLimit(ScannerContext.LimitScope checkerScope)
(package private) boolean	checkSizeLimit(ScannerContext.LimitScope checkerScope)
(package private) boolean	checkTimeLimit(ScannerContext.LimitScope checkerScope)
(package private) void	clearProgress() Clear away any progress that has been made so far.
(package private) int	getBatchLimit()
(package private) int	getBatchProgress()
(package private) long	getDataSizeLimit()
(package private) long	getDataSizeProgress()
(package private) long	getHeapSizeProgress()
(package private) boolean	getKeepProgress()
(package private) Cell	getLastPeekedCell()
ServerSideScanMetrics	getMetrics() Get the metrics instance.
(package private) long	getTimeLimit()
(package private) long	getTimeProgress() Deprecated. will be removed in 3.0
(package private) boolean	hasAnyLimit(ScannerContext.LimitScope checkerScope)
(package private) boolean	hasBatchLimit(ScannerContext.LimitScope checkerScope)
(package private) boolean	hasSizeLimit(ScannerContext.LimitScope checkerScope)
(package private) boolean	hasTimeLimit(ScannerContext.LimitScope checkerScope)
(package private) void	incrementBatchProgress(int batch) Progress towards the batch limit has been made.
(package private) void	incrementSizeProgress(long dataSize, long heapSize) Progress towards the size limit has been made.
boolean	isTrackingMetrics()
(package private) boolean	mayHaveMoreCellsInRow()
static ScannerContext.Builder	newBuilder()
static ScannerContext.Builder	newBuilder(boolean keepProgress)
(package private) void	returnImmediately()
(package private) void	setBatchProgress(int batchProgress)
(package private) void	setKeepProgress(boolean keepProgress)
(package private) void	setLastPeekedCell(Cell lastPeekedCell)
(package private) void	setProgress(int batchProgress, long sizeProgress, long heapSizeProgress)
(package private) void	setProgress(int batchProgress, long sizeProgress, long heapSizeProgress, long timeProgress) Deprecated. will be removed in 3.0
(package private) ScannerContext.NextState	setScannerState(ScannerContext.NextState state) Note that this is not a typical setter.
(package private) void	setSizeLimitScope(ScannerContext.LimitScope scope)
(package private) void	setSizeProgress(long dataSizeProgress, long heapSizeProgress)
(package private) void	setTimeLimitScope(ScannerContext.LimitScope scope)
(package private) void	setTimeProgress(long timeProgress) Deprecated. will be removed in 3.0
String	toString()
(package private) void	updateTimeProgress() Deprecated. will be removed in 3.0

Methods inherited from class java.lang.Object

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

Field Detail

limits

ScannerContext.LimitFields limits

progress

ScannerContext.ProgressFields progress

A different set of progress fields. Only include batch, dataSize and heapSize. Compare to LimitFields, ProgressFields doesn't contain time field. As we save a deadline in LimitFields, so use System.currentTimeMillis() directly when check time limit.

scannerState

ScannerContext.NextState scannerState

The state of the scanner after the invocation of InternalScanner.next(java.util.List) or InternalScanner.next(java.util.List).

DEFAULT_STATE

private static final ScannerContext.NextState DEFAULT_STATE

keepProgress

boolean keepProgress

Used as an indication to invocations of InternalScanner.next(java.util.List) and InternalScanner.next(java.util.List) that, if true, the progress tracked within this ScannerContext instance should be considered while evaluating the limits. Useful for enforcing a set of limits across multiple calls (i.e. the limit may not be reached in a single invocation, but any progress made should be considered in future invocations)

Defaulting this value to false means that, by default, any tracked progress will be wiped clean on invocations to InternalScanner.next(java.util.List) and InternalScanner.next(java.util.List) and the call will be treated as though no progress has been made towards the limits so far.

This is an important mechanism. Users of Internal/Region scanners expect that they can define some limits and then repeatedly invoke InternalScanner.next(List) or InternalScanner.next(List) where each invocation respects these limits separately.

For example:

 
 ScannerContext context = new ScannerContext.newBuilder().setBatchLimit(5).build();
 RegionScanner scanner = ...
 List<Cell> results = new ArrayList<Cell>();
 while(scanner.next(results, context)) {
   // Do something with a batch of 5 cells
 }
 

However, in the case of RPCs, the server wants to be able to define a set of limits for a particular RPC request and have those limits respected across multiple invocations. This means that the progress made towards the limits in earlier calls will be saved and considered in future invocations

DEFAULT_KEEP_PROGRESS

private static boolean DEFAULT_KEEP_PROGRESS

lastPeekedCell

private Cell lastPeekedCell

returnImmediately

private boolean returnImmediately

metrics

final ServerSideScanMetrics metrics

Tracks the relevant server side metrics during scans. null when metrics should not be tracked

Constructor Detail

ScannerContext

ScannerContext(boolean keepProgress,
               ScannerContext.LimitFields limitsToCopy,
               boolean trackMetrics)

Method Detail

isTrackingMetrics

public boolean isTrackingMetrics()

getMetrics

public ServerSideScanMetrics getMetrics()

Get the metrics instance. Should only be called after a call to isTrackingMetrics() has been made to confirm that metrics are indeed being tracked.

Returns:

ServerSideScanMetrics instance that is tracking metrics for this scan

getKeepProgress

boolean getKeepProgress()

Returns:

true if the progress tracked so far in this instance will be considered during an invocation of InternalScanner.next(java.util.List) or InternalScanner.next(java.util.List). false when the progress tracked so far should not be considered and should instead be wiped away via clearProgress()

setKeepProgress

void setKeepProgress(boolean keepProgress)

incrementBatchProgress

void incrementBatchProgress(int batch)

Progress towards the batch limit has been made. Increment internal tracking of batch progress

incrementSizeProgress

void incrementSizeProgress(long dataSize,
                           long heapSize)

Progress towards the size limit has been made. Increment internal tracking of size progress

updateTimeProgress

@Deprecated
void updateTimeProgress()

Deprecated. will be removed in 3.0

Update the time progress with System.currentTimeMillis()

getBatchProgress

int getBatchProgress()

getDataSizeProgress

long getDataSizeProgress()

getHeapSizeProgress

long getHeapSizeProgress()

getTimeProgress

@Deprecated
long getTimeProgress()

Deprecated. will be removed in 3.0

setProgress

@Deprecated
void setProgress(int batchProgress,
                             long sizeProgress,
                             long heapSizeProgress,
                             long timeProgress)

Deprecated. will be removed in 3.0

setProgress

void setProgress(int batchProgress,
                 long sizeProgress,
                 long heapSizeProgress)

setSizeProgress

void setSizeProgress(long dataSizeProgress,
                     long heapSizeProgress)

setBatchProgress

void setBatchProgress(int batchProgress)

setTimeProgress

@Deprecated
void setTimeProgress(long timeProgress)

Deprecated. will be removed in 3.0

clearProgress

void clearProgress()

Clear away any progress that has been made so far. All progress fields are reset to initial values

setScannerState

ScannerContext.NextState setScannerState(ScannerContext.NextState state)

Note that this is not a typical setter. This setter returns the ScannerContext.NextState that was passed in so that methods can be invoked against the new state. Furthermore, this pattern allows the NoLimitScannerContext to cleanly override this setter and simply return the new state, thus preserving the immutability of NoLimitScannerContext

Parameters:

state -

Returns:

The state that was passed in.

mayHaveMoreCellsInRow

boolean mayHaveMoreCellsInRow()

Returns:

true when we have more cells for the current row. This usually because we have reached a limit in the middle of a row

hasBatchLimit

boolean hasBatchLimit(ScannerContext.LimitScope checkerScope)

Parameters:

checkerScope -

Returns:

true if the batch limit can be enforced in the checker's scope

hasSizeLimit

boolean hasSizeLimit(ScannerContext.LimitScope checkerScope)

Parameters:

checkerScope -

Returns:

true if the size limit can be enforced in the checker's scope

hasTimeLimit

boolean hasTimeLimit(ScannerContext.LimitScope checkerScope)

Parameters:

checkerScope -

Returns:

true if the time limit can be enforced in the checker's scope

hasAnyLimit

boolean hasAnyLimit(ScannerContext.LimitScope checkerScope)

Parameters:

checkerScope -

Returns:

true if any limit can be enforced within the checker's scope

setSizeLimitScope

void setSizeLimitScope(ScannerContext.LimitScope scope)

Parameters:

scope - The scope in which the size limit will be enforced

setTimeLimitScope

void setTimeLimitScope(ScannerContext.LimitScope scope)

Parameters:

scope - The scope in which the time limit will be enforced

getBatchLimit

int getBatchLimit()

getDataSizeLimit

long getDataSizeLimit()

getTimeLimit

long getTimeLimit()

checkBatchLimit

boolean checkBatchLimit(ScannerContext.LimitScope checkerScope)

Parameters:

checkerScope - The scope that the limit is being checked from

Returns:

true when the limit is enforceable from the checker's scope and it has been reached

checkSizeLimit

boolean checkSizeLimit(ScannerContext.LimitScope checkerScope)

Parameters:

checkerScope - The scope that the limit is being checked from

Returns:

true when the limit is enforceable from the checker's scope and it has been reached

checkTimeLimit

boolean checkTimeLimit(ScannerContext.LimitScope checkerScope)

Parameters:

checkerScope - The scope that the limit is being checked from. The time limit is always checked against System.currentTimeMillis()

Returns:

true when the limit is enforceable from the checker's scope and it has been reached

checkAnyLimitReached

boolean checkAnyLimitReached(ScannerContext.LimitScope checkerScope)

Parameters:

checkerScope - The scope that the limits are being checked from

Returns:

true when some limit is enforceable from the checker's scope and it has been reached

getLastPeekedCell

Cell getLastPeekedCell()

setLastPeekedCell

void setLastPeekedCell(Cell lastPeekedCell)

returnImmediately

void returnImmediately()

toString

public String toString()

Overrides:

toString in class Object

newBuilder

public static ScannerContext.Builder newBuilder()

newBuilder

public static ScannerContext.Builder newBuilder(boolean keepProgress)