001package jmri.profile;
002
003import javax.annotation.CheckForNull;
004import javax.annotation.Nonnull;
005import org.w3c.dom.Element;
006
007/**
008 * JMRI local copy of the NetBeans Platform
009 * org.netbeans.spi.project.AuxiliaryConfiguration.
010 * <p>
011 * <strong>Note</strong> This uses {@link org.w3c.dom.Element} instead of
012 * {@link org.jdom2.Element} because the NetBeans Platform uses the DOM model
013 * included in the JRE.
014 *
015 * @author Randall Wood
016 */
017public interface AuxiliaryConfiguration {
018
019    /**
020     * Get a configuration fragment as an XML element.
021     * <p>
022     * Multiple elements in a configuration file can have the same name as long
023     * as they have different namespaces. If using versioned namespaces, this
024     * would allow two different versions of JMRI with incompatible preferences
025     * for a given element to use the same name without stomping on each other.
026     * <p>
027     * <strong>Note:</strong> Use
028     * {@link jmri.util.jdom.JDOMUtil#toJDOMElement(org.w3c.dom.Element)} to
029     * convert a non-null result to a JDOM {@link org.jdom2.Element}.
030     *
031     * @param elementName the name of the element.
032     * @param namespace   the namespace of the element.
033     * @param shared      true if the fragment is for all computers using this
034     *                    profile, false if the fragment is for just the current
035     *                    computer.
036     * @return the matching Element or null if a matching element cannot be
037     *         found.
038     */
039    @CheckForNull
040    Element getConfigurationFragment(@Nonnull String elementName, @Nonnull String namespace, boolean shared);
041
042    /**
043     * Store a configuration fragement as an XML element.
044     * <p>
045     * Multiple elements in a configuration file can have the same name as long
046     * as they have different namespaces. If using versioned namespaces, this
047     * would allow two different versions of JMRI with incompatible preferences
048     * for a given element to use the same name without stomping on each other.
049     * <p>
050     * <strong>Note:</strong> Use
051     * {@link jmri.util.jdom.JDOMUtil#toW3CElement(org.jdom2.Element)} to
052     * convert a JDOM {@link org.jdom2.Element} to a W3C
053     * {@link org.w3c.dom.Element}. The JDOM element must have a namespace
054     * associated with it.
055     *
056     * @param fragment the XML element. It must have a valid namespace property.
057     * @param shared   true if the fragment is for all computers using this
058     *                 profile, false if the fragment is for just the current
059     *                 computer.
060     */
061    void putConfigurationFragment(@Nonnull Element fragment, boolean shared);
062
063    /**
064     * Remove a configuration fragment from the configuration.
065     * <p>
066     * Multiple elements in a configuration file can have the same name as long
067     * as they have different namespaces. If using versioned namespaces, this
068     * would allow two different versions of JMRI with incompatible preferences
069     * for a given element to use the same name without stomping on each other.
070     *
071     * @param elementName the name of the element.
072     * @param namespace   the namespace of the element.
073     * @param shared      true if the fragment is for all computers using this
074     *                    profile, false if the fragment is for just the current
075     *                    computer.
076     * @return true if the fragment could be removed, false otherwise.
077     */
078    boolean removeConfigurationFragment(String elementName, String namespace, boolean shared);
079
080}