﻿ EditorDocumentApi - NetBeans Wiki


(Difference between revisions)
Sdedic (Talk | contribs)
(Created page with 'A lot of Editor APIs used in code manipulation and transformation actually depend on several features of the '''BaseDocument''. Some implementation use StyledDocument. The issue …')
Newer edit →

Revision as of 11:23, 4 September 2014

A lot of Editor APIs used in code manipulation and transformation actually depend on several features of the BaseDocument. Some implementation use StyledDocument. The issue is that BaseDocument' is defined in the editor.lib module, which is semi-deprecated. According to transition plan, new code is produced into editor.lib2 and adapted/modernized code is migrated there as well.

Both editor.lib and editor.lib2 have strong dependncies on Swing. Specifically BaseDocument is a subclass of Swing AbstractDocument, which is not totally bad itself, but certain parts of implementation could attempt to use unwanted Swing features (UIManager, BiDi support etc) - these features are perfectly valid in a desktop IDE, less wanted in pure data processing.

Relevant issues:


New API module

The APIs needed by non-editor modules to work with document contents were centralized into a new module, editor.document. Document implementation itself is still in editor.lib, this new module contains just APIs and utilities that make use of those APIs. All editor modules depend on this editor.document for document interface.

Non-editor modules are stronly encouraged to depend on editor.document for content manipulation, and use editor.lib and editor.lib2 dependencies only when implementing UI features.

New interfaces

The necessary document structure APIs were extracted as LineDocument interface, which BasicDocument now implements. Additional features, like locking, were extracted to stand-alone interfaces, which can be looked up by a Lookup-like API based on the Document:

  • DocumentLockState - inspect state of locks on the document
  • AtomicLockDocument - allows to group operations into 'atomic' ones (in terms of Undo), work as 'user' (respect potential protected areas)

These interfaces might be provided by the document implementation; the NetBeans platform may provide a stub implementation for the APIs even for documents which do not support the API directly - this is the case of AtomicLockDocument.

LineDocumentUtils, extensibility

Collection of line and column navigation and search utilities previously found in DocumentUtilities were moved here. The name 'LineDocument' was selected because the usual adjectives (base, default, abstract, standard) were already taken by Swing or IDE implementations and the core of the interface is paragraph view in which one paragraph Element corresponds to a single document line.

Optional document features can be looked up by using LineDocument.as method, which attempts to locate an implementation suitable for the Document class (not Mime type !). A provider can register using @ServiceProvider on path Editors/Documents/<full-class-name> its DocumentServiceFactory, which in turn creates and provides the implementation of a service, given a Document instance. Stub implementation can be registered for all documents against javax.text.swing.Document interface. Such stub is instantiated only when client demands some implementation of the feature for its function - through LineDocument.asRequired. asRequired fails if the Document does not support the requested feature and the platform is not able to provide a stub implementation. It is a replacement for code fragment like

Document doc = .... ; // obtain document
if (doc instanceof BaseDocument) {
} else {
    throw new IllegalArgumentException();

or alternatively

Document doc = .... ; // obtain document
Runnable r = .... ; // the real code

if (doc instanceof BaseDocument) {
} else {

Non-editor module implementations may work against LineDocument instead of BaseDocument for basic character services, and lookup extensions using LineDocumentUtils.as.


The MIME types supported by the IDE's editing infrastructure (this is different from set of MIME types actually recognized by MIMERecognizers) were traditionally obtained through Editor Settings modules, which is an unwanted dependency for non-editor and non-UI modules in general. The EditorMimeTypes API class provides a list of MIME types supported for editing, which could be used for:

  • UI that lists kinds of editors (= editable mime types)
  • approximation of what files could be worth to analyse (noneditable files can be skipped from parsing)

Similar to EditorSettings, the class supports change notification in the case that module set changes and editor becomes (un)available.

The API placement into editor.document module is partly forced: the API cannot be hosted by editor.lib*, as they concentrate on UI parts of the editor. editor.util does not depend on anything but base JRE (while the API implementation requires at least Lookup or FileSystems) - so the API would either stand itself in its own module, or it can be joined to some "core editor" library - like editor.document is.

Not logged in. Log in, Register
