<commit_before><?xml version="1.0"?>
<!--
   Licensed to the Apache Software Foundation (ASF) under one or more
   contributor license agreements.  See the NOTICE file distributed with
   this work for additional information regarding copyright ownership.
   The ASF licenses this file to You under the Apache License, Version 2.0
   (the "License"); you may not use this file except in compliance with
   the License.  You may obtain a copy of the License at

       http://www.apache.org/licenses/LICENSE-2.0

   Unless required by applicable law or agreed to in writing, software
   distributed under the License is distributed on an "AS IS" BASIS,
   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
   See the License for the specific language governing permissions and
   limitations under the License.
-->

<document>

 <properties>
  <title>File-based Configurations</title>
  <author email="<EMAIL>"><NAME></author>
 </properties>

<body>
    <section name="File-based Configurations">
        <p>
          Often configuration properties are stored in files on the user's hard
          disk, e.g. in .properties files or as XML documents. In order to
          access this data, functionality is needed to select the configuration
          files, load them into memory, and write changes back to disk. The
          following sections describe how this can be done.
        </p>

        <subsection name="FileBasedConfigurationBuilder">
        <p>
          In <em>Commons Configuration</em> a specialized
          <a href="howto_builders.html#Configuration_Builders">configuration
          builder</a> implementation is responsible for the creation of
          file-based configuration objects and the management of their
          associated data files:
          <code><a href="../apidocs/org/apache/commons/configuration2/builder/FileBasedConfigurationBuilder.html">
          FileBasedConfigurationBuilder</a></code>. Usage of this class follows
          the typical pattern for configuration builders, i.e. a builder
          instance is created providing the class of the <code>Configuration</code>
          object to be created, the <code>configure()</code> method is called
          with initialization parameters, and finally <code>getConfiguration()</code>
          returns an initialized instance of the configuration class. When
          configuring the builder the file to be loaded can be specified; if this
          was done, the <code>Configuration</code> object returned by the
          builder contains all properties read from the underlying file.
        </p>
        <p>
          In order to define the file to be loaded, a parameters object
          implementing the
          <code><a href="../apidocs/org/apache/commons/configuration2/builder/FileBasedBuilderProperties.html">
          FileBasedBuilderProperties</a></code> interface can be passed to the
          builder's <code>configure()</code> method. Using this interface the
          location of the file to be loaded can be provided in multiple ways:
          <ul>
            <li>With the <code>setFile()</code> method the data file can be
            specified as a <code>java.io.File</code> object.</li>
            <li>The <code>setURL()</code> method takes a <code>java.net.URL</code>
            as argument; the file will be loaded from this URL.</li>
            <li>The methods <code>setFileName()</code> and <code>setBasePath()</code>
            allow specifying the path of the data file. The base path is
            important if relative paths are to be resolved based on this file.</li>
            <li>With <code>setPath()</code> an absolute path to the file to be
            loaded can be provided.</li>
          </ul>
          A parameters object for file-based configurations is typically obtained
          from a <code><a href="../apidocs/org/apache/commons/configuration2/builder/fluent/Parameters.html">
          Parameters</a></code> instance. Here the <code>fileBased()</code> method
          or one of the methods returning parameter objects derived from
          <code>FileBasedBuilderProperties</code> can be used. In addition to
          the properties that define the location of the file to be loaded, the
          parameters object support a couple of other properties, too, which
          are mainly related to way how the file is resolved. This is described
          later on in this chapter.
        </p>
        <p>
          As an example for using a file-based configuration builder, the
          following code fragment shows how a properties file can be read whose
          location is specified using a <code>File</code> object:
        </p>
        <source><![CDATA[
Parameters params = new Parameters();
// Read data from this file
File propertiesFile = new File("config.properties");

FileBasedConfigurationBuilder<Configuration> builder =
    new FileBasedConfigurationBuilder<Configuration>(PropertiesConfiguration.class)
    .configure(params.fileBased()
        .setFile(propertiesFile));
try
{
    Configuration config = builder.getConfiguration();
    // config contains all properties read from the file
}
catch(ConfigurationException cex)
{
    // loading of the configuration file failed
}]]></source>
        <p>
          In this example a parameters object for file-based configurations
          is obtained from a <code>Parameters</code> instance. We could of
          course also have used a derived parameters class - when loading a
          properties file a parameters object for properties configurations
          would have been a logic choice. Here only a single parameter, the
          file to be loaded, is set; but remember that all other initialization
          parameters common to all configuration classes are available as well.
        </p>
	<p>
	  A configuration instance created this way stays connected to its
	  builder. Especially, the builder stores the location of the
	  underlying configuration file. This comes in handy if changes on
	  the configuration object are to be written back to disk. For this
	  purpose, <code>FileBasedConfigurationBuilder</code> provides a
	  convenient <code>save()</code> method. Calling this method stores
	  the current content of the associated configuration into its original
	  configuration file, overwriting the existing file on disk. This is
	  demonstrated in the following code fragment which continues from the
	  previous example:
	</p>
        <source><![CDATA[
// Some manipulations on the configuration object
config.addProperty("newProperty", "new");
config.setProperty("updateProperty", "changedValue");

// Make changes persistent
try
{
    builder.save();
}
catch(ConfigurationException cex)
{
    // saving of the configuration file failed
}]]></source>
	<p>
	  Note that the <code>save()</code> method of the builder does not
	  expect a configuration object as parameter. It always operates on
	  the instance managed by this builder. Because of this relationship
	  it is typically better to store the builder object rather than the
	  configuration. The configuration can always be obtained via the
	  builder's <code>getConfiguration()</code> method, but operations
	  related to the configuration file are only available through the
	  builder.
	</p>
	<p>
	  In addition to the <code>save()</code> method,
	  <code>FileBasedConfigurationBuilder</code> offers functionality for
	  automatically saving changes on its managed configuration. This can
	  be used to ensure that every modification of a configuration object is
	  immideately written to disk. This feature is enabled via the
	  <code>setAutoSave()</code> method as shown in the following example:
	</p>
        <source><![CDATA[
FileBasedConfigurationBuilder<Configuration> builder =
    new FileBasedConfigurationBuilder<Configuration>(PropertiesConfiguration.class)
    .configure(params.fileBased()
        .setFile(new File("config.properties")));
// enable auto save mode
builder.setAutoSave(true);

Configuration config = builder.getConfiguration();
config.setProperty("colors.background", "#000000"); // the configuration is saved after this call
]]></source>
	<p>
	  Be careful with this mode when you have many updates on your
          configuration. This will lead to many I/O operations, too. Behind
          the scenes, automatic saving is implemented via the
          <a href="howto_events.html">event notification mechanism</a> available
          for all configuration objects. A specialized event listener is
          registered at the builder's managed configuration object which triggers
          the <code>save()</code> method every time an update event is received.
	</p><commit_msg>[CONFIGURATION-620] Fixed wrong examples in user's guide.<commit_after><?xml version="1.0"?>
