org.freehep.record.loop

Class DefaultRecordLoop

java.lang.Object

org.freehep.record.loop.DefaultRecordLoop

All Implemented Interfaces:

RecordLoop

Direct Known Subclasses:

ConcurrentRecordLoop

public class DefaultRecordLoop
extends Object
implements RecordLoop

Default implementation of RecordLoop. If this class is used directly, records are fetched from the record source and supplied to listeners in a single thread. Subclasses may override some of the steps in command execution to enable concurrent processing. This class is mostly thread safe, with a few caveats :

• Loop logic assumes exclusive access to the record source. Moreover, many RecordSource implementations are not thread safe. Manipulating the record source directly while it is used by the DefaultRecordLoop may lead to unpredictable results.
• Code in RecordSource implementations should not call methods of DefaultRecordLoop that is using it.

Version:

$Id$

Author:

Dmitry Onoprienko

Nested Class Summary

Nested classes/interfaces inherited from interface org.freehep.record.loop.RecordLoop

RecordLoop.Command, RecordLoop.Event, RecordLoop.State

Constructor Summary

Constructors

Constructor and Description
DefaultRecordLoop()

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 referenced 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 successfully fetched by this loop from the record source.
List<LoopListener>	getLoopListeners() Returns a 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 a 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 true if the flag requesting stop or pause in the loop is set.
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.
void	setStopOnEOF(boolean stopOnEOF) Sets "stop on end-of-source" flag.
void	setStopOnRewind(boolean stopOnRewind) Sets "stop on rewind" flag.

Methods inherited from class java.lang.Object

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

Constructor Detail

DefaultRecordLoop

public DefaultRecordLoop()

Method Detail

addRecordListener

public void addRecordListener(RecordListener listener)

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

Specified by:

addRecordListener in interface RecordLoop

removeRecordListener

public void removeRecordListener(RecordListener listener)

Removes the listener processing records supplied by this loop.

Specified by:

removeRecordListener in interface RecordLoop

getRecordListeners

public List<RecordListener> getRecordListeners()

Returns a list of listeners processing records supplied by this loop.

Specified by:

getRecordListeners in interface RecordLoop

addLoopListener

public void addLoopListener(LoopListener listener)

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

Specified by:

addLoopListener in interface RecordLoop

removeLoopListener

public void removeLoopListener(LoopListener listener)

Removes the listener receiving LoopEvents fired by this loop.

Specified by:

removeLoopListener in interface RecordLoop

getLoopListeners

public List<LoopListener> getLoopListeners()

Returns a list of listeners receiving LoopEvents fired by this loop.

Specified by:

getLoopListeners in interface RecordLoop

isInterruptRequested

public boolean isInterruptRequested()

Returns true if the flag requesting stop or pause in the loop is set.

Specified by:

isInterruptRequested in interface RecordLoop

getRecordSource

public RecordSource getRecordSource()

Returns RecordSource used by this loop.

Specified by:

getRecordSource in interface RecordLoop

getProgress

public 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.

Specified by:

getProgress in interface RecordLoop

getState

public RecordLoop.State getState()

Returns the current state of this loop.

Specified by:

getState in interface RecordLoop

getSupplied

public 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.

Specified by:

getSupplied in interface RecordLoop

getTotalSupplied

public long getTotalSupplied()

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

Specified by:

getTotalSupplied in interface RecordLoop

getConsumed

public 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.

Specified by:

getConsumed in interface RecordLoop

getTotalConsumed

public long getTotalConsumed()

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

Specified by:

getTotalConsumed in interface RecordLoop

getCountableConsumed

public 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.

Specified by:

getCountableConsumed in interface RecordLoop

getTotalCountableConsumed

public long getTotalCountableConsumed()

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

Specified by:

getTotalCountableConsumed in interface RecordLoop

getLastRecord

public Object getLastRecord()

Returns the last record successfully fetched by this loop from the record source. Returns null in no records have been fetched since the last START event.

Specified by:

getLastRecord in interface RecordLoop

setRecordSource

public void setRecordSource(RecordSource source)

Sets RecordSource used by this loop. CONFIGURE event is fired once the source has been set. Equivalent to execute(SET_SOURCE, source).

Specified by:

setRecordSource in interface RecordLoop

Throws:

IllegalStateException - if this loop is in LOOPING state.

setConfiguration

public void setConfiguration(Object config)

Supplies an object used to configure this loop. CONFIGURE event is fired once configuration is complete. Equivalent to execute(CONFIG, config).

Specified by:

setConfiguration in interface RecordLoop

Throws:

IllegalStateException - if this loop is in LOOPING state.

setProgressByRecords

public void setProgressByRecords(long numberOfRecords)

Sets progress reporting interval. PROGRESS event will be fired every numberOfRecords records when looping. Setting the interval to zero (default) means no reporting.

Specified by:

setProgressByRecords in interface RecordLoop

setProgressByTime

public void setProgressByTime(long milliseconds)

Sets progress reporting interval. PROGRESS event will be fired every milliseconds milliseconds when looping. Setting the interval to zero (default) means no reporting.

Specified by:

setProgressByTime in interface RecordLoop

setStopOnRewind

public void setStopOnRewind(boolean stopOnRewind)

Sets "stop on rewind" flag. The flag affects default behavior of the REWIND command. If set to true (default), this loop will transition to IDLE before rewinding the source if REWIND command is issued while the loop is in READY state. FINISH event will be sent to LoopListeners during the transition.

setStopOnEOF

public void setStopOnEOF(boolean stopOnEOF)

Sets "stop on end-of-source" flag. The flag affects default behavior of the RecordLoop.Command.GO or RecordLoop.Command.GO_N commands. If set to true (default), this loop will transition to IDLE state (through READY) if the record source is exhausted while executing RecordLoop.Command.GO or RecordLoop.Command.GO_N commands. If set to false, the loop will pause in READY state.

doNotCount

public 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().

Specified by:

doNotCount in interface RecordLoop

Returns:

true if was marked for exclusion from counting as a result of this call.

dispose

public void dispose()

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

Specified by:

dispose in interface RecordLoop

isEnabled

public 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 RecordLoop.execute(Command, Object...) for the description of parameters used by different commands.

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

Specified by:

isEnabled in interface RecordLoop

execute

public 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. If the stop parameter is omitted, the value of the "stop on rewind" flag is used.	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. If the stop parameter is omitted, the value of the "stop on end-of-source" flag is used.	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. If the stop parameter is omitted, the value of the "stop on end-of-source" flag is used.	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

This method blocks until command execution is finished.

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 or UnsupportedOperationException thrown by the source while retrieving a record is handled in the same way.

All other types of unchecked exceptions thrown by the source or by listeners terminate the program (this behavior can be changed in subclasses by overriding handleClientError(Throwable) and handleSourceError methods).

The method acquires state lock briefly to check whether the command can be executed, and either rejects the command by throwing IllegalStateException, or launches the command and modifies the state accordingly. No alien code (including loop listener notifications) is called while the lock is held.

Specified by:

execute in interface RecordLoop

Throws:

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