AuxiliaryConfiguration (NetBeans Project API) - NetBeans API Javadoc 5.0.0

Overview

Package

Class

Use

Tree

Deprecated

Index

Help

PREV CLASS NEXT CLASS

FRAMES NO FRAMES

SUMMARY: NESTED | FIELD | CONSTR | METHOD

DETAIL: FIELD | CONSTR | METHOD

org.netbeans.spi.project
Interface AuxiliaryConfiguration

public interface AuxiliaryConfiguration

Ability for a project to permit other modules to insert arbitrary metadata into the project storage area.

For example, the debugger may wish to store a list of breakpoints in the project private settings area without relying on the exact structure of the project. Similarly, the editor may wish to keep a parser database associated with a project without direct support from the project type.

A module is only permitted to read and write its own metadata fragments unless it is explicitly given permission to read and/or write other fragments owned by another module. XML namespaces should be used to scope the data to avoid accidental clashes.

See Also:: Project.getLookup()

Method Summary

Element getConfigurationFragment(String elementName, String namespace, boolean shared)
          Retrieve a custom fragment of the project's unstructured configuration data as a portion of a DOM tree.

void putConfigurationFragment(Element fragment, boolean shared)
          Insert a custom fragment into the project's unstructured configuration data as a portion of a DOM tree.

boolean removeConfigurationFragment(String elementName, String namespace, boolean shared)
          Remove a custom fragment from the project's unstructured configuration data as a portion of a DOM tree.

Method Detail

getConfigurationFragment

public Element getConfigurationFragment(String elementName,
                                        String namespace,
                                        boolean shared)

Retrieve a custom fragment of the project's unstructured configuration data as a portion of a DOM tree. This fragment should not have a parent node, to prevent unauthorized access to other data; it may be modified by the caller, but putConfigurationFragment(org.w3c.dom.Element, boolean) is required to insert any changes back into the project settings.

Parameters:: elementName - the simple name of the element expected; namespace - an XML namespace that elementName is qualified with (may not be empty); shared - true to look in a sharable settings area, false to look in a private settings area
Returns:: a configuration fragment, or null if none such was found

putConfigurationFragment

public void putConfigurationFragment(Element fragment,
                                     boolean shared)
                              throws IllegalArgumentException

Insert a custom fragment into the project's unstructured configuration data as a portion of a DOM tree.

This fragment may have a parent node, but the implementor should ignore that, and clone the fragment so as to be insulated from any further modifications.

If a fragment with the same name already exists, it is overwritten with the new fragment.

Implementations ought to acquires write access from ProjectManager.mutex(). However, from client code you are well advised to explicitly enclose a complete operation within write access, starting with getConfigurationFragment(java.lang.String, java.lang.String, boolean), to prevent race conditions.

Parameters:: fragment - a DOM tree fragment; the root element must have a defined namespace; shared - true to save in a sharable settings area, false to save in a private settings area
Throws:: IllegalArgumentException - if the fragment does not have a namespace or the element name and namespace is already reserved by the project type for its own purposes

removeConfigurationFragment

public boolean removeConfigurationFragment(String elementName,
                                           String namespace,
                                           boolean shared)
                                    throws IllegalArgumentException

Remove a custom fragment from the project's unstructured configuration data as a portion of a DOM tree.

Parameters:: elementName - the simple name of the element which should be removed; namespace - an XML namespace that elementName is qualified with (may not be empty); shared - true to save in a sharable settings area, false to save in a private settings area
Returns:: true if the requested fragment was actually removed, false if not
Throws:: IllegalArgumentException - if the element name and namespace is already reserved by the project type for its own purposes