org.netbeans.api.extexecution
Class ExternalProcessBuilder

java.lang.Object
  org.netbeans.api.extexecution.ExternalProcessBuilder

All Implemented Interfaces:

Callable<Process>

public final class ExternalProcessBuilder
extends Object
implements Callable<Process>

Utility class to make the external process creation easier.

Builder handle command, working directory, PATH variable and HTTP proxy.

This class is immutable.

See Also:

call()

Constructor Summary

ExternalProcessBuilder(String executable)
Creates the new builder that will create the process by running given executable.

Method Summary

ExternalProcessBuilder	addArgument(String argument) Returns a builder with additional argument for the command.
ExternalProcessBuilder	addEnvironmentVariable(String name, String value) Returns a builder with additional environment variable for the command.
Process	call() Creates the new Process based on the properties configured in this builder.
ExternalProcessBuilder	prependPath(File path) Returns a builder with additional path in PATH variable.
ExternalProcessBuilder	redirectErrorStream(boolean redirectErrorStream) Returns a builder with configured error stream redirection.
ExternalProcessBuilder	workingDirectory(File workingDirectory) Returns a builder with configured working directory.

Methods inherited from class java.lang.Object

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

Constructor Detail

ExternalProcessBuilder

public ExternalProcessBuilder(@NonNull
                              String executable)

Creates the new builder that will create the process by running given executable. Arguments must not be part of the string.

Parameters:

executable - executable to run

Method Detail

workingDirectory

@NonNull
@CheckReturnValue
public ExternalProcessBuilder workingDirectory(@NonNull
                                                                        File workingDirectory)

Returns a builder with configured working directory. Process subsequently created by the call() method on returned builder will be executed with this directory as current working dir.

The default value is undefined. Note that in such case each process has working directory corresponding to the value of user.dir system property.

All other properties of the returned builder are inherited from this.

Parameters:

workingDirectory - working directory

Returns:

new builder with configured working directory

redirectErrorStream

@NonNull
@CheckReturnValue
public ExternalProcessBuilder redirectErrorStream(boolean redirectErrorStream)

Returns a builder with configured error stream redirection. If configured value is true process subsequently created by the call() method on returned builder will redirect the error stream to the standard output stream.

The default value is false.

All other properties of the returned builder are inherited from this.

Parameters:

redirectErrorStream - if true error stream will be redirected to standard output

Returns:

new builder with configured error stream redirection

prependPath

@NonNull
@CheckReturnValue
public ExternalProcessBuilder prependPath(@NonNull
                                                                   File path)

Returns a builder with additional path in PATH variable.

In the group of paths added by this call the last added path will be the first one in the PATH variable.

By default no additional paths are added to PATH variable.

All other properties of the returned builder are inherited from this.

Parameters:

path - path to add to PATH variable

Returns:

new builder with additional path in PATH variable

addArgument

@NonNull
@CheckReturnValue
public ExternalProcessBuilder addArgument(@NonNull
                                                                   String argument)

Returns a builder with additional argument for the command. Arguments are passed to executable in the same order in which they are added.

By default no additional arguments are passed to executable.

All other properties of the returned builder are inherited from this.

If there is a need to parse arguments already provided as one big string the method that can help is Utilities.parseParameters(java.lang.String).

Parameters:

argument - command argument to add

Returns:

new builder with additional argument for the command

addEnvironmentVariable

@NonNull
@CheckReturnValue
public ExternalProcessBuilder addEnvironmentVariable(@NonNull
                                                                              String name,
                                                                              @NonNull
                                                                              String value)

Returns a builder with additional environment variable for the command.

By default no additional environment variables are configured.

All other properties of the returned builder are inherited from this.

Parameters:

name - name of the variable

value - value of the variable

Returns:

new builder with additional environment variable for the command

See Also:

call()

call

@NonNull
public Process call()
             throws IOException

Creates the new Process based on the properties configured in this builder. Created process will try to kill all its children on call to Process.destroy().

Process is created by executing the executable with configured arguments. If custom working directory is specified it is used otherwise value of system property user.dir is used as working dir.

Environment variables are prepared in following way:

1. Get table of system environment variables.
2. Put all environment variables configured by addEnvironmentVariable(java.lang.String, java.lang.String). This rewrites system variables if conflict occurs.
3. Get PATH variable and append all paths added by prependPath(java.io.File). The order of paths in PATH variable is reversed to order of addition (the last added is the first one in PATH). Original content of PATH follows the added content.
4. If neither http_proxy nor HTTP_PROXY environment variable is set then HTTP proxy settings configured in the IDE are stored as http_proxy environment variable (the format of the value is http://username:password@host:port).

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