public class Exec extends LimitedFiringSource
This actor uses java.lang.Runtime.exec() to invoke a subprocess named by the command parameter in a specified directory with a specified 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.
To get the effect of executing a command provided in a shell interpreter, set the prependPlatformDependentShellCommand parameter to true. This will prepend a default platform-dependent shell command to the command you wish to execute so that your command is executed within the shell. Alternatively, you can set command to "cmd" (Windows) or "sh" (Windows with Cygwin or Linux), and then provide commands at the input port. In this case, however, your model will only work on platforms that have the shell command you have specified. Note that in this case each command must be terminated with a newline. For example, to open a model in vergil and run it, you can set command to "sh" and use a Const actor to provide on the input port the string:
"vergil -run model.xml\n exit\n"
A much more interesting actor could be written using a Kahn Process Network. This actor would generate output asynchronously as the process was executing.
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
| Yellow (cxh) 2/24/04 |
| Yellow (cxh) 2/5/04 |
Entity.ContainedObjectsIterator| Modifier and Type | Field and Description |
|---|---|
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 |
exitCode
The exit code of the subprocess.
|
Parameter |
ignoreIOExceptionReadErrors
If true, ignore IOException errors from the subprocess.
|
TypedIOPort |
input
Strings to pass to the standard input of the subprocess.
|
Parameter |
prependPlatformDependentShellCommand
If true, then prepend the platform dependent shell command
to the parsed value of the command parameter.
|
Parameter |
throwExceptionOnNonZeroReturn
If true, then throw an exception if the subprocess returns
non-zero.
|
Parameter |
waitForProcess
If true, then actor will wait until subprocess completes.
|
_firingCountLimit, _iterationCount, firingCountLimit_triggered, output, trigger_typesValid_actorFiringListeners, _initializables, _notifyingActorFiring, _stopRequested_changeListeners, _changeLock, _changeRequests, _debugging, _debugListeners, _deferChangeRequests, _elementName, _isPersistent, _verbose, _workspace, ATTRIBUTES, CLASSNAME, COMPLETE, CONTENTS, DEEP, FULLNAME, LINKSCOMPLETED, NOT_READY, STOP_ITERATING| Constructor and Description |
|---|
Exec(CompositeEntity container,
java.lang.String name)
Construct an actor with the given container and name.
|
| Modifier and Type | Method and Description |
|---|---|
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.
|
attributeChanged, initialize, postfire_customTypeConstraints, prefire_containedTypeConstraints, _defaultTypeConstraints, _fireAt, _fireAt, attributeTypeChanged, clone, clone, isBackwardTypeInferenceEnabled, newPort, typeConstraintList, typeConstraints_actorFiring, _actorFiring, _declareDelayDependency, addActorFiringListener, addInitializable, connectionsChanged, createReceivers, declareDelayDependency, getCausalityInterface, getDirector, getExecutiveDirector, getManager, inputPortList, isFireFunctional, isStrict, iterate, newReceiver, outputPortList, preinitialize, pruneDependencies, recordFiring, removeActorFiringListener, removeDependency, removeInitializable, setContainer, terminate_adjustDeferrals, _checkContainer, _getContainedObject, _propagateExistence, getContainer, instantiate, isAtomic, isOpaque, moveDown, moveToFirst, moveToIndex, moveToLast, moveUp, propagateExistence, setName_addPort, _description, _exportMoMLContents, _removePort, _validateSettables, connectedPortList, connectedPorts, containedObjectsIterator, getAttribute, getPort, getPorts, linkedRelationList, linkedRelations, portList, removeAllPorts, setClassDefinition, uniqueName_setParent, exportMoML, getChildren, getElementName, getParent, getPrototypeList, isClassDefinition, isWithinClassDefinition_addAttribute, _adjustOverride, _attachText, _cloneFixAttributeFields, _containedDecorators, _copyChangeRequestList, _debug, _debug, _debug, _debug, _debug, _executeChangeRequests, _getIndentPrefix, _isMoMLSuppressed, _markContentsDerived, _notifyHierarchyListenersAfterChange, _notifyHierarchyListenersBeforeChange, _propagateValue, _removeAttribute, _splitName, _stripNumericSuffix, addChangeListener, addDebugListener, addHierarchyListener, 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, workspaceequals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, waitcreateReceivers, getCausalityInterface, getDirector, getExecutiveDirector, getManager, inputPortList, newReceiver, outputPortListisFireFunctional, isStrict, iterate, terminateaddInitializable, preinitialize, removeInitializabledescription, getContainer, getDisplayName, getFullName, getName, getName, setNamegetDerivedLevel, getDerivedList, propagateValuepublic PortParameter command
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.
public FileParameter directory
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.
public Parameter environment
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.
public TypedIOPort error
public TypedIOPort exitCode
public Parameter ignoreIOExceptionReadErrors
public TypedIOPort input
public Parameter prependPlatformDependentShellCommand
Under Windows NT or XP, the arguments "cmd.exe" and "/C" are prepended. Under Windows 95, the arguments "command.com" and "/C" are prepended. Under all other platforms, the arguments "/bin/sh" and "-c" are prepended.
By prepending sh or cmd, then this actor can use the file redirection operations.
The default value of this parameter is a boolean of value false, which allows the user to arbitrarily invoke /bin/sh scripts on all platforms.
public Parameter throwExceptionOnNonZeroReturn
public Parameter waitForProcess
public Exec(CompositeEntity container, java.lang.String name) throws NameDuplicationException, IllegalActionException
container - The container.name - The name of this actor.IllegalActionException - If the actor cannot be contained
by the proposed container.NameDuplicationException - If the container already has an
actor with this name.public void fire()
throws IllegalActionException
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).
fire in interface Executablefire in class SourceIllegalActionException - 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.public void stop()
stop in interface Executablestop in class AtomicActor<TypedIOPort>public void stopFire()
stopFire in interface ExecutablestopFire in class AtomicActor<TypedIOPort>public void wrapup()
throws IllegalActionException
wrapup in interface Initializablewrapup in class AtomicActor<TypedIOPort>IllegalActionException - Not thrown in this base class.