Purpose

The exec accessor provides a general purpose mechanism for executing a native process on the local native operating-system. It enables a native process to be wrapped and treated as a service within NetKernel.

stdin, stdout and stderr of the invoked process can be harnessed as pipelines to/from NetKernel services or equally other operating system native processes.

Usage

The command argument specifies a command and its arguments (argv) that will be passed to the underlying operating system to execute in a platform specific way. The command can either be specified as a string (an easy way to pass a string from DPML or in a URI is to use the data: scheme) or as an XML document with a set of <arg> elements containing the text of each part of the command line.

The working directory of the executed process defaults to the working directory of the NetKernel process. If a wd argument is specified using a file: URI then this will be used as the working directory.

Dealing with stdin

Any resource can be passed to the process via its stdin stream. The resource must be capable of being serialized to a binary stream.

Dealing with stdout

The default operation of the exec accessor is to return the stdout stream from the process as its response. The response is generated as a stream such that it may be pipelined into another service without being buffered in memory - this is an important consideration if the amount of data being processed is large, it also means that the actual execution of the native application only occurs just-in-time when a resource is used (this is analogous to a SAX pipeline) and means that true application pipelines can be composed.

If the process returns a non-zero return code then it assumed to be an error and an exception is thrown. If you wish to override this default behaviour you can specify an <ignoreReturnCode/> element in the param document.

The default mime-type of the response is text/plain. This can be overriden by specifying in the param document a first-child <mimetype> element containing the mime-type as text.

Dealing with stderr

By default the stderr stream from a process is logged line-by-line into the system log as a warning. This behaviour can be stopped by specifying an <ignoreStderr/> element on the param document. The default behaviour can be overridden by setting a custom stderr handler service URI specified in the stderr argument.

A stderr handler service is invoked with the URI specified on the stderr argument. It is also passed a command argument which is the command string that generated the stderr, and a stderr argument which is the stderr stream. Any response from the stderr handler is ignored, however if it fails its exception will be propagated back to the caller of the exec accessor.

Termination

The exec accessor is valuable for enabling access to the standard Unix system tools which process stdin to stdout such as sed, awk, gzip etc etc. It is assumed that these applications will terminate when the stdin file is closed. It is not possible to kill a native system process started with the exec accessor so, for example, a GUI application started with exec will block an initiating NetKernel process until it exits.

Example

A simple native OS pipeline written as a DPML script to compress an XML literal using gzip and then gunzip to expand it again: