See: Description
| 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.
The StartupExtenderImplementation javadoc did not specify how to handle parameters with spaces in them. Some of the implementations quote/escape the parameters they return, but most of them not. This causes issues later when the parameters are processed or re-arranged into the final commandline. This change allows a StartupExtenderImplementation to declare its quoting policy.
Use overloaded ExecutionDescriptor.postExecution
method to obtain exit code of just finished application.
Allows the user of the API to register a callback to be invoked on rerun action.
Splitting the API deprecating major parts.
Providers of ProcessBuilderImplementation are
advised to throw UserQuestionException in case
they need some interaction with user.
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.
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.
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.
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.
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.
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.
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.
|
The sources for the module are in the Apache Git repositories or in the GitHub repositories.
Nothing.
Read more about the implementation in the answers to architecture questions.