OpenNMS API 1.2.3

org.opennms.netmgt.utils
Class ExecRunner

java.lang.Object
  extended byorg.opennms.netmgt.utils.ExecRunner

public class ExecRunner
extends java.lang.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".

Version:
CVS $Id: ExecRunner.java,v 1.5 2004/11/21 03:31:19 brozow Exp $
Author:
Scott McCrory .

Field Summary
private static java.lang.String CLASS_NAME
          The name of this class for logging *
private  java.lang.String err
          String to capture STDERR *
private static java.lang.String MAX_RUN_TIME_EXCEEDED_STRING
          String to send to STDERR if program exceeds max run time *
private  boolean maxRunTimeExceeded
          Flag to indicate if we've exceeded max run time *
private  int maxRunTimeSecs
          Default max run time (in seconds) *
private  java.lang.String out
          String to capture STDOUT *
private static int POLL_DELAY_MS
          Number of miliseconds to wait between polling watched thread *
private static java.lang.String VERSION
          The version of this class (filled in by CVS) *
private static java.lang.String WINDOWS_9X_ME_COMMAND_1
          Win 9X/MEHome require cmd.exe to run programs *
private static java.lang.String WINDOWS_9X_ME_COMMAND_2
          Win 9X/MEHome require the /C to specify what to run *
private static java.lang.String WINDOWS_NT_2000_COMMAND_1
          Win NT/2K/MEPro require cmd.exe to run programs *
private static java.lang.String WINDOWS_NT_2000_COMMAND_2
          Win NT/2K/MEPro require the /C to specify what to run *
 
Constructor Summary
ExecRunner()
          Basic ExecRunner constructor.
ExecRunner(java.lang.String command)
          ExecRunner constructor which also conveniently runs exec(String).
 
Method Summary
 java.lang.Object clone()
          We override the clone method here to prevent cloning of our class.
 int exec(java.lang.String command)
          The exec(String) method runs a process inside of a watched thread.
 int exec(java.lang.String command, java.io.OutputStream stdoutStream, java.io.OutputStream stderrStream)
          Convenience method for calling exec with OutputStreams.
 int exec(java.lang.String command, java.io.PrintWriter stdoutWriter, java.io.PrintWriter stderrWriter)
          The exec(String, PrintWriter, PrintWriter) method runs a process inside of a watched thread.
 java.lang.String getErrString()
          Returns the error string if exec(String) was invoked.
 int getMaxRunTimeSecs()
          Returns the maximum run time in seconds for this object.
 java.lang.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(java.lang.String[] args)
          This is for unit testing of the class.
private  void readObject(java.io.ObjectInputStream in)
          We override the readObject method here to prevent deserialization of our class for security reasons.
 void setMaxRunTimeSecs(int max)
          Sets the maximum run time in seconds.
private  void writeObject(java.io.ObjectOutputStream out)
          We override the writeObject method here to prevent serialization of our class for security reasons.
 
Methods inherited from class java.lang.Object
equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Field Detail

WINDOWS_NT_2000_COMMAND_1

private static final java.lang.String WINDOWS_NT_2000_COMMAND_1
Win NT/2K/MEPro require cmd.exe to run programs *

See Also:
Constant Field Values

WINDOWS_NT_2000_COMMAND_2

private static final java.lang.String WINDOWS_NT_2000_COMMAND_2
Win NT/2K/MEPro require the /C to specify what to run *

See Also:
Constant Field Values

WINDOWS_9X_ME_COMMAND_1

private static final java.lang.String WINDOWS_9X_ME_COMMAND_1
Win 9X/MEHome require cmd.exe to run programs *

See Also:
Constant Field Values

WINDOWS_9X_ME_COMMAND_2

private static final java.lang.String WINDOWS_9X_ME_COMMAND_2
Win 9X/MEHome require the /C to specify what to run *

See Also:
Constant Field Values

MAX_RUN_TIME_EXCEEDED_STRING

private static final java.lang.String MAX_RUN_TIME_EXCEEDED_STRING
String to send to STDERR if program exceeds max run time *

See Also:
Constant Field Values

out

private java.lang.String out
String to capture STDOUT *


err

private java.lang.String err
String to capture STDERR *


maxRunTimeSecs

private int maxRunTimeSecs
Default max run time (in seconds) *


maxRunTimeExceeded

private boolean maxRunTimeExceeded
Flag to indicate if we've exceeded max run time *


CLASS_NAME

private static final java.lang.String CLASS_NAME
The name of this class for logging *

See Also:
Constant Field Values

VERSION

private static final java.lang.String VERSION
The version of this class (filled in by CVS) *

See Also:
Constant Field Values

POLL_DELAY_MS

private static final int POLL_DELAY_MS
Number of miliseconds to wait between polling watched thread *

See Also:
Constant Field Values
Constructor Detail

ExecRunner

public ExecRunner()
Basic ExecRunner constructor.


ExecRunner

public ExecRunner(java.lang.String command)
           throws java.lang.ExceptionInInitializerError
ExecRunner constructor which also conveniently runs exec(String).

Parameters:
command - The program or command to run
Throws:
java.lang.ExceptionInInitializerError - thrown if a problem occurs
Method Detail

clone

public final java.lang.Object clone()
                             throws java.lang.CloneNotSupportedException
We override the clone method here to prevent cloning of our class.

Returns:
Nothing ever really returned since we throw a CloneNotSupportedException
Throws:
java.lang.CloneNotSupportedException - To indicate cloning is not allowed

exec

public int exec(java.lang.String command)
         throws java.io.IOException,
                java.lang.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 (Exception 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:
java.io.IOException - thrown if a problem occurs
java.lang.InterruptedException - thrown if a problem occurs

exec

public int exec(java.lang.String command,
                java.io.OutputStream stdoutStream,
                java.io.OutputStream stderrStream)
         throws java.io.IOException,
                java.lang.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:
java.io.IOException - thrown if a problem occurs
java.lang.InterruptedException - thrown if a problem occurs

exec

public int exec(java.lang.String command,
                java.io.PrintWriter stdoutWriter,
                java.io.PrintWriter stderrWriter)
         throws java.io.IOException,
                java.lang.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:
java.io.IOException - thrown if a problem occurs
java.lang.InterruptedException - thrown if a problem occurs

getErrString

public java.lang.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 java.lang.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(java.lang.String[] args)
                 throws java.io.IOException
This is for unit testing of the class.

Parameters:
args - an array of command-line arguments
Throws:
java.io.IOException - thrown if a problem occurs

readObject

private final void readObject(java.io.ObjectInputStream in)
                       throws java.io.IOException
We override the readObject method here to prevent deserialization of our class for security reasons.

Parameters:
in - java.io.ObjectInputStream
Throws:
java.io.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

writeObject

private final void writeObject(java.io.ObjectOutputStream out)
                        throws java.io.IOException
We override the writeObject method here to prevent serialization of our class for security reasons.

Parameters:
out - java.io.ObjectOutputStream
Throws:
java.io.IOException - thrown if a problem occurs

OpenNMS API 1.2.3

Generated by eevans on May 29 2005 2015.