1 /* 2 * Licensed to the Apache Software Foundation (ASF) under one or more 3 * contributor license agreements. See the NOTICE file distributed with 4 * this work for additional information regarding copyright ownership. 5 * The ASF licenses this file to You under the Apache License, Version 2.0 6 * (the "License"); you may not use this file except in compliance with 7 * the License. You may obtain a copy of the License at 8 * 9 * http://www.apache.org/licenses/LICENSE-2.0 10 * 11 * Unless required by applicable law or agreed to in writing, software 12 * distributed under the License is distributed on an "AS IS" BASIS, 13 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 14 * See the License for the specific language governing permissions and 15 * limitations under the License. 16 */ 17 18 package org.apache.commons.configuration; 19 20 import java.io.File; 21 import java.io.InputStream; 22 import java.io.OutputStream; 23 import java.io.Reader; 24 import java.io.Writer; 25 import java.net.URL; 26 27 import org.apache.commons.configuration.reloading.ReloadingStrategy; 28 29 /** 30 * A persistent configuration loaded and saved to a file. 31 * 32 * @author Emmanuel Bourg 33 * @version $Id: FileConfiguration.java 1209883 2011-12-03 10:56:57Z oheger $ 34 * @since 1.0-rc2 35 */ 36 public interface FileConfiguration extends Configuration 37 { 38 /** 39 * Load the configuration from the underlying URL. If the URL is not 40 * specified, it attempts to locate the specified file name. 41 * 42 * @throws ConfigurationException if an error occurs during the load operation 43 */ 44 void load() throws ConfigurationException; 45 46 /** 47 * Locate the specified file and load the configuration. 48 * 49 * @param fileName the name of the file loaded 50 * 51 * @throws ConfigurationException if an error occurs during the load operation 52 */ 53 void load(String fileName) throws ConfigurationException; 54 55 /** 56 * Load the configuration from the specified file. 57 * 58 * @param file the loaded file 59 * 60 * @throws ConfigurationException if an error occurs during the load operation 61 */ 62 void load(File file) throws ConfigurationException; 63 64 /** 65 * Load the configuration from the specified URL. 66 * 67 * @param url the URL of the file loaded 68 * 69 * @throws ConfigurationException if an error occurs during the load operation 70 */ 71 void load(URL url) throws ConfigurationException; 72 73 /** 74 * Load the configuration from the specified stream, using the encoding 75 * returned by {@link #getEncoding()}. 76 * 77 * @param in the input stream 78 * 79 * @throws ConfigurationException if an error occurs during the load operation 80 */ 81 void load(InputStream in) throws ConfigurationException; 82 83 /** 84 * Load the configuration from the specified stream, using the specified 85 * encoding. If the encoding is null the default encoding is used. 86 * 87 * @param in the input stream 88 * @param encoding the encoding used. {@code null} to use the default encoding 89 * 90 * @throws ConfigurationException if an error occurs during the load operation 91 */ 92 void load(InputStream in, String encoding) throws ConfigurationException; 93 94 /** 95 * Load the configuration from the specified reader. 96 * 97 * @param in the reader 98 * 99 * @throws ConfigurationException if an error occurs during the load operation 100 */ 101 void load(Reader in) throws ConfigurationException; 102 103 /** 104 * Save the configuration. 105 * 106 * @throws ConfigurationException if an error occurs during the save operation 107 */ 108 void save() throws ConfigurationException; 109 110 /** 111 * Save the configuration to the specified file. 112 * 113 * @param fileName the name of the file to be saved 114 * 115 * @throws ConfigurationException if an error occurs during the save operation 116 */ 117 void save(String fileName) throws ConfigurationException; 118 119 /** 120 * Save the configuration to the specified file. 121 * 122 * @param file specifies the file to be saved 123 * 124 * @throws ConfigurationException if an error occurs during the save operation 125 */ 126 void save(File file) throws ConfigurationException; 127 128 /** 129 * Save the configuration to the specified URL. 130 * 131 * @param url the URL 132 * 133 * @throws ConfigurationException if an error occurs during the save operation 134 */ 135 void save(URL url) throws ConfigurationException; 136 137 /** 138 * Save the configuration to the specified stream, using the encoding 139 * returned by {@link #getEncoding()}. 140 * 141 * @param out the output stream 142 * 143 * @throws ConfigurationException if an error occurs during the save operation 144 */ 145 void save(OutputStream out) throws ConfigurationException; 146 147 /** 148 * Save the configuration to the specified stream, using the specified 149 * encoding. If the encoding is null the default encoding is used. 150 * 151 * @param out the output stream 152 * @param encoding the encoding to be used 153 * @throws ConfigurationException if an error occurs during the save operation 154 */ 155 void save(OutputStream out, String encoding) throws ConfigurationException; 156 157 /** 158 * Save the configuration to the specified writer. 159 * 160 * @param out the writer 161 * 162 * @throws ConfigurationException if an error occurs during the save operation 163 */ 164 void save(Writer out) throws ConfigurationException; 165 166 /** 167 * Return the name of the file. 168 * 169 * @return the file name 170 */ 171 String getFileName(); 172 173 /** 174 * Set the name of the file. 175 * 176 * @param fileName the name of the file 177 */ 178 void setFileName(String fileName); 179 180 /** 181 * Returns the base path. One way to specify the location of a configuration 182 * source is by setting its base path and its file name. This method returns 183 * this base path. The concrete value returned by this method depends on the 184 * way the location of the configuration file was set. If methods like 185 * {@code setFile()} or {@code setURL()} were used, the base 186 * path typically points to the parent directory of the configuration file 187 * (e.g. for the URL {@code file:/temp/test.properties} the base path 188 * will be {@code file:/temp/}). If the base path was explicitly set 189 * using {@code setBasePath()}, this method will return the exact 190 * value specified here without further modifications. 191 * 192 * @return the base path 193 * @see AbstractFileConfiguration#setBasePath(String) 194 */ 195 String getBasePath(); 196 197 /** 198 * Sets the base path. The methods {@code setBasePath()} and 199 * {@code setFileName()} can be used together to specify the location 200 * of the configuration file to be loaded. If relative file names are to 201 * be resolved (e.g. for the include files supported by 202 * {@code PropertiesConfiguration}), this base path will be used. 203 * 204 * @param basePath the base path. 205 */ 206 void setBasePath(String basePath); 207 208 /** 209 * Return the file where the configuration is stored. 210 * 211 * @return the configuration file 212 */ 213 File getFile(); 214 215 /** 216 * Set the file where the configuration is stored. 217 * 218 * @param file the file 219 */ 220 void setFile(File file); 221 222 /** 223 * Return the URL where the configuration is stored. 224 * 225 * @return the URL of the configuration 226 */ 227 URL getURL(); 228 229 /** 230 * The URL where the configuration is stored. 231 * 232 * @param url the URL 233 */ 234 void setURL(URL url); 235 236 /** 237 * Enable or disable the automatically saving of modified properties to the disk. 238 * 239 * @param autoSave {@code true} to enable, {@code false} to disable 240 * @since 1.1 241 */ 242 void setAutoSave(boolean autoSave); 243 244 /** 245 * Tells if properties are automatically saved to the disk. 246 * 247 * @return {@code true} if auto-saving is enabled, {@code false} otherwise 248 * @since 1.1 249 */ 250 boolean isAutoSave(); 251 252 /** 253 * Return the reloading strategy. 254 * 255 * @return the reloading strategy currently used 256 * @since 1.1 257 */ 258 ReloadingStrategy getReloadingStrategy(); 259 260 /** 261 * Set the reloading strategy. 262 * 263 * @param strategy the reloading strategy to use 264 * @since 1.1 265 */ 266 void setReloadingStrategy(ReloadingStrategy strategy); 267 268 /** 269 * Reload the configuration. 270 * 271 * @since 1.1 272 */ 273 void reload(); 274 275 /** 276 * Return the encoding used to store the configuration file. If the value 277 * is null the default encoding is used. 278 * 279 * @return the current encoding 280 * @since 1.1 281 */ 282 String getEncoding(); 283 284 /** 285 * Set the encoding used to store the configuration file. Set the encoding 286 * to null to use the default encoding. 287 * 288 * @param encoding the encoding to use 289 * @since 1.1 290 */ 291 void setEncoding(String encoding); 292 293 }