org.netbeans.api.extexecution

Class ExecutionDescriptor

java.lang.Object

org.netbeans.api.extexecution.ExecutionDescriptor

public final class ExecutionDescriptor
extends Object

Descriptor for the execution environment. Describes the runtime attributes of the ExecutionService.

Thread safety of this class depends on type of objects passed to its configuration methods. If these objects are immutable, resulting descriptor is immutable as well. It these objects are thread safe, resulting descriptor is thread safe as well.

See Also:

ExecutionService

Nested Class Summary

Nested Classes

Modifier and Type	Class and Description
static interface	ExecutionDescriptor.InputProcessorFactory Factory creating the input processor.
static interface	ExecutionDescriptor.LineConvertorFactory Factory creating the line covertor.
static interface	ExecutionDescriptor.RerunCondition Represents the possibility of reruning the action.

Constructor Summary

Constructors

Constructor and Description
ExecutionDescriptor() Creates the new descriptor.

Method Summary

Methods

Modifier and Type	Method and Description
ExecutionDescriptor	charset(Charset charset) Returns a descriptor with configured charset.
ExecutionDescriptor	controllable(boolean controllable) Returns a descriptor with configured controllable flag.
ExecutionDescriptor	errConvertorFactory(ExecutionDescriptor.LineConvertorFactory convertorFactory) Returns a descriptor with configured factory for convertor for standard error output.
ExecutionDescriptor	errLineBased(boolean errLineBased) Returns a descriptor with configured flag indicating line based standard error output.
ExecutionDescriptor	errProcessorFactory(ExecutionDescriptor.InputProcessorFactory errProcessorFactory) Returns a descriptor with configured factory for standard error output processor.
ExecutionDescriptor	frontWindow(boolean frontWindow) Returns a descriptor with configured front window flag.
ExecutionDescriptor	frontWindowOnError(boolean frontWindowOnError) Returns a descriptor with configured front window on error flag.
ExecutionDescriptor	inputOutput(InputOutput io) Returns a descriptor with configured custom io.
ExecutionDescriptor	inputVisible(boolean inputVisible) Returns a descriptor with configured input visible flag.
ExecutionDescriptor	noReset(boolean noReset) Returns a descriptor with configured no reset flag.
ExecutionDescriptor	optionsPath(String optionsPath) Returns a descriptor with configured options path.
ExecutionDescriptor	outConvertorFactory(ExecutionDescriptor.LineConvertorFactory convertorFactory) Returns a descriptor with configured factory for convertor for standard output.
ExecutionDescriptor	outLineBased(boolean outLineBased) Returns a descriptor with configured flag indicating line based standard output.
ExecutionDescriptor	outProcessorFactory(ExecutionDescriptor.InputProcessorFactory outProcessorFactory) Returns a descriptor with configured factory for standard output processor.
ExecutionDescriptor	postExecution(Runnable postExecution) Returns a descriptor with configured post execution runnable.
ExecutionDescriptor	preExecution(Runnable preExecution) Returns a descriptor with configured pre execution runnable.
ExecutionDescriptor	rerunCondition(ExecutionDescriptor.RerunCondition rerunCondition) Returns a descriptor with configured rerun condition.
ExecutionDescriptor	showProgress(boolean showProgress) Returns a descriptor with configured show progress flag.
ExecutionDescriptor	showSuspended(boolean showSuspended) Returns a descriptor with configured show suspend flag.

Methods inherited from class java.lang.Object

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

Constructor Detail

ExecutionDescriptor

public ExecutionDescriptor()

Creates the new descriptor. All properties are initalized to null or false.

Method Detail

inputOutput

@NonNull
@CheckReturnValue
public ExecutionDescriptor inputOutput(@NullAllowed
                                                       InputOutput io)

Returns a descriptor with configured custom io. When configured to null it means that client is fine with infrustructure provided io (visible as tab in output pane).

If configured value is not null values configured via methods controllable(boolean), rerunCondition(RerunCondition) and getOptionsPath() are ignored by ExecutionService.

The default (not configured) value is null.

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

Parameters:

io - custom input output, null allowed

Returns:

new descriptor with configured custom io

controllable

@NonNull
@CheckReturnValue
public ExecutionDescriptor controllable(boolean controllable)

Returns a descriptor with configured controllable flag. When true the control buttons (rerun, stop) will be available io tab created by ExecutionService.

Note that this property has no meaning when custom io is used (see inputOutput(org.openide.windows.InputOutput)).

The default (not configured) value is false.

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

Parameters:

controllable - controllable flag

Returns:

new descriptor with configured controllable flag

frontWindow

@NonNull
@CheckReturnValue
public ExecutionDescriptor frontWindow(boolean frontWindow)

Returns a descriptor with configured front window flag. When true the io tab will be selected before the execution invoked by ExecutionService.run().

The default (not configured) value is false.

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

Parameters:

frontWindow - front window flag

Returns:

new descriptor with configured front window flag

inputVisible

@NonNull
@CheckReturnValue
public ExecutionDescriptor inputVisible(boolean inputVisible)

Returns a descriptor with configured input visible flag. When configured value is true the input from user will be allowed.

The default (not configured) value is false.

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

Parameters:

inputVisible - input visible flag

Returns:

new descriptor with configured input visible flag

showProgress

@NonNull
@CheckReturnValue
public ExecutionDescriptor showProgress(boolean showProgress)

Returns a descriptor with configured show progress flag. When configured value is true the progress bar will be visible.

The default (not configured) value is false.

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

Parameters:

showProgress - show progress flag

Returns:

new descriptor with configured show progress flag

showSuspended

@NonNull
@CheckReturnValue
public ExecutionDescriptor showSuspended(boolean showSuspended)

Returns a descriptor with configured show suspend flag. When configured value is true the progress bar will be suspended to just "running" message.

The default (not configured) value is false.

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

Parameters:

showSuspended - show suspended flag

Returns:

new descriptor with configured show suspended flag

noReset

@NonNull
@CheckReturnValue
public ExecutionDescriptor noReset(boolean noReset)

Returns a descriptor with configured no reset flag. When configured value is true the output window won't be cleared before the execution. Valid only for custom InputOutput configured via inputOutput(org.openide.windows.InputOutput), ignored in all other cases.

The default (not configured) value is false.

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

Parameters:

noReset - no reset flag

Returns:

new descriptor with configured no reset flag

Since:

1.20

outLineBased

@NonNull
@CheckReturnValue
public ExecutionDescriptor outLineBased(boolean outLineBased)

Returns a descriptor with configured flag indicating line based standard output. When configured value is true the default printing processor will always wait for the whole line before converting and printing it.

Parameters:

outLineBased - line based flag

Returns:

descriptor with configured flag indicating line based standard output

See Also:

outProcessorFactory(org.netbeans.api.extexecution.ExecutionDescriptor.InputProcessorFactory)

errLineBased

@NonNull
@CheckReturnValue
public ExecutionDescriptor errLineBased(boolean errLineBased)

Returns a descriptor with configured flag indicating line based standard error output. When configured value is true the default printing processor will always wait for the whole line before converting and printing it.

Parameters:

errLineBased - line based flag

Returns:

descriptor with configured flag indicating line based standard error output

See Also:

errProcessorFactory(org.netbeans.api.extexecution.ExecutionDescriptor.InputProcessorFactory)

frontWindowOnError

@NonNull
@CheckReturnValue
public ExecutionDescriptor frontWindowOnError(boolean frontWindowOnError)

Returns a descriptor with configured front window on error flag. When configured value is true and the process will return nonzero exit value the output window will be moved to front on execution finish.

The default (not configured) value is false.

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

Parameters:

frontWindowOnError - front window on error flag

Returns:

new descriptor with configured front window on error flag

Since:

1.29

outProcessorFactory

@NonNull
@CheckReturnValue
public ExecutionDescriptor outProcessorFactory(@NullAllowed
                                                               ExecutionDescriptor.InputProcessorFactory outProcessorFactory)

Returns a descriptor with configured factory for standard output processor. The factory is used by ExecutionService to create additional processor for standard output.

Note that ExecutionService automatically uses the printing processor created by InputProcessors.printing(org.openide.windows.OutputWriter, org.netbeans.api.extexecution.print.LineConvertor, boolean) or LineProcessors.printing(org.openide.windows.OutputWriter, org.netbeans.api.extexecution.print.LineConvertor, boolean) (in case outLineBased(boolean) is configured to true) if there is no configured factory.

The default (not configured) value is null.

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

Parameters:

outProcessorFactory - factory for standard output processor, null allowed

Returns:

new descriptor with configured factory for additional processor to use for standard output

errProcessorFactory

@NonNull
@CheckReturnValue
public ExecutionDescriptor errProcessorFactory(@NullAllowed
                                                               ExecutionDescriptor.InputProcessorFactory errProcessorFactory)

Returns a descriptor with configured factory for standard error output processor. The factory is used by ExecutionService to create additional processor for standard error output.

Note that ExecutionService automatically uses the printing processor created by InputProcessors.printing(org.openide.windows.OutputWriter, org.netbeans.api.extexecution.print.LineConvertor, boolean) or LineProcessors.printing(org.openide.windows.OutputWriter, org.netbeans.api.extexecution.print.LineConvertor, boolean) (in case errLineBased(boolean) is configured to true) if there is no configured factory.

The default (not configured) value is null.

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

Parameters:

errProcessorFactory - factory for standard error output processor, null allowed

Returns:

new descriptor with configured factory for additional processor to use for standard error output

outConvertorFactory

@NonNull
@CheckReturnValue
public ExecutionDescriptor outConvertorFactory(@NullAllowed
                                                               ExecutionDescriptor.LineConvertorFactory convertorFactory)

Returns a descriptor with configured factory for convertor for standard output. The factory is used by ExecutionService to create convertor to use with processor printing the standard output.

Note that ExecutionService always uses the printing processor for the standard output. Convertor created by the returned factory will be passed to this default printing processor. See outProcessorFactory(org.netbeans.api.extexecution.ExecutionDescriptor.InputProcessorFactory) too.

The default (not configured) value is null.

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

Parameters:

convertorFactory - factory for convertor for standard output, null allowed

Returns:

new descriptor with configured factory for converter for standard output

errConvertorFactory

@NonNull
@CheckReturnValue
public ExecutionDescriptor errConvertorFactory(@NullAllowed
                                                               ExecutionDescriptor.LineConvertorFactory convertorFactory)

Returns a descriptor with configured factory for convertor for standard error output. The factory is used by ExecutionService to create convertor to use with processor printing the standard error output.

Note that ExecutionService always uses the printing processor for the standard error output. Convertor created by the returned factory will be passed to this default printing processor. See errProcessorFactory(org.netbeans.api.extexecution.ExecutionDescriptor.InputProcessorFactory) too.

The default (not configured) value is null.

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

Parameters:

convertorFactory - factory for convertor for standard error output, null allowed

Returns:

new descriptor with configured factory for converter for standard error output

preExecution

@NonNull
@CheckReturnValue
public ExecutionDescriptor preExecution(@NullAllowed
                                                        Runnable preExecution)

Returns a descriptor with configured pre execution runnable. This runnable is executed before the external execution itself (when invoked by ExecutionService.run()).

The default (not configured) value is null.

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

Parameters:

preExecution - pre execution runnable, null allowed

Returns:

new descriptor with configured pre execution runnable

postExecution

@NonNull
@CheckReturnValue
public ExecutionDescriptor postExecution(@NullAllowed
                                                         Runnable postExecution)

Returns a descriptor with configured post execution runnable. This runnable is executed after the external execution itself (when invoked by ExecutionService.run()).

The default (not configured) value is null.

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

Parameters:

postExecution - post execution runnable, null allowed

Returns:

new descriptor with configured post execution runnable

rerunCondition

@NonNull
@CheckReturnValue
public ExecutionDescriptor rerunCondition(@NullAllowed
                                                          ExecutionDescriptor.RerunCondition rerunCondition)

Returns a descriptor with configured rerun condition. The condition is used by ExecutionService to control the possibility of the rerun action.

The default (not configured) value is null.

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

Parameters:

rerunCondition - rerun condition, null allowed

Returns:

new descriptor with configured rerun condition

optionsPath

@NonNull
@CheckReturnValue
public ExecutionDescriptor optionsPath(@NullAllowed
                                                       String optionsPath)

Returns a descriptor with configured options path. If configured value is not null the ExecutionService will display the button in the output tab displaying the proper options when pressed. For this to work there has to be a OptionOpenHandler in the system. Otherwise the options button won't be displayed.

Note that this property has no meaning when custom io is used (see inputOutput(org.openide.windows.InputOutput)).

The default (not configured) value is null.

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

Parameters:

optionsPath - options path, null allowed

Returns:

this descriptor with configured options path

See Also:

OptionOpenHandler

charset

@NonNull
@CheckReturnValue
public ExecutionDescriptor charset(@NullAllowed
                                                   Charset charset)

Returns a descriptor with configured charset. If configured value is not null the ExecutionService will use the given charset to decode the process streams. When null the platform default will be used.

Note that in the most common scenario of execution of OS native process you shouldn't need to set the charset. The platform default (which is the default used) is just the right choice.

The default (not configured) value is null.

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

Parameters:

charset - charset, null allowed

Returns:

this descriptor with configured charset