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}