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}