ptolemy.actor.lib.hoc
Class ApplyFilterOverArray

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.hoc.ApplyFilterOverArray

All Implemented Interfaces:

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

public class ApplyFilterOverArray
extends TypedAtomicActor
implements ExecutionListener

This is an atomic actor that filters an array received at its inputArray input port via applying a model specified by a file or URL. The specified model is evaluated on each input array element and should return a boolean value, and the output is an array that only contains elements satisfying the specified model (the evaluated result is true). An element of the array received at inputArray is provided to the model by setting its inputArrayElement parameter (which it must have defined). The result of executing the model is obtained by reading its evaluatedValue parameter (which it must have defined).

Instead of outputing all the satisfied elements in the input array, the parameter maxOutputLength can be used to specify how many elements this actor should only output. If the specified length is larger than the number of satisfied elements, it will ignore the specified length and only output all the satisfied elements.

FIXME: what should be the correct behavior if there are not enough elements to output?

FIXME: make a convention, say when the maxOutputLength is -1, for output all the satisfied elements? FIXME: should add a ModelToken and an input port for receiving the filter model. Create a composite actor for providing a ModelToken from its inside model.

Since:

Ptolemy II 4.1

Version:

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

Author:

Yang Zhao, Ilkay Altintas

See Also:

ModelReference, Serialized Form

Accepted Rating:

Red (ellen_zh)

Proposed Rating:

Yellow (ellen_zh)

Nested Class Summary

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

Entity.ContainedObjectsIterator

Field Summary

private Manager	_manager The manager currently managing execution.
protected NamedObj	_model The model.
private int	_outputLength the output array length if there are enough elements satisfying the filter model.
private java.lang.Throwable	_throwable
TypedIOPort	inputArray The input port for an input array.
Parameter	maxOutputLength The max amount of elements in the output array.
FileParameter	modelFileOrURL The file name or URL of the filter model.
TypedIOPort	outputArray The output port for output the filtered array.

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

ApplyFilterOverArray(CompositeEntity container, java.lang.String name)
Construct a ApplyFilterOverArray with a name and a container.

Method Summary

private boolean	_getResult() Retrieve the value of the parameter "evaluatedValue" of the model.
private void	_updateParameter(Token t) Set the parameter "inputArrayElement" of the model to an element of the input array.
void	attributeChanged(Attribute attribute) Override the base class to open the model specified if the attribute is modelFileOrURL, or for other parameters, to cache their values.
java.lang.Object	clone(Workspace workspace) Clone the actor into the specified workspace.
void	executionError(Manager manager, java.lang.Throwable throwable) React to the fact that execution has failed by unregistering as an execution listener and by allowing subsequent executions.
void	executionFinished(Manager manager) React to the fact that execution is finished by unregistering as an execution listener and by allowing subsequent executions.
void	fire() Execute the filter model on each input array element until it gets as many elements as specified by the maxOutputLength parameter.
void	managerStateChanged(Manager manager) Report in debugging statements that the manager state has changed.
boolean	postfire() Remove this class from the manager's list of execution listeners.
void	stop() Override the base class to call stop() on the referenced model.
void	stopFire() Override the base class to call stopFire() on the referenced model.
void	terminate() Override the base class to call terminate() on the referenced model.
void	wrapup() Report an exception if it occurred in a background run.

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, initialize, inputPortList, isFireFunctional, isStrict, iterate, newReceiver, outputPortList, prefire, preinitialize, pruneDependencies, recordFiring, removeActorFiringListener, removeDependency, removeInitializable, setContainer

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, prefire

Methods inherited from interface ptolemy.actor.Initializable

addInitializable, initialize, preinitialize, 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

inputArray

public TypedIOPort inputArray

The input port for an input array. It is an ArrayType.

outputArray

public TypedIOPort outputArray

The output port for output the filtered array. It has the same type as the inputArray port.

maxOutputLength

public Parameter maxOutputLength

The max amount of elements in the output array.

modelFileOrURL

public FileParameter modelFileOrURL

The file name or URL of the filter model.

_model

protected NamedObj _model

The model.

_manager

private Manager _manager

The manager currently managing execution.

_outputLength

private int _outputLength

the output array length if there are enough elements satisfying the filter model.

_throwable

private transient java.lang.Throwable _throwable

Constructor Detail

ApplyFilterOverArray

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

