Package org.apache.hadoop.hbase.regionserver

Class ScannerContext

java.lang.Object

org.apache.hadoop.hbase.regionserver.ScannerContext

Direct Known Subclasses:

NoLimitScannerContext

@LimitedPrivate("Coprocesssor")
@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	Description
static final 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 enum	ScannerContext.LimitScope	The various scopes where a limit can be enforced.
static enum	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	Description
private static boolean	DEFAULT_KEEP_PROGRESS
private static final 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) final 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).
(package private) boolean	skippingRow	Allows temporarily ignoring limits and skipping tracking of batch and size progress.

Constructor Summary

Constructors

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

Method Summary

Modifier and Type	Method	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	getBlockSizeProgress()
(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.
boolean	getSkippingRow()	In this mode, only block size progress is tracked, and limits are ignored.
(package private) long	getTimeLimit()
(package private) long	getTimeProgress()	Deprecated. will be removed in 3.0
(package private) boolean	hasAnyLimit(ScannerContext.LimitScope checkerScope)	Returns true if any limit can be enforced within the checker's scope
(package private) boolean	hasBatchLimit(ScannerContext.LimitScope checkerScope)	Returns true if the batch limit can be enforced in the checker's scope
(package private) boolean	hasSizeLimit(ScannerContext.LimitScope checkerScope)	Returns true if the size limit can be enforced in the checker's scope
(package private) boolean	hasTimeLimit(ScannerContext.LimitScope checkerScope)	Returns true if the time limit can be enforced in the checker's scope
(package private) void	incrementBatchProgress(int batch)	Progress towards the batch limit has been made.
(package private) void	incrementBlockProgress(int blockSize)	Progress towards the block 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	setSkippingRow(boolean skippingRow)
(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 Details

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 EnvironmentEdgeManager.currentTime() 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

skippingRow

boolean skippingRow

Allows temporarily ignoring limits and skipping tracking of batch and size progress. Used when skipping to the next row, in which case all processed cells are thrown away so should not count towards 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 Details

ScannerContext

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

Method Details

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(). This only applies to per-row progress, like batch and data/heap size. Block size is never reset because it tracks all of the blocks scanned for an entire request.

setKeepProgress

void setKeepProgress(boolean keepProgress)

getSkippingRow

public boolean getSkippingRow()

In this mode, only block size progress is tracked, and limits are ignored. We set this mode when skipping to next row, in which case all cells returned a thrown away so should not count towards progress.

Returns:

true if we are in skipping row mode.

setSkippingRow

void setSkippingRow(boolean skippingRow)

Parameters:

skippingRow - set true to cause disabling of collecting per-cell progress or enforcing any limits. This is used when trying to skip over all cells in a row, in which case those cells are thrown away so should not count towards progress.

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.

incrementBlockProgress

void incrementBlockProgress(int blockSize)

Progress towards the block limit has been made. Increment internal track of block progress

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

getBlockSizeProgress

long getBlockSizeProgress()

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. Only clears progress that should reset between rows. getBlockSizeProgress() is not reset because it increments for all blocks scanned whether the result is included or filtered.

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

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)

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

hasSizeLimit

boolean hasSizeLimit(ScannerContext.LimitScope checkerScope)

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

hasTimeLimit

boolean hasTimeLimit(ScannerContext.LimitScope checkerScope)

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

hasAnyLimit

boolean hasAnyLimit(ScannerContext.LimitScope 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 EnvironmentEdgeManager.currentTime

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)