OpenNMS API 1.2.9

## org.opennms.netmgt.utils
Class ExecRunner

    java.lang.Object
      org.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 1199 2004-11-21 03:31:16Z brozow $
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.9

Generated by ranger on May 19 2007 2335.