Module ibm.jzos
Package com.ibm.jzos

Class Exec

java.lang.Object
com.ibm.jzos.Exec
public class Exec extends 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

    Fields
    Modifier and Type
    Field
    Description
    static final String
    CHILD_PROCESS_INPUT_ENCODING_PROPERTY
     

  • Constructor Summary

    Constructors
    Constructor
    Description
    Exec(String command)
    Construct an instance.
    Exec(String[] cmdargs)
    Construct an instance with a tokenized command.
    Exec(String[] cmdargs, String[] envp)
    Construct an instance with a tokenized command and environment.
    Exec(String[] cmdargs, String[] envp, File dir)
    Construct an instance with a tokenzied command, environment and working dir
    Exec(String command, String[] envp)
    Construct an instance with a given command and environment.
    Exec(String command, String[] envp, File dir)
    Construct an instance with a given command, environment, and working directory.

  • Method Summary

    Modifier and Type
    Method
    Description
    void
    consumeOutput()
    Convenience method to drain the external process stdout lines.
    void
    consumeOutput(StringBuffer buf)
    Convenience method to read the external process stdout lines into the supplied StringBuffer.
    static String
    getChildProcessInputEncoding()
    Return the default encoding to use for sending data to child process's stdin stream.
    List<String>
    getErrorLines()
    Answer the error lines buffered from the external process.
    int
    getMaxErrorLines()
    Answer the current maxErrorLines setting.
    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.
    OutputStream
    getStdinStream()
    Answer an OutputStream which is connected to the stdin input of the external process.
    BufferedWriter
    getStdinWriter()
    Return a BufferedWriter to the child's stdin.
    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(String[] args)
    An example main method for launching a command from main args
    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

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

  • Field Details

    • CHILD_PROCESS_INPUT_ENCODING_PROPERTY

      public static final String CHILD_PROCESS_INPUT_ENCODING_PROPERTY
      See Also:

  • Constructor Details

  • Method Details

    • main

      public static void main(String[] args) throws IOException
      An example main method for launching a command from main args
      Parameters:
      args - the command to run
      Throws:
      IOException

    • getChildProcessInputEncoding

      public static 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:

      • If the System property "com.ibm.jzos.Exec.input.encoding", use it.
      • Otherwise, if running on SDK 1.4, use the codepage for the current locale
      • Otherwise, use the "file.encoding" System property, since SDK5 SR3 will then transcode from file.encoding to the console.encoding (EBCDIC).

    • getErrorLines

      public List<String> 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 OutputStream getStdinStream()
      Answer an OutputStream which is connected to the stdin input of the external process.

    • getStdinWriter

      public 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:

    • 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(StringBuffer buf) throws 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:
      IOException

    • consumeOutput

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

    • readLine

      public String readLine() throws 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:
      IOException

    • getOutputReader

      public 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 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 IOException
      Create (and start) the Runtime.exec process. Also start the health timer and stderr consumer thread.
      Throws:
      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.