ptolemy.actor.ptalon.lib
Class SplitReader

java.lang.Object
  ptolemy.kernel.util.NamedObj
      ptolemy.kernel.InstantiableNamedObj
          ptolemy.kernel.Entity
              ptolemy.kernel.ComponentEntity
                  ptolemy.actor.AtomicActor
                      ptolemy.actor.TypedAtomicActor
                          ptolemy.actor.lib.Source
                              ptolemy.actor.ptalon.lib.SplitReader

All Implemented Interfaces:

java.io.Serializable, java.lang.Cloneable, Actor, Executable, FiringsRecordable, Initializable, TypedActor, Changeable, Debuggable, DebugListener, Derivable, Instantiable, ModelErrorHandler, MoMLExportable, Moveable, Nameable

public class SplitReader
extends Source

Read a file a file or URL, one line at a time, and output each line as a string. This actor has multiple outputs, and emits blocks of lines to each output at each firing, splitting the lines as chuncks of data for distributed processing.

The file or URL is specified using any form acceptable to FileParameter. Before an end of file is reached, the endOfFile output produces false. The blockSize and numberOfOutputs parameters determine how many lines are written to each output on each firing, and how many outputs to write to. If both of these are set to 1, this actor behaves exactly like the LineReader actor. In the iteration where the last line of the file is read and produced on an output port channel, this actor produces true on the endOfFile port. In that iteration, postfire() returns false. If the actor is iterated again, after the end of file, then prefire() and postfire() will both return false, output will produce the string "EOF", and endOfFile will produce true.

In some domains (such as SDF), returning false in postfire() causes the model to cease executing. In other domains (such as DE), this causes the director to avoid further firings of this actor. So usually, the actor will not be invoked again after the end of file is reached.

This actor reads ahead in the file so that it can produce an output true on endOfFile in the same iteration where it outputs the last line. It reads the first line in preinitialize(), and subsequently reads a new line in each invocation of postfire(). The line read is produced on the output in the next iteration after it is read.

This actor can skip some lines at the beginning of the file or URL, with the number specified by the numberOfLinesToSkip parameter. The default value of this parameter is 0.

If you need to reset this line reader to start again at the beginning of the file, the way to do this is to call initialize() during the run of the model. This can be done, for example, using a modal model with a transition where reset is enabled.

Since:

Ptolemy II 6.1

Version:

$Id: SplitReader.java 57040 2010-01-27 20:52:32Z cxh $

Author:

Adam Cataldo

See Also:

LineReader, Serialized Form

Accepted Rating:

Red (cxh)

Proposed Rating:

Red (cxh)

Nested Class Summary

Nested classes/interfaces inherited from class ptolemy.kernel.Entity

Entity.ContainedObjectsIterator

Field Summary

protected java.lang.String[][]	_currentLines Cache of most recently read data.
private boolean	_firedSinceWrapup Indicator that the fire() method has been called, but wrapup has not.
private java.lang.String	_previousFileOrURL Previous value of fileOrURL parameter.
private boolean	_reachedEOF Indicator that we have reached the end of file.
protected java.io.BufferedReader	_reader The current reader for the input file.
Parameter	blockSize This number of lines to output to each port when this actor is fired.
TypedIOPort	endOfFile An output port that produces false until the end of file is reached, at which point it produces true.
FileParameter	fileOrURL The file name or URL from which to read.
Parameter	numberOfLinesToSkip The number of lines to skip at the beginning of the file or URL.
Parameter	numberOfOutputs The number of output actors to write to.

Fields inherited from class ptolemy.actor.lib.Source

output, trigger

Fields inherited from class ptolemy.actor.AtomicActor

_actorFiringListeners, _initializables, _notifyingActorFiring, _stopRequested

Fields inherited from class ptolemy.kernel.util.NamedObj

_changeListeners, _changeLock, _changeRequests, _debugging, _debugListeners, _elementName, _isPersistent, _verbose, _workspace, ATTRIBUTES, CLASSNAME, COMPLETE, CONTENTS, DEEP, FULLNAME, LINKS

Fields inherited from interface ptolemy.actor.Executable

COMPLETED, NOT_READY, STOP_ITERATING

Constructor Summary

SplitReader(CompositeEntity container, java.lang.String name)
Construct an actor with the given container and name.

Method Summary

