Overview (Editor Guarded Sections)

Editor Guarded Sections
Package	Description
org.netbeans.api.editor.guards
org.netbeans.spi.editor.guards
org.netbeans.spi.editor.guards.support

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

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

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

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 SectionsOfficial

What is New (see all changes)?

Use Cases

Add new section

Delete existing section

Plug guarded sections stuff into the editor

Exported Interfaces

Group of java interfaces

Group of property interfaces

Group of lookup interfaces

Implementation Details

Where are the sources for the module?

What do other modules need to do to declare a dependency on this one, in addition to or instead of a plain module dependency?

Editor Guarded Sections
Official