org.freehep.record.loop
Interface SequentialRecordLoop

All Superinterfaces:

RecordListenerManager

All Known Implementing Classes:

SequentialRecordLoopImpl

public interface SequentialRecordLoop

extends RecordListenerManager

This interface defines the methods available to any framework which wishes to make used of a sequential record loop.

The basic premise of this interface is that when the "loop" method is invoked each record that is supplied by this object's SequentialRecordSource is passed to its RecordListener using its recordSupplied event.

This class has a standard add/removed mechanism for handling a single RecordListener. Only one RecordListener can be registered at a time as this avoids any implementation of this interface enacting an ordering policy that may not match that expected by its client. A Client can impose an ordering policy by providing a suitable RecordListener implementation which passes the RecordEvents it receives onto other RecordListeners. SequentialAnalysis and ThreePhaseAnalysis are two examples of such a class.

The loop(long) method of this class will processes the specified number of "countable" records. By default all records are countable, however if the doNotCount(java.lang.Object) method is called and its argument is a record that is currently being supplied by this class then that record will not count toward the requested number of records, not will it contribute to the return value of the loop method.

This looping can be interrupted by using the setInterruptRequested(boolean) method to set the appropriate flag to true. This will cause the loop to terminate once all data with which it is dealing has been handled. It is important to realize that simply interrupting a loop does not directly terminate any processing that is already underway, it just stops new records from being requested. This means that if some part of the implementation of the recordSupplied listener method is waiting for something, such as networks access or a "next record" click from the user, the loop method will continue to block until that code completes. Any loop that is interrupted this way will throw a LoopInterruptedException even if all of the requested number of records have been handled.

Version:

$Id: SequentialRecordLoop.java,v 1.2 2004/01/19 21:23:51 duns Exp $

Author:

patton

Source Code:

SequentialRecordLoop.java

Method Summary

void	addRecordLoopListener(RecordLoopListener listener) Adds the specified RecordLoopListener to this object.
void	dispose() Signals that this object in no longer going to be used.
void	doNotCount(Object record) Tells this object that if it is currently supplying the specified record then it should not be added to the "countable" record total.
SequentialRecordSource	getRecordSource() Returns the SequentialRecordSource used by this object.
long	getTotalCountableSupplied() Returns the total number of countable records supplied.
long	getTotalSupplied() Returns the total number of records supplied.
boolean	isInterruptRequested() Returns true if an interrupt has been requested and the loop method has not yet returned.
long	loop(long number) Processes the specified number of records through the record loop.
void	removeRecordLoopListener(RecordLoopListener listener) Removes the specified listener from this object if it is this objects listener, otherwise it does nothing.
void	reset() Resets the loop so that the next time loop is called this object will behave as if the previous calls to loop never happened.
void	setConfiguration(Object configuration) Sets the configuration object which should be passed to this objects RecordListener next time the loop(long) method is invoked.
void	setInterruptRequested(boolean interruptRequested) This method can either request that the loop method terminate when it has finished dealing with all its current data or clear such a request.
void	setProgessByRecords(long records) Set the progress reporting interval in terms of records.
void	setProgessByTime(long milliseconds) Set the progress reporting interval in terms of milliseconds.
void	setRecordSource(SequentialRecordSource source) Sets this objects SequentialRecordSource to the one that is specified.

Methods inherited from interface org.freehep.record.loop.event.RecordListenerManager

addRecordListener, getRecordListener, removeRecordListener

Method Detail

addRecordLoopListener

public void addRecordLoopListener(RecordLoopListener listener)

Adds the specified RecordLoopListener to this object.

Parameters:

listener - the RecordLoopListener to add.

See Also:

removeRecordLoopListener(org.freehep.record.loop.event.RecordLoopListener)

doNotCount

public void doNotCount(Object record)

Tells this object that if it is currently supplying the specified record then it should not be added to the "countable" record total.

Parameters:

record - the recornd that should not be counted.

dispose

public void dispose()

Signals that this object in no longer going to be used. If this object has a RecordListener, then the listener is passed a finish event.

getRecordSource

public SequentialRecordSource getRecordSource()

Returns the SequentialRecordSource used by this object.

Returns:

the SequentialRecordSource used by this object.

getTotalSupplied

public long getTotalSupplied()

