Package org.apache.commons.configuration2.builder

# Class FileBasedBuilderParametersImpl

java.lang.Object
org.apache.commons.configuration2.builder.BasicBuilderParameters
org.apache.commons.configuration2.builder.FileBasedBuilderParametersImpl

All Implemented Interfaces:
  `Cloneable`, `BasicBuilderProperties<BasicBuilderParameters>`, `BuilderParameters`, `FileBasedBuilderProperties<FileBasedBuilderParametersImpl>`

Direct Known Subclasses:
  `HierarchicalBuilderParametersImpl`, `PropertiesBuilderParametersImpl`

public class FileBasedBuilderParametersImpl extends BasicBuilderParameters implements FileBasedBuilderProperties<FileBasedBuilderParametersImpl>

An implementation of `BuilderParameters` which contains parameters related to `Configuration` implementations that are loaded from files.

The parameters defined here are interpreted by builder implementations that can deal with file-based configurations. Note that these parameters are typically no initialization properties of configuration objects (i.e. they are not passed to set methods after the creation of the result configuration). Rather, the parameters object is stored as a whole in the builder's map with initialization parameters and can be accessed from there.

This class is not thread-safe. It is intended that an instance is constructed and initialized by a single thread during configuration of a `ConfigurationBuilder`.

Since:
  2.0

- ## Field Summary

  ### Fields inherited from interface org.apache.commons.configuration2.builder.BuilderParameters

  `RESERVED_PARAMETER_PREFIX`

- ## Constructor Summary

  Constructors
  Constructor
  Description
  `FileBasedBuilderParametersImpl()`
  Creates a new instance of `FileBasedBuilderParametersImpl` with an uninitialized `FileHandler` object.
  `FileBasedBuilderParametersImpl(FileHandler handler)`
  Creates a new instance of `FileBasedBuilderParametersImpl` and associates it with the given `FileHandler` object.

- ## Method Summary

  Modifier and Type
  Method
  Description
  `FileBasedBuilderParametersImpl`
  `clone()`
  Clones this object.
  `static FileBasedBuilderParametersImpl`
  `fromMap(Map<String,?> map)`
  Creates a new `FileBasedBuilderParametersImpl` object from the content of the given map.
  `static FileBasedBuilderParametersImpl`
  `fromParameters(Map<String,?> params)`
  Looks up an instance of this class in the specified parameters map.
  `static FileBasedBuilderParametersImpl`
  `fromParameters(Map<String,?> params, boolean createIfMissing)`
  Looks up an instance of this class in the specified parameters map and optionally creates a new one if none is found.
  `FileHandler`
  `getFileHandler()`
  Gets the `FileHandler` managed by this object.
  `Map<String,Object>`
  `getParameters()`
  Gets a map with all parameters defined by this objects.
  `ReloadingDetectorFactory`
  `getReloadingDetectorFactory()`
  Gets the `ReloadingDetectorFactory`.
  `Long`
  `getReloadingRefreshDelay()`
  Gets the refresh delay for reload operations.
  `void`
  `inheritFrom(Map<String,?> source)`
  Inherits properties from the specified map.
  `FileBasedBuilderParametersImpl`
  `setBasePath(String path)`
  Sets the base path of the associated `FileHandler`.
  `FileBasedBuilderParametersImpl`
  `setEncoding(String enc)`
  Sets the encoding of the associated `FileHandler`.
  `FileBasedBuilderParametersImpl`
  `setFile(File file)`
  Sets the location of the associated `FileHandler` as a `File` object.
  `FileBasedBuilderParametersImpl`
  `setFileName(String name)`
  Sets the file name of the associated `FileHandler`.
  `FileBasedBuilderParametersImpl`
  `setFileSystem(FileSystem fs)`
  Sets the `FileSystem` of the associated `FileHandler`.
  `FileBasedBuilderParametersImpl`
  `setLocationStrategy(FileLocationStrategy strategy)`
  Sets the `FileLocationStrategy` for resolving the referenced file.
  `FileBasedBuilderParametersImpl`
  `setPath(String path)`
  Sets the location of the associated `FileHandler` as an absolute file path.
  `FileBasedBuilderParametersImpl`
  `setReloadingDetectorFactory(ReloadingDetectorFactory reloadingDetectorFactory)`
  Sets the factory for creating `ReloadingDetector` objects.
  `FileBasedBuilderParametersImpl`
  `setReloadingRefreshDelay(Long reloadingRefreshDelay)`
  Sets the refresh delay for reloading support
  `FileBasedBuilderParametersImpl`
  `setURL(URL url)`
  Sets the location of the associated `FileHandler` as a `URL` object.
  `FileBasedBuilderParametersImpl`
  `setURL(URL url, URLConnectionOptions urlConnectionOptions)`
  Sets the location of the associated `FileHandler` as a `URL` object.

  ### Methods inherited from class org.apache.commons.configuration2.builder.BasicBuilderParameters

  `copyPropertiesFrom, fetchBeanHelper, fetchInterpolatorSpecification, fetchProperty, merge, setBeanHelper, setConfigurationDecoder, setConversionHandler, setDefaultLookups, setInterpolator, setListDelimiterHandler, setLogger, setParentInterpolator, setPrefixLookups, setSynchronizer, setThrowExceptionOnMissing, storeProperty`

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

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

