ScannerContext (Apache HBase 1.2.12 API)

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)`

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.
`(package private) ScannerContext.LimitFields`	`limits` Two sets of the same fields.
`private static org.apache.commons.logging.Log`	`LOG`
`(package private) ServerSideScanMetrics`	`metrics` Tracks the relevant server side metrics during scans.
`(package private) ScannerContext.LimitFields`	`progress`
`(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)

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

Method Summary

Methods
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) boolean`	`getKeepProgress()`
`(package private) ServerSideScanMetrics`	`getMetrics()` Get the metrics instance.
`(package private) long`	`getSizeLimit()`
`(package private) long`	`getSizeProgress()`
`(package private) long`	`getTimeLimit()`
`(package private) long`	`getTimeProgress()`
`(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 size)` Progress towards the size limit has been made.
`(package private) boolean`	`isTrackingMetrics()`
`(package private) boolean`	`midRowResultFormed()`
`static ScannerContext.Builder`	`newBuilder()`
`static ScannerContext.Builder`	`newBuilder(boolean keepProgress)`
`(package private) boolean`	`partialResultFormed()`
`(package private) void`	`setBatchProgress(int batchProgress)`
`(package private) void`	`setKeepProgress(boolean keepProgress)`
`(package private) void`	`setProgress(int batchProgress, long sizeProgress, long timeProgress)`
`(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 sizeProgress)`
`(package private) void`	`setTimeLimitScope(ScannerContext.LimitScope scope)`
`(package private) void`	`setTimeProgress(long timeProgress)`
`String`	`toString()`
`(package private) void`	`updateTimeProgress()` Update the time progress with `System.currentTimeMillis()`

Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait

- Field Detail
  - LOG
```
private static final org.apache.commons.logging.Log LOG
```
  - limits
```
ScannerContext.LimitFields limits
```
    Two sets of the same fields. One for the limits, another for the progress towards those limits
  - progress
```
ScannerContext.LimitFields progress
```
  - 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 results = new ArrayList();
 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
```
  - 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
```
boolean isTrackingMetrics()
```
  - getMetrics
```
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 size)
```
    Progress towards the size limit has been made. Increment internal tracking of size progress
  - updateTimeProgress
```
void updateTimeProgress()
```
    Update the time progress with System.currentTimeMillis()
  - getBatchProgress
```
int getBatchProgress()
```
  - getSizeProgress
```
long getSizeProgress()
```
  - getTimeProgress
```
long getTimeProgress()
```
  - setProgress
```
void setProgress(int batchProgress,
               long sizeProgress,
               long timeProgress)
```
  - setSizeProgress
```
void setSizeProgress(long sizeProgress)
```
  - setBatchProgress
```
void setBatchProgress(int batchProgress)
```
  - setTimeProgress
```
void setTimeProgress(long timeProgress)
```
  - 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.
  - partialResultFormed
```
boolean partialResultFormed()
```
    Returns:
    true when a partial result is formed. A partial result is formed when a limit is reached in the middle of a row.
  - midRowResultFormed
```
boolean midRowResultFormed()
```
    Returns:
    true when a mid-row result is formed.
  - 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()
```
  - getSizeLimit
```
long getSizeLimit()
```
  - 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
  - toString
```
public String toString()
```
    Overrides:
    
    toString in class Object
  - newBuilder
```
public static ScannerContext.Builder newBuilder()
```
  - newBuilder
```
public static ScannerContext.Builder newBuilder(boolean keepProgress)
```

Class ScannerContext

Nested Class Summary

Field Summary

Constructor Summary

Method Summary

Methods inherited from class java.lang.Object

Field Detail

LOG

limits

progress

scannerState

DEFAULT_STATE

keepProgress

DEFAULT_KEEP_PROGRESS

metrics

Constructor Detail

ScannerContext

Method Detail

isTrackingMetrics

getMetrics

getKeepProgress

setKeepProgress

incrementBatchProgress

incrementSizeProgress

updateTimeProgress

getBatchProgress

getSizeProgress

getTimeProgress

setProgress

setSizeProgress

setBatchProgress

setTimeProgress

clearProgress

setScannerState

partialResultFormed

midRowResultFormed

hasBatchLimit

hasSizeLimit

hasTimeLimit

hasAnyLimit

setSizeLimitScope

setTimeLimitScope

getBatchLimit

getSizeLimit

getTimeLimit

checkBatchLimit

checkSizeLimit

checkTimeLimit

checkAnyLimitReached

toString

newBuilder

newBuilder