    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
    018    package org.apache.commons.configuration;
    019
    020    import java.io.File;
    021    import java.io.InputStream;
    022    import java.io.OutputStream;
    023    import java.io.Reader;
    024    import java.io.Writer;
    025    import java.net.URL;
    026
    027    import 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     */
    036    public 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    }