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: 439648 $, $Date: 2006-09-02 22:42:10 +0200 (Sa, 02 Sep 2006) $
    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 if it's a file 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      * Return the base path.
    182      *
    183      * @return the base path
    184      */
    185     String getBasePath();
    186
    187     /***
    188      * Set the base path. Relative configurations are loaded from this path.
    189      *
    190      * @param basePath the base path.
    191      */
    192     void setBasePath(String basePath);
    193
    194     /***
    195      * Return the file where the configuration is stored.
    196      *
    197      * @return the configuration file
    198      */
    199     File getFile();
    200
    201     /***
    202      * Set the file where the configuration is stored.
    203      *
    204      * @param file the file
    205      */
    206     void setFile(File file);
    207
    208     /***
    209      * Return the URL where the configuration is stored.
    210      *
    211      * @return the URL of the configuration
    212      */
    213     URL getURL();
    214
    215     /***
    216      * The URL where the configuration is stored.
    217      *
    218      * @param url the URL
    219      */
    220     void setURL(URL url);
    221
    222     /***
    223      * Enable or disable the automatical saving of modified properties to the disk.
    224      *
    225      * @param autoSave <code>true</code> to enable, <code>false</code> to disable
    226      * @since 1.1
    227      */
    228     void setAutoSave(boolean autoSave);
    229
    230     /***
    231      * Tells if properties are automatically saved to the disk.
    232      *
    233      * @return <code>true</code> if auto-saving is enabled, <code>false</code> otherwise
    234      * @since 1.1
    235      */
    236     boolean isAutoSave();
    237
    238     /***
    239      * Return the reloading strategy.
    240      *
    241      * @return the reloading strategy currently used
    242      * @since 1.1
    243      */
    244     ReloadingStrategy getReloadingStrategy();
    245
    246     /***
    247      * Set the reloading strategy.
    248      *
    249      * @param strategy the reloading strategy to use
    250      * @since 1.1
    251      */
    252     void setReloadingStrategy(ReloadingStrategy strategy);
    253
    254     /***
    255      * Reload the configuration.
    256      *
    257      * @since 1.1
    258      */
    259     void reload();
    260
    261     /***
    262      * Return the encoding used to store the configuration file. If the value
    263      * is null the default encoding is used.
    264      *
    265      * @return the current encoding
    266      * @since 1.1
    267      */
    268     String getEncoding();
    269
    270     /***
    271      * Set the encoding used to store the configuration file. Set the encoding
    272      * to null to use the default encoding.
    273      *
    274      * @param encoding the encoding to use
    275      * @since 1.1
    276      */
    277     void setEncoding(String encoding);
    278
    279 }