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.

Do not look for this object directly in project lookup. Instead use ProjectUtils.getAuxiliaryConfiguration(org.netbeans.api.project.Project).

See Also:

Project.getLookup()

Method Summary

Modifier and Type	Method and Description
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

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 AuxiliaryConfiguration.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

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 AuxiliaryConfiguration.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

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