com.ibm.jzos
Class Exec

java.lang.Object
  extended by com.ibm.jzos.Exec

public class Exec
extends java.lang.Object

Class for running an external process that buffers output, provides timeout control and stdout/stderr character encoding.

The process' error output is buffered in a separate thread to keep the process from blocking and timing out.

Process flow:

  1. Create an instance of the class via one of the Runtime.exec(java.lang.String) style constructors.
  2. Run the process via run()
  3. Read the process stdout via readLine() until EOF is encountered
  4. Retrieve the process return code via getReturnCode(). This step is necessary to join the stderr thread.
  5. (optional) Read and process the buffered stderr output via getErrorLines()
This class is simply a wrapper/helper for java.lang.Runtime.exec().

For an example see: main(String[])


Field Summary
static java.lang.String CHILD_PROCESS_INPUT_ENCODING_PROPERTY
           
 
Constructor Summary
Exec(java.lang.String command)
          Construct an instance.
Exec(java.lang.String[] cmdargs)
          Construct an instance with a tokenized command.
Exec(java.lang.String[] cmdargs, java.lang.String[] envp)
          Construct an instance with a tokenized command and environment.
Exec(java.lang.String[] cmdargs, java.lang.String[] envp, java.io.File dir)
          Construct an instance with a tokenzied command, environment and working dir
Exec(java.lang.String command, java.lang.String[] envp)
          Construct an instance with a given commmand and environment.
Exec(java.lang.String command, java.lang.String[] envp, java.io.File dir)
          Construct an instance with a given command, environment, and working directory.
 
Method Summary
 void consumeOutput()
          Convenience method to drain the external process stdout lines.
 void consumeOutput(java.lang.StringBuffer buf)
          Convenience method to read the external process stdout lines into the supplied StringBuffer.
static java.lang.String getChildProcessInputEncoding()
          Return the default encoding to use for sending data to child process's stdin stream.
 java.util.List getErrorLines()
          Answer the error lines buffered from the external process.
 int getMaxErrorLines()
          Answer the current maxErrorLines setting.
 java.io.BufferedReader getOutputReader()
          Return a BufferedReader on the external process stdout stream.
 int getReturnCode()
          Once all output is read (stderr and stdout), this method is called to wait for the process to complete and retrieve the exit value.
 java.io.OutputStream getStdinStream()
          Answer an OutputStream which is connected to the stdin input of the external process.
 java.io.BufferedWriter getStdinWriter()
          Return a BufferedWriter to the child's stdin.
 java.io.InputStream getStdoutStream()
          Return an InputStream on the external process stdout stream.
 boolean isDestroyed()
          Answer true if the external process has been destroyed.
 boolean isTimedOut()
          Answer true if the external process was destroyed due to timeout.
static void main(java.lang.String[] args)
          An example main method for launching a command from main args
 java.lang.String readLine()
          Reads a line from the external process stdout stream.
 void run()
          Create (and start) the Runtime.exec process.
 void setMaxErrorLines(int maxErrorLines)
          Set the limit for how many of the external process stderr lines will be kept.
 void setTimeout(int timeout)
          Sets the length of time, in milliseconds, to wait for the external process if no response (stdout or stderr) is received.
 void updateHealthTimer()
          Reset the health timer for the external process.
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Field Detail

CHILD_PROCESS_INPUT_ENCODING_PROPERTY

public static final java.lang.String CHILD_PROCESS_INPUT_ENCODING_PROPERTY
See Also:
Constant Field Values
Constructor Detail

Exec

public Exec(java.lang.String command)
Construct an instance.

See Also:
Runtime.exec(java.lang.String)

Exec

public Exec(java.lang.String command,
            java.lang.String[] envp)
Construct an instance with a given commmand and environment.

See Also:
Runtime.exec(java.lang.String, java.lang.String[])

Exec

public Exec(java.lang.String command,
            java.lang.String[] envp,
            java.io.File dir)
Construct an instance with a given command, environment, and working directory.

See Also:
Runtime.exec(java.lang.String, java.lang.String[], java.io.File)

Exec

public Exec(java.lang.String[] cmdargs)
Construct an instance with a tokenized command.

See Also:
Runtime.exec(java.lang.String[])

Exec

public Exec(java.lang.String[] cmdargs,
            java.lang.String[] envp)
Construct an instance with a tokenized command and environment.

See Also:
Runtime.exec(java.lang.String[], java.lang.String[])

Exec

public Exec(java.lang.String[] cmdargs,
            java.lang.String[] envp,
            java.io.File dir)
Construct an instance with a tokenzied command, environment and working dir

See Also:
Runtime.exec(java.lang.String[], java.lang.String[], java.io.File)
Method Detail

main

public static void main(java.lang.String[] args)
                 throws java.io.IOException
An example main method for launching a command from main args

Parameters:
args - the command to run
Throws:
java.io.IOException

getChildProcessInputEncoding

public static java.lang.String getChildProcessInputEncoding()
Return the default encoding to use for sending data to child process's stdin stream.

SDKs prior to Java 5.0 SR3 should use ZUtil.getCodePageCurrentLocale() whereas later SDKs should use the default JVM file.encoding since automatic transcoding of the child stdin data is done by Runtime.exec().

This method returns the encoding to use:


getErrorLines

public java.util.List getErrorLines()
Answer the error lines buffered from the external process. The size of this list is limited by the maxLines threshold.


setMaxErrorLines

public void setMaxErrorLines(int maxErrorLines)
Set the limit for how many of the external process stderr lines will be kept.

Parameters:
maxErrorLines - maximum lines to keep. Zero sets no limit.

getMaxErrorLines

public int getMaxErrorLines()
Answer the current maxErrorLines setting.


getReturnCode

public int getReturnCode()
Once all output is read (stderr and stdout), this method is called to wait for the process to complete and retrieve the exit value. This code is a little tricky because process.exitValue() sometimes throws an exeception even when it's supposed to be complete.

Returns:
the external process return code

getStdinStream

public java.io.OutputStream getStdinStream()
Answer an OutputStream which is connected to the stdin input of the external process.


getStdinWriter

public java.io.BufferedWriter getStdinWriter()
Return a BufferedWriter to the child's stdin. The encoding for this stream

This method should not be used while also using getStdinStream() directly.

See Also:
getChildProcessInputEncoding()

setTimeout

public void setTimeout(int timeout)
Sets the length of time, in milliseconds, to wait for the external process if no response (stdout or stderr) is received. If this timeout is exceeded, the process will be killed.

Parameters:
timeout - millisecond timeout. Zero disables timeout checking.

consumeOutput

public void consumeOutput(java.lang.StringBuffer buf)
                   throws java.io.IOException
Convenience method to read the external process stdout lines into the supplied StringBuffer. This method blocks until EOF has been reached on the stdout stream.

Parameters:
buf - The buffer to hold the stdout lines.
Throws:
java.io.IOException

consumeOutput

public void consumeOutput()
                   throws java.io.IOException
Convenience method to drain the external process stdout lines. This method blocks until EOF has been reached on the stdout stream.

Throws:
java.io.IOException

readLine

public java.lang.String readLine()
                          throws java.io.IOException
Reads a line from the external process stdout stream.

After each line is read, the timeout health time is updated

Returns:
the line, or null of EOF has been reached.
Throws:
java.io.IOException

getOutputReader

public java.io.BufferedReader getOutputReader()
Return a BufferedReader on the external process stdout stream. This reader is encoded with the current platform locale codepage.

This method should not be used while also using getStdoutStream() directly.


getStdoutStream

public java.io.InputStream getStdoutStream()
Return an InputStream on the external process stdout stream.

This method should not be used in combination with getOutputReader().

Returns:
the input stream.

isDestroyed

public boolean isDestroyed()
Answer true if the external process has been destroyed.


isTimedOut

public boolean isTimedOut()
Answer true if the external process was destroyed due to timeout.


run

public void run()
         throws java.io.IOException
Create (and start) the Runtime.exec process. Also start the health timer and stderr consumer thread.

Throws:
java.io.IOException

updateHealthTimer

public void updateHealthTimer()
Reset the health timer for the external process. This will defer a timeout condition until the timeout interval is reached without any subsequent output from the external process.