Returns the total number of records supplied.

Returns:

the total number of records supplied.

getTotalCountableSupplied

public long getTotalCountableSupplied()

Returns the total number of countable records supplied.

Returns:

the total number of countable records supplied.

isInterruptRequested

public boolean isInterruptRequested()

Returns true if an interrupt has been requested and the loop method has not yet returned. As the interrupt may come for another thread this method must always be implemented in a thread-safe manner.

Returns:

true if an interrupt has been requested and the loop method has not yet returned.

loop

public long loop(long number)
          throws LoopException,
                 IOException

Processes the specified number of records through the record loop. If the number of records is specified to be less than zero then the loop will continue until this objects SequentialRecordSource throws a LoopSourceExhaustedException respose to its getCurrentRecord method. If the doNotCount(java.lang.Object) method is called while this method is executing and its argument is a record that is currently being supplied by this object then that record will not count towards the specified number of records requested. Nor will it be counted in the return value of this method. If the loop is interrupted before it is completed then a LoopInterruptedException is thrown, even if the requested number of records have been supplied. The number of completed countable records is contained in the LoopInterruptedException so\ this value can be used to determine whether all requested records where supplied on not.

Parameters:

number - the number of countable records to supply.

Returns:

the number of countable records that have been supplied.

Throws:

LoopInterruptedException - if the loop ended due to an interruption being requested.

LoopSourceExhaustedException - if number is non-negative and the source runs out of records.

IllegalStateException - if this method is called before a setRecordSource is set.

IOException - if there is problems reading a record.

NoLoopRecordException - if the record to supply could not be found.

LoopException

removeRecordLoopListener

public void removeRecordLoopListener(RecordLoopListener listener)

Removes the specified listener from this object if it is this objects listener, otherwise it does nothing.

Parameters:

listener - the RecordLoopListener to remove.

See Also:

addRecordLoopListener(org.freehep.record.loop.event.RecordLoopListener)

reset

public void reset()
           throws IOException

Resets the loop so that the next time loop is called this object will behave as if the previous calls to loop never happened. This means that this object's SequentialRecordSource will have its rewing method called while the objects listener, if it exists, will be sent a finish event. At the next loop call the listener will receive a configure event rather than a reconfigure or resume event.

Throws:

IOException - if there is problems rewinding this object's source.

setConfiguration

public void setConfiguration(Object configuration)

Sets the configuration object which should be passed to this objects RecordListener next time the loop(long) method is invoked. If this method is called any time after the first loop invocation (even with the same configuration object) then a reconfigure event will be used to start the next loop. Otherwise the next loop will start with a resume event.

Parameters:

configuration - the configuration object to pass to this object's RecordListener.

setProgessByRecords

public void setProgessByRecords(long records)

Set the progress reporting interval in terms of records. This number is only a guideline to the the loop, which can choose to ignore it wishes. If the loop if it is observing both guidelines and the interval has been specified by both time and number of records, the interval which expired first should be the one used by the loop. If neither method has been used to specify an interval the the loop will use a sensible defaualt. A value of zero or less with effectively remove any guideline that has been set.

Parameters:

records - the number of records between progress reports.

setProgessByTime

public void setProgessByTime(long milliseconds)

Set the progress reporting interval in terms of milliseconds. This number is only a guideline to the the loop, which can choose to ignore it wishes. If the loop if it is observing both guidelines and the interval has been specified by both time and number of records, the interval which expired first should be the one used by the loop. If neither method has been used to specify an interval the the loop will use a sensible defaualt. A value of zero or less with effectively remove any guideline that has been set.

Parameters:

milliseconds - the number of milliseconds between progress reports.

setRecordSource

public void setRecordSource(SequentialRecordSource source)

Sets this objects SequentialRecordSource to the one that is specified. If this object already has a SequentialRecordSource it will be replaced by the new one.

Parameters:

source - the SequentialRecordSource to use with this object.

setInterruptRequested

public void setInterruptRequested(boolean interruptRequested)

This method can either request that the loop method terminate when it has finished dealing with all its current data or clear such a request. For a meaningful interrupt to happen it must come from a thread other than the one executing the loop method, therefore this method must always be implemented in a thread-safe manner.

Parameters:

interruptRequested - true if the loop should be interrupted.