ptolemy.actor.lib.io
Class LineReader

java.lang.Object
  extended byptolemy.kernel.util.NamedObj
      extended byptolemy.kernel.InstantiableNamedObj
          extended byptolemy.kernel.Entity
              extended byptolemy.kernel.ComponentEntity
                  extended byptolemy.actor.AtomicActor
                      extended byptolemy.actor.TypedAtomicActor
                          extended byptolemy.actor.lib.Source
                              extended byptolemy.actor.lib.io.LineReader
All Implemented Interfaces:
ptolemy.actor.Actor, ptolemy.kernel.util.Changeable, java.lang.Cloneable, ptolemy.kernel.util.Debuggable, ptolemy.kernel.util.DebugListener, ptolemy.kernel.util.Derivable, ptolemy.actor.Executable, ptolemy.kernel.util.Instantiable, ptolemy.kernel.util.ModelErrorHandler, ptolemy.kernel.util.MoMLExportable, ptolemy.kernel.util.Nameable, java.io.Serializable, ptolemy.actor.TypedActor
Direct Known Subclasses:
ExpressionReader

public class LineReader
extends Source

This actor reads a file or URL, one line at a time, and outputs each line as a string. The file or URL is specified using any form acceptable to FileParameter. Before an end of file is reached, the endOfFile output produces false. In the iteration where the last line of the file is read and produced on the output port, 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 2.2
Version:
$Id: LineReader.java,v 1.20 2004/04/13 03:07:10 cxh Exp $
Author:
Edward A. Lee, Yuhong Xiong
See Also:
FileParameter, Serialized Form
Accepted Rating:
Yellow (cxh)
Proposed Rating:
Green (eal)

Nested Class Summary
 
Nested classes inherited from class ptolemy.kernel.Entity
ptolemy.kernel.Entity.ContainedObjectsIterator
 
Field Summary
protected  java.lang.String _currentLine
          Cache of most recently read data.
protected  java.io.BufferedReader _reader
          The current reader for the input file.
 ptolemy.actor.TypedIOPort endOfFile
          An output port that produces false until the end of file is reached, at which point it produces true.
 ptolemy.data.expr.FileParameter fileOrURL
          The file name or URL from which to read.
 ptolemy.data.expr.Parameter numberOfLinesToSkip
          The number of lines to skip at the beginning of the file or URL.
 
Fields inherited from class ptolemy.actor.lib.Source
output, trigger
 
Fields inherited from class ptolemy.actor.AtomicActor
_stopRequested
 
Fields inherited from class ptolemy.kernel.util.NamedObj
_changeListeners, _changeLock, _changeRequests, _debugging, _debugListeners, _elementName, _isPersistent, _workspace, ATTRIBUTES, CLASSNAME, COMPLETE, CONTENTS, DEEP, FULLNAME, LINKS
 
Fields inherited from interface ptolemy.actor.Executable
COMPLETED, NOT_READY, STOP_ITERATING
 
Constructor Summary
LineReader(ptolemy.kernel.CompositeEntity container, java.lang.String name)
          Construct an actor with the given container and name.
 