private void	_openAndReadFirstLine() Open the file and read the first line.
void	attributeChanged(Attribute attribute) If the specified attribute is fileOrURL and there is an open file being read, then close that file and open the new one; if the attribute is numberOfLinesToSkip and its value is negative, then throw an exception.
java.lang.Object	clone(Workspace workspace) Clone the actor into the specified workspace.
void	fire() Output the data read in the preinitialize() or in the previous invocation of postfire(), if there is any.
void	initialize() If this is called after prefire() has been called but before wrapup() has been called, then close any open file re-open it, skip the number of lines given by the numberOfLinesToSkip parameter, and read the first line to be produced in the next invocation of prefire().
boolean	postfire() Read the next line from the file.
boolean	prefire() Return false if there is no more data available in the file.
void	preinitialize() Open the file or URL, skip the number of lines specified by the numberOfLinesToSkip parameter, and read the first line to be sent out in the fire() method.
void	wrapup() Close the reader if there is one.

Methods inherited from class ptolemy.actor.TypedAtomicActor

_addPort, _fireAt, _fireAt, attributeTypeChanged, clone, newPort, typeConstraintList, typeConstraints

Methods inherited from class ptolemy.actor.AtomicActor

_actorFiring, _actorFiring, addActorFiringListener, addInitializable, connectionsChanged, createReceivers, declareDelayDependency, getCausalityInterface, getDirector, getExecutiveDirector, getManager, inputPortList, isFireFunctional, isStrict, iterate, newReceiver, outputPortList, pruneDependencies, recordFiring, removeActorFiringListener, removeDependency, removeInitializable, setContainer, stop, stopFire, terminate

Methods inherited from class ptolemy.kernel.ComponentEntity

_adjustDeferrals, _checkContainer, _getContainedObject, _propagateExistence, getContainer, instantiate, isAtomic, isOpaque, moveDown, moveToFirst, moveToIndex, moveToLast, moveUp, propagateExistence, setName

Methods inherited from class ptolemy.kernel.Entity

_description, _exportMoMLContents, _removePort, _validateSettables, connectedPortList, connectedPorts, containedObjectsIterator, getAttribute, getPort, getPorts, linkedRelationList, linkedRelations, portList, removeAllPorts, setClassDefinition, uniqueName

Methods inherited from class ptolemy.kernel.InstantiableNamedObj

_setParent, exportMoML, getChildren, getElementName, getParent, getPrototypeList, isClassDefinition, isWithinClassDefinition

Methods inherited from class ptolemy.kernel.util.NamedObj

_addAttribute, _adjustOverride, _attachText, _cloneFixAttributeFields, _debug, _debug, _debug, _debug, _debug, _getIndentPrefix, _isMoMLSuppressed, _markContentsDerived, _propagateValue, _recordDecoratedAttributes, _removeAttribute, _splitName, _stripNumericSuffix, addChangeListener, addDebugListener, attributeList, attributeList, deepContains, depthInHierarchy, description, description, event, executeChangeRequests, exportMoML, exportMoML, exportMoML, exportMoML, exportMoMLPlain, getAttribute, getAttributes, getChangeListeners, getClassName, getDecoratorAttribute, getDecoratorAttributes, getDerivedLevel, getDerivedList, getDisplayName, getFullName, getModelErrorHandler, getName, getName, getSource, handleModelError, isDeferringChangeRequests, isOverridden, isPersistent, lazyContainedObjectsIterator, message, propagateValue, propagateValues, removeChangeListener, removeDebugListener, requestChange, setClassName, setDeferringChangeRequests, setDerivedLevel, setDisplayName, setModelErrorHandler, setPersistent, setSource, sortContainedObjects, toplevel, toString, validateSettables, workspace

Methods inherited from class java.lang.Object

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

Methods inherited from interface ptolemy.actor.Actor

createReceivers, getCausalityInterface, getDirector, getExecutiveDirector, getManager, inputPortList, newReceiver, outputPortList

Methods inherited from interface ptolemy.actor.Executable

isFireFunctional, isStrict, iterate, stop, stopFire, terminate

Methods inherited from interface ptolemy.actor.Initializable

addInitializable, removeInitializable

Methods inherited from interface ptolemy.kernel.util.Nameable

description, getContainer, getDisplayName, getFullName, getName, getName, setName

Methods inherited from interface ptolemy.kernel.util.Derivable

getDerivedLevel, getDerivedList, propagateValue

Field Detail

blockSize

public Parameter blockSize

This number of lines to output to each port when this actor is fired.

endOfFile

public TypedIOPort endOfFile

An output port that produces false until the end of file is reached, at which point it produces true. The type is boolean.

fileOrURL

public FileParameter fileOrURL

The file name or URL from which to read. This is a string with any form accepted by FileParameter.

See Also:

FileParameter

numberOfLinesToSkip

public Parameter numberOfLinesToSkip

The number of lines to skip at the beginning of the file or URL. This parameter contains an IntToken, initially with value 0. The value of this parameter must be non-negative.

