ch.javasoft.job
Class ExecJob

java.lang.Object
  ch.javasoft.job.ExecJob

All Implemented Interfaces:

Executable<Void>, Job<ExecJobMonitor>

public class ExecJob
extends Object
implements Job<ExecJobMonitor>, Executable<Void>

An ExecJob represents a command line executable, such as those being passed to Runtime.exec(String) and related methods.

A sample usage of this class, piping 2 jobs and displaying the results on the standard output/error could look like this:

        public void pipe2Jobs() throws Exception {
                ExecJob job1 = new ExecJob("cat /tmp/efms.txt");
                ExecJob job2 = new ExecJob("grep 191");
                ExecJobMonitor hdl1 = job1.exec();
                ExecJobMonitor hdl2 = job2.exec();
                hdl1.pipeTo(hdl2, true);
                hdl2.pipeTo(System.out, System.err, false);
                hdl2.waitForResult();
                System.out.println("DONE.");
        }
 

Constructor Summary

ExecJob(String command)
Constructs an ExecJob with the specified string command

ExecJob(String[] cmdarray)
Constructs an ExecJob with the specified string command

ExecJob(String[] cmdarray, File dir)
Constructs an ExecJob with the specified string command and working directory.

ExecJob(String[] cmdarray, String[] envp)
Constructs an ExecJob with the specified string command and environment.

ExecJob(String[] cmdarray, String[] envp, File dir)
Constructs an ExecJob with the specified string command, environment and working directory.

ExecJob(String command, File dir)
Constructs an ExecJob with the specified string command and working directory.

ExecJob(String command, String[] envp)
Constructs an ExecJob with the specified string command and environment.

ExecJob(String command, String[] envp, File dir)
Constructs an ExecJob with the specified string command, environment and working directory.

Method Summary

ExecJobMonitor	exec() Executes and returns immediately, without waiting for completion.
ExecJobMonitor	exec(JobTerminationHandler<Void> terminationHandler) Executes and returns immediately, without waiting for completion.
JobResult<Void>	execAndWait() Executes and waits for completion.
Void	execAndWaitThrowException() Executes and waits for completion.
<E extends Throwable> void	execWaitForResultThrowException(Class<E> exClass) Like execAndWait(), but if the result was exceptional, an Exception is thrown.
String	execWaitForStdOutString() Like execAndWait(), but returning a string containing the stuff which was written to the standard output of the process.
Object	id()
ExecJobMonitor	run() Executes the job, blocks until the result is present or an exception is thrown.
String	toString()

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait

Constructor Detail

ExecJob

public ExecJob(String command)

Constructs an ExecJob with the specified string command

This is a convenience method. An invocation of the form ExecJob(command) behaves in exactly the same way as the invocation exec(command, null, null).

Parameters:

command - a specified system command.

Throws:

NullPointerException - if command is null

See Also:

Runtime.exec(String)

ExecJob

public ExecJob(String command,
               String[] envp)

Constructs an ExecJob with the specified string command and environment.

This is a convenience method. An invocation of the form ExecJob(command, envp) behaves in exactly the same way as the invocation exec(command, envp, null).

Parameters:

command - a specified system command.

envp - array of strings, each element of which has environment variable settings in the format name=value, or null if the subprocess should inherit the environment of the current process.

Throws:

NullPointerException - if command is null

See Also:

Runtime.exec(String, String[]), Env

ExecJob

public ExecJob(String command,
               File dir)

Constructs an ExecJob with the specified string command and working directory.

This is a convenience method. An invocation of the form ExecJob(command, dir) behaves in exactly the same way as the invocation exec(command, null, dir).

Parameters:

command - a specified system command.

dir - the working directory of the subprocess, or null if the subprocess should inherit the working directory of the current process.

Throws:

NullPointerException - if command is null

See Also:

Runtime.exec(String, String[], File), Env

ExecJob

public ExecJob(String command,
               String[] envp,
               File dir)

Constructs an ExecJob with the specified string command, environment and working directory.

Parameters:

command - a specified system command.

envp - array of strings, each element of which has environment variable settings in the format name=value, or null if the subprocess should inherit the environment of the current process.

dir - the working directory of the subprocess, or null if the subprocess should inherit the working directory of the current process.

Throws:

NullPointerException - if command is null

See Also:

Runtime.exec(String, String[], File), Env

ExecJob

public ExecJob(String[] cmdarray)

Constructs an ExecJob with the specified string command

This is a convenience method. An invocation of the form ExecJob(command) behaves in exactly the same way as the invocation exec(command, null, null).

Parameters:

cmdarray - array containing the command to call and its arguments.

Throws:

NullPointerException - if command is null

See Also:

Runtime.exec(String)

ExecJob

public ExecJob(String[] cmdarray,
               String[] envp)

Constructs an ExecJob with the specified string command and environment.

