org.netbeans.api.extexecution

Class ExecutionDescriptor

java.lang.Object

org.netbeans.api.extexecution.ExecutionDescriptor

public final class ExecutionDescriptor
extends Object

Descriptor for the execution service. 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 Deprecated. use ExecutionDescriptor.InputProcessorFactory2
static interface	ExecutionDescriptor.InputProcessorFactory2 Factory creating the input processor.
static interface	ExecutionDescriptor.LineConvertorFactory Factory creating the line convertor.
static interface	ExecutionDescriptor.RerunCallback Provides a callback to be invoked when rerun action is invoked.
static interface	ExecutionDescriptor.RerunCondition Represents the possibility of reruning the action.

Constructor Summary

Constructors

Constructor and Description
ExecutionDescriptor() Creates the new descriptor.

Method Summary

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) Deprecated. use ExecutionDescriptor.errProcessorFactory(org.netbeans.api.extexecution.ExecutionDescriptor.InputProcessorFactory2)
ExecutionDescriptor	errProcessorFactory(ExecutionDescriptor.InputProcessorFactory2 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) Deprecated. use ExecutionDescriptor.outProcessorFactory(org.netbeans.api.extexecution.ExecutionDescriptor.InputProcessorFactory2)
ExecutionDescriptor	outProcessorFactory(ExecutionDescriptor.InputProcessorFactory2 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	rerunCallback(ExecutionDescriptor.RerunCallback rerunCallback) Returns a descriptor with configured rerun callback.
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 ExecutionDescriptor.controllable(boolean), ExecutionDescriptor.rerunCondition(RerunCondition) and ExecutionDescriptor.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 ExecutionDescriptor.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 ExecutionDescriptor.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:

ExecutionDescriptor.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:

ExecutionDescriptor.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)

Deprecated. use ExecutionDescriptor.outProcessorFactory(org.netbeans.api.extexecution.ExecutionDescriptor.InputProcessorFactory2)

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 ExecutionDescriptor.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

outProcessorFactory

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

Returns a descriptor with configured factory for standard output processor. The factory is used by ExecutionService to create additional processor for standard output. The configured value will be ignored if you previously configured processor via deprecated ExecutionDescriptor.outProcessorFactory(org.netbeans.api.extexecution.ExecutionDescriptor.InputProcessorFactory).

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 ExecutionDescriptor.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)

Deprecated. use ExecutionDescriptor.errProcessorFactory(org.netbeans.api.extexecution.ExecutionDescriptor.InputProcessorFactory2)

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 ExecutionDescriptor.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

errProcessorFactory

@NonNull
 @CheckReturnValue
public ExecutionDescriptor errProcessorFactory(@NullAllowed
                                                                           ExecutionDescriptor.InputProcessorFactory2 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. The configured value will be ignored if you previously configured processor via deprecated ExecutionDescriptor.errProcessorFactory(org.netbeans.api.extexecution.ExecutionDescriptor.InputProcessorFactory).

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 ExecutionDescriptor.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 ExecutionDescriptor.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 ExecutionDescriptor.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

See Also:

ExecutionDescriptor.rerunCallback(org.netbeans.api.extexecution.ExecutionDescriptor.RerunCallback)

rerunCallback

@NonNull
 @CheckReturnValue
public ExecutionDescriptor rerunCallback(@NullAllowed
                                                                     ExecutionDescriptor.RerunCallback rerunCallback)

Returns a descriptor with configured rerun callback. The callback is invoked when the execution is triggered by the rerun action.

The default (not configured) value is null.

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

Parameters:

rerunCallback - rerun callback, null allowed

Returns:

new descriptor with configured rerun callback

Since:

1.46

See Also:

ExecutionDescriptor.rerunCondition(org.netbeans.api.extexecution.ExecutionDescriptor.RerunCondition)

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 ExecutionDescriptor.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