org.netbeans.api.extexecution.base

Class ExplicitProcessParameters

java.lang.Object

org.netbeans.api.extexecution.base.ExplicitProcessParameters

public final class ExplicitProcessParameters
extends Object

Allows to augment or replace process parameters for a single execution action. The class is intended to be used by launchers which build parameters based on some persistent configuration (project, workspace) to allow additions, or replacements for a single execution only.

It is strongly recommended for any feature that performs execution of a process to support ExplicitProcessParameters, from a contextual Lookup, or at worst from Lookup.getDefault(). It will allow for future customizations and automation of the feature, enhancing the process launch for various environments, technologies etc.

Note: please refer also to StartupExtender API in the extexecution module, which contributes globally to launcher arguments.

Two groups of parameters are recognized: ExplicitProcessParameters.getLauncherArguments(), which should be passed first to the process (i.e. launcher parameters) and ExplicitProcessParameters.getArguments() that represent the ordinary process arguments.

For java applications when java executable is used to launch the application, or even Maven project (see below), the launcherArgs should correspond to VM arguments, and args correspond to the main class' arguments (passed to the main class). Additional environment variables can be specified.

If the object is marked as ExplicitProcessParameters.isArgReplacement(), the launcher implementor SHOULD replace all default or configured parameters with contents of this instruction. Both arguments and launcherArguments can have value null, which means "undefined": in that case, the relevant group of configured parameters should not be affected.

Since these parameters are passed externally, there's an utility method, ExplicitProcessParameters.buildExplicitParameters(org.openide.util.Lookup) that builds the explicit parameter instruction based on Lookup contents. The parameters are merged in the order of the configured rank and appearance (in the sort ascending order). The default rank is 0, which allows both append or prepend parameters. If an item's ExplicitProcessParameters.isArgReplacement() is true, all arguments collected so far are discarded.

If the combining algorithm is acceptable for the caller's purpose, the following pattern may be used to build the final command line:

// collect all instructions from the Lookup and build decorating parameters
ExplicitProcessParameters decorator = ExplicitProcessParameters.buildExplicitParameters(runContext);

ExplicitProcessParameters params = ExplicitProcessParameters.builder().
        // include project's (or pre-configured) application parameters
        args(getProjectAppParams()).
        // include project's (or pre-configured) VM parameters as launcher ones
        launcherArgs(getProjectVMParams()).
        
        // now combine with the decorating instructions: will append or reset args or launcher args
        combine(decorator).
        build();

// build a commandline for e.g. launcher or VM: include launcher args first
// then the fixed "middle part" (e.g. the main class name), then application arguments.
List<String> commandLine = params.getAllArguments("theMainClass");

This example will combine some args and extra args from project, or configuration with arguments passed from the runContext Lookup. Supposing that a Maven project module supports ExplicitProcessParameters (it does from version 2/2.144), the caller may influence or override the parameters passed to the maven exec:exec task (for Run action) this way:

   ActionProvider ap = ... ; // obtain ActionProvider from the project.
   ExplicitProcessParameters explicit = ExplicitProcessParameters.builder().
           launcherArg("-DvmArg2=2").
           arg("paramY").
      build();
   ap.invokeAction(ActionProvider.COMMAND_RUN, Lookups.fixed(explicit));
 

By default, args instruction(s) will discard the default parameters, so the above example will also ignore all application parameters provided in maven action mapping. The caller may, for example, want to just append parameters (i.e. list of files ?) and completely replace (default) VM parameters which may be unsuitable for the operation:

ExplicitProcessParameters override = ExplicitProcessParameters.builder().
        // override the default: do not append to the base ones, but discard them
        replaceLauncherArgs(true).
        // ... and insist on empty launcher args
        launcherArgs().
        // ... or some other specific one(s)
        launcherArgs("-Xmx1000m").
        
        // override the default: keep base application arguments
        replaceArgs(false).
        
        // and add file list
        args(files).
        build();

Note that multiple ExplicitProcessParameters instances may be added to the Lookup, acting as append or replacement for the parameters collected so far.

Since:

1.16

Nested Class Summary

Nested Classes

Modifier and Type	Class and Description
static class	ExplicitProcessParameters.Builder Builds the ExplicitProcessParameters instance.

Method Summary

