AuxiliaryConfiguration


1   /*
2    * The contents of this file are subject to the terms of the Common Development
3    * and Distribution License (the License). You may not use this file except in
4    * compliance with the License.
5    *
6    * You can obtain a copy of the License at http://www.netbeans.org/cddl.html
7    * or http://www.netbeans.org/cddl.txt.
8    *
9    * When distributing Covered Code, include this CDDL Header Notice in each file
10   * and include the License file at http://www.netbeans.org/cddl.txt.
11   * If applicable, add the following below the CDDL Header, with the fields
12   * enclosed by brackets [] replaced by your own identifying information:
13   * "Portions Copyrighted [year] [name of copyright owner]"
14   *
15   * The Original Software is NetBeans. The Initial Developer of the Original
16   * Software is Sun Microsystems, Inc. Portions Copyright 1997-2006 Sun
17   * Microsystems, Inc. All Rights Reserved.
18   */
19  
20  package org.netbeans.spi.project;
21  
22  import org.w3c.dom.Element  ;
23  
24  /**
25   * Ability for a project to permit other modules to insert arbitrary metadata
26   * into the project storage area.
27   * <p class="nonnormative">
28   * For example, the debugger may wish to store a list of breakpoints in the
29   * project private settings area without relying on the exact structure of
30   * the project. Similarly, the editor may wish to keep a parser database
31   * associated with a project without direct support from the project type.
32   * </p>
33   * <p>
34   * A module is only permitted to read and write its own metadata fragments
35   * unless it is explicitly given permission to read and/or write other fragments
36   * owned by another module. XML namespaces should be used to scope the data
37   * to avoid accidental clashes.
38   * </p>
39   * @see org.netbeans.api.project.Project#getLookup
40   * @author Jesse Glick
41   */
42  public interface AuxiliaryConfiguration {
43      
44      /**
45       * Retrieve a custom fragment of the project's unstructured configuration data
46       * as a portion of a DOM tree.
47       * This fragment should not have a parent node, to prevent unauthorized access
48       * to other data; it may be modified by the caller, but {@link #putConfigurationFragment}
49       * is required to insert any changes back into the project settings.
50       * @param elementName the simple name of the element expected
51       * @param namespace an XML namespace that <code>elementName</code> is qualified with
52       *                  (may not be empty)
53       * @param shared true to look in a sharable settings area, false to look in a private
54       *               settings area
55       * @return a configuration fragment, or null if none such was found
56       */
57      Element   getConfigurationFragment(String   elementName, String   namespace, boolean shared);
58      
59      /**
60       * Insert a custom fragment into the project's unstructured configuration data
61       * as a portion of a DOM tree.
62       * <p>
63       * This fragment may have a parent node, but the implementor should ignore that,
64       * and clone the fragment so as to be insulated from any further modifications.
65       * <p>
66       * If a fragment with the same name already exists, it is overwritten with the
67       * new fragment.
68       * <p>Implementations ought to acquires write access from
69       * {@link org.netbeans.api.project.ProjectManager#mutex}.
70       * However, from client code you are well advised to explicitly enclose a
71       * <em>complete</em> operation within write access, starting with
72       * {@link #getConfigurationFragment}, to prevent race conditions.
73       * @param fragment a DOM tree fragment; the root element must have a defined namespace
74       * @param shared true to save in a sharable settings area, false to save in a private
75       *               settings area
76       * @throws IllegalArgumentException if the fragment does not have a namespace or the element name
77       *                                  and namespace is already reserved by the project type for its
78       *                                  own purposes
79       */
80      void putConfigurationFragment(Element   fragment, boolean shared) throws IllegalArgumentException  ;
81      
82      /**
83       * Remove a custom fragment from the project's unstructured configuration data
84       * as a portion of a DOM tree.
85       * @param elementName the simple name of the element which should be removed
86       * @param namespace an XML namespace that <code>elementName</code> is qualified with
87       *                  (may not be empty)
88       * @param shared true to save in a sharable settings area, false to save in a private
89       *               settings area
90       * @return true if the requested fragment was actually removed, false if not
91       * @throws IllegalArgumentException if the element name and namespace is already reserved
92       *                                  by the project type for its own purposes
93       */
94      boolean removeConfigurationFragment(String   elementName, String   namespace, boolean shared) throws IllegalArgumentException  ;
95      
96  }
97
A to Z: JavaDoc & Examples Daily Java News & Articles Open Source Projects Open Source Codes Free Computer Books Remove Frame
Popular Tags