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}