ptolemy.actor.lib
Class Exec

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.Exec
All Implemented Interfaces:
Actor, Changeable, java.lang.Cloneable, Debuggable, DebugListener, Derivable, Executable, Instantiable, ModelErrorHandler, MoMLExportable, Nameable, java.io.Serializable, TypedActor

public class Exec
extends TypedAtomicActor

Execute a command as a separately running subprocess.

This actor uses java.lang.Runtime.exec() to invoke a subprocess named be the command parameter in a directory with an environment. Data from the input port (if any) is passed to the input of the subprocess. The subprocess is run until it exits and then contents of the output and error streams of the subprocess (if any) are passed to the output and error ports.

If the subprocess generates no data on the output or error stream, then the data on the corresponding port(s) will consist of the empty string.

A much more interesting actor could be written using a Kahn Process Network. This actor would generate output asynchronously as the process was executing.

Currently, there appears to be no way to get the subprocess to exit by passing it input. For example, if the command is set to the cat command, and we pass in a Const with the value \04, then the cat subprocess does not interpret this as the end of file marker and exit.

For information about Runtime.exec(), see:
http://www.javaworld.com/javaworld/jw-12-2000/jw-1229-traps.html
and
http://mindprod.com/jgloss/exec.html

Since:
Ptolemy II 4.0
Version:
$Id: Exec.java,v 1.42.2.1 2004/07/29 21:53:29 cxh Exp $
Author:
Christopher Hylands Brooks, Contributor: Edward A. Lee
See Also:
Serialized Form
Accepted Rating:
Yellow (cxh) 2/24/04
Proposed Rating:
Yellow (cxh) 2/5/04

Nested Class Summary
 
Nested classes inherited from class ptolemy.kernel.Entity
Entity.ContainedObjectsIterator
 
Field Summary
 PortParameter command
          The command to be executed.
 FileParameter directory
          The directory in which to execute the command.
 Parameter environment
          The environment in which to execute the command.
 TypedIOPort error
          Data that is generated by the subprocess on its standard error.
 TypedIOPort input
          Strings to pass to the standard input of the subprocess.
 TypedIOPort output
          Data that is generated by the subprocess on standard out.
 
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
Exec(CompositeEntity container, java.lang.String name)
          Construct an actor with the given container and name.
 
Method Summary
 void fire()
          Invoke a subprocess, read the input data (if any) and wait for the subprocess to terminate before sending any output or error data to the appropriate ports.
 void stop()
          Override the base class and terminate the process.
 void stopFire()
          Override the base class to stop waiting for input data.
 void wrapup()
          Terminate the subprocess.
 
Methods inherited from class ptolemy.actor.TypedAtomicActor
_addPort, attributeTypeChanged, clone, newPort, typeConstraintList
 
Methods inherited from class ptolemy.actor.AtomicActor
_createReceivers, clone, connectionsChanged, getDirector, getExecutiveDirector, getFunctionDependency, getManager, initialize, inputPortList, iterate, newReceiver, outputPortList, postfire, prefire, preinitialize, pruneDependencies, removeDependency, setContainer, 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, attributeChanged, 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
initialize, iterate, postfire, prefire, preinitialize, 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

command

public PortParameter command
The command to be executed. The command is parsed by StringUtilities.tokenizeForExec(String) into tokens and then executed as a separate subprocess. The initial default value is the string echo "Hello, world.".

The command parameter is read only once during fire(). If you want to spawn another different command, use life cycle management actors such RunCompositeActor.


directory

public FileParameter directory
The directory in which to execute the command.

This parameter is an Expert mode parameter, so it is usually hidden. To edit it, right click on the actor, select 'Configure', then hit the 'Preferences' button and select 'Expert Mode'.

This parameter is read each time the subprocess is started in fire(). Once the subprocess is running, this parameter is not read again until fire() is called again.

The initial default value of this parameter $CWD, which corresponds with the value of the Java virtual machine user.dir property which is the user's current working directory. Note that if we are running inside a menu launched application, then ptolemy.actor.gui.jnlp.MenuApplication will change user.dir to be the value of user.home, which is the name of the user's home directory.


environment

public Parameter environment
The environment in which to execute the command.

This parameter is an Expert mode parameter, so it is usually hidden. To edit it, right click on the actor, select 'Configure', then hit the 'Preferences' button and select 'Expert Mode'.

This parameter is read each time the subprocess is started in fire(). Once the subprocess is running, this parameter is not read again until fire() is called again.

This parameter is an array of records that name an environment variable and the value for the value. The format is:

  {{name = "NAME1", value = "value1"}...}
  
Where NAME1 is the name of the environment variable, and value1 is the value.

For example {{name = "PTII", value = "c:/ptII"}} would set the value of the PTII to c:/ptII.

If the initial value of the parameter is {{name="", value = ""}}, then the environment from the calling or parent process is used in the new command.

Note that if this parameter sets any environment variable, then under Windows the other environment variables in the calling or parent process might not be passed to the subprocess. This behaviour could be platform or JVM dependent. When in doubt, try setting the command value to "env" to print out the environment.


error

public TypedIOPort error
Data that is generated by the subprocess on its standard error. While the process is running, any error data generated by the subprocess is stored until the subprocess exits and then the stored error data is sent to the error port. If the subprocess generates no data on standard error, then the empty string (a string of length zero) is generated.

The port is an output port of type String.


input

public TypedIOPort input
Strings to pass to the standard input of the subprocess. Note that a newline is not appended to the string. If you require a newline, add one using the AddSubtract actor.

This port is an input port of type String.


output

public TypedIOPort output
Data that is generated by the subprocess on standard out. While the process is running, any output data generated by the subprocess is stored until the subprocess exits and then the stored output data is sent to the output port. If the subprocess generates no data on standard out, then the empty string (a string of length zero) is generated.

The port is an output port of type String.

Constructor Detail

Exec

public Exec(CompositeEntity container,
            java.lang.String name)
     throws NameDuplicationException,
            IllegalActionException
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

fire

public void fire()
          throws IllegalActionException
Invoke a subprocess, read the input data (if any) and wait for the subprocess to terminate before sending any output or error data to the appropriate ports.

If there is no data on the input port, then the subprocess executes without reading any input. If there is no output or error data from the subprocess, then the empty string is sent to the appropriate port(s).

Specified by:
fire in interface Executable
Overrides:
fire in class AtomicActor
Throws:
IllegalActionException - If the subprocess cannot be started, if the input of the subprocess cannot be written, if the subprocess gets interrupted, or if the return value of the process is non-zero.

stop

public void stop()
Override the base class and terminate the process.

Specified by:
stop in interface Executable
Overrides:
stop in class AtomicActor

stopFire

public void stopFire()
Override the base class to stop waiting for input data.

Specified by:
stopFire in interface Executable
Overrides:
stopFire in class AtomicActor

wrapup

public void wrapup()
            throws IllegalActionException
Terminate the subprocess. This method is invoked exactly once per execution of an application. None of the other action methods should be be invoked after it.

Specified by:
wrapup in interface Executable
Overrides:
wrapup in class AtomicActor
Throws:
IllegalActionException - Not thrown in this base class.