Package org.opennms.core.utils

Class ExecRunner

java.lang.Object

org.opennms.core.utils.ExecRunner

public class ExecRunner
extends Object

Runs external executables, optionally under a watched thread. In addition, probably the most useful feature of ExecRunner is using it to run a command-line program and obtain its stdout and stderr results in two strings. This is done with exec(String) - see that method for an example. With acknowledgements to Michael C. Daconta, author of "Java Pitfalls, Time Saving Solutions, and Workarounds to Improve Programs." and his article in JavaWorld "When Runtime.exec() Won't".

Author:

Scott McCrory .

Constructor Summary

Constructors

Constructor	Description
ExecRunner()	Basic ExecRunner constructor.
ExecRunner(String command)	ExecRunner constructor which also conveniently runs exec(String).

Method Summary

Modifier and Type	Method	Description
Object	clone()	We override the clone method here to prevent cloning of our class.
int	exec(String command)	The exec(String) method runs a process inside of a watched thread.
int	exec(String command, OutputStream stdoutStream, OutputStream stderrStream)	Convenience method for calling exec with OutputStreams.
int	exec(String command, PrintWriter stdoutWriter, PrintWriter stderrWriter)	The exec(String, PrintWriter, PrintWriter) method runs a process inside of a watched thread.
String	getErrString()	Returns the error string if exec(String) was invoked.
int	getMaxRunTimeSecs()	Returns the maximum run time in seconds for this object.
String	getOutString()	Returns the output string if exec(String) was invoked.
boolean	isMaxRunTimeExceeded()	Returns whether the maximum runtime was exceeded or not.
static void	main(String[] args)	This is for unit testing of the class.
void	setMaxRunTimeSecs(int max)	Sets the maximum run time in seconds.

Methods inherited from class java.lang.Object

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

Constructor Detail

ExecRunner

public ExecRunner()

Basic ExecRunner constructor.

ExecRunner

public ExecRunner(String command)
           throws ExceptionInInitializerError

ExecRunner constructor which also conveniently runs exec(String).

Parameters:

command - The program or command to run

Throws:

ExceptionInInitializerError - thrown if a problem occurs

Method Detail

clone

public final Object clone()
                   throws CloneNotSupportedException

We override the clone method here to prevent cloning of our class.

Overrides:

clone in class Object

Returns:

Nothing ever really returned since we throw a CloneNotSupportedException

Throws:

CloneNotSupportedException - To indicate cloning is not allowed

exec

public int exec(String command)
         throws IOException,
                InterruptedException

The exec(String) method runs a process inside of a watched thread. It returns the client's exit code and feeds its STDOUT and STDERR to ExecRunner's out and err strings, where you then use getOutString() and getErrString() to obtain these values. Example:

 // Execute the program and grab the results
 try {
     ExecRunner er = new ExecRunner();
     er.setMaxRunTimeSecs(5);
     er.exec("ls -l");
     if (!er.getMaxRunTimeExceeded()) {
         out = er.getOutString();
         err = er.getErrString();
     } else {
         System.out.println("Maximum run time exceeded!");
     }
 } catch (Throwable e) {
     System.out.println("Error executing " + program + ": " + e.getMessage());
     continue;
 }
 

Parameters:

command - The program or command to run

Returns:

The command's return code

Throws:

IOException - thrown if a problem occurs

InterruptedException - thrown if a problem occurs

exec

public int exec(String command,
                OutputStream stdoutStream,
                OutputStream stderrStream)
         throws IOException,
                InterruptedException

Convenience method for calling exec with OutputStreams.

Parameters:

command - The program or command to run

stdoutStream - java.io.OutputStream

stderrStream - java.io.OutputStream

Returns:

The command's return code

Throws:

IOException - thrown if a problem occurs

InterruptedException - thrown if a problem occurs

exec

public int exec(String command,
                PrintWriter stdoutWriter,
                PrintWriter stderrWriter)
         throws IOException,
                InterruptedException

The exec(String, PrintWriter, PrintWriter) method runs a process inside of a watched thread. It returns the client's exit code and feeds its STDOUT and STDERR to the passed-in streams.

Parameters:

command - The program or command to run

stdoutWriter - java.io.PrintWriter

stderrWriter - java.io.PrintWriter

Returns:

The command's return code

Throws:

IOException - thrown if a problem occurs

InterruptedException - thrown if a problem occurs

getErrString

public String getErrString()

Returns the error string if exec(String) was invoked.

Returns:

The error string if exec(String) was invoked.

isMaxRunTimeExceeded

public boolean isMaxRunTimeExceeded()

Returns whether the maximum runtime was exceeded or not.

Returns:

boolean indicating whether the maximum runtime was exceeded or not.

getMaxRunTimeSecs

public int getMaxRunTimeSecs()

Returns the maximum run time in seconds for this object.

Returns:

the maximum run time in seconds for this object.

getOutString

public String getOutString()

Returns the output string if exec(String) was invoked.

Returns:

The output string if exec(String) was invoked.

main

public static void main(String[] args)
                 throws IOException

This is for unit testing of the class.

Parameters:

args - an array of command-line arguments

Throws:

IOException - thrown if a problem occurs

setMaxRunTimeSecs

public void setMaxRunTimeSecs(int max)

Sets the maximum run time in seconds. If you do not want to limit the executable's run time, simply pass in a 0 (which is also the default).

Parameters:

max - Maximim number of seconds to let program run