001/* 002 * Licensed to the Apache Software Foundation (ASF) under one or more 003 * contributor license agreements. See the NOTICE file distributed with 004 * this work for additional information regarding copyright ownership. 005 * The ASF licenses this file to You under the Apache License, Version 2.0 006 * (the "License"); you may not use this file except in compliance with 007 * the License. You may obtain a copy of the License at 008 * 009 * http://www.apache.org/licenses/LICENSE-2.0 010 * 011 * Unless required by applicable law or agreed to in writing, software 012 * distributed under the License is distributed on an "AS IS" BASIS, 013 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 014 * See the License for the specific language governing permissions and 015 * limitations under the License. 016 */ 017 018package org.apache.commons.configuration; 019 020import java.io.File; 021import java.io.InputStream; 022import java.io.OutputStream; 023import java.io.Reader; 024import java.io.Writer; 025import java.net.URL; 026 027import org.apache.commons.configuration.reloading.ReloadingStrategy; 028 029/** 030 * A persistent configuration loaded and saved to a file. 031 * 032 * @author Emmanuel Bourg 033 * @version $Id: FileConfiguration.java 1209883 2011-12-03 10:56:57Z oheger $ 034 * @since 1.0-rc2 035 */ 036public interface FileConfiguration extends Configuration 037{ 038 /** 039 * Load the configuration from the underlying URL. If the URL is not 040 * specified, it attempts to locate the specified file name. 041 * 042 * @throws ConfigurationException if an error occurs during the load operation 043 */ 044 void load() throws ConfigurationException; 045 046 /** 047 * Locate the specified file and load the configuration. 048 * 049 * @param fileName the name of the file loaded 050 * 051 * @throws ConfigurationException if an error occurs during the load operation 052 */ 053 void load(String fileName) throws ConfigurationException; 054 055 /** 056 * Load the configuration from the specified file. 057 * 058 * @param file the loaded file 059 * 060 * @throws ConfigurationException if an error occurs during the load operation 061 */ 062 void load(File file) throws ConfigurationException; 063 064 /** 065 * Load the configuration from the specified URL. 066 * 067 * @param url the URL of the file loaded 068 * 069 * @throws ConfigurationException if an error occurs during the load operation 070 */ 071 void load(URL url) throws ConfigurationException; 072 073 /** 074 * Load the configuration from the specified stream, using the encoding 075 * returned by {@link #getEncoding()}. 076 * 077 * @param in the input stream 078 * 079 * @throws ConfigurationException if an error occurs during the load operation 080 */ 081 void load(InputStream in) throws ConfigurationException; 082 083 /** 084 * Load the configuration from the specified stream, using the specified 085 * encoding. If the encoding is null the default encoding is used. 086 * 087 * @param in the input stream 088 * @param encoding the encoding used. {@code null} to use the default encoding 089 * 090 * @throws ConfigurationException if an error occurs during the load operation 091 */ 092 void load(InputStream in, String encoding) throws ConfigurationException; 093 094 /** 095 * Load the configuration from the specified reader. 096 * 097 * @param in the reader 098 * 099 * @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}