- ## Constructor Details

  - ### FileBasedBuilderParametersImpl

    public FileBasedBuilderParametersImpl()
    Creates a new instance of `FileBasedBuilderParametersImpl` with an uninitialized `FileHandler` object.

  - ### FileBasedBuilderParametersImpl

    public FileBasedBuilderParametersImpl(FileHandler handler)
    Creates a new instance of `FileBasedBuilderParametersImpl` and associates it with the given `FileHandler` object. If the handler is null, a new handler instance is created.
    Parameters:
      `handler` - the associated `FileHandler` (can be null)

- ## Method Details

  - ### fromMap

    public static FileBasedBuilderParametersImpl fromMap(Map<String,?> map)
    Creates a new `FileBasedBuilderParametersImpl` object from the content of the given map. While `fromParameters()` expects that an object already exists and is stored in the given map, this method creates a new instance based on the content of the map. The map can contain properties of a `FileHandler` and some additional settings which are stored directly in the newly created object. If the map is null, an uninitialized instance is returned.
    Parameters:
      `map` - the map with properties (must not be null)
    Returns:
      the newly created instance
    Throws:
      `ClassCastException` - if the map contains invalid data

  - ### fromParameters

    public static FileBasedBuilderParametersImpl fromParameters(Map<String,?> params)
    Looks up an instance of this class in the specified parameters map. This is equivalent to `fromParameters(params, false`;}
    Parameters:
      `params` - the map with parameters (must not be null
    Returns:
      the instance obtained from the map or null
    Throws:
      `IllegalArgumentException` - if the map is null

  - ### fromParameters

    public static FileBasedBuilderParametersImpl fromParameters(Map<String,?> params, boolean createIfMissing)
    Looks up an instance of this class in the specified parameters map and optionally creates a new one if none is found. This method can be used to obtain an instance of this class which has been stored in a parameters map. It is compatible with the `getParameters()` method.
    Parameters:
      `params` - the map with parameters (must not be null
      `createIfMissing` - determines the behavior if no instance is found in the map; if true, a new instance with default settings is created; if false, null is returned
    Returns:
      the instance obtained from the map or null
    Throws:
      `IllegalArgumentException` - if the map is null

  - ### clone

    public FileBasedBuilderParametersImpl clone()
    Clones this object. This is useful because multiple builder instances may use a similar set of parameters. However, single instances of parameter objects must not assigned to multiple builders. Therefore, cloning a parameters object provides a solution for this use case. This method creates a new parameters object with the same content as this one. The internal map storing the parameter values is cloned, too, also collection structures contained in this map. However, no a full deep clone operation is performed. Objects like a `ConfigurationInterpolator` or `Lookup`s are shared between this and the newly created instance. This implementation also creates a copy of the `FileHandler`.
    Overrides:
      `clone` in class `BasicBuilderParameters`
    Returns:
      a clone of this object

  - ### getFileHandler

    public FileHandler getFileHandler()
    Gets the `FileHandler` managed by this object. This object is updated every time the file location is changed.
    Returns:
      the managed `FileHandler`

  - ### getParameters

    public Map<String,Object> getParameters()
    Gets a map with all parameters defined by this objects. The keys of the map correspond to concrete properties supported by the `Configuration` implementation class the builder produces. The values are the corresponding property values. The return value must not be null. This implementation returns a copy of the internal parameters map with the values set so far. Collection structures (e.g. for lookup objects) are stored as defensive copies, so the original data cannot be modified. This implementation returns a map which contains this object itself under a specific key. The static `fromParameters()` method can be used to extract an instance from a parameters map. Of course, the properties inherited from the base class are also added to the result map.
    Specified by:
      `getParameters` in interface `BuilderParameters`
    Overrides:
      `getParameters` in class `BasicBuilderParameters`
    Returns:
      a map with builder parameters

  - ### getReloadingDetectorFactory

    public ReloadingDetectorFactory getReloadingDetectorFactory()
    Gets the `ReloadingDetectorFactory`. Result may be null which means that the default factory is to be used.
    Returns:
      the `ReloadingDetectorFactory`

  - ### getReloadingRefreshDelay

    public Long getReloadingRefreshDelay()
    Gets the refresh delay for reload operations. Result may be null if this value has not been set.
    Returns:
      the reloading refresh delay

  - ### inheritFrom

    public void inheritFrom(Map<String,?> source)
    Inherits properties from the specified map. This can be used for instance to reuse parameters from one builder in another builder - also in parent-child relations in which a parent builder creates child builders. The purpose of this method is to let a concrete implementation decide which properties can be inherited. Because parameters are basically organized as a map it would be possible to simply copy over all properties from the source object. However, this is not appropriate in all cases. For instance, some properties - like a `ConfigurationInterpolator` - are tightly connected to a configuration and cannot be reused in a different context. For other properties, e.g. a file name, it does not make sense to copy it. Therefore, an implementation has to be explicit in the properties it wants to take over. This implementation takes some properties defined in this class into account.
    Overrides:
      `inheritFrom` in class `BasicBuilderParameters`
    Parameters:
      `source` - the source properties to inherit from

  - ### setBasePath

    public FileBasedBuilderParametersImpl setBasePath(String path)
    Description copied from interface: `FileBasedBuilderProperties`
    Sets the base path of the associated `FileHandler`.
    Specified by:
      `setBasePath` in interface `FileBasedBuilderProperties<FileBasedBuilderParametersImpl>`
    Parameters:
      `path` - the base path
    Returns:
      a reference to this object for method chaining

  - ### setEncoding

    public FileBasedBuilderParametersImpl setEncoding(String enc)
    Description copied from interface: `FileBasedBuilderProperties`
    Sets the encoding of the associated `FileHandler`.
    Specified by:
      `setEncoding` in interface `FileBasedBuilderProperties<FileBasedBuilderParametersImpl>`
    Parameters:
      `enc` - the encoding
    Returns:
      a reference to this object for method chaining

  - ### setFile

    public FileBasedBuilderParametersImpl setFile(File file)
    Description copied from interface: `FileBasedBuilderProperties`
    Sets the location of the associated `FileHandler` as a `File` object.
    Specified by:
      `setFile` in interface `FileBasedBuilderProperties<FileBasedBuilderParametersImpl>`
    Parameters:
      `file` - the `File` location
    Returns:
      a reference to this object for method chaining

  - ### setFileName

    public FileBasedBuilderParametersImpl setFileName(String name)
    Description copied from interface: `FileBasedBuilderProperties`
    Sets the file name of the associated `FileHandler`.
    Specified by:
      `setFileName` in interface `FileBasedBuilderProperties<FileBasedBuilderParametersImpl>`
    Parameters:
      `name` - the file name
    Returns:
      a reference to this object for method chaining

  - ### setFileSystem

    public FileBasedBuilderParametersImpl setFileSystem(FileSystem fs)
    Description copied from interface: `FileBasedBuilderProperties`
    Sets the `FileSystem` of the associated `FileHandler`.
    Specified by:
      `setFileSystem` in interface `FileBasedBuilderProperties<FileBasedBuilderParametersImpl>`
    Parameters:
      `fs` - the `FileSystem`
    Returns:
      a reference to this object for method chaining

  - ### setLocationStrategy

    public FileBasedBuilderParametersImpl setLocationStrategy(FileLocationStrategy strategy)
    Description copied from interface: `FileBasedBuilderProperties`
    Sets the `FileLocationStrategy` for resolving the referenced file.
    Specified by:
      `setLocationStrategy` in interface `FileBasedBuilderProperties<FileBasedBuilderParametersImpl>`
    Parameters:
      `strategy` - the `FileLocationStrategy`
    Returns:
      a reference to this object for method chaining

  - ### setPath

    public FileBasedBuilderParametersImpl setPath(String path)
    Description copied from interface: `FileBasedBuilderProperties`
    Sets the location of the associated `FileHandler` as an absolute file path.
    Specified by:
      `setPath` in interface `FileBasedBuilderProperties<FileBasedBuilderParametersImpl>`
    Parameters:
      `path` - the path location
    Returns:
      a reference to this object for method chaining

  - ### setReloadingDetectorFactory

    public FileBasedBuilderParametersImpl setReloadingDetectorFactory(ReloadingDetectorFactory reloadingDetectorFactory)
    Description copied from interface: `FileBasedBuilderProperties`
    Sets the factory for creating `ReloadingDetector` objects. With this method a custom factory for reloading detectors can be installed. Per default, a factory creating `FileHandlerReloadingDetector` objects is used.
    Specified by:
      `setReloadingDetectorFactory` in interface `FileBasedBuilderProperties<FileBasedBuilderParametersImpl>`
    Parameters:
      `reloadingDetectorFactory` - the `ReloadingDetectorFactory`
    Returns:
      a reference to this object for method chaining

  - ### setReloadingRefreshDelay

    public FileBasedBuilderParametersImpl setReloadingRefreshDelay(Long reloadingRefreshDelay)
    Description copied from interface: `FileBasedBuilderProperties`
    Sets the refresh delay for reloading support
    Specified by:
      `setReloadingRefreshDelay` in interface `FileBasedBuilderProperties<FileBasedBuilderParametersImpl>`
    Parameters:
      `reloadingRefreshDelay` - the refresh delay (in milliseconds)
    Returns:
      a reference to this object for method chaining

  - ### setURL

    public FileBasedBuilderParametersImpl setURL(URL url)
    Description copied from interface: `FileBasedBuilderProperties`
    Sets the location of the associated `FileHandler` as a `URL` object.
    Specified by:
      `setURL` in interface `FileBasedBuilderProperties<FileBasedBuilderParametersImpl>`
    Parameters:
      `url` - the `URL` location
    Returns:
      a reference to this object for method chaining

  - ### setURL

    public FileBasedBuilderParametersImpl setURL(URL url, URLConnectionOptions urlConnectionOptions)
    Description copied from interface: `FileBasedBuilderProperties`
    Sets the location of the associated `FileHandler` as a `URL` object.
    Specified by:
      `setURL` in interface `FileBasedBuilderProperties<FileBasedBuilderParametersImpl>`
    Parameters:
      `url` - the `URL` location
      `urlConnectionOptions` - options
    Returns:
      a reference to this object for method chaining