Coverage Report - org.apache.commons.configuration.FileConfiguration
 
Classes in this File Line Coverage Branch Coverage Complexity
FileConfiguration
N/A
N/A
1
 
 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: org.apache.commons.configuration.FileConfiguration.html 910708 2014-05-31 19:13:45Z 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  
 }