numberOfOutputs

public Parameter numberOfOutputs

The number of output actors to write to. This parameter contains an IntToken, initially with value 1. The value must be greater than zero.

_currentLines

protected java.lang.String[][] _currentLines

Cache of most recently read data.

_reader

protected java.io.BufferedReader _reader

The current reader for the input file.

_firedSinceWrapup

private boolean _firedSinceWrapup

Indicator that the fire() method has been called, but wrapup has not. That is, we are in the middle of a run.

_previousFileOrURL

private java.lang.String _previousFileOrURL

Previous value of fileOrURL parameter.

_reachedEOF

private boolean _reachedEOF

Indicator that we have reached the end of file.

Constructor Detail

SplitReader

public SplitReader(CompositeEntity container,
                   java.lang.String name)
            throws IllegalActionException,
                   NameDuplicationException

Construct an actor with the given container and name.

Parameters:

container - The container.

name - The name of this actor.

Throws:

IllegalActionException - If the actor cannot be contained by the proposed container.

NameDuplicationException - If the container already has an actor with this name.

Method Detail

attributeChanged

public void attributeChanged(Attribute attribute)
                      throws IllegalActionException

If the specified attribute is fileOrURL and there is an open file being read, then close that file and open the new one; if the attribute is numberOfLinesToSkip and its value is negative, then throw an exception. In the case of fileOrURL, do nothing if the file name is the same as the previous value of this attribute.

Overrides:

attributeChanged in class NamedObj

Parameters:

attribute - The attribute that has changed.

Throws:

IllegalActionException - If the specified attribute is fileOrURL and the file cannot be opened, or the previously opened file cannot be closed; or if the attribute is numberOfLinesToSkip and its value is negative.

clone

public java.lang.Object clone(Workspace workspace)
                       throws java.lang.CloneNotSupportedException

Clone the actor into the specified workspace.

Overrides:

clone in class AtomicActor

Parameters:

workspace - The workspace for the new object.

Returns:

A new actor.

Throws:

java.lang.CloneNotSupportedException - If a derived class contains an attribute that cannot be cloned.

See Also:

NamedObj.exportMoML(Writer, int, String), NamedObj.setDeferringChangeRequests(boolean)

fire

public void fire()
          throws IllegalActionException

Output the data read in the preinitialize() or in the previous invocation of postfire(), if there is any.

Specified by:

fire in interface Executable

Overrides:

fire in class Source

Throws:

IllegalActionException - If there's no director.

initialize

public void initialize()
                throws IllegalActionException

If this is called after prefire() has been called but before wrapup() has been called, then close any open file re-open it, skip the number of lines given by the numberOfLinesToSkip parameter, and read the first line to be produced in the next invocation of prefire(). This occurs if this actor is re-initialized during a run of the model.

Specified by:

initialize in interface Initializable

Overrides:

initialize in class AtomicActor

Throws:

IllegalActionException - If the file or URL cannot be opened, or if the lines to be skipped and the first line to be sent out in the fire() method cannot be read.

postfire

public boolean postfire()
                 throws IllegalActionException

Read the next line from the file. If there is no next line, return false. Otherwise, return whatever the superclass returns.

Specified by:

postfire in interface Executable

Overrides:

postfire in class AtomicActor

Returns:

True if execution can continue into the next iteration.

Throws:

IllegalActionException - If there is a problem reading the file.

prefire

public boolean prefire()
                throws IllegalActionException

Return false if there is no more data available in the file. Otherwise, return whatever the superclass returns.

Specified by:

prefire in interface Executable

Overrides:

prefire in class Source

Returns:

True, unless the trigger input is connected and has no input.

Throws:

IllegalActionException - If the superclass throws it.

preinitialize

public void preinitialize()
                   throws IllegalActionException

Open the file or URL, skip the number of lines specified by the numberOfLinesToSkip parameter, and read the first line to be sent out in the fire() method. This is done in preinitialize() so that derived classes can extract information from the file that affects information used in type resolution or scheduling.

Specified by:

preinitialize in interface Initializable

Overrides:

preinitialize in class AtomicActor

Throws:

IllegalActionException - If the file or URL cannot be opened, or if the lines to be skipped and the first line to be sent out in the fire() method cannot be read.

wrapup

public void wrapup()
            throws IllegalActionException

Close the reader if there is one.

Specified by:

wrapup in interface Initializable

Overrides:

wrapup in class AtomicActor

Throws:

IllegalActionException - If an IO error occurs.

_openAndReadFirstLine

private void _openAndReadFirstLine()
                            throws IllegalActionException

Open the file and read the first line.

Throws:

IllegalActionException