Executable (A grabbag of wonderful things. 1.8.1 API)

java.lang.Object
- com.eaio.exec.Executable

All Implemented Interfaces:

Serializable, Runnable, Future<Executable>, RunnableFuture<Executable>
```
public class Executable
extends Object
implements RunnableFuture<Executable>, Serializable
```
Builder for external processes with a fluent API. Not as lame as ProcessBuilder and works really well with Groovy.

Features
- Runs any number of commands sequentially.
- Captures the standard output and standard error streams of each process.
- Standard output and standard error streams are stored per-line in a Queue or buffered in a StringBuffer.
- Storing of each stream can be turned off to save memory or to prevent buggy programs from crashing your VM.
- Output may be read already before any of the commands is completed.
- Supports blocking and non-blocking modes.
- Thread safe.
- Null safe.
- For the threads that read standard output and standard error, both thread priority and daemon mode may be set.
- Serializable.
- A customized ThreadFactory may be used.
- Processing may be stopped if unexpected exit values are encountered.
- Chaining API.
- Strong focus on DOS prevention from buggy programs.
Logging

Executable has a logger for executed processes – media.processes.Executable – and loggers for the output and error streams of each process – media.processes.ExecutableOutput and media.processes.ExecutableError.
- Commands that return with an unexpected exit value will have the command line and the error message from Commons Exec logged as warn.
- If trace is not enabled, each executed command line will be logged as debug, along with the time in milliseconds it took to execute it.
- If trace is enabled, a message will be logged before and after a command is run.
Output streams and error streams are logged as debug to the media.processes.ExecutableOutput and media.processes.ExecutableError loggers.

Sample Usage

Groovy, synchronous mode
```
 Executable ex = new Executable([ 'cp foo bar', 'sha1sum bar' ]).ignoreStderr().lowPriority()
 ex.run()
 println ex.output.join('\n')
 
```
Java, two commands, asynchronous mode
```
 Executable ex = new Executable("cp foo bar").bufferStdout();
 someExecutor.execute(ex)
 while (ex.get(1, TimeUnit.SECONDS) == null) {
     System.out.println("Still running");
 }
 System.out.println("foo has been copied to bar");
 System.out.println(ex.output);
 
```
Dependencies
More help is available by turning on assertions (-ea).
Version:

$Id: Executable.java 5238 2012-10-23 19:09:16Z johann $

Author:

Johann Burkard

See Also:
heavy use at media.io, Serialized Form

Nested Class Summary

Nested Classes
Modifier and Type Class and Description

static class Executable.StreamPumper<T>
Sort of mimics Commons Exec's StreamPumper.

Nested Classes
Modifier and Type	Class and Description
`static class`	`Executable.StreamPumper<T>` Sort of mimics Commons Exec's StreamPumper.

Constructor Summary

Constructors
Constructor and Description
`Executable(Iterable<?> commands)` Prepares each command in the given `Iterable`.
`Executable(Object... commands)` Prepares each command in the Object array.

Method Summary

