Class ScannerContext
- Direct Known Subclasses:
NoLimitScannerContext
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
Modifier and TypeClassDescriptionstatic final class
private static class
The different fields that can be used as limits in calls toInternalScanner.next(java.util.List)
andInternalScanner.next(java.util.List)
static enum
The various scopes where a limit can be enforced.static enum
The possible states a scanner may be in following a call toInternalScanner.next(List)
private static class
-
Field Summary
Modifier and TypeFieldDescriptionprivate static boolean
private static final ScannerContext.NextState
(package private) boolean
Used as an indication to invocations ofInternalScanner.next(java.util.List)
andInternalScanner.next(java.util.List)
that, if true, the progress tracked within thisScannerContext
instance should be considered while evaluating the limits.private Cell
(package private) ScannerContext.LimitFields
(package private) final ServerSideScanMetrics
Tracks the relevant server side metrics during scans.(package private) ScannerContext.ProgressFields
A different set of progress fields.private boolean
(package private) ScannerContext.NextState
The state of the scanner after the invocation ofInternalScanner.next(java.util.List)
orInternalScanner.next(java.util.List)
.(package private) boolean
Allows temporarily ignoring limits and skipping tracking of batch and size progress. -
Constructor Summary
ConstructorDescriptionScannerContext
(boolean keepProgress, ScannerContext.LimitFields limitsToCopy, boolean trackMetrics) -
Method Summary
Modifier and TypeMethodDescription(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
Clear away any progress that has been made so far.(package private) int
(package private) int
(package private) long
(package private) long
(package private) long
(package private) long
(package private) boolean
(package private) Cell
Get the metrics instance.boolean
In this mode, only block size progress is tracked, and limits are ignored.(package private) long
(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
(package private) boolean
static ScannerContext.Builder
static ScannerContext.Builder
newBuilder
(boolean keepProgress) (package private) void
(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) ScannerContext.NextState
Note that this is not a typical setter.(package private) void
(package private) void
setSizeProgress
(long dataSizeProgress, long heapSizeProgress) (package private) void
setSkippingRow
(boolean skippingRow) (package private) void
toString()
-
Field Details
-
limits
-
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 useEnvironmentEdgeManager.currentTime()
directly when check time limit. -
scannerState
The state of the scanner after the invocation ofInternalScanner.next(java.util.List)
orInternalScanner.next(java.util.List)
. -
DEFAULT_STATE
-
keepProgress
boolean keepProgressUsed as an indication to invocations ofInternalScanner.next(java.util.List)
andInternalScanner.next(java.util.List)
that, if true, the progress tracked within thisScannerContext
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)
andInternalScanner.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)
orInternalScanner.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 }
-
DEFAULT_KEEP_PROGRESS
-
skippingRow
boolean skippingRowAllows 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
-
returnImmediately
-
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
-
getMetrics
Get the metrics instance. Should only be called after a call toisTrackingMetrics()
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)
orInternalScanner.next(java.util.List)
. false when the progress tracked so far should not be considered and should instead be wiped away viaclearProgress()
. 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
-
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
- 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
Progress towards the batch limit has been made. Increment internal tracking of batch progress -
incrementSizeProgress
Progress towards the size limit has been made. Increment internal tracking of size progress -
incrementBlockProgress
Progress towards the block limit has been made. Increment internal track of block progress -
getBatchProgress
int getBatchProgress() -
getDataSizeProgress
long getDataSizeProgress() -
getHeapSizeProgress
long getHeapSizeProgress() -
getBlockSizeProgress
long getBlockSizeProgress() -
setProgress
-
setSizeProgress
-
setBatchProgress
-
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
Note that this is not a typical setter. This setter returns theScannerContext.NextState
that was passed in so that methods can be invoked against the new state. Furthermore, this pattern allows theNoLimitScannerContext
to cleanly override this setter and simply return the new state, thus preserving the immutability ofNoLimitScannerContext
- 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
Returns true if the batch limit can be enforced in the checker's scope -
hasSizeLimit
Returns true if the size limit can be enforced in the checker's scope -
hasTimeLimit
Returns true if the time limit can be enforced in the checker's scope -
hasAnyLimit
Returns true if any limit can be enforced within the checker's scope -
setSizeLimitScope
- Parameters:
scope
- The scope in which the size limit will be enforced
-
setTimeLimitScope
- Parameters:
scope
- The scope in which the time limit will be enforced
-
getBatchLimit
int getBatchLimit() -
getDataSizeLimit
long getDataSizeLimit() -
getTimeLimit
long getTimeLimit() -
checkBatchLimit
- 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
- 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
- Parameters:
checkerScope
- The scope that the limit is being checked from. The time limit is always checked againstEnvironmentEdgeManager.currentTime
- Returns:
- true when the limit is enforceable from the checker's scope and it has been reached
-
checkAnyLimitReached
- 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
-
setLastPeekedCell
-
returnImmediately
void returnImmediately() -
toString
-
newBuilder
-
newBuilder
-