Overview of Editor Guarded Sections module

GuardedSectionsAPI The Guarded Sections module is supposed to operate over the Swing's StyledDocument. It allows clients to manipulate named guarded sections that prevents user to modify the content. So if you like to create, modify or delete guarded sections the GuardedSectionManager is the best place where to start.

GuardedSectionsSPI The module also allows to implement custom guarded section persistance in various content types like java, xml, ... The easiest way is to subclass AbstractGuardedSectionsProvider.
In order to bind guarded sections to your editor see GuardedSectionsFactory.

What is New (see all changes)?

Feb 17 '16 Allow to protect existing text Added method to create guarded block on top of existing text.
May 21 '14 DocumentGuards API
APIs exposed and actually used on GuardedDocument in editor.lib module is now declared in Editor Guarded Sections. Clients may depend on Guarded Sections instead of on fading-away editor.lib module.

Dependency on openide.text eliminated, new SPI GuardedRegionMarker is added for Documents that are willing to style their contents according to guarded areas.
Nov 25 '12 Ability run guarded readers/writers when the content of the guarded section's content is set
When this option is set, setting the content of a GuardedSection will pass the data through the given guarded writer and back through the given guarded reader, to ensure the result is the same as if it would be read from the disk.

Note that this new mode is not fully compatible with the original mode, e.g. all the set methods of all the GuardedSection classes will throw IllegalStateException if invoked inside the write&read part.
Jun 19 '07 GuardedSectionsProvider supports Charset In order to use proper encoding by guards impl it is necessary to change GuardedSectionsProvider to accept encoding rather as java.nio.Charset instance than as a plain encoding name.
- Reader createGuardedReader(InputStream stream, String encoding) throws UnsupportedEncodingException replaced with Reader createGuardedReader(InputStream stream, Charset charset)
- Writer createGuardedWriter(OutputStream stream, String encoding) throws UnsupportedEncodingException replaced with Reader createGuardedReader(InputStream stream, Charset charset)

Use Cases

Add new section

In order to add a new section after the existing section, which seems to be most frequent, use:

        String sectionName = ...;
        StyledDocument doc = ...;
        GuardedSectionManager guards = GuardedSectionManager.getInstance(doc);
        GuardedSection g = guards.findSimpleSection(sectionName);
        guards.createSimpleSection("new_name", doc.createPosition(g.getEndPosition().getOffset() + 1));

Delete existing section

        StyledDocument doc = ...;
        GuardedSectionManager guards = GuardedSectionManager.getInstance(doc);
        GuardedSection g = guards.findSimpleSection("sectionName");
        g.deleteSection();

Plug guarded sections stuff into the editor

In case you want your CloneableEditorSupport to provide guarded sections you should implement the GuardedEditorSupport interface.

        private final class MyGuardedEditor implements GuardedEditorSupport {
           ...
        }

Further implement reading and writing of existing sections.

        protected void loadFromStreamToKit(StyledDocument doc, InputStream stream, EditorKit kit) throws IOException, BadLocationException {
            if (guardedEditor == null) {
                guardedEditor = new MyGuardedEditor();
                // remember the provider
                String mimeType = ((CloneableEditorSupport.Env) this.env).getMimeType();
                guardedProvider = GuardedSectionsFactory.find(mimeType).create(guardedEditor);
            }

            // load content to kit
            if (guardedProvider != null) {
                guardedEditor.setDocument(doc);
                Charset cs = FileEncodingQuery.getEncoding(this.getDataObject().getPrimaryFile());
                Reader reader = guardedProvider.createGuardedReader(stream, cs);
                try {
                    kit.read(reader, doc, 0);
                } finally {
                    reader.close();
                }
            } else {
                kit.read(stream, doc, 0);
            }
        }

        protected void saveFromKitToStream(StyledDocument doc, EditorKit kit, OutputStream stream) throws IOException, BadLocationException {
            if (guardedProvider != null) {
                Charset cs = FileEncodingQuery.getEncoding(this.getDataObject().getPrimaryFile());
                Writer writer = guardedProvider.createGuardedWriter(stream, cs);
                try {
                    kit.write(writer, doc, 0, doc.getLength());
                } finally {
                    writer.close();
                }
            } else {
                kit.write(stream, doc, 0, doc.getLength());
            }
        }

Your module should also require a proper implementation. In case of java content add to your module manifest file:

        OpenIDE-Module-Requires: org.netbeans.api.editor.guards.Java

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

Group of java interfaces
Interface Name	In/Out	Stability	Specified in What Document?
GuardedSectionsAPI	Exported	Official	The Guarded Sections module is supposed to operate over the Swing's `StyledDocument`. It allows clients to manipulate named guarded sections that prevents user to modify the content. So if you like to create, modify or delete guarded sections the `GuardedSectionManager` is the best place where to start.
GuardedSectionsSPI	Exported	Official	The module also allows to implement custom guarded section persistance in various content types like java, xml, ... The easiest way is to subclass `AbstractGuardedSectionsProvider`. In order to bind guarded sections to your editor see `GuardedSectionsFactory`.

Group of property interfaces

Group of property interfaces
Interface Name	In/Out	Stability	Specified in What Document?
org.netbeans.api.editor.guards.GuardedSectionManager	Exported	Private	The `GuardedSectionManager` instance is physically stored as a property of the document with key `org.netbeans.api.editor.guards.GuardedSectionManager.class`. Modules should not depend on this.

Group of lookup interfaces

Group of lookup interfaces
Interface Name	In/Out	Stability	Specified in What Document?
GuardedSectionsFactory	Exported	Official	.../guards/GuardedSectionsFactory.html Factories of custom providers that implements reading and writing guarded sections should be registered under `Editors/<mime path>` in the module layer file. The first one is chosen for the given mime path.

Implementation Details

Where are the sources for the module?

The sources for the module are in the Apache Git repositories or in the GitHub 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?

A module using the Guarded Sections API should also require a proper implementation. Eg in case of java content add to your module manifest file:

        OpenIDE-Module-Requires: org.netbeans.api.editor.guards.Java

A module implementing the Guarded Sections SPI should provide a token in the manifest file. Eg in case of java content add:

        OpenIDE-Module-Provides: org.netbeans.api.editor.guards.Java

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

Editor Guarded Sections

Package

Description

org.netbeans.api.editor.guards

org.netbeans.spi.editor.guards

org.netbeans.spi.editor.guards.support

Editor Guarded SectionsOfficial