org.freehep.record.loop

Interface RecordLoop

All Known Implementing Classes:

ConcurrentRecordLoop, DefaultRecordLoop

public interface RecordLoop

Manages fetching records from RecordSource and supplying them to consumers. To obtain information on the current state of this loop, users should normally create a loop snapshot through a call to getProgress() (unless an instance of LoopEvent created at a relevant moment is already available), then use LoopEvent getters. For legacy code compatibility, RecordLoop also provides direct access to individual state variables through isInterruptRequested(), getSupplied(), getTotalSupplied(), getConsumed(), getTotalConsumed(), getCountableConsumed(), and getTotalCountableConsumed() methods. A record is considered "supplied" as soon as it has been fetched from RecordSource. A record is considered "consumed" as soon as recordSupplied(RecordEvent event) methods of all registered RecordListeners have returned. If doNotCount(record) of this loop is called between the moment the specified record was supplied and the moment it was consumed, that record is not considered "countable".

Version:

$Id$

Author:

Dmitry Onoprienko

Nested Class Summary

Nested Classes

Modifier and Type	Interface and Description
static class	RecordLoop.Command Enumeration of commands that can be issued to this loop by users.
static class	RecordLoop.Event Enumeration of LoopEvent types that can be fired by this loop.
static class	RecordLoop.State Enumeration of states of this loop.

Method Summary

Methods

Modifier and Type	Method and Description
void	addLoopListener(LoopListener listener) Adds a listener that will be receiving LoopEvents fired by this loop.
void	addRecordListener(RecordListener listener) Adds a listener that will be processing records supplied by this loop.
void	dispose() Release all resources owned by this loop.
boolean	doNotCount(Object record) If the specified record is being currently supplied to listeners, tells this loop not to count it towards the number of records that will be reported by getTotalCountableSupplied().
void	execute(RecordLoop.Command command, Object... parameters) Executes the specified command on this loop.
long	getConsumed() Returns the number of records consumed by listeners in the latest LOOPING phase, or zero the loop moved through IDLE state since then.
long	getCountableConsumed() Returns the number of countable records consumed by listeners in the latest LOOPING phase, or zero the loop moved through IDLE state since then.
Object	getLastRecord() Returns the last record fetched by this loop from the record source.
List<LoopListener>	getLoopListeners() Returns an unmodifiable list of listeners receiving LoopEvents fired by this loop.
LoopEvent	getProgress() Creates and returns PROGRESS event describing the current state of this record loop.
List<RecordListener>	getRecordListeners() Returns an unmodifiable list of listeners processing records supplied by this loop.
RecordSource	getRecordSource() Returns RecordSource used by this loop.
RecordLoop.State	getState() Returns the current state of this loop.
long	getSupplied() Returns the number of records supplied to listeners in the latest LOOPING phase, or zero the loop moved through IDLE state since then.
long	getTotalConsumed() Returns the number of records consumed by listeners since the last START event.
long	getTotalCountableConsumed() Returns the number of countable records consumed by listeners since the last START event.
long	getTotalSupplied() Returns the number of records supplied to listeners since the last START event.
boolean	isEnabled(RecordLoop.Command command, Object... parameters) Returns true if the specified command is enabled in the current state of this loop, and a call to execute(command, parameters) might succeed.
boolean	isInterruptRequested() Returns the current value of the "interrupt requested" flag.
void	removeLoopListener(LoopListener listener) Removes the listener receiving LoopEvents fired by this loop.
void	removeRecordListener(RecordListener listener) Removes the listener processing records supplied by this loop.
void	setConfiguration(Object config) Supplies an object used to configure this loop.
void	setProgressByRecords(long numberOfRecords) Sets progress reporting interval.
void	setProgressByTime(long milliseconds) Sets progress reporting interval.
void	setRecordSource(RecordSource source) Sets RecordSource used by this loop.

Method Detail

addRecordListener

void addRecordListener(RecordListener listener)

Adds a listener that will be processing records supplied by this loop.

removeRecordListener

void removeRecordListener(RecordListener listener)

Removes the listener processing records supplied by this loop.

getRecordListeners

List<RecordListener> getRecordListeners()

Returns an unmodifiable list of listeners processing records supplied by this loop.

addLoopListener

void addLoopListener(LoopListener listener)

Adds a listener that will be receiving LoopEvents fired by this loop.

removeLoopListener

void removeLoopListener(LoopListener listener)

Removes the listener receiving LoopEvents fired by this loop.

getLoopListeners

List<LoopListener> getLoopListeners()

Returns an unmodifiable list of listeners receiving LoopEvents fired by this loop.

isEnabled

boolean isEnabled(RecordLoop.Command command,
                Object... parameters)

Returns true if the specified command is enabled in the current state of this loop, and a call to execute(command, parameters) might succeed. If called without parameters, returns true if the call might succeed with at least some parameters. See execute(Command, Object...) for the description of parameters used by different commands.

Since not all RecordSource implementations are able to figure out whether retrieving the requested record is possible before trying it, the fact that this method returned true does not exclude the possibility of failure of the subsequent call to execute(command, parameters).

