Overview | Package | Class | Tree | Deprecated | Index | Help
PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD

## com.ibm.jzos
Class Exec

    java.lang.Object
      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:

  - 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 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.

Overview | Package | Class | Tree | Deprecated | Index | Help
PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD