Package org.apache.commons.configuration2.builder

## Class FileBasedConfigurationBuilder<T extends FileBasedConfiguration>

- java.lang.Object
- - org.apache.commons.configuration2.builder.BasicConfigurationBuilder<T>
  - - org.apache.commons.configuration2.builder.FileBasedConfigurationBuilder<T>

- Type Parameters:
    `T` - the concrete type of `Configuration` objects created by this builder
  All Implemented Interfaces:
    `ConfigurationBuilder<T>`, `EventSource`
  Direct Known Subclasses:
    `ReloadingFileBasedConfigurationBuilder`

      public class FileBasedConfigurationBuilder<T extends FileBasedConfiguration>
      extends BasicConfigurationBuilder<T>

  A specialized `ConfigurationBuilder` implementation which can handle configurations read from a `FileHandler`.

  This class extends its base class by the support of a `FileBasedBuilderParametersImpl` object, and especially of the `FileHandler` contained in this object. When the builder creates a new object the resulting `Configuration` instance is associated with the `FileHandler`. If the `FileHandler` has a location set, the `Configuration` is directly loaded from this location.

  The `FileHandler` is kept by this builder and can be queried later on. It can be used for instance to save the current `Configuration` after it was modified. Some care has to be taken when changing the location of the `FileHandler`: The new location is recorded and also survives an invocation of the `resetResult()` method. However, when the builder's initialization parameters are reset by calling `resetParameters()` the location is reset, too.

  Since:
    2.0

- - ### Constructor Summary

    Constructors
    Constructor | Description
    --- | ---
    `FileBasedConfigurationBuilder​(Class<? extends T> resCls)` | Creates a new instance of `FileBasedConfigurationBuilder` which produces result objects of the specified class.
    `FileBasedConfigurationBuilder​(Class<? extends T> resCls, Map<String,​Object> params)` | Creates a new instance of `FileBasedConfigurationBuilder` which produces result objects of the specified class and sets initialization parameters.
    `FileBasedConfigurationBuilder​(Class<? extends T> resCls, Map<String,​Object> params, boolean allowFailOnInit)` | Creates a new instance of `FileBasedConfigurationBuilder` which produces result objects of the specified class and sets initialization parameters and the allowFailOnInit flag.

  - ### Method Summary

    All Methods Static Methods Instance Methods Concrete Methods
    Modifier and Type | Method | Description
    --- | --- | ---
    `FileBasedConfigurationBuilder<T>` | `configure​(BuilderParameters... params)` | Appends the content of the specified `BuilderParameters` objects to the current initialization parameters.
    `static String` | `getDefaultEncoding​(Class<?> configClass)` | Gets the default encoding for the specified configuration class.
    `FileHandler` | `getFileHandler()` | Gets the `FileHandler` associated with this builder.
    `protected void` | `initFileHandler​(FileHandler handler)` | Initializes the new current `FileHandler`.
    `protected void` | `initResultInstance​(T obj)` | Initializes a newly created result object.
    `boolean` | `isAutoSave()` | Gets a flag whether auto save mode is currently active.
    `void` | `save()` | Convenience method which saves the associated configuration.
    `void` | `setAutoSave​(boolean enabled)` | Enables or disables auto save mode.
    `static void` | `setDefaultEncoding​(Class<?> configClass, String encoding)` | Sets a default encoding for a specific configuration class.
    `BasicConfigurationBuilder<T>` | `setParameters​(Map<String,​Object> params)` | Sets the initialization parameters of this builder.

    - ### Methods inherited from class org.apache.commons.configuration2.builder.BasicConfigurationBuilder

      `addEventListener, addParameters, connectToReloadingController, copyEventListeners, copyEventListeners, createResult, createResultDeclaration, createResultInstance, fetchBeanHelper, fireBuilderEvent, getConfiguration, getParameters, getResultClass, getResultDeclaration, installEventListener, isAllowFailOnInit, removeEventListener, reset, resetParameters, resetResult`

    - ### Methods inherited from class java.lang.Object

      `clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait`

- - ### Constructor Detail

    - #### FileBasedConfigurationBuilder

          public FileBasedConfigurationBuilder​(Class<? extends T> resCls)

      Creates a new instance of `FileBasedConfigurationBuilder` which produces result objects of the specified class.
      Parameters:
        `resCls` - the result class (must not be null
      Throws:
        `IllegalArgumentException` - if the result class is null

    - #### FileBasedConfigurationBuilder

          public FileBasedConfigurationBuilder​(Class<? extends T> resCls,
                                               Map<String,​Object> params)

      Creates a new instance of `FileBasedConfigurationBuilder` which produces result objects of the specified class and sets initialization parameters.
      Parameters:
        `resCls` - the result class (must not be null
        `params` - a map with initialization parameters
      Throws:
        `IllegalArgumentException` - if the result class is null

    - #### FileBasedConfigurationBuilder

          public FileBasedConfigurationBuilder​(Class<? extends T> resCls,
                                               Map<String,​Object> params,
                                               boolean allowFailOnInit)

      Creates a new instance of `FileBasedConfigurationBuilder` which produces result objects of the specified class and sets initialization parameters and the allowFailOnInit flag.
      Parameters:
        `resCls` - the result class (must not be null
        `params` - a map with initialization parameters
        `allowFailOnInit` - the allowFailOnInit flag
      Throws:
        `IllegalArgumentException` - if the result class is null

  - ### Method Detail

    - #### getDefaultEncoding

          public static String getDefaultEncoding​(Class<?> configClass)

      Gets the default encoding for the specified configuration class. If an encoding has been set for the specified class (or one of its super classes), it is returned. Otherwise, result is null.
      Parameters:
        `configClass` - the configuration class in question
      Returns:
        the default encoding for this class (may be null)

    - #### setDefaultEncoding

          public static void setDefaultEncoding​(Class<?> configClass,
                                                String encoding)

      Sets a default encoding for a specific configuration class. This encoding is used if an instance of this configuration class is to be created and no encoding has been set in the parameters object for this builder. The encoding passed here not only applies to the specified class but also to its sub classes. If the encoding is null, it is removed.
      Parameters:
        `configClass` - the name of the configuration class (must not be null)
        `encoding` - the default encoding for this class
      Throws:
        `IllegalArgumentException` - if the class is null

    - #### configure

          public FileBasedConfigurationBuilder<T> configure​(BuilderParameters... params)

      Appends the content of the specified `BuilderParameters` objects to the current initialization parameters. Calling this method multiple times will create a union of the parameters provided. This method is overridden here to change the result type.
      Overrides:
        `configure` in class `BasicConfigurationBuilder<T extends FileBasedConfiguration>`
      Parameters:
        `params` - an arbitrary number of objects with builder parameters
      Returns:
        a reference to this builder for method chaining

    - #### getFileHandler

          public FileHandler getFileHandler()

      Gets the `FileHandler` associated with this builder. If already a result object has been created, this `FileHandler` can be used to save it. Otherwise, the `FileHandler` from the initialization parameters is returned (which is not associated with a `FileBased` object). Result is never null.
      Returns:
        the `FileHandler` associated with this builder

    - #### setParameters

          public BasicConfigurationBuilder<T> setParameters​(Map<String,​Object> params)

      Sets the initialization parameters of this builder. Already existing parameters are replaced by the content of the given map. This implementation just records the fact that new parameters have been set. This means that the next time a result object is created, the `FileHandler` has to be initialized from initialization parameters rather than reusing the existing one.
      Overrides:
        `setParameters` in class `BasicConfigurationBuilder<T extends FileBasedConfiguration>`
      Parameters:
        `params` - the new initialization parameters of this builder; can be null, then all initialization parameters are removed
      Returns:
        a reference to this builder for method chaining

    - #### save

          public void save()
                    throws ConfigurationException

      Convenience method which saves the associated configuration. This method expects that the managed configuration has already been created and that a valid file location is available in the current `FileHandler`. The file handler is then used to store the configuration.
      Throws:
        `ConfigurationException` - if an error occurs

    - #### isAutoSave

          public boolean isAutoSave()

      Gets a flag whether auto save mode is currently active.
      Returns:
        true if auto save is enabled, false otherwise

    - #### setAutoSave

          public void setAutoSave​(boolean enabled)

      Enables or disables auto save mode. If auto save mode is enabled, every update of the managed configuration causes it to be saved automatically; so changes are directly written to disk.
      Parameters:
        `enabled` - true if auto save mode is to be enabled, false otherwise

    - #### initResultInstance

          protected void initResultInstance​(T obj)
                                     throws ConfigurationException

      Initializes a newly created result object. This is the second step of the process of producing a result object for this builder. This implementation uses the `BeanHelper` class to initialize the object's property based on the `BeanDeclaration` returned by `BasicConfigurationBuilder.getResultDeclaration()`. Note: This method is invoked in a synchronized block. This is required because internal state is accessed. Sub classes must not call this method without proper synchronization. This implementation deals with the creation and initialization of a `FileHandler` associated with the new result object.
      Overrides:
        `initResultInstance` in class `BasicConfigurationBuilder<T extends FileBasedConfiguration>`
      Parameters:
        `obj` - the object to be initialized
      Throws:
        `ConfigurationException` - if an error occurs

    - #### initFileHandler

          protected void initFileHandler​(FileHandler handler)
                                  throws ConfigurationException

      Initializes the new current `FileHandler`. When a new result object is created, a new `FileHandler` is created, too, and associated with the result object. This new handler is passed to this method. If a location is defined, the result object is loaded from this location. Note: This method is called from a synchronized block.
      Parameters:
        `handler` - the new current `FileHandler`
      Throws:
        `ConfigurationException` - if an error occurs