public interface NuProcess
NuProcessBuilder.start()
method creates a native process and
returns an instance of a platform-specific implementation of
NuProcess
that can be used to control the process and obtain
information about it. The NuProcess
interface provides methods for
expressing desire to perform output to the process, waiting for the process
to complete, checking the status of the process, and destroying (killing) the
process.
The methods that create processes may not work well for special processes on certain native platforms, such as native windowing processes, daemon processes, Win16/DOS processes on Microsoft Windows, or shell scripts.
See the NuProcessHandler
interface for asynchronous callbacks related
to start, exit, and input/output notifications and operations for the
process.
Modifier and Type | Field and Description |
---|---|
static int |
BUFFER_CAPACITY |
Modifier and Type | Method and Description |
---|---|
void |
closeStdin()
This method is used to close the STDIN pipe between the Java process and
the spawned process.
|
void |
destroy(boolean force)
Terminates the process.
If force is false , the process will be terminated
gracefully (i.e. |
boolean |
hasPendingWrites()
This method is most useful in combination with
writeStdin(java.nio.ByteBuffer) . |
boolean |
isRunning()
Tests whether or not the process is still running or has exited.
|
void |
setProcessHandler(NuProcessHandler processHandler)
Sets a new process handler for this
NuProcess instance. |
int |
waitFor(long timeout,
TimeUnit timeUnit)
Waits for the process to exit in a blocking fashion.
|
void |
wantWrite()
Express a desire to write data to the STDIN stream of the process.
|
void |
writeStdin(ByteBuffer buffer)
Performs a "direct write" rather than expressing a desire to write using
wantWrite() and performing the write in a callback. |
static final int BUFFER_CAPACITY
int waitFor(long timeout, TimeUnit timeUnit) throws InterruptedException
NuProcessHandler.onExit(int)
for the non-blocking method process exit
notification and exit code retrieval. If the process is terminated by the
destroy(boolean)
method, the exit code is non-deterministic.timeout
- a timeout value, 0 indicates an infinite waittimeUnit
- the unit of time indicator for the timeout valueInteger.MIN_VALUE
if the
timeout is reachedInterruptedException
- thrown if the thread is interrupted while
waitingvoid wantWrite()
NuProcessHandler.onStdinReady(java.nio.ByteBuffer)
callback method of the process handler being called when space is
available in the STDIN pipe.
This method will throw a IllegalStateException
if the
closeStdin()
method has already been called.
void writeStdin(ByteBuffer buffer)
wantWrite()
and performing the write in a callback. Be careful
mixing this paradigm with the asynchronous paradigm imposed by
wantWrite()
.
This method returns immediately and the write of the data occurs on the
asynchronous processing thread. You can perform multiple
writeStdin()
calls without regard to the size of the interprocess
pipe; the writes will be queued and written asynchronously as space is
available in the pipe.
Note that if the client process is not pulling data out of the pipe, calling this method repeatedly will result is the accumulation of unwritten ByteBuffers in the Java process and possibly an eventual out of memory condition.
Using a Direct ByteBuffer will provide performance improvements. Note that
NuProcess will not flip the buffer for you; after writing your data into
the buffer
you must flip the buffer before returning from this
method.
buffer
- the ByteBuffer
to write to the STDIN stream of the
processvoid closeStdin()
boolean hasPendingWrites()
writeStdin(java.nio.ByteBuffer)
. This
method returns true if there is outstanding data to be written to the
stdin stream, and false if there are no pending writes.true
if there are pending writes, false
otherwisevoid destroy(boolean force)
force
is false
, the process will be terminated
gracefully (i.e. its shutdown logic will be allowed to execute), assuming
the OS supports such behavior. Note that the process may not actually
terminate, as its cleanup logic may fail or it may choose to ignore the
termination request. If a guarantee of termination is required, call this
method with force
equal to true
instead.
You can also call waitFor(long, TimeUnit)
after calling this
method with force=false
, to give the process an opportunity to
terminate gracefully. If the timeout expires, you can then call this
method again with force=true
to ensure the process is terminated.
If force
is true, the process is guaranteed to terminate, but
whether it is terminated gracefully or not is OS-dependent. Note that it
may take the OS a moment to terminate the process, so isRunning()
may return true for a brief period after calling this method. You can use
waitFor(long, TimeUnit)
if you want to wait until the process has
actually been terminated.
When this method is called with force, the exit code returned by
waitFor(long, java.util.concurrent.TimeUnit)
or passed to the NuProcessHandler.onExit(int)
callback
method is non-deterministic.
force
- if true
is passed, the process will be forcibly
killedboolean isRunning()
void setProcessHandler(NuProcessHandler processHandler)
NuProcess
instance. This
method is only safe to call from within one of the callback methods of the
existing NuProcessHandler
.processHandler
- the new NuProcessHandler
Copyright © 2015 Zaxxer.com. All rights reserved.