<!--
   Licensed to the Apache Software Foundation (ASF) under one or more
   contributor license agreements.  See the NOTICE file distributed with
   this work for additional information regarding copyright ownership.
   The ASF licenses this file to You under the Apache License, Version 2.0
   (the "License"); you may not use this file except in compliance with
   the License.  You may obtain a copy of the License at

       http://www.apache.org/licenses/LICENSE-2.0

   Unless required by applicable law or agreed to in writing, software
   distributed under the License is distributed on an "AS IS" BASIS,
   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
   See the License for the specific language governing permissions and
   limitations under the License.
-->

<document>

 <properties>
  <title>File-based Configurations</title>
  <author email="<EMAIL>"><NAME></author>
 </properties>

<body>
    <section name="File-based Configurations">
        <p>
          Often configuration properties are stored in files on the user's hard
          disk, e.g. in .properties files or as XML documents. In order to
          access this data, functionality is needed to select the configuration
          files, load them into memory, and write changes back to disk. The
          following sections describe how this can be done.
        </p>

        <subsection name="FileBasedConfigurationBuilder">
        <p>
          In <em>Commons Configuration</em> a specialized
          <a href="howto_builders.html#Configuration_Builders">configuration
          builder</a> implementation is responsible for the creation of
          file-based configuration objects and the management of their
          associated data files:
          <code><a href="../apidocs/org/apache/commons/configuration2/builder/FileBasedConfigurationBuilder.html">
          FileBasedConfigurationBuilder</a></code>. Usage of this class follows
          the typical pattern for configuration builders, i.e. a builder
          instance is created providing the class of the <code>Configuration</code>
          object to be created, the <code>configure()</code> method is called
          with initialization parameters, and finally <code>getConfiguration()</code>
          returns an initialized instance of the configuration class. When
          configuring the builder the file to be loaded can be specified; if this
          was done, the <code>Configuration</code> object returned by the
          builder contains all properties read from the underlying file.
        </p>
        <p>
          In order to define the file to be loaded, a parameters object
          implementing the
          <code><a href="../apidocs/org/apache/commons/configuration2/builder/FileBasedBuilderProperties.html">
          FileBasedBuilderProperties</a></code> interface can be passed to the
          builder's <code>configure()</code> method. Using this interface the
          location of the file to be loaded can be provided in multiple ways:
          <ul>
            <li>With the <code>setFile()</code> method the data file can be
            specified as a <code>java.io.File</code> object.</li>
            <li>The <code>setURL()</code> method takes a <code>java.net.URL</code>
            as argument; the file will be loaded from this URL.</li>
            <li>The methods <code>setFileName()</code> and <code>setBasePath()</code>
            allow specifying the path of the data file. The base path is
            important if relative paths are to be resolved based on this file.</li>
            <li>With <code>setPath()</code> an absolute path to the file to be
            loaded can be provided.</li>
          </ul>
          A parameters object for file-based configurations is typically obtained
          from a <code><a href="../apidocs/org/apache/commons/configuration2/builder/fluent/Parameters.html">
          Parameters</a></code> instance. Here the <code>fileBased()</code> method
          or one of the methods returning parameter objects derived from
          <code>FileBasedBuilderProperties</code> can be used. In addition to
          the properties that define the location of the file to be loaded, the
          parameters object support a couple of other properties, too, which
          are mainly related to way how the file is resolved. This is described
          later on in this chapter.
        </p>
        <p>
          As an example for using a file-based configuration builder, the
          following code fragment shows how a properties file can be read whose
          location is specified using a <code>File</code> object:
        </p>
        <source><![CDATA[
Parameters params = new Parameters();
// Read data from this file
File propertiesFile = new File("config.properties");

FileBasedConfigurationBuilder<FileBasedConfiguration> builder =
    new FileBasedConfigurationBuilder<FileBasedConfiguration>(PropertiesConfiguration.class)
    .configure(params.fileBased()
        .setFile(propertiesFile));
try
{
    Configuration config = builder.getConfiguration();
    // config contains all properties read from the file
}
catch(ConfigurationException cex)
{
    // loading of the configuration file failed
}]]></source>
        <p>
          In this example a parameters object for file-based configurations
          is obtained from a <code>Parameters</code> instance. We could of
          course also have used a derived parameters class - when loading a
          properties file a parameters object for properties configurations
          would have been a logic choice. Here only a single parameter, the
          file to be loaded, is set; but remember that all other initialization
          parameters common to all configuration classes are available as well.
        </p>
	<p>
	  A configuration instance created this way stays connected to its
	  builder. Especially, the builder stores the location of the
	  underlying configuration file. This comes in handy if changes on
	  the configuration object are to be written back to disk. For this
	  purpose, <code>FileBasedConfigurationBuilder</code> provides a
	  convenient <code>save()</code> method. Calling this method stores
	  the current content of the associated configuration into its original
	  configuration file, overwriting the existing file on disk. This is
	  demonstrated in the following code fragment which continues from the
	  previous example:
	</p>
        <source><![CDATA[
// Some manipulations on the configuration object
config.addProperty("newProperty", "new");
config.setProperty("updateProperty", "changedValue");

// Make changes persistent
try
{
    builder.save();
}
catch(ConfigurationException cex)
{
    // saving of the configuration file failed
}]]></source>
	<p>
	  Note that the <code>save()</code> method of the builder does not
	  expect a configuration object as parameter. It always operates on
	  the instance managed by this builder. Because of this relationship
	  it is typically better to store the builder object rather than the
	  configuration. The configuration can always be obtained via the
	  builder's <code>getConfiguration()</code> method, but operations
	  related to the configuration file are only available through the
	  builder.
	</p>
	<p>
	  In addition to the <code>save()</code> method,
	  <code>FileBasedConfigurationBuilder</code> offers functionality for
	  automatically saving changes on its managed configuration. This can
	  be used to ensure that every modification of a configuration object is
	  immideately written to disk. This feature is enabled via the
	  <code>setAutoSave()</code> method as shown in the following example:
	</p>
        <source><![CDATA[
FileBasedConfigurationBuilder<FileBasedConfiguration> builder =
    new FileBasedConfigurationBuilder<FileBasedConfiguration>(PropertiesConfiguration.class)
    .configure(params.fileBased()
        .setFile(new File("config.properties")));
// enable auto save mode
builder.setAutoSave(true);

Configuration config = builder.getConfiguration();
config.setProperty("colors.background", "#000000"); // the configuration is saved after this call
]]></source>
	<p>
	  Be careful with this mode when you have many updates on your
          configuration. This will lead to many I/O operations, too. Behind
          the scenes, automatic saving is implemented via the
          <a href="howto_events.html">event notification mechanism</a> available
          for all configuration objects. A specialized event listener is
          registered at the builder's managed configuration object which triggers
          the <code>save()</code> method every time an update event is received.
	</p>
{'fraction_non_alphanumeric': 0.07342419080068142, 'fraction_numerical': 0.0018739352640545145, 'mean_word_length': 3.1604063312071817, 'pattern_counts': {'":': 0, '<': 245, '<?xml version=': 2, '>': 245, 'https://': 0, 'lorem ipsum': 0, 'www.': 2, 'xml': 2}, 'pii_count': 0, 'substrings_counts': 0, 'word_list_counts': {'cursed_substrings.json': 0, 'profanity_word_list.json': 0, 'sexual_word_list.json': 0, 'zh_pornsignals.json': 0}}
{'dir': 'git-commits-cleaned', 'id': '6191673', 'n_tokens_mistral': 4131, 'n_tokens_neox': 4017, 'n_words': 1913}