View Javadoc

    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.net.URL;
    21  import java.io.InputStream;
    22  import java.io.Reader;
    23  import java.io.OutputStream;
    24  import java.io.Writer;
    25  import java.io.File;
    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 $Revision: 529194 $, $Date: 2007-04-16 12:40:42 +0200 (Mo, 16 Apr 2007) $
    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</code> 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()</code> or <code>setURL()</code> 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</code> the base path
    188      * will be <code>file:/temp/</code>). If the base path was explictly set
    189      * using <code>setBasePath()</code>, 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()</code> and
    199      * <code>setFileName()</code> 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</code>), 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 automatical saving of modified properties to the disk.
    238      *
    239      * @param autoSave <code>true</code> to enable, <code>false</code> 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</code> if auto-saving is enabled, <code>false</code> 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 }