001package jmri;
002
003import java.io.File;
004import java.net.URL;
005import java.util.List;
006
007import javax.annotation.CheckForNull;
008import javax.annotation.CheckReturnValue;
009
010import jmri.jmrit.XmlFile;
011
012/**
013 * Provide load/store capabilities for general configuration.
014 * <p>
015 * Areas of responsibility:
016 * <ul>
017 * <li>Register and deregister configuration objects so they can eventually be
018 * stored.
019 * <li>Invoke the load and store operations as needed
020 * <li>Give access to the configuration objects for independent GUIs
021 * </ul>
022 * <p>
023 * The managed items are divided into four types:
024 * <ol>
025 * <li>"Prefs" - handled first on read, these are the general preferences
026 * controlling how the program starts up
027 * <li>"Config" - layout configuration information, e.g. turnout, signal, etc
028 *   - generally, all NamedBeanManagers
029 * <li>"Tool" - (Not really clear yet, but present)
030 * <li>"User" - typically information about panels and windows, these are
031 * handled last during startup - all the jmri.display panel types
032 * </ol>
033 * <p>
034 * The configuration manager is generally located through the InstanceManager.
035 * <p>
036 * The original implementation was via the {@link jmri.configurexml} package.
037 *
038 * <hr>
039 * This file is part of JMRI.
040 * <p>
041 * JMRI is free software; you can redistribute it and/or modify it under the
042 * terms of version 2 of the GNU General Public License as published by the Free
043 * Software Foundation. See the "COPYING" file for a copy of this license.
044 * <p>
045 * JMRI is distributed in the hope that it will be useful, but WITHOUT ANY
046 * WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR
047 * A PARTICULAR PURPOSE. See the GNU General Public License for more details.
048 *
049 * @author Bob Jacobsen Copyright (C) 2002, 2010, 2017, 2020
050 * @author Matthew Harris Copyright (C) 2010, 2016
051 * @author Randall Wood Coyright (C) 2013, 2015, 2017
052 * @see jmri.InstanceManager
053 * @see jmri.configurexml.ConfigXmlManager
054 */
055public interface ConfigureManager {
056
057    void registerPref(Object o);
058
059    void removePrefItems();
060
061    void registerConfig(Object o);
062
063    void registerConfig(Object o, int x);
064
065    void registerTool(Object o);
066
067    void registerUser(Object o);
068
069    void registerUserPrefs(Object o);
070
071    void deregister(Object o);
072
073    /**
074     * Find the ith instance of an object of particular class that's been
075     * registered for storage.
076     * <p>
077     * Note that the index of an object can change when other objects are stored
078     * or removed. The index is for indexing over the objects stored at a
079     * moment, not for use as an identification number.
080     * <p>
081     * There may be synchronization issues associated with this, although they
082     * are expected to be rare in practice.
083     *
084     * @param c     Class of the desired objects
085     * @param index a 1-based index of the object to return
086     * @return an object of class c or null
087     */
088    @CheckForNull
089    Object findInstance(Class<?> c, int index);
090
091    /**
092     * Returns a list of instances stored for a given class.
093     *
094     * @param c Class of the desired objects
095     * @return an List of objects of class c or null
096     */
097    List<Object> getInstanceList(Class<?> c);
098
099    /**
100     * Stores just preferences information.
101     * <p>
102     * Where that information is stored is implementation-specific.
103     */
104    void storePrefs();
105
106    /**
107     * Stores just preferences information.
108     *
109     * @param file the to store preferences into
110     */
111    void storePrefs(File file);
112
113    /**
114     * Stores just user preferences information.
115     *
116     * @param file the file to store user preferences into
117     */
118    void storeUserPrefs(File file);
119
120    /**
121     * Stores just configuration information.
122     *
123     * @param file Output file
124     * @return true if successful; false otherwise
125     */
126    @CheckReturnValue
127    boolean storeConfig(File file);
128
129    /**
130     * Stores user and config information.
131     *
132     * @param file Output file
133     * @return true if succeeded
134     */
135    @CheckReturnValue
136    boolean storeUser(File file);
137
138    /**
139     * Create the objects defined in a particular configuration file
140     *
141     * @param file Input file
142     * @return true if succeeded
143     * @throws jmri.JmriException if unable to load file due to internal error
144     */
145    @CheckReturnValue
146    boolean load(File file) throws JmriException;
147
148    /**
149     * Create the objects defined in a particular configuration file
150     *
151     * @param file Input URL
152     * @return true if succeeded
153     * @throws jmri.JmriException if unable to load URL due to internal error
154     */
155    @CheckReturnValue
156    boolean load(URL file) throws JmriException;
157
158    /**
159     * Create the objects defined in a particular configuration file
160     *
161     * @param file             Input file
162     * @param registerDeferred true to register actions for deferred load
163     * @return true if succeeded
164     * @throws JmriException if problem during load
165     * @since 2.11.2
166     */
167    @CheckReturnValue
168    boolean load(File file, boolean registerDeferred) throws JmriException;
169
170    /**
171     * Create the objects defined in a particular configuration file
172     *
173     * @param file             Input URL
174     * @param registerDeferred true to register actions for deferred load
175     * @return true if succeeded
176     * @throws JmriException if problem during load
177     * @since 2.11.2
178     */
179    @CheckReturnValue
180    boolean load(URL file, boolean registerDeferred) throws JmriException;
181
182    /**
183     * Create the objects defined in a particular configuration file that have
184     * been deferred until after basic GUI construction completed
185     *
186     * @param file Input file
187     * @return true if succeeded
188     * @throws JmriException if problem during load
189     * @see jmri.configurexml.XmlAdapter#loadDeferred()
190     * @since 2.11.2
191     */
192    @CheckReturnValue
193    boolean loadDeferred(File file) throws JmriException;
194
195    /**
196     * Create the objects defined in a particular configuration file that have
197     * been deferred until after basic GUI construction completed
198     *
199     * @param file Input URL
200     * @return true if succeeded
201     * @throws JmriException if problem during load
202     * @see jmri.configurexml.XmlAdapter#loadDeferred()
203     * @since 2.11.2
204     */
205    @CheckReturnValue
206    boolean loadDeferred(URL file) throws JmriException;
207
208    /**
209     * Provide a method-specific way of locating a file to be loaded from a
210     * name.
211     *
212     * @param filename Local filename, perhaps without path information
213     * @return Corresponding {@link java.net.URL}
214     */
215    URL find(String filename);
216
217    /**
218     * Make a backup file.
219     *
220     * @param file to be backed up
221     * @return true if successful
222     */
223    @CheckReturnValue
224    boolean makeBackup(File file);
225
226    /**
227     * Control the scope of validation of XML files when loading.
228     *
229     * @param validate the validation scope
230     */
231    void setValidate(XmlFile.Validate validate);
232
233    /**
234     * Get the scope of validation of XML files when loading.
235     *
236     * @return the validation scope
237     */
238    XmlFile.Validate getValidate();
239}