Method Summary
 void attributeChanged(ptolemy.kernel.util.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(ptolemy.kernel.util.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, attributeTypeChanged, clone, newPort, typeConstraintList
 
Methods inherited from class ptolemy.actor.AtomicActor
_createReceivers, connectionsChanged, getDirector, getExecutiveDirector, getFunctionDependency, getManager, inputPortList, iterate, newReceiver, outputPortList, pruneDependencies, removeDependency, setContainer, stop, stopFire, terminate
 
Methods inherited from class ptolemy.kernel.ComponentEntity
_adjustDeferrals, _checkContainer, _getContainedObject, _propagateExistence, getContainer, instantiate, isAtomic, isOpaque, propagateExistence, setName
 
Methods inherited from class ptolemy.kernel.Entity
_description, _exportMoMLContents, _removePort, connectedPortList, connectedPorts, containedObjectsIterator, getAttribute, getPort, getPorts, linkedRelationList, linkedRelations, portList, removeAllPorts, setClassDefinition, uniqueName, validateSettables
 
Methods inherited from class ptolemy.kernel.InstantiableNamedObj
_setParent, exportMoML, getChildren, getElementName, getParent, getPrototypeList, isClassDefinition
 
Methods inherited from class ptolemy.kernel.util.NamedObj
_addAttribute, _attachText, _cloneFixAttributeFields, _debug, _debug, _debug, _debug, _debug, _getIndentPrefix, _isMoMLSuppressed, _markContentsDerived, _propagateValue, _removeAttribute, _splitName, _stripNumericSuffix, addChangeListener, addDebugListener, attributeList, attributeList, deepContains, depthInHierarchy, description, description, event, executeChangeRequests, exportMoML, exportMoML, exportMoML, exportMoML, getAttribute, getAttributes, getChangeListeners, getClassName, getDerivedLevel, getDerivedList, getFullName, getModelErrorHandler, getName, getName, getSource, handleModelError, isDeferringChangeRequests, isOverridden, isPersistent, message, propagateValue, propagateValues, removeChangeListener, removeDebugListener, requestChange, setClassName, setDeferringChangeRequests, setDerivedLevel, setModelErrorHandler, setPersistent, setSource, toplevel, toString, workspace
 
Methods inherited from class java.lang.Object
equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait
 
Methods inherited from interface ptolemy.actor.Actor
getDirector, getExecutiveDirector, getFunctionDependency, getManager, inputPortList, newReceiver, outputPortList
 
Methods inherited from interface ptolemy.actor.Executable
iterate, stop, stopFire, terminate
 
Methods inherited from interface ptolemy.kernel.util.Derivable
getDerivedLevel, getDerivedList, propagateValue
 
Methods inherited from interface ptolemy.kernel.util.Nameable
description, getFullName, getName, getName
 

Field Detail

endOfFile

public ptolemy.actor.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 ptolemy.data.expr.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 ptolemy.data.expr.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.


_currentLine

protected java.lang.String _currentLine
Cache of most recently read data.


_reader

protected java.io.BufferedReader _reader
The current reader for the input file.

Constructor Detail

LineReader

public LineReader(ptolemy.kernel.CompositeEntity container,
                  java.lang.String name)
           throws ptolemy.kernel.util.IllegalActionException,
                  ptolemy.kernel.util.NameDuplicationException
Construct an actor with the given container and name.

Parameters:
container - The container.
name - The name of this actor.
Throws:
ptolemy.kernel.util.IllegalActionException - If the actor cannot be contained by the proposed container.
ptolemy.kernel.util.NameDuplicationException - If the container already has an actor with this name.
Method Detail

attributeChanged

public void attributeChanged(ptolemy.kernel.util.Attribute attribute)
                      throws ptolemy.kernel.util.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.

Parameters:
attribute - The attribute that has changed.
Throws:
ptolemy.kernel.util.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(ptolemy.kernel.util.Workspace workspace)
                       throws java.lang.CloneNotSupportedException
Clone the actor into the specified workspace.

Returns:
A new actor.
Throws:
java.lang.CloneNotSupportedException - If a derived class contains an attribute that cannot be cloned.

fire

public void fire()
          throws ptolemy.kernel.util.IllegalActionException
Output the data read in the preinitialize() or in the previous invocation of postfire(), if there is any.

Specified by:
fire in interface ptolemy.actor.Executable
Overrides:
fire in class Source
Throws:
ptolemy.kernel.util.IllegalActionException - If there's no director.

initialize

public void initialize()
                throws ptolemy.kernel.util.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.

Throws:
ptolemy.kernel.util.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 ptolemy.kernel.util.IllegalActionException
Read the next line from the file. If there is no next line, return false. Otherwise, return whatever the superclass returns.

Throws:
ptolemy.kernel.util.IllegalActionException - If there is a problem reading the file.

prefire

public boolean prefire()
                throws ptolemy.kernel.util.IllegalActionException
Return false if there is no more data available in the file. Otherwise, return whatever the superclass returns.

Throws:
ptolemy.kernel.util.IllegalActionException - If the superclass throws it.

preinitialize

public void preinitialize()
                   throws ptolemy.kernel.util.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.

Throws:
ptolemy.kernel.util.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 ptolemy.kernel.util.IllegalActionException
Close the reader if there is one.

Throws:
ptolemy.kernel.util.IllegalActionException - If an IO error occurs.