Modifier and Type	Method and Description
static ExplicitProcessParameters.Builder	builder()
static ExplicitProcessParameters	buildExplicitParameters(Collection<? extends ExplicitProcessParameters> items) Merges individual instruction.
static ExplicitProcessParameters	buildExplicitParameters(Lookup context) Merges ExplicitProcessParameters instructions found in the Lookup.
static ExplicitProcessParameters	empty() Returns an empty instance of parameters that has no effect.
List<String>	getAllArguments(List<String> middle) Returns the argument lists merged.
List<String>	getAllArguments(String... middle) Returns the argument lists merged.
List<String>	getArguments() Returns the arguments to be passed.
Map<String,String>	getEnvironmentVariables() Returns a map of additional environment variables to be set for the process.
List<String>	getLauncherArguments() Returns the launcher arguments to be passed.
File	getWorkingDirectory() Returns working directory to be set for the process.
boolean	isArgReplacement() Instructs to replace arguments collected so far.
boolean	isEmpty() Returns true, if the instance has no effect when ExplicitProcessParameters.Builder.combine(org.netbeans.api.extexecution.base.ExplicitProcessParameters)d onto base parameters.
boolean	isLauncherArgReplacement() Instructs to replace launcher arguments collected so far.

Methods inherited from class java.lang.Object

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

Method Detail

empty

public static ExplicitProcessParameters empty()

Returns an empty instance of parameters that has no effect. DO NOT check for emptiness by equality or reference using the instance; use ExplicitProcessParameters.isEmpty().

Returns:

empty instance.

isEmpty

public boolean isEmpty()

Returns true, if the instance has no effect when ExplicitProcessParameters.Builder.combine(org.netbeans.api.extexecution.base.ExplicitProcessParameters)d onto base parameters.

Returns:

true, if no effect is expected.

getArguments

public List<String> getArguments()

Returns the arguments to be passed. Returns null if the object does not want to alter the argument list.

Returns:

arguments to be passed or null if the argument list should not be altered.

getLauncherArguments

public List<String> getLauncherArguments()

Returns the launcher arguments to be passed. Returns null if the object does not want to alter the argument list.

Returns:

arguments to be passed or null if the launcher argument list should not be altered.

isArgReplacement

public boolean isArgReplacement()

Instructs to replace arguments collected so far.

Returns:

true, if arguments collected should be discarded.

isLauncherArgReplacement

public boolean isLauncherArgReplacement()

Instructs to replace launcher arguments collected so far.

Returns:

true, if launcher arguments collected should be discarded.

getAllArguments

@NonNull
public List<String> getAllArguments(List<String> middle)

Returns the argument lists merged. Launcher arguments (if any) are passed first, followed by middle (if any), then (normal) arguments. The method is a convenience to build a complete command line for the launcher + command + command arguments.

Returns:

combined arguments.

getAllArguments

@NonNull
public List<String> getAllArguments(@NullAllowed
                                             String... middle)

Returns the argument lists merged. Launcher arguments (if any) are passed first, followed by middle (if any), then (normal) arguments. The method is a convenience to build a complete command line for the launcher + command + command arguments.

Returns:

combined arguments.

getWorkingDirectory

@CheckForNull
public File getWorkingDirectory()

Returns working directory to be set for the process.

Returns:

working directory, or nul

Since:

1.20

getEnvironmentVariables

@NonNull
public Map<String,String> getEnvironmentVariables()

Returns a map of additional environment variables to be set for the process. Always non-null. Values of existing environment variables are overridden. A null value of a variable should be interpreted as a removal of that variable from the environment.

Returns:

map of additional environment variables

Since:

1.20

buildExplicitParameters

@NonNull
public static ExplicitProcessParameters buildExplicitParameters(Lookup context)

Merges ExplicitProcessParameters instructions found in the Lookup. See ExplicitProcessParameters.buildExplicitParameters(java.util.Collection) for more details.

Parameters:

context - context for the execution

Returns:

merged instructions

buildExplicitParameters

public static ExplicitProcessParameters buildExplicitParameters(Collection<? extends ExplicitProcessParameters> items)

Merges individual instruction. This method serves as a convenience and uniform ("standard") methods to merge argument lists for process execution. Should be used whenever a process (build, run, tool, ...) is executed. If the feature diverges, it should document how it processes the ExplicitProcessParameters. It is strongly recommended to support explicit parameters in order to allow for customizations and automation.

Processes instructions in the order of ExplicitProcessParameters.Builder.position(int) and appearance. Whenever an item is flagged as a replacement, all arguments (launcher arguments) collected to that point are discarded. Item's arguments (launcher arguments) will become the only ones listed.

Note: if a replacement instruction and all the following (if any) have ExplicitProcessParameters.getArguments() null (= no change), the result will report no change. It is therefore possible to discard all contributions by appending a no-change replacement last.

Environment variables are overridden by newly set variables.

Parameters:

items - individual instructions.

Returns:

combined instructions.

builder

public static ExplicitProcessParameters.Builder builder()