org.netbeans.modules.extexecution/2 1.25.1

External Execution Support
Stable

See:
          Description

External Execution Support
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.spi.extexecution.destroy The support SPI for terminating external processes.

 

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.

Another exported API ExternalExecutionInputAPI define interfaces for input processing (character or line based) and provides common implementations of these with factory methods.

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.

There is also SPI allowing to register support for destroying the process tree ExternalExecutionDestroySPI.

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.

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.

Destroying a process

Client wants to destroy the process, trying to kill whole process tree. 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.

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

ExternalExecutionDestroySPIExportedStable .../destroy/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.


org.netbeans.modules.extexecution/2 1.25.1

Built on December 5 2011.  |  Portions Copyright 1997-2011 Sun Microsystems, Inc. All rights reserved.