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:

  • Method Summary

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

    • 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 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 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