getRecordSource

RecordSource getRecordSource()

Returns RecordSource used by this loop.

getProgress

LoopEvent getProgress()

Creates and returns PROGRESS event describing the current state of this record loop. This method should be used in preference to individual convenience getters (isInterruptRequested(), getSupplied(), getTotalSupplied(), getConsumed(), getTotalConsumed(), getCountableConsumed(), getTotalCountableConsumed()) since it provides a snapshot of this loop in a consistent state.

getState

RecordLoop.State getState()

Returns the current state of this loop.

isInterruptRequested

boolean isInterruptRequested()

Returns the current value of the "interrupt requested" flag.

getSupplied

long getSupplied()

Returns the number of records supplied to listeners in the latest LOOPING phase, or zero the loop moved through IDLE state since then.

getTotalSupplied

long getTotalSupplied()

Returns the number of records supplied to listeners since the last START event.

getConsumed

long getConsumed()

Returns the number of records consumed by listeners in the latest LOOPING phase, or zero the loop moved through IDLE state since then.

getTotalConsumed

long getTotalConsumed()

Returns the number of records consumed by listeners since the last START event.

getCountableConsumed

long getCountableConsumed()

Returns the number of countable records consumed by listeners in the latest LOOPING phase, or zero the loop moved through IDLE state since then.

getTotalCountableConsumed

long getTotalCountableConsumed()

Returns the number of countable records consumed by listeners since the last START event.

getLastRecord

Object getLastRecord()

Returns the last record fetched by this loop from the record source. Returns null in no records have been fetched since the last START event, or if the last record is no longer available.

setProgressByRecords

void setProgressByRecords(long numberOfRecords)

Sets progress reporting interval. PROGRESS event will be fired every numberOfRecords records when looping. Setting the interval to zero means no reporting based on the number of records processed.

setProgressByTime

void setProgressByTime(long milliseconds)

Sets progress reporting interval. PROGRESS event will be fired every milliseconds milliseconds when looping. Setting the interval to zero means no reporting based on time elapsed.

setConfiguration

void setConfiguration(Object config)

Supplies an object used to configure this loop. CONFIGURE event is fired once configuration is complete.

Throws:

IllegalStateException - if this loop is in LOOPING state.

setRecordSource

void setRecordSource(RecordSource source)

Sets RecordSource used by this loop. CONFIGURE event is fired once the source has been set.

Throws:

IllegalStateException - if this loop is in LOOPING state.

execute

void execute(RecordLoop.Command command,
           Object... parameters)

Executes the specified command on this loop.

Commands:

Command	Parameters	Action	Enabled when
REWIND	[boolean stop]	Rewind the record source. If stop is true and the current state is READY, this loop goes to IDLE state before rewinding the source.	IDLE, READY
PREVIOUS		Supply the previous record from the record source to listeners.	IDLE, READY
PAUSE		Requests pause in event processing. No new records will be fetched from the source; once those already fetched are processed, this loop moves to READY state.	LOOPING
NEXT		Supply the next record from the record source to listeners.	IDLE, READY
GO_N	[int nRecords, boolean stop]	Supply the next nRecords records from the source to listeners. If stop is true, this loop goes to IDLE state once the specified number of records is processed (or the end of source is reached. Otherwise, the loop remaines in READY state.	IDLE, READY
GO	[boolean stop]	Supply records to listeners until the end of the source is reached. If stop is true, this loop goes to IDLE state once all remaining records in the source are processed. Otherwise, the loop remaines in READY state.	IDLE, READY
JUMP	[RecordTag tag] [false, int index] [true, int offset]	Supply the specified record to listeners. If the first parameter is false, the second parameter is interpreted as an absolute index of the requested record. If the first parameter is true, the second parameter is interpreted as an offset with respect to the current record.	IDLE, READY
REFRESH		Reload the current record from the source and supply it to listeners.	IDLE, READY
STOP		Request interrupt if in LOOPING; once interrupted, moves to IDLE state	IDLE, READY, LOOPING
CONFIG	[Object config]	Set loop configuration	IDLE, READY
SET_SOURCE	[RecordSource source]	Set record source	IDLE, READY

Depending on implementation, this method might block until command execution is finished, or it might launch the command and return immediately.

If any of the commands that supply records to listeners attempts to load a non-existing record, an instance of NoSuchRecordException thrown by the source will be reported by SUSPEND and FINISH events fired by this loop at the end of the command execution, and will remain referenced by this loop until the next command is issued. It can be retrieved by calling getProgress().getException(). IOException thrown by the source while retrieving a record is handled in the same way.

The handling of all other types of unchecked exceptions thrown by the source or by listeners is implementation dependent.

Throws:

IllegalStateException - if the specified command cannot be executed by this loop in its current state.

doNotCount

boolean doNotCount(Object record)

If the specified record is being currently supplied to listeners, tells this loop not to count it towards the number of records that will be reported by getTotalCountableSupplied().

Returns:

true if the call resulted in the specified record being excluded from counting.

dispose

void dispose()

Release all resources owned by this loop. The loop cannot be used once this method has been called.