Parsing API module contains parts, which are not strictly APIs, but rather default implementations tied to the desktop IDE environment. If the parsing system was running for example over source checkout in a headless environment, these parts would bring in unnecessary UI, desktop, Swing library dependencies and would potentially cause exceptions in non-GUI environment.

The following parts need to be moved to a special module that provides bindings to the IDE:


Default Scheduler implementation

All the schedulers are tied to either focus (nodes, window system) or caret position (editor components). In a headless environment, the focus has to be implemented other way, for example using last accessed file, in multi-user environment individual user contexts must be separated etc. Scheduler implementation was moved off to a IDE bridge module (see below). Schedulers are now looked up by name during class initialization, so the API constants in Parsing API are properly initialized.

DataObjects should be avoided

DataObjects are designed to bind UI services to a FileObject or a composition of FileObjects. They may also bind processing logic, but most of their designed functionality lies in connecting data to the UI. If UI part is to be separated from the Parsing API, it should not rely on DataObjects, if possible.

Document lookup and creation

NetBeans way of creating Documents involve DataObject, EditorCookies etc. Behind the scenes, Parser API implementation relies on a cache of file-to-DataObjects, each of them carries its EditorCookie with the associated Document. The feature of mapping FileObjects to Documents - lookup an existing document, or create a new one atomically, maintain document dirty state (somehow) is still needed, but the DataObject is an implementation-introduced intermediary, which can be hidden from the Parsing API - see the SourceEnvironment below.


This class is the basic connection point between the Parsing API and the deployment environment. It helps Parsing API to locate Scheduler and Parser implementations, maps Documents back to FileObjects and most importantly creates a SourceEnvironment which connects a specific Source object to its surroundings. The EnvironmentFactory also provides suitable Lookup for Parsing API operations. It is supposed that in a service-oriented (multi-user) environment, each Parsing API computation is performed on behalf of some user or within context of a certain workspace. This context has to be propagated further - the context Lookup is stored in the Source object and can be obtained using new API method Source.getLookup. Scheduler implementations are specific and tied to the (IDE) environment that hosts Parsing API. The Parsers are not specific to the environment, but they are typically sensitive to the execution context (Lookup) for the particular Parsing API operation: if the Parser stores some of its internal state for the Source, it must be cached for the Source's context (Lookup) only and must not be used in other contexts. I admit taht the parser creation could be placed into a specific Factory interface, but it seemed that theoretically cleaner design would not leverage pollution by yet another single-purpose Factory with only a single method.

SourceEnvironment, SourceControl, SchedulerControl

These interfaces replace the former org.netbeans.modules.parsing.impl.event.EventSupport which coordinated those events and works with SourceAccessor and TaskProcessor directly.

SourceEnvironment ties an individual Source (a Parsing API abstraction of the source text) to a particular FileObject and Document. The job of SourceEnvironment is to load the Document (or lookup an existing one, if one exists for the Source). Implementation of SourceEnvironment is also responsible for calling back to Parsing API when the Source's storage or contents changes somehow - SourceControl callback interface is used to report region change, source change (i.e. move) or general non-content change which could require re-parsing. If a Scheduler is created to watch the file, it has be also informed that the source has been effectively replaced, like moved to another location (represented by another FileObject). SchedulerControl callback interface allows to wake up a scheduler - its implementation may need to reconnect to the new FileObject in that case.

References to DataObjects were removed from this part of the Parsing API - the implementation of EnvironmentFactory and SourceEnvironment may use DataObjects to load contents and intercept content change events.

Source and Lookup

The Source class has been changed so that it is connected to a Lookup, which is context-dependent. The Lookup is initialized for the context effective when the Source was created. That means a given Source object may only belong to a single user (or a single workspace/environment). Other code, which formerly used Lookup.getDefault may need to change to get the Lookup instance from the Source, so it can properly communicate with context-dependent services. An example the EnvironmentFactory should be located from the context Lookup.

Relationships between classes

Initialization and user interaction

Parsing IDE Bridge module

The internal implementation of EventSupport is moved to a separate module, parsing.nb, which ties Parsing API to the rest of the NetBeans IDE environment. This module also hosts Scheduler implementations, which work with Editor component and Swing + Window system focus.

Backwards compatibility

The Parsing IDE Bridge module is injected using module-auto-deps feature. Existing APIs are preserved, new SPIs are created to allow communication across friend modules. Modules that declare impl dependency on Parsing API may need to be revised, as non-API parts of the module changed significantly.

Not logged in. Log in, Register

By use of this website, you agree to the NetBeans Policies and Terms of Use. © 2012, Oracle Corporation and/or its affiliates. Sponsored by Oracle logo