com.yahoo.documentapi

Class VisitorControlHandler

java.lang.Object

com.yahoo.documentapi.VisitorControlHandler

public class VisitorControlHandler
extends Object

A class for controlling a visitor supplied through visitor parameters when creating the visitor session. The class defines callbacks for reporting progress and that the visitor is done. If you want to reimplement the default behavior of those callbacks, you can write your own subclass.

Author:

Håkon Humberset

Nested Class Summary

Nested Classes

Modifier and Type	Class and Description
static class	VisitorControlHandler.CompletionCode Possible completion codes for visiting.
class	VisitorControlHandler.Result The result of the visitor, containing a completion code and an optional error message.

Field Summary

Fields

Modifier and Type	Field and Description
private boolean	completed
private ProgressToken	currentProgress
private com.yahoo.vdslib.VisitorStatistics	currentStatistics
private VisitorControlHandler.Result	result
private VisitorControlSession	session

Constructor Summary

Constructors

Constructor and Description
VisitorControlHandler()

Method Summary

Modifier and Type	Method and Description
void	abort() Abort this visitor
ProgressToken	getProgress()
VisitorControlHandler.Result	getResult()
com.yahoo.vdslib.VisitorStatistics	getVisitorStatistics()
boolean	hasVisitedAnyBuckets() Returns true iff the statistics reported by the visiting session indicates at least one bucket has been completely visited.
boolean	isDone()
void	onDone(VisitorControlHandler.CompletionCode code, String message) Callback called when the visitor is done.
void	onProgress(ProgressToken token) Callback called when progress has changed.
void	onVisitorError(String message) Callback for visitor error messages.
void	onVisitorStatistics(com.yahoo.vdslib.VisitorStatistics vs) Callback for visitor statistics updates.
void	reset() Called before the visitor starts.
void	setSession(VisitorControlSession session)
void	waitUntilDone() Waits until visiting is done.
boolean	waitUntilDone(Duration timeout) Waits until visiting is done, or the given timeout (in ms) expires.
boolean	waitUntilDone(long timeoutMs) Waits until visiting is done, or the given timeout (in ms) expires.

Methods inherited from class java.lang.Object

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

Field Detail

session

private VisitorControlSession session

currentProgress

private ProgressToken currentProgress

completed

private boolean completed

result

private VisitorControlHandler.Result result

currentStatistics

private com.yahoo.vdslib.VisitorStatistics currentStatistics

Constructor Detail

VisitorControlHandler

public VisitorControlHandler()

Method Detail

reset

public void reset()

Called before the visitor starts. Override this method if you need to reset local data. Remember to call the superclass' method as well.

onProgress

public void onProgress(ProgressToken token)

Callback called when progress has changed.

Parameters:

token - the most recent progress token for this visitor

onVisitorError

public void onVisitorError(String message)

Callback for visitor error messages.

Parameters:

message - the error message

onVisitorStatistics

public void onVisitorStatistics(com.yahoo.vdslib.VisitorStatistics vs)

Callback for visitor statistics updates.

Parameters:

vs - The current statistics for this visitor.

hasVisitedAnyBuckets

public boolean hasVisitedAnyBuckets()

Returns true iff the statistics reported by the visiting session indicates at least one bucket has been completely visited. Not thread safe, so should only be called on a quiescent session after waitUntilDone has completed successfully.

onDone

public void onDone(VisitorControlHandler.CompletionCode code,
                   String message)

Callback called when the visitor is done.

Parameters:

code - the completion code

message - an optional error message

setSession

public void setSession(VisitorControlSession session)

Parameters:

session - the visitor session used for this visitor

getProgress

public ProgressToken getProgress()

Returns:

Retrieves the last progress token gotten for this visitor. If visitor has not been started, returns null.

getVisitorStatistics

public com.yahoo.vdslib.VisitorStatistics getVisitorStatistics()

isDone

public boolean isDone()

Returns:

True if the visiting is done (either by error or success).

waitUntilDone

public boolean waitUntilDone(Duration timeout)
                      throws InterruptedException

Waits until visiting is done, or the given timeout (in ms) expires. Will wait forever if timeout is 0.

Parameters:

timeout - Maximum time duration to wait before returning.

Returns:

True if visiting is done (either by error or success), false if session has timed out.

Throws:

InterruptedException - If an interrupt signal was received while waiting.

waitUntilDone

public boolean waitUntilDone(long timeoutMs)
                      throws InterruptedException

Waits until visiting is done, or the given timeout (in ms) expires. Will wait forever if timeout is 0.

Parameters:

timeoutMs - The maximum amount of milliseconds to wait.

Returns:

True if visiting is done (either by error or success), false if session has timed out.

Throws:

InterruptedException - If an interrupt signal was received while waiting. TODO deprecate this in favor of waitUntilDone(Duration)

waitUntilDone

public void waitUntilDone()
                   throws InterruptedException

Waits until visiting is done. Session timeout implicitly completes the visitor session, but will set an unsuccessful result code.

Throws:

InterruptedException - If an interrupt signal was received while waiting.

abort

public void abort()

Abort this visitor

getResult

public VisitorControlHandler.Result getResult()

Returns:

The result of the visiting, if done. If not done, returns null.