org.netbeans.api.extexecution.base

Class ProcessBuilder

java.lang.Object

org.netbeans.api.extexecution.base.ProcessBuilder

All Implemented Interfaces:

Callable<Process>, Lookup.Provider

public final class ProcessBuilder
extends Object
implements Callable<Process>, Lookup.Provider

Abstraction of process builders. You can freely configure the parameters and then create a process by calling the ProcessBuilder.call() method. You can also (re)configure the builder and spawn a different process.

Note the API does not prescribe the actual meaning of Process. It may be local process, remote process or some other implementation.

You can use the default implementation returned by ProcessBuilder.getLocal() for creating the local machine OS processes.

Thread safety of this class depends on thread safety of the implementation class.

If the ProcessBuilderImplementation is used and it is thread safe (if possible the implementation should be even stateless) this class is thread safe as well.

If the ProcessBuilderImplementation is used and it is (including EnvironmentImplementation) thread safe and does not have any mutable configuration accessible via ProcessBuilderImplementation.getLookup() it is thread safe as well. Otherwise it is not thread safe.

The synchronization mechanism used in this object is the ProcessBuilderImplementation object monitor.

Method Summary

Modifier and Type	Method and Description
Process	call() Creates the new Process based on the properties configured in this builder.
String	getDescription() Returns the human readable description of this builder.
Environment	getEnvironment() Returns the object for environment variables manipulation.
static ProcessBuilder	getLocal() Returns the ProcessBuilder creating the OS process on local machine.
Lookup	getLookup() Returns the associated Lookup.
void	setArguments(List<String> arguments) Sets the arguments passed to the process created by subsequent call of ProcessBuilder.call().
void	setExecutable(String executable) Sets the executable to run.
void	setRedirectErrorStream(boolean redirectErrorStream) Configures the error stream redirection.
void	setWorkingDirectory(String workingDirectory) Sets the working directory for the process created by subsequent call of ProcessBuilder.call().

Methods inherited from class java.lang.Object

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

Method Detail

getLocal

public static ProcessBuilder getLocal()

Returns the ProcessBuilder creating the OS process on local machine. Returned implementation is thread safe. The returned builder also attempts to properly configure HTTP proxy for the process.

Returns:

the ProcessBuilder creating the OS process on local machine

getDescription

@NonNull
public String getDescription()

Returns the human readable description of this builder.

Returns:

the human readable description of this builder

setExecutable

public void setExecutable(@NonNull
                          String executable)

Sets the executable to run. There is no default value. The ProcessBuilder.call() methods throws IllegalStateException when there is no executable configured.

Parameters:

executable - the executable to run

setWorkingDirectory

public void setWorkingDirectory(@NullAllowed
                                String workingDirectory)

Sets the working directory for the process created by subsequent call of ProcessBuilder.call(). The default value is implementation specific.

Parameters:

workingDirectory - the working directory of the process

setArguments

public void setArguments(@NonNull
                         List<String> arguments)

Sets the arguments passed to the process created by subsequent call of ProcessBuilder.call(). By default there are no arguments.

Parameters:

arguments - the arguments passed to the process

setRedirectErrorStream

public void setRedirectErrorStream(boolean redirectErrorStream)

Configures the error stream redirection. If true the error stream of process created by subsequent call of ProcessBuilder.call() method will be redirected to standard output stream.

Parameters:

redirectErrorStream - the error stream redirection

getEnvironment

@NonNull
public Environment getEnvironment()

Returns the object for environment variables manipulation.

Returns:

the object for environment variables manipulation

getLookup

public Lookup getLookup()

Returns the associated Lookup. Extension point provided by ProcessBuilderImplementation.

Specified by:

getLookup in interface Lookup.Provider

Returns:

the associated Lookup.

See Also:

ProcessBuilderImplementation.getLookup()

call

@NonNull
public Process call()
                      throws IOException

Creates the new Process based on the properties configured in this builder.

Actual behavior depends on the builder implementation, but it should respect all the properties configured on this builder.

Specified by:

call in interface Callable<Process>

Returns:

the new Process based on the properties configured in this builder

Throws:

IOException - if the process could not be created

IllegalStateException - if there is no executable configured by ProcessBuilder.setExecutable(java.lang.String)

See Also:

ProcessBuilderImplementation