This is a convenience method. An invocation of the form ExecJob(command, envp) behaves in exactly the same way as the invocation exec(command, envp, null).

Parameters:

cmdarray - array containing the command to call and its arguments.

envp - array of strings, each element of which has environment variable settings in the format name=value, or null if the subprocess should inherit the environment of the current process.

Throws:

NullPointerException - if command is null

See Also:

Runtime.exec(String, String[]), Env

ExecJob

public ExecJob(String[] cmdarray,
               File dir)

Constructs an ExecJob with the specified string command and working directory.

This is a convenience method. An invocation of the form ExecJob(command, dir) behaves in exactly the same way as the invocation exec(command, null, dir).

Parameters:

cmdarray - array containing the command to call and its arguments.

dir - the working directory of the subprocess, or null if the subprocess should inherit the working directory of the current process.

Throws:

NullPointerException - if command is null

See Also:

Runtime.exec(String, String[], File), Env

ExecJob

public ExecJob(String[] cmdarray,
               String[] envp,
               File dir)

Constructs an ExecJob with the specified string command, environment and working directory.

Parameters:

cmdarray - array containing the command to call and its arguments.

envp - array of strings, each element of which has environment variable settings in the format name=value, or null if the subprocess should inherit the environment of the current process.

dir - the working directory of the subprocess, or null if the subprocess should inherit the working directory of the current process.

Throws:

NullPointerException - if command is null

See Also:

Runtime.exec(String, String[], File), Env

Method Detail

id

public Object id()

Returns:

the object itself (this)

run

public ExecJobMonitor run()
                   throws IOException

Description copied from interface: Job

Executes the job, blocks until the result is present or an exception is thrown.
Note: It is usually not a good idea to call this method manually, but to let this job be executed by a JobProcessor. Most job implementations also implement Executable with the more preferable Executable.exec() and Executable.execAndWait() methods.

Specified by:

run in interface Job<ExecJobMonitor>

Returns:

the job result, or null of type Void for void methods

Throws:

IOException

exec

public ExecJobMonitor exec()

Description copied from interface: Executable

Executes and returns immediately, without waiting for completion.

Specified by:

exec in interface Executable<Void>

Returns:

the job monitor, which also allows access to the result when execution completed

exec

public ExecJobMonitor exec(JobTerminationHandler<Void> terminationHandler)

Description copied from interface: Executable

Executes and returns immediately, without waiting for completion. The submitted termination handler is notified upon normal or exceptional termination.

Specified by:

exec in interface Executable<Void>

Parameters:

terminationHandler - the handler for normal and exceptional termination of this job

Returns:

the job monitor

execAndWait

public JobResult<Void> execAndWait()
                            throws InterruptedException

Description copied from interface: Executable

Executes and waits for completion.

Specified by:

execAndWait in interface Executable<Void>

Returns:

the job result, giving access to the return value on success, or to the exception if execution caused any.

Throws:

InterruptedException

execAndWaitThrowException

public Void execAndWaitThrowException()
                               throws InterruptedException,
                                      Throwable

Description copied from interface: Executable

Executes and waits for completion. The result is returned on normal termination, and an exception is thrown on abnormal (exceptional) termination.

Specified by:

execAndWaitThrowException in interface Executable<Void>

Returns:

the result if termination is normal

Throws:

InterruptedException

Throwable

execWaitForResultThrowException

public <E extends Throwable> void execWaitForResultThrowException(Class<E> exClass)
                                     throws E extends Throwable

Like execAndWait(), but if the result was exceptional, an Exception is thrown. The exception type to be thrown is defined with the exClass parameter, every exception not being of that type will be transformed into a RuntimeException if necessary.

Parameters:

exClass - The desired exception type, e.g. use RuntimeException.class that only runtime exceptions are thrown, or Throwable.class to rethrow every occuring exception unchanged.

Throws:

E - The exception of the specified type

RuntimeException - If an exception was thrown not being of type E and not being an Error. If it was already a runtime exception, it is rethrown, if not, it is nested in a runtime exception which is then thrown.

Error - If an error was thrown not being of type E

E extends Throwable

execWaitForStdOutString

public String execWaitForStdOutString()
                               throws ExecException,
                                      ExitValueException,
                                      StdErrNonEmptyException,
                                      InterruptedException

Like execAndWait(), but returning a string containing the stuff which was written to the standard output of the process. If the process also wrote to the standard error, a StdErrNonEmptyException is thrown. If the process exits with an exit code unequal to 0, an ExitValueException is thrown.

Returns:

the string containing what was written to the standard output of the process

Throws:

ExitValueException - if the process terminated with an exit value unequal to 0

StdErrNonEmptyException - if the process wrote to the standard error

InterruptedException - if waiting for termination of the process was interrupted, e.g. by calling ExecJobMonitor.interrupt()

ExecException - if any other exception occurred during the process execution

toString

public String toString()

Overrides:

toString in class Object