ptolemy.actor.lib

Class Dictionary

java.lang.Object

ptolemy.kernel.util.NamedObj

ptolemy.kernel.InstantiableNamedObj

ptolemy.kernel.Entity<T>

ptolemy.kernel.ComponentEntity<T>

ptolemy.actor.AtomicActor<TypedIOPort>

ptolemy.actor.TypedAtomicActor

ptolemy.actor.lib.Dictionary

All Implemented Interfaces:

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

public class Dictionary
extends TypedAtomicActor

A store for key-value pairs. This actor stores key-value pairs and provides an interface for retrieving them one at a time or in groups.

Since:

Ptolemy II 10.0

Version:

$Id$

Author:

Shuhei Emoto, Edward A. Lee, Kentaro Mizouchi, Tetsuya Suga

Pt.AcceptedRating:

Red (cxh)

Pt.ProposedRating:

Yellow (cxh)

Nested Class Summary

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

Entity.ContainedObjectsIterator

Field Summary

Fields

Modifier and Type	Field and Description
FileParameter	file If a file is given here, it will be read upon initialization (if it exists and can be parsed as an array of arrays of tokens) to initialize the dictionary.
TypedIOPort	keys Upon receiving any token at the triggerKeys port, this actor will produce on this output an array containing all the keys of entries in the dictionary.
FileParameter	loggingDirectory If given, a log file will be written to the specified directory.
TypedIOPort	notFound An output listing one or more keys that were requested but not found in the dictionary.
TypedIOPort	readKey An input that provides a key for a value to be read from the dictionary.
TypedIOPort	readKeyArray An input that provides an array of keys to be read simultaneously from the dictionary.
TypedIOPort	result An output providing the result of a single reading of the dictionary via the readKey input port.
TypedIOPort	resultArray An output providing the result of a multiple reading of the dictionary via the readKeyArray input port.
TypedIOPort	triggerKeys Upon receiving any token at this port, this actor will produce on the keys output an array containing all the keys of entries in the dictionary.
TypedIOPort	triggerValues Upon receiving any token at this port, this actor will produce on the values output an array containing all the values of entries in the dictionary.
Parameter	updateFile If set to true, and if a file parameter is given, then upon each update to the dictionary, the contents of the dictionary will be stored in the file.
TypedIOPort	value Input port for providing a value to store in the dictionary.
TypedIOPort	values Upon receiving any token at the triggerValues port, this actor will produce on this output an array containing all the values of entries in the dictionary.
TypedIOPort	writeKey An input that provides a key for a key-value pair to be stored in the dictionary.

Fields inherited from class ptolemy.actor.TypedAtomicActor

_typesValid

Fields inherited from class ptolemy.actor.AtomicActor

_actorFiringListeners, _initializables, _notifyingActorFiring, _stopRequested

Fields inherited from class ptolemy.kernel.util.NamedObj

_changeListeners, _changeLock, _changeRequests, _debugging, _debugListeners, _deferChangeRequests, _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

Constructors

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

Method Summary

Modifier and Type	Method and Description
java.lang.Object	clone(Workspace workspace) Clone the actor into the specified workspace.
void	fire() If there is a writeKey input, then update the dictionary; specifically, if there is also a value input, then insert into the dictionary the key-value pair given by these two inputs.
void	initialize() Clear the dictionary.
void	wrapup() If a file has been specified and updateFile is true, then save the current state of the dictionary in the file.

Methods inherited from class ptolemy.actor.TypedAtomicActor

_containedTypeConstraints, _customTypeConstraints, _defaultTypeConstraints, _fireAt, _fireAt, attributeTypeChanged, clone, isBackwardTypeInferenceEnabled, newPort, typeConstraintList, typeConstraints

Methods inherited from class ptolemy.actor.AtomicActor

_actorFiring, _actorFiring, _declareDelayDependency, addActorFiringListener, addInitializable, connectionsChanged, createReceivers, declareDelayDependency, getCausalityInterface, getDirector, getExecutiveDirector, getManager, inputPortList, isFireFunctional, isStrict, iterate, newReceiver, outputPortList, postfire, prefire, preinitialize, 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

_addPort, _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, _containedDecorators, _copyChangeRequestList, _debug, _debug, _debug, _debug, _debug, _executeChangeRequests, _getIndentPrefix, _isMoMLSuppressed, _markContentsDerived, _notifyHierarchyListenersAfterChange, _notifyHierarchyListenersBeforeChange, _propagateValue, _removeAttribute, _splitName, _stripNumericSuffix, addChangeListener, addDebugListener, addHierarchyListener, attributeChanged, attributeDeleted, attributeList, attributeList, decorators, 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, notifyOfNameChange, propagateValue, propagateValues, removeAttribute, removeChangeListener, removeDebugListener, removeHierarchyListener, 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, postfire, prefire, stop, stopFire, terminate

Methods inherited from interface ptolemy.actor.Initializable

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

file

public FileParameter file

If a file is given here, it will be read upon initialization (if it exists and can be parsed as an array of arrays of tokens) to initialize the dictionary.

keys

public TypedIOPort keys

Upon receiving any token at the triggerKeys port, this actor will produce on this output an array containing all the keys of entries in the dictionary. The order is arbitrary. If there are no entries in the dictionary, then send an empty array. The type is array of string.

loggingDirectory

public FileParameter loggingDirectory

If given, a log file will be written to the specified directory.

A file name can also contain the following strings that start with "$", which get substituted with the appropriate values.

"Properties that are substituted.

String	Description	Property
$CWD	The current working directory	user.dir
$HOME	The user's home directory	user.home
$PTII	The home directory of the Ptolemy II installation	ptolemy.ptII.dir
$TMPDIR	The temporary directory	java.io.tmpdir
$USERNAME	The user's account name	user.name

notFound

public TypedIOPort notFound

An output listing one or more keys that were requested but not found in the dictionary. The output is produced only if a key is not found. The output type is an array of strings.

readKey

public TypedIOPort readKey

An input that provides a key for a value to be read from the dictionary. If the dictionary does not contain any value corresponding to this key, then the output will be a nil token. This has type string.

readKeyArray

public TypedIOPort readKeyArray

An input that provides an array of keys to be read simultaneously from the dictionary. The output will be an array with the same length as this input where each entry in the output array is the value corresponding to the corresponding key in the input array. For any key that has no entry in the dictionary, a nil token will be inserted in the output array. The type is array of string.

result

public TypedIOPort result

An output providing the result of a single reading of the dictionary via the readKey input port. If the specified key is not found, this port will produce a nil token, and an array of length one with the key will be produced on the notFound output port.

resultArray

public TypedIOPort resultArray

An output providing the result of a multiple reading of the dictionary via the readKeyArray input port. For any of the keys in the readKeyArray input is not in the dictionary, there will be a nil token in the result array in the position of the missing key. The missing keys will be produced on the notFound output.

triggerKeys

public TypedIOPort triggerKeys

Upon receiving any token at this port, this actor will produce on the keys output an array containing all the keys of entries in the dictionary. The order is arbitrary.

triggerValues

public TypedIOPort triggerValues

Upon receiving any token at this port, this actor will produce on the values output an array containing all the values of entries in the dictionary. The order is arbitrary.

values

public TypedIOPort values

Upon receiving any token at the triggerValues port, this actor will produce on this output an array containing all the values of entries in the dictionary. The order is arbitrary. If there are no entries in the dictionary, then send an empty array. The type is array of token.

updateFile

public Parameter updateFile

If set to true, and if a file parameter is given, then upon each update to the dictionary, the contents of the dictionary will be stored in the file. This defaults to false.

value

public TypedIOPort value

Input port for providing a value to store in the dictionary. The value will be stored only if a writeKey input arrives at the same time. Otherwise, it will be discarded.

writeKey

public TypedIOPort writeKey

An input that provides a key for a key-value pair to be stored in the dictionary. If a key arrives on this port, but there is no value on the value port or the value is nil, then the dictionary entry with the specified key will be removed. Otherwise, the value provided on the value port will be stored indexed by this key. This has type string.

Constructor Detail

Dictionary

public Dictionary(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

clone

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

Clone the actor into the specified workspace.

Overrides:

clone in class TypedAtomicActor

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

If there is a writeKey input, then update the dictionary; specifically, if there is also a value input, then insert into the dictionary the key-value pair given by these two inputs. Otherwise, or if the value input is a nil token, then delete the dictionary entry corresponding to the key. If there is a readKey input, then read the dictionary and produce on the result output the entry corresponding to the key, or a nil token if there is no such entry. If there is a readKeyArray input, then read the dictionary and produce on the resultArray output the entries corresponding to the keys, with nil tokens inserted for any missing entry. If there is a triggerKeys input, then produce on the keys output an array containing all the keys in the dictionary, in arbitrary order.

Specified by:

fire in interface Executable

Overrides:

fire in class AtomicActor<TypedIOPort>

Throws:

IllegalActionException - Not thrown in this base class.

initialize

public void initialize()
                throws IllegalActionException

Clear the dictionary. If a file is specified, attempt to read it to initialize the dictionary. If enableLogging is true, then start logging.

Specified by:

initialize in interface Initializable

Overrides:

initialize in class AtomicActor<TypedIOPort>

Throws:

IllegalActionException - If the superclass throws it.

wrapup

public void wrapup()
            throws IllegalActionException

If a file has been specified and updateFile is true, then save the current state of the dictionary in the file. If the file cannot be written, then dictionary contents will be sent to standard out and an exception will be thrown.

Specified by:

wrapup in interface Initializable

Overrides:

wrapup in class AtomicActor<TypedIOPort>

Throws:

IllegalActionException - If the file cannot be written.