Construct a ApplyFilterOverArray with a name and a container. The container argument must not be null, or a NullPointerException will be thrown. If the name argument is null, then the name is set to the empty string.

Parameters:

container - The container.

name - The name of this actor.

Throws:

IllegalActionException - If the container is incompatible with this actor.

NameDuplicationException - If the name coincides with an actor already in the container.

Method Detail

attributeChanged

public void attributeChanged(Attribute attribute)
                      throws IllegalActionException

Override the base class to open the model specified if the attribute is modelFileOrURL, or for other parameters, to cache their values.

Overrides:

attributeChanged in class NamedObj

Parameters:

attribute - The attribute that changed.

Throws:

IllegalActionException - If the change is not acceptable to this container (not thrown in this base class).

clone

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

Clone the actor into the specified workspace. This overrides the base class ensure that private variables are reset to null.

Overrides:

clone in class AtomicActor

Parameters:

workspace - The workspace for the new object.

Returns:

A new instance of ApplyFilterOverArray.

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)

executionError

public void executionError(Manager manager,
                           java.lang.Throwable throwable)

React to the fact that execution has failed by unregistering as an execution listener and by allowing subsequent executions. Report an execution failure at the next opportunity. This method will be called when an exception or error is caught by a manager during a run in another thread of the referenced model.

Specified by:

executionError in interface ExecutionListener

Parameters:

manager - The manager controlling the execution.

throwable - The throwable to report.

executionFinished

public void executionFinished(Manager manager)

React to the fact that execution is finished by unregistering as an execution listener and by allowing subsequent executions. This is called when an execution of the referenced model in another thread has finished and the wrapup sequence has completed normally. The number of successfully completed iterations can be obtained by calling getIterationCount() on the manager.

Specified by:

executionFinished in interface ExecutionListener

Parameters:

manager - The manager controlling the execution.

fire

public void fire()
          throws IllegalActionException

Execute the filter model on each input array element until it gets as many elements as specified by the maxOutputLength parameter. If there are no enough elements satisfying the filter model, then only output all the satisfied elements. Before running the filter model, this method update the filter model's inputArrayElement parameter for each array element. After running the filter model, this method looks for the evaluatedValue parameter and keep the input element if the evaluated value is ture, otherwise, skip the element.

Specified by:

fire in interface Executable

Overrides:

fire in class AtomicActor

Throws:

IllegalActionException - If there is no director, or if the director's action methods throw it.

managerStateChanged

public void managerStateChanged(Manager manager)

Report in debugging statements that the manager state has changed. This method is called if the referenced model is executed in another thread and the manager changes state.

Specified by:

managerStateChanged in interface ExecutionListener

Parameters:

manager - The manager controlling the execution.

See Also:

Manager.getState()

postfire

public boolean postfire()
                 throws IllegalActionException

Remove this class from the manager's list of execution listeners.

Specified by:

postfire in interface Executable

Overrides:

postfire in class AtomicActor

Returns:

Whatever the superclass returns (probably true).

Throws:

IllegalActionException - If removing the execution listener throws it, or if thrown by the superclass. is not valid.

stop

public void stop()

Override the base class to call stop() on the referenced model.

Specified by:

stop in interface Executable

Overrides:

stop in class AtomicActor

stopFire

public void stopFire()

Override the base class to call stopFire() on the referenced model.

Specified by:

stopFire in interface Executable

Overrides:

stopFire in class AtomicActor

terminate

public void terminate()

Override the base class to call terminate() on the referenced model.

Specified by:

terminate in interface Executable

Overrides:

terminate in class AtomicActor

wrapup

public void wrapup()
            throws IllegalActionException

Report an exception if it occurred in a background run.

Specified by:

wrapup in interface Initializable

Overrides:

wrapup in class AtomicActor

Throws:

IllegalActionException - If there is no director, or if a background run threw an exception.

_updateParameter

private void _updateParameter(Token t)
                       throws IllegalActionException

Set the parameter "inputArrayElement" of the model to an element of the input array.

Parameters:

t - The element value.

Throws:

IllegalActionException - If the model does not have a settable attribute named "inputArrayElement".

_getResult

private boolean _getResult()
                    throws IllegalActionException

Retrieve the value of the parameter "evaluatedValue" of the model.

Returns:

The value of the "evaluatedValue" parameter.

Throws:

IllegalActionException - If the model does not have a settable attribute named "evaluatedValue".