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