Methods
Modifier and Type	Method and Description
`Executable`	`bufferStderr()` The standard error stream of all commands is returned in a `StringBuffer`.
`Executable`	`bufferStdout()` The standard output stream of all commands is returned in a `StringBuffer`.
`boolean`	`cancel(boolean mayInterruptIfRunning)`
`protected long`	`currentTimeMillis()` Hook if you use something special for System#currentTimeMillis()
`Executable`	`daemonThreads()` The threads reading from stdout and stderr are `daemon` threads.
`Executable`	`encoding(String encoding)` Sets the encoding.
`Executable`	`expect(int value)` Sets the expected exit value.
`Executable`	`expect(Object values)` Sets the expected exit values.
`Executable`	`get()`
`Executable`	`get(long timeout, TimeUnit unit)`
`Map<String,Object>`	`getEnv()`
`Object`	`getError()` Returns the standard output stream object.
`List<Object>`	`getExitValues()` Returns the collected exit values.
`Object`	`getOutput()` Returns the standard output stream object.
`Executable`	`ignoreStderr()` The standard error stream of the command is ignored.
`Executable`	`ignoreStdout()` The standard output stream of the command is ignored.
`Executable`	`in(Object workingDirectory)` Sets the directory the commands are run in.
`boolean`	`isCancelled()`
`boolean`	`isDone()`
`boolean`	`isRunning()` Bonus method: `true` if currently running.
`String`	`lastCommand()` Returns the last command that was passed on to commons-exec.
`Executable`	`limit(int linesOrCharacters)` Limits the number of stored lines (if using Queues) or characters (if using `StringBuffers`).
`Executable`	`lowPriority()` Convenience method that sets the `thread priority` to `Thread.MIN_PRIORITY` and configures `daemon threads`.
`Executable`	`priority(int priority)` Sets the thread priority of the two threads reading from stdout and stderr.
`void`	`run()` Runs all commands.
`Executable`	`stderr(Executable.StreamPumper pumper)` Sets the standard error `Executable.StreamPumper` to use.
`Executable`	`stdout(Executable.StreamPumper pumper)` Sets the standard output `Executable.StreamPumper` to use.
`Executable`	`stopOnFailure()` If a command returns an `unexpected` exit value, no further commands will be run.
`Executable`	`substitute(Map<String,Object> substitutions)` Substitute all `${key}` sequences in any command with the corresponding value in `substitutions`.
`Executable`	`substitute(String key, Object value)` Substitute a `${key}` sequence in any command with `value`.
`Executable`	`with(ThreadFactory factory)` Sets the thread factory to use.

Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

- Constructor Detail
  - Executable
```
public Executable(Object... commands)
```
    Prepares each command in the Object array.
    
    Parameters:
    commands - individual commands
  - Executable
```
public Executable(Iterable<?> commands)
```
    Prepares each command in the given Iterable.
    
    Parameters:
    commands - individual commands
- Method Detail
  - in
```
public Executable in(Object workingDirectory)
```
    Sets the directory the commands are run in. The argument can be a File or an object that evaluates to a directory. If the directory does not exist, it will be created.
    
    See Also:
    File.mkdirs()
  - priority
```
public Executable priority(int priority)
```
    Sets the thread priority of the two threads reading from stdout and stderr.
    Can only be used if no ThreadFactory has been set.
    
    See Also:
    Thread.setPriority(int), Thread.MIN_PRIORITY, Thread.MAX_PRIORITY
  - daemonThreads
```
public Executable daemonThreads()
```
    The threads reading from stdout and stderr are daemon threads.
    Can only be used if no ThreadFactory has been set.
  - lowPriority
```
public Executable lowPriority()
```
    Convenience method that sets the thread priority to Thread.MIN_PRIORITY and configures daemon threads.
  - encoding
```
public Executable encoding(String encoding)
```
    Sets the encoding. The initial value is the VM's default charset, as obtained from Charset.defaultCharset().
    
    Parameters:
    encoding - the encoding, may not be null
  - stdout
```
public Executable stdout(Executable.StreamPumper pumper)
```
    Sets the standard output Executable.StreamPumper to use.
  - stderr
```
public Executable stderr(Executable.StreamPumper pumper)
```
    Sets the standard error Executable.StreamPumper to use.
  - ignoreStdout
```
public Executable ignoreStdout()
```
    The standard output stream of the command is ignored.
    The return value of getOutput() will be a null after this call.
  - ignoreStderr
```
public Executable ignoreStderr()
```
    The standard error stream of the command is ignored.
    The return value of getError() will be null after this call.
  - bufferStdout
```
public Executable bufferStdout()
```
    The standard output stream of all commands is returned in a StringBuffer.
  - bufferStderr
```
public Executable bufferStderr()
```
    The standard error stream of all commands is returned in a StringBuffer.
  - substitute
```
public Executable substitute(String key,
                    Object value)
```
    Substitute a ${key} sequence in any command with value. This method may be called repeatedly.
    
    Parameters:
    key - the key, may be null
    value - the value, may be null
    See Also:
    CommandLine.parse(String, Map)
  - substitute
```
public Executable substitute(Map<String,Object> substitutions)
```
    Substitute all ${key} sequences in any command with the corresponding value in substitutions. Does not replace previous substitutions so substitute(String, Object) and substitute(Map) may be called repeatedly.
    
    Parameters:
    substitutions - a Map of substitutions, may be null
    See Also:
    CommandLine.parse(String, Map)
  - expect
```
public Executable expect(Object values)
```
    Sets the expected exit values. The default is to only expect 0.
    
    Parameters:
    values - the exit values
    See Also:
    Executor.setExitValues(int[])
  - expect
```
public Executable expect(int value)
```
    Sets the expected exit value. The default is to only expect 0.
    
    Parameters:
    value - the exit value
    See Also:
    Executor.setExitValues(int[])
  - getOutput
```
public Object getOutput()
```
    Returns the standard output stream object. This may be a Queue, null, a StringBuffer or your own custom implementation.
  - getError
```
public Object getError()
```
    Returns the standard output stream object. This may be a Queue, null, a StringBuffer or your own custom implementation.
  - getExitValues
```
public List<Object> getExitValues()
```
    Returns the collected exit values.
    
    Returns:
    a list of Number or a Throwable instances
  - stopOnFailure
```
public Executable stopOnFailure()
```
    If a command returns an unexpected exit value, no further commands will be run.
  - limit
```
public Executable limit(int linesOrCharacters)
```
    Limits the number of stored lines (if using Queues) or characters (if using StringBuffers).
    Has no effect if ignoreStderr() or ignoreStdout() are used.
    
    Parameters:
    lines - the maximum number of lines or characters stored
  - with
```
public Executable with(ThreadFactory factory)
```
    Sets the thread factory to use.
  - lastCommand
```
public String lastCommand()
```
    Returns the last command that was passed on to commons-exec.
    
    Returns:
    the command, may be null
  - getEnv
```
public Map<String,Object> getEnv()
```
  - isRunning
```
public boolean isRunning()
```
    Bonus method: true if currently running.
  - run
```
public void run()
```
    Runs all commands.
    
    Specified by:
    
    run in interface Runnable
    
    Specified by:
    
    run in interface RunnableFuture<Executable>
    
    See Also:
    Runnable.run()
  - cancel
```
public boolean cancel(boolean mayInterruptIfRunning)
```
    Specified by:
    
    cancel in interface Future<Executable>
    
    See Also:
    Future.cancel(boolean)
  - get
```
public Executable get()
               throws InterruptedException,
                      ExecutionException
```
    Specified by:
    
    get in interface Future<Executable>
    
    Throws:
    
    InterruptedException
    
    ExecutionException
    See Also:
    Future.get()
  - get
```
public Executable get(long timeout,
             TimeUnit unit)
               throws InterruptedException,
                      ExecutionException,
                      TimeoutException
```
    Specified by:
    
    get in interface Future<Executable>
    
    Throws:
    
    InterruptedException
    
    ExecutionException
    
    TimeoutException
    See Also:
    Future.get(long, java.util.concurrent.TimeUnit)
  - isCancelled
```
public boolean isCancelled()
```
    Specified by:
    
    isCancelled in interface Future<Executable>
    
    See Also:
    Future.isCancelled()
  - isDone
```
public boolean isDone()
```
    Specified by:
    
    isDone in interface Future<Executable>
    
    See Also:
    Future.isDone()
  - currentTimeMillis
```
protected long currentTimeMillis()
```
    Hook if you use something special for System#currentTimeMillis()

Class Executable

Features

Logging

Sample Usage

Groovy, synchronous mode

Java, two commands, asynchronous mode

Dependencies

Nested Class Summary

Constructor Summary

Method Summary

Methods inherited from class java.lang.Object

Constructor Detail

Executable

Executable

Method Detail

in

priority

daemonThreads

lowPriority

encoding

stdout

stderr

ignoreStdout

ignoreStderr

bufferStdout

bufferStderr

substitute

substitute

expect

expect

getOutput

getError

getExitValues

stopOnFailure

limit

with

lastCommand

getEnv

isRunning

run

cancel

get

get

isCancelled

isDone

currentTimeMillis