001package jmri.configurexml;
002
003import java.awt.GraphicsEnvironment;
004import javax.annotation.Nonnull;
005import javax.annotation.CheckForNull;
006import jmri.configurexml.swing.DialogErrorHandler;
007import org.jdom2.Element;
008
009/**
010 * Interface assumed during configuration operations.
011 *
012 * @author Bob Jacobsen Copyright (c) 2002
013 * @see ConfigXmlManager
014 */
015public interface XmlAdapter {
016
017    /**
018     * Create a set of configured objects from their XML description
019     *
020     * @param e Top-level XML element containing the description
021     * @throws JmriConfigureXmlException when a error prevents creating the objects as as
022     *                   required by the input XML.
023     * @return true if successful
024     */
025    boolean load(Element e) throws JmriConfigureXmlException;
026
027    /**
028     * Create a set of configured objects from their XML description.
029     *
030     * @param shared  Top-level XML element containing the common, multi-node
031     *                elements of the description
032     * @param perNode Top-level XML element containing the private, single-node
033     *                elements of the description
034     * @throws JmriConfigureXmlException when a error prevents creating the objects as as
035     *                   required by the input XML
036     * @return true if successful
037     */
038    boolean load(Element shared, Element perNode) throws JmriConfigureXmlException;
039
040    /**
041     * Determine if this set of configured objects should be loaded after basic
042     * GUI construction is completed
043     *
044     * @return true to defer loading
045     * @since 2.11.2
046     */
047    boolean loadDeferred();
048
049    /**
050     * Create a set of configured objects from their XML description, using an
051     * auxiliary object.
052     * <p>
053     * For example, the auxilary object o might be a manager or GUI of some type
054     * that needs to be informed as each object is created.
055     *
056     * @param e Top-level XML element containing the description
057     * @param o Implementation-specific Object needed for the conversion
058     * @throws JmriConfigureXmlException when a error prevents creating the objects as as
059     *                   required by the input XML
060     */
061    void load(Element e, Object o) throws JmriConfigureXmlException;
062
063    /**
064     * Create a set of configured objects from their XML description, using an
065     * auxiliary object.
066     * <p>
067     * For example, the auxilary object o might be a manager or GUI of some type
068     * that needs to be informed as each object is created.
069     *
070     * @param shared  Top-level XML element containing the common description
071     * @param perNode Top-level XML element containing the per-node description
072     * @param o       Implementation-specific Object needed for the conversion
073     * @throws JmriConfigureXmlException when a error prevents creating the objects as as
074     *                   required by the input XML
075     */
076    void load(Element shared, Element perNode, Object o) throws JmriConfigureXmlException;
077
078    /**
079     * Store the object in XML
080     *
081     * @param o The object to be recorded. Specific XmlAdapter implementations
082     *          will require this to be of a specific type; that binding is done
083     *          in ConfigXmlManager.
084     * @return The XML representation Element
085     */
086    Element store(Object o);
087
088    /**
089     * Store the object in XML
090     *
091     * @param o      The object to be recorded. Specific XmlAdapter
092     *               implementations will require this to be of a specific type;
093     *               that binding is done in ConfigXmlManager.
094     * @param shared true if the returned element should be the common XML and
095     *               false if the returned element should be per-node.
096     * @return The XML representation Element
097     */
098    Element store(Object o, boolean shared);
099
100    int loadOrder();
101
102    /**
103     * Provide a simple handler for errors.
104     *
105     * Calls the configured {@link jmri.configurexml.ErrorHandler} with an
106     * {@link jmri.configurexml.ErrorMemo} created using the provided
107     * parameters.
108     *
109     * @param description description of error encountered
110     * @param operation   the operation being performed, may be null
111     * @param systemName  system name of bean being handled, may be null
112     * @param userName    user name of the bean being handled, may be null
113     * @param exception   Any exception being handled in the processing, may be
114     *                    null
115     * @throws JmriConfigureXmlException in place for later expansion; should be
116     *                                   propagated upward to higher-level error
117     *                                   handling
118     */
119    void handleException(
120            @Nonnull String description,
121            @CheckForNull String operation,
122            @CheckForNull String systemName,
123            @CheckForNull String userName,
124            @CheckForNull Exception exception) throws JmriConfigureXmlException;
125
126    /**
127     * Set the error handler that will handle any errors encountered while
128     * parsing the XML. If not specified, the default error handler will be
129     * used.
130     *
131     * @param errorHandler the error handler or null to ignore parser errors
132     */
133    void setExceptionHandler(ErrorHandler errorHandler);
134
135    /**
136     * Get the current error handler.
137     *
138     * @return the error handler or null if no error handler is assigned
139     */
140    ErrorHandler getExceptionHandler();
141
142    /**
143     * Get the default error handler.
144     *
145     * @return the default error handler
146     */
147    static ErrorHandler getDefaultExceptionHandler() {
148        if (GraphicsEnvironment.isHeadless()) {
149            return new ErrorHandler();
150        }
151        return new DialogErrorHandler();
152    }
153}