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

  • Field Details

    • DEFAULT_ENCODINGS

      private static final Map<Class<?>,String> DEFAULT_ENCODINGS
      A map for storing default encodings for specific configuration classes.

    • currentFileHandler

      private FileHandler currentFileHandler
      Stores the FileHandler associated with the current configuration.

    • autoSaveListener

      private AutoSaveListener autoSaveListener
      A specialized listener for the auto save mechanism.

    • resetParameters

      private boolean resetParameters
      A flag whether the builder's parameters were reset.

  • Constructor Details

    • 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 Details

    • 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)

    • initializeDefaultEncodings

      private static Map<Class<?>,String> initializeDefaultEncodings()
      Creates a map with default encodings for configuration classes and populates it with default entries.
      Returns:
      the map with default encodings

    • 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

    • fetchFileHandlerFromParameters

      private FileHandler fetchFileHandlerFromParameters()
      Obtains the FileHandler from this builder's parameters. If no FileBasedBuilderParametersImpl object is found in this builder's parameters, a new one is created now and stored. This makes it possible to change the location of the associated file even if no parameters object was provided.
      Returns:
      the FileHandler from initialization parameters

    • 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

    • initEncoding

      private void initEncoding(FileHandler handler)
      Initializes the encoding of the specified file handler. If already an encoding is set, it is used. Otherwise, the default encoding for the result configuration class is obtained and set.
      Parameters:
      handler - the handler to be initialized

    • 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

    • 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

    • installAutoSaveListener

      private void installAutoSaveListener()
      Installs the listener for the auto save mechanism if it is not yet active.

    • isAutoSave

      public boolean isAutoSave()
      Gets a flag whether auto save mode is currently active.
      Returns:
      true if auto save is enabled, false otherwise

    • removeAutoSaveListener

      private void removeAutoSaveListener()
      Removes the listener for the auto save mechanism if it is currently active.

    • 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

    • 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

    • 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