001: /*
002: * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS HEADER.
003: *
004: * Copyright 1997-2007 Sun Microsystems, Inc. All rights reserved.
005: *
006: * The contents of this file are subject to the terms of either the GNU
007: * General Public License Version 2 only ("GPL") or the Common
008: * Development and Distribution License("CDDL") (collectively, the
009: * "License"). You may not use this file except in compliance with the
010: * License. You can obtain a copy of the License at
011: * http://www.netbeans.org/cddl-gplv2.html
012: * or nbbuild/licenses/CDDL-GPL-2-CP. See the License for the
013: * specific language governing permissions and limitations under the
014: * License. When distributing the software, include this License Header
015: * Notice in each file and include the License file at
016: * nbbuild/licenses/CDDL-GPL-2-CP. Sun designates this
017: * particular file as subject to the "Classpath" exception as provided
018: * by Sun in the GPL Version 2 section of the License file that
019: * accompanied this code. If applicable, add the following below the
020: * License Header, with the fields enclosed by brackets [] replaced by
021: * your own identifying information:
022: * "Portions Copyrighted [year] [name of copyright owner]"
023: *
024: * Contributor(s):
025: *
026: * The Original Software is NetBeans. The Initial Developer of the Original
027: * Software is Sun Microsystems, Inc. Portions Copyright 1997-2006 Sun
028: * Microsystems, Inc. All Rights Reserved.
029: *
030: * If you wish your version of this file to be governed by only the CDDL
031: * or only the GPL Version 2, indicate your decision by adding
032: * "[Contributor] elects to include this software in this distribution
033: * under the [CDDL or GPL Version 2] license." If you do not indicate a
034: * single choice of license, a recipient has the option to distribute
035: * your version of this file under either the CDDL, the GPL Version 2 or
036: * to extend the choice of license to its licensees as provided above.
037: * However, if you add GPL Version 2 code and therefore, elected the GPL
038: * Version 2 license, then the option applies only if the new code is
039: * made subject to such option by the copyright holder.
040: */
041:
042: package org.netbeans.spi.project;
043:
044: import org.w3c.dom.Element;
045:
046: /**
047: * Ability for a project to permit other modules to insert arbitrary metadata
048: * into the project storage area.
049: * <p class="nonnormative">
050: * For example, the debugger may wish to store a list of breakpoints in the
051: * project private settings area without relying on the exact structure of
052: * the project. Similarly, the editor may wish to keep a parser database
053: * associated with a project without direct support from the project type.
054: * </p>
055: * <p>
056: * A module is only permitted to read and write its own metadata fragments
057: * unless it is explicitly given permission to read and/or write other fragments
058: * owned by another module. XML namespaces should be used to scope the data
059: * to avoid accidental clashes.
060: * </p>
061: * @see org.netbeans.api.project.Project#getLookup
062: * @author Jesse Glick
063: */
064: public interface AuxiliaryConfiguration {
065:
066: /**
067: * Retrieve a custom fragment of the project's unstructured configuration data
068: * as a portion of a DOM tree.
069: * This fragment should not have a parent node, to prevent unauthorized access
070: * to other data; it may be modified by the caller, but {@link #putConfigurationFragment}
071: * is required to insert any changes back into the project settings.
072: * @param elementName the simple name of the element expected
073: * @param namespace an XML namespace that <code>elementName</code> is qualified with
074: * (may not be empty)
075: * @param shared true to look in a sharable settings area, false to look in a private
076: * settings area
077: * @return a configuration fragment, or null if none such was found
078: */
079: Element getConfigurationFragment(String elementName,
080: String namespace, boolean shared);
081:
082: /**
083: * Insert a custom fragment into the project's unstructured configuration data
084: * as a portion of a DOM tree.
085: * <p>
086: * This fragment may have a parent node, but the implementor should ignore that,
087: * and clone the fragment so as to be insulated from any further modifications.
088: * <p>
089: * If a fragment with the same name already exists, it is overwritten with the
090: * new fragment.
091: * <p>Implementations ought to acquires write access from
092: * {@link org.netbeans.api.project.ProjectManager#mutex}.
093: * However, from client code you are well advised to explicitly enclose a
094: * <em>complete</em> operation within write access, starting with
095: * {@link #getConfigurationFragment}, to prevent race conditions.
096: * @param fragment a DOM tree fragment; the root element must have a defined namespace
097: * @param shared true to save in a sharable settings area, false to save in a private
098: * settings area
099: * @throws IllegalArgumentException if the fragment does not have a namespace or the element name
100: * and namespace is already reserved by the project type for its
101: * own purposes
102: */
103: void putConfigurationFragment(Element fragment, boolean shared)
104: throws IllegalArgumentException;
105:
106: /**
107: * Remove a custom fragment from the project's unstructured configuration data
108: * as a portion of a DOM tree.
109: * @param elementName the simple name of the element which should be removed
110: * @param namespace an XML namespace that <code>elementName</code> is qualified with
111: * (may not be empty)
112: * @param shared true to save in a sharable settings area, false to save in a private
113: * settings area
114: * @return true if the requested fragment was actually removed, false if not
115: * @throws IllegalArgumentException if the element name and namespace is already reserved
116: * by the project type for its own purposes
117: */
118: boolean removeConfigurationFragment(String elementName,
119: String namespace, boolean shared)
120: throws IllegalArgumentException;
121:
122: }
|