Skip navigation links
org.netbeans.modules.extexecution/2 1.49

External Execution API
Stable

See: Description

External Execution API 
Package Description
org.netbeans.api.extexecution
The API supporting execution of an external process in the IDE.
org.netbeans.api.extexecution.input
The support API for processing the growing streams or files.
org.netbeans.api.extexecution.print
The support API extending the capabalities of input processing.
org.netbeans.api.extexecution.startup
The support API allowing client to query the startup extenders.
org.netbeans.spi.extexecution
The support SPI for creation of external processes.
org.netbeans.spi.extexecution.destroy
The support SPI for terminating external processes.
org.netbeans.spi.extexecution.open
The support SPI to allow pluggability of predefined LineConvertors.
org.netbeans.spi.extexecution.startup
The support SPI for registration of startup extenders.

The major parts of this API has been refactored to External Execution Base API in version 1.43. This API is now to be used in situations where the base support is not sufficient such as when you need progress and output window integration.

To see the simplest usage of this API to handle external process including input and output integration see documentation of ExecutionService

The External Execution module provides the ExternalExecutionAPI that contains support for execution of external processes in the IDE. It also provide support class for the actual creation of the external process and support for destroying the process tree. There is also abstraction of process builder. The builder is now deprecated and replaced by one in External Execution Base API.

Another exported API ExternalExecutionInputAPI define interfaces for input processing (character or line based) and provides common implementations of these with factory methods. This API is now deprecated in favor of External Execution Base API.

Natural extension to input processing API is printing API ExternalExecutionInputPrintingAPI that defines interfaces transforming lines to lines printed to org.openide.windows.OutputWriter. API provides common implementations too and provides processor for org.openide.windows.OutputWriter printing.

The SPI ExternalExecutionSPI allows different implementations of process builder. This API is now deprecated in favor of External Execution Base API.

There is also SPI allowing to register support for destroying the process tree ExternalExecutionDestroySPI. This API is now deprecated in favor of org.netbeans.spi.extexecution.base.ProcessesImplementation from External Execution Base API.

The ExternalExecutionOpenSPI allows implementation module to determine particular way of file or HTTP URL opening in predefined covertors. It also makes options dialog opening pluggable.

There is also API to provide additional startup arguments to interested clients such as projects and servers ExternalExecutionStartupAPI. Th corresponding SPI for plugins which need to provide such additional arguments is also available as ExternalExecutionStartupSPI.

What is New (see all changes)?

Use Cases

Execution of an external process

Client needs to execute an external process and handle process streams and display the output in the output tab.

In order to achieve this client creates the ExecutionDescriptor. Via this object client configures all the UI behaviour of the subsequent execution. As a next step client creates the ExecutionService itself and calls run to execute the job. Run can be called multiple times. The output and input streams are presented in output tab. Additional processing and printing conversion can be configured in descriptor through interfaces described in following usecases.

The creation of the external process is supported by ExternalProcessBuilder to make things easier.

Processing the input

Client needs to process character data coming from stream, file or other source. This usecase should be solved by External Execution Base API.

To abstract the source of the data client must implement InputReader. To abstract the data processing client must implement InputProcessor or LineProcessor. For all three interfaces there are prepared common implementations (and bridge from character based to line based processing) at these three factory classes:

To configure additional functionality specific to org.openide.windows.OutputWriter see the next usecase.

Once the data source and processing objects are prepared client creates InputReaderTask. Factory methods of the InputReaderTask can create either common task exiting on interruption or cancellation or draining task which is trying to drain out all available data before exiting.

Printing the input

Client intends to process input lines and print them to org.openide.windows.OutputWriter. In addition printed lines should be transformed (converted) somehow and enriched by line listeners.

The both default printing processors provide factory method accepting LineConvertor. Namely InputProcessors.printing(org.openide.windows.OutputWriter out, LineConvertor convertor, boolean resetEnabled) and LineProcessors.printing(org.openide.windows.OutputWriter out, LineConvertor convertor, boolean resetEnabled). Convertor is then used to convert received lines to printed ones. Common convertors (file, http) are provided in factory class LineConvertors.

Custom process builder

Third party wants to implement custom process builder to provide additional functionality, such as remote execution. This usecase should be solved by External Execution Base API.

In order to do so it will implement ProcessBuilderImplementation and pass ProcessBuilder to its clients. The API instances are created with help of ProcessBuilderFactory.

Destroying a process

Client wants to destroy the process, trying to kill whole process tree. This usecase should be solved by External Execution Base API. Method ExternalProcessSupport.destroy(java.lang.Process process, Map<String,String> env) is designed for that. It will use a ProcessDestroyPerformer registered in default lookup to do so.

Extending startup environment

The third party plugin may want to be able provide additional arguments for the process startup in a standardized way. In order to do so it will register a implementation of StartupExtenderImplementation to the layer folder StartupExtender. The annotation StartupExtenderImplementation.Registration can be used for that.

The clients (for exmaple project or server) may query the extenders via the API class StartupExtender and use the additional arguments for the process.

Making certain open actions pluggable

Some default LineConvertors returned by LineConvertor needs to open file or URL. A bit special case is also options dialog opening required by ExecutionService to open options dialog specified by ExecutionDescriptor. To cover this three usecases in a pluggable way while keeping dependencies minimal there are three corresponding SPI classes one may implement. So there is FileOpenHandler to handle file opening, HttpOpenHandler to deal with HTTP URLs and OptionOpenHandler to open proper options dialog.

Exported Interfaces

This table lists all of the module exported APIs with defined stability classifications. It is generated based on answers to questions about the architecture of the module. Read them all...
Group of java interfaces
Interface NameIn/OutStabilitySpecified in What Document?
ExternalExecutionAPIExportedStable .../api/extexecution/package-summary.html

ExternalExecutionInputAPIExportedStable .../extexecution/input/package-summary.html

ExternalExecutionInputPrintingAPIExportedStable .../extexecution/print/package-summary.html

ExternalExecutionSPIExportedStable .../spi/extexecution/package-summary.html

ExternalExecutionDestroySPIExportedStable .../destroy/package-summary.html

ExternalExecutionOpenSPIExportedStable .../extexecution/open/package-summary.html

ExternalExecutionStartupAPIExportedStable .../startup/package-summary.html

ExternalExecutionStartupSPIExportedStable .../startup/package-summary.html

Implementation Details

Where are the sources for the module?

The sources for the module are in the NetBeans Mercurial repositories.

What do other modules need to do to declare a dependency on this one, in addition to or instead of a plain module dependency?

Nothing.

Read more about the implementation in the answers to architecture questions.

Skip navigation links
org.netbeans.modules.extexecution/2 1.49

Built on December 10 2016.  |  Portions Copyright 1997-2016 Oracle. All rights reserved.