com.zaxxer.nuprocess

Class NuAbstractProcessHandler

java.lang.Object

com.zaxxer.nuprocess.NuAbstractProcessHandler

All Implemented Interfaces:

NuProcessHandler

public abstract class NuAbstractProcessHandler
extends Object
implements NuProcessHandler

Convenience base class for a NuProcessHandler with default methods that can be overridden.

Author:

Brett Wooldridge

Constructor Summary

Constructors

Constructor and Description
NuAbstractProcessHandler()

Method Summary

Modifier and Type	Method and Description
void	onExit(int statusCode) 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.

Methods inherited from class java.lang.Object

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

Constructor Detail

NuAbstractProcessHandler

public NuAbstractProcessHandler()

Method Detail

onPreStart

public 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 NuProcessHandler.onStart(NuProcess) method, this method is invoked before the process is spawned, and is guaranteed to be invoked before any other methods are called.

Specified by:

onPreStart in interface NuProcessHandler

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 NuProcessHandler.onStart(NuProcess) instead.

onStart

public 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 NuProcessHandler.onExit(int)) to be called first. If you need a guarantee that no other methods will be called first, use NuProcessHandler.onPreStart(NuProcess) instead.

Specified by:

onStart in interface NuProcessHandler

Parameters:

nuProcess - the NuProcess that is starting

onExit

public void onExit(int statusCode)

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.

Specified by:

onExit in interface NuProcessHandler

Parameters:

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

onStdout

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

Specified by:

onStdout in interface NuProcessHandler

Parameters:

buffer - a ByteBuffer containing received stdout data

closed - true if EOF has been reached

onStderr

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

Specified by:

onStderr in interface NuProcessHandler

Parameters:

buffer - a ByteBuffer containing received stderr data

closed - true if EOF has been reached

onStdinReady

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

Specified by:

onStdinReady in interface NuProcessHandler

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