com.zaxxer.nuprocess

Interface NuProcessHandler

All Known Implementing Classes:

NuAbstractCharsetHandler, NuAbstractProcessHandler

public interface NuProcessHandler

Executors of a NuProcess must provide an implementation of this class to the ProcessBuilder prior to calling ProcessBuilder.start() . This interface provides the primary means of asynchronous interaction between the running child process and your code.

Methods specified by this interface will be invoked by the asynchronous processing thread. It is up to the implementation of this interface to handle the resulting state changes or process the data passed to it.

Note that the processing thread that executes these callbacks on behalf of a NuProcess is the same thread that handles processing for other instances of NuProcess, and as a result you should never perform a blocking or time-consuming operation on the callback thread. Doing so will block or severely hinder the processing of other NuProcess instances. Any operation that requires more than single-digit millisecond processing should be handed off to another thread so that the processing thread can return to immediately service other NuProcess instances.

Author:

Brett Wooldridge

Method Summary

Modifier and Type	Method and Description
void	onExit(int exitCode) This method is invoked when the process exits.
void	onPreStart(NuProcess nuProcess) This method is invoked when you call the ProcessBuilder.start() method.
void	onStart(NuProcess nuProcess) This method is invoked when you call the ProcessBuilder.start() method.
void	onStderr(ByteBuffer buffer, boolean closed) This method is invoked when there is stderr data to process or an the end-of-file (EOF) condition has been reached.
boolean	onStdinReady(ByteBuffer buffer) This method is invoked after you have expressed a desire to write to stdin by first calling NuProcess.wantWrite().
void	onStdout(ByteBuffer buffer, boolean closed) This method is invoked when there is stdout data to process or an the end-of-file (EOF) condition has been reached.

Method Detail

onPreStart

void onPreStart(NuProcess nuProcess)

This method is invoked when you call the ProcessBuilder.start() method. This is an opportunity to store away the NuProcess instance, possibly in your listener, so that it can be used for interaction within other callbacks in this interface.

Unlike the onStart(NuProcess) method, this method is invoked before the process is spawned, and is guaranteed to be invoked before any other methods are called.

Parameters:

nuProcess - The NuProcess that is starting. Note that the instance is not yet initialized, so it is not legal to call any of its methods, and doing so will result in undefined behavior. If you need to call any of the instance's methods, use onStart(NuProcess) instead.

onStart

void onStart(NuProcess nuProcess)

This method is invoked when you call the ProcessBuilder.start() method. This is an opportunity to store away the NuProcess instance, possibly in your listener, so that it can be used for interaction within other callbacks in this interface.

Note that this method is called at some point after the process is spawned. It is possible for other methods (even onExit(int)) to be called first. If you need a guarantee that no other methods will be called first, use onPreStart(NuProcess) instead.

Parameters:

nuProcess - the NuProcess that is starting

onExit

void onExit(int exitCode)

This method is invoked when the process exits. This method is also invoked immediately in the case of a failure to launch the child process.

There are two special values, besides ordinary process exit codes, that may be passed to this method. A value of Integer.MIN_VALUE indicates some kind of launch failure. A value of Integer.MAX_VALUE indicates an unknown or expected failure mode.

Parameters:

exitCode - the exit code of the process, or a special value indicating unexpected failures

onStdout

void onStdout(ByteBuffer buffer,
              boolean closed)

This method is invoked when there is stdout data to process or an the end-of-file (EOF) condition has been reached. In the case of EOF, the closed parameter will be true; this is your signal that EOF has been reached.

You do not own the ByteBuffer provided to you. You should not retain a reference to this buffer.

Upon returning from this method, if any bytes are left in the buffer (i.e., buffer.hasRemaining() returns true), then the buffer will be compacted after returning. Any unused data will be kept at the start of the buffer and passed back to you as part of the next invocation of this method (which might be when EOF is reached and closed is true).

Exceptions thrown out from your method will be ignored, but your method should handle all exceptions itself.

Parameters:

buffer - a ByteBuffer containing received stdout data

closed - true if EOF has been reached

onStderr

void onStderr(ByteBuffer buffer,
              boolean closed)

This method is invoked when there is stderr data to process or an the end-of-file (EOF) condition has been reached. In the case of EOF, the closed parameter will be true; this is your signal that EOF has been reached.

You do not own the ByteBuffer provided to you. You should not retain a reference to this buffer.

Upon returning from this method, if any bytes are left in the buffer (i.e., buffer.hasRemaining() returns true), then the buffer will be compacted after returning. Any unused data will be kept at the start of the buffer and passed back to you as part of the next invocation of this method (which might be when EOF is reached and closed is true).

Users wishing to merge stderr into stdout should simply delegate this callback to onStdout(ByteBuffer, boolean) when invoked, like so:

    public void onStderr(ByteBuffer buffer, closed) {
       if (!closed) {
          onStdout(buffer, closed);
       }
    }
 

Notice that an EOF check is performed. If you merge streams in this way, and you do not check for EOF here, then your onStdout(ByteBuffer, boolean) method will be called twice for an EOF condition; once when the stdout stream closes, and once when the stderr stream closes. If you check for EOF as above, your onStdout(ByteBuffer, boolean) method would only be called once (for the close of stdout).

Exceptions thrown out from your method will be ignored, but your method should handle all exceptions itself.

Parameters:

buffer - a ByteBuffer containing received stderr data

closed - true if EOF has been reached

onStdinReady

boolean onStdinReady(ByteBuffer buffer)

This method is invoked after you have expressed a desire to write to stdin by first calling NuProcess.wantWrite(). When this method is invoked, your code should write data to be sent to the stdin of the child process into the provided ByteBuffer. After writing data into the buffer your code must flip the buffer before returning.

If not all of the data needed to be written will fit in the provided buffer, this method can return true to indicate a desire to write more data. If there is no more data to be written at the time this method is invoked, then false should be returned from this method. It is always possible to call NuProcess.wantWrite() later if data becomes available to be written.

Parameters:

buffer - a ByteBuffer into which your stdin-bound data should be written

Returns:

true if you have more data to write immediately, false otherwise