Package org.apache.commons.configuration2.io

# Class FileHandler

java.lang.Object
org.apache.commons.configuration2.io.FileHandler

public class FileHandler extends Object

A class that manages persistence of an associated `FileBased` object.

Instances of this class can be used to load and save arbitrary objects implementing the `FileBased` interface in a convenient way from and to various locations. At construction time the `FileBased` object to manage is passed in. Basically, this object is assigned a location from which it is loaded and to which it can be saved. The following possibilities exist to specify such a location:

- URLs: With the method `setURL()` a full URL to the configuration source can be specified. This is the most flexible way. Note that the `save()` methods support only file: URLs.
- Files: The `setFile()` method allows to specify the configuration source as a file. This can be either a relative or an absolute file. In the former case the file is resolved based on the current directory.
- As file paths in string form: With the `setPath()` method a full path to a configuration file can be provided as a string.
- Separated as base path and file name: The base path is a string defining either a local directory or a URL. It can be set using the `setBasePath()` method. The file name, non surprisingly, defines the name of the configuration file.

An instance stores a location. The `load()` and `save()` methods that do not take an argument make use of this internal location. Alternatively, it is also possible to use overloaded variants of `load()` and `save()` which expect a location. In these cases the location specified takes precedence over the internal one; the internal location is not changed.

The actual position of the file to be loaded is determined by a `FileLocationStrategy` based on the location information that has been provided. By providing a custom location strategy the algorithm for searching files can be adapted. Save operations require more explicit information. They cannot rely on a location strategy because the file to be written may not yet exist. So there may be some differences in the way location information is interpreted by load and save operations. In order to avoid this, the following approach is recommended:

- Use the desired `setXXX()` methods to define the location of the file to be loaded.
- Call the `locate()` method. This method resolves the referenced file (if possible) and fills out all supported location information.
- Later on, `save()` can be called. This method now has sufficient information to store the file at the correct location.

When loading or saving a `FileBased` object some additional functionality is performed if the object implements one of the following interfaces:

- `FileLocatorAware`: In this case an object with the current file location is injected before the load or save operation is executed. This is useful for `FileBased` objects that depend on their current location, e.g. to resolve relative path names.
- `SynchronizerSupport`: If this interface is implemented, load and save operations obtain a write lock on the `FileBased` object before they access it. (In case of a save operation, a read lock would probably be sufficient, but because of the possible injection of a `FileLocator` object it is not allowed to perform multiple save operations in parallel; therefore, by obtaining a write lock, we are on the safe side.)

This class is thread-safe.

Since:
  2.0

- ## Constructor Summary

  Constructors
  Constructor
  Description
  `FileHandler()`
  Creates a new instance of `FileHandler` which is not associated with a `FileBased` object and thus does not have a content.
  `FileHandler(FileBased obj)`
  Creates a new instance of `FileHandler` and sets the managed `FileBased` object.
  `FileHandler(FileBased obj, FileHandler c)`
  Creates a new instance of `FileHandler` which is associated with the given `FileBased` object and the location defined for the given `FileHandler` object.

- ## Method Summary

  Modifier and Type
  Method
  Description
  `void`
  `addFileHandlerListener(FileHandlerListener l)`
  Adds a listener to this `FileHandler`.
  `void`
  `clearLocation()`
  Clears the location of this `FileHandler`.
  `static FileHandler`
  `fromMap(Map<String,?> map)`
  Creates a new `FileHandler` instance from properties stored in a map.
  `String`
  `getBasePath()`
  Gets the base path.
  `final FileBased`
  `getContent()`
  Gets the `FileBased` object associated with this `FileHandler`.
  `String`
  `getEncoding()`
  Gets the encoding of the associated file.
  `File`
  `getFile()`
  Gets the location of the associated file as a `File` object.
  `FileLocator`
  `getFileLocator()`
  Gets a `FileLocator` object with the specification of the file stored by this `FileHandler`.
  `String`
  `getFileName()`
  Gets the name of the file.
  `FileSystem`
  `getFileSystem()`
  Gets the `FileSystem` to be used by this object when locating files.
  `FileLocationStrategy`
  `getLocationStrategy()`
  Gets the `FileLocationStrategy` to be applied when accessing the associated file.
  `String`
  `getPath()`
  Gets the full path to the associated file.
  `URL`
  `getURL()`
  Gets the location of the associated file as a URL.
  `boolean`
  `isLocationDefined()`
  Tests whether a location is defined for this `FileHandler`.
  `void`
  `load()`
  Loads the associated file from the underlying location.
  `void`
  `load(File file)`
  Loads the associated file from the specified `File`.
  `void`
  `load(InputStream in)`
  Loads the associated file from the specified stream, using the encoding returned by `getEncoding()`.
  `void`
  `load(InputStream in, String encoding)`
  Loads the associated file from the specified stream, using the specified encoding.
  `void`
  `load(Reader in)`
  Loads the associated file from the specified reader.
  `void`
  `load(String fileName)`
  Loads the associated file from the given file name.
  `void`
  `load(URL url)`
  Loads the associated file from the specified URL.
  `boolean`
  `locate()`
  Locates the referenced file if necessary and ensures that the associated `FileLocator` is fully initialized.
  `void`
  `removeFileHandlerListener(FileHandlerListener l)`
  Removes the specified listener from this object.
  `void`
  `resetFileSystem()`
  Resets the `FileSystem` used by this object.
  `void`
  `save()`
  Saves the associated file to the current location set for this object.
  `void`
  `save(File file)`
  Saves the associated file to the specified `File`.
  `void`
  `save(OutputStream out)`
  Saves the associated file to the specified stream using the encoding returned by `getEncoding()`.
  `void`
  `save(OutputStream out, String encoding)`
  Saves the associated file to the specified stream using the specified encoding.
  `void`
  `save(Writer out)`
  Saves the associated file to the given `Writer`.
  `void`
  `save(String fileName)`
  Saves the associated file to the specified file name.
  `void`
  `save(URL url)`
  Saves the associated file to the specified URL.
  `void`
  `setBasePath(String basePath)`
  Sets the base path.
  `void`
  `setEncoding(String encoding)`
  Sets the encoding of the associated file.
  `void`
  `setFile(File file)`
  Sets the location of the associated file as a `File` object.
  `void`
  `setFileLocator(FileLocator locator)`
  Sets the file to be accessed by this `FileHandler` as a `FileLocator` object.
  `void`
  `setFileName(String fileName)`
  Sets the name of the file.
  `void`
  `setFileSystem(FileSystem fileSystem)`
  Sets the `FileSystem` to be used by this object when locating files.
  `void`
  `setLocationStrategy(FileLocationStrategy strategy)`
  Sets the `FileLocationStrategy` to be applied when accessing the associated file.
  `void`
  `setPath(String path)`
  Sets the location of the associated file as a full or relative path name.
  `void`
  `setURL(URL url)`
  Sets the location of the associated file as a URL.
  `void`
  `setURL(URL url, URLConnectionOptions urlConnectionOptions)`
  Sets the location of the associated file as a URL.

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

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

- ## Constructor Details

  - ### FileHandler

    public FileHandler()
    Creates a new instance of `FileHandler` which is not associated with a `FileBased` object and thus does not have a content. Objects of this kind can be used to define a file location, but it is not possible to actually load or save data.

  - ### FileHandler

    public FileHandler(FileBased obj)
    Creates a new instance of `FileHandler` and sets the managed `FileBased` object.
    Parameters:
      `obj` - the file-based object to manage

  - ### FileHandler

    public FileHandler(FileBased obj, FileHandler c)
    Creates a new instance of `FileHandler` which is associated with the given `FileBased` object and the location defined for the given `FileHandler` object. A copy of the location of the given `FileHandler` is created. This constructor is a possibility to associate a file location with a `FileBased` object.
    Parameters:
      `obj` - the `FileBased` object to manage
      `c` - the `FileHandler` from which to copy the location (must not be null)
    Throws:
      `IllegalArgumentException` - if the `FileHandler` is null

- ## Method Details

  - ### fromMap

    public static FileHandler fromMap(Map<String,?> map)
    Creates a new `FileHandler` instance from properties stored in a map. This method tries to extract a `FileLocator` from the map. A new `FileHandler` is created based on this `FileLocator`.
    Parameters:
      `map` - the map (may be null)
    Returns:
      the newly created `FileHandler`
    See Also:
      - `FileLocatorUtils.fromMap(Map)`

  - ### addFileHandlerListener

    public void addFileHandlerListener(FileHandlerListener l)
    Adds a listener to this `FileHandler`. It is notified about property changes and IO operations.
    Parameters:
      `l` - the listener to be added (must not be null)
    Throws:
      `IllegalArgumentException` - if the listener is null

  - ### clearLocation

    public void clearLocation()
    Clears the location of this `FileHandler`. Afterwards this handler does not point to any valid file.

  - ### getBasePath

    public String getBasePath()
    Gets the base path. If no base path is defined, but a URL, the base path is derived from there.
    Returns:
      the base path

  - ### getContent

    public final FileBased getContent()
    Gets the `FileBased` object associated with this `FileHandler`.
    Returns:
      the associated `FileBased` object

  - ### getEncoding

    public String getEncoding()
    Gets the encoding of the associated file. Result can be null if no encoding has been set.
    Returns:
      the encoding of the associated file

  - ### getFile

    public File getFile()
    Gets the location of the associated file as a `File` object. If the base path is a URL with a protocol different than "file", or the file is within a compressed archive, the return value will not point to a valid file object.
    Returns:
      the location as `File` object; this can be null

  - ### getFileLocator

    public FileLocator getFileLocator()
    Gets a `FileLocator` object with the specification of the file stored by this `FileHandler`. Note that this method returns the internal data managed by this `FileHandler` as it was defined. This is not necessarily the same as the data returned by the single access methods like `getFileName()` or `getURL()`: These methods try to derive missing data from other values that have been set.
    Returns:
      a `FileLocator` with the referenced file

  - ### getFileName

    public String getFileName()
    Gets the name of the file. If only a URL is defined, the file name is derived from there.
    Returns:
      the file name

  - ### getFileSystem

    public FileSystem getFileSystem()
    Gets the `FileSystem` to be used by this object when locating files. Result is never null; if no file system has been set, the default file system is returned.
    Returns:
      the used `FileSystem`

  - ### getLocationStrategy

    public FileLocationStrategy getLocationStrategy()
    Gets the `FileLocationStrategy` to be applied when accessing the associated file. This method never returns null. If a `FileLocationStrategy` has been set, it is returned. Otherwise, result is the default `FileLocationStrategy`.
    Returns:
      the `FileLocationStrategy` to be used

  - ### getPath

    public String getPath()
    Gets the full path to the associated file. The return value is a valid `File` path only if this location is based on a file on the local disk. If the file was loaded from a packed archive, the returned value is the string form of the URL from which the file was loaded.
    Returns:
      the full path to the associated file

  - ### getURL

    public URL getURL()
    Gets the location of the associated file as a URL. If a URL is set, it is directly returned. Otherwise, an attempt to locate the referenced file is made.
    Returns:
      a URL to the associated file; can be null if the location is unspecified

  - ### isLocationDefined

    public boolean isLocationDefined()
    Tests whether a location is defined for this `FileHandler`.
    Returns:
      true if a location is defined, false otherwise

  - ### load

    public void load() throws ConfigurationException
    Loads the associated file from the underlying location. If no location has been set, an exception is thrown.
    Throws:
      `ConfigurationException` - if loading of the configuration fails

  - ### load

    public void load(File file) throws ConfigurationException
    Loads the associated file from the specified `File`.
    Parameters:
      `file` - the file to load
    Throws:
      `ConfigurationException` - if an error occurs

  - ### load

    public void load(InputStream in) throws ConfigurationException
    Loads the associated file from the specified stream, using the encoding returned by `getEncoding()`.
    Parameters:
      `in` - the input stream
    Throws:
      `ConfigurationException` - if an error occurs during the load operation

  - ### load

    public void load(InputStream in, String encoding) throws ConfigurationException
    Loads the associated file from the specified stream, using the specified encoding. If the encoding is null, the default encoding is used.
    Parameters:
      `in` - the input stream
      `encoding` - the encoding used, `null` to use the default encoding
    Throws:
      `ConfigurationException` - if an error occurs during the load operation

  - ### load

    public void load(Reader in) throws ConfigurationException
    Loads the associated file from the specified reader.
    Parameters:
      `in` - the reader
    Throws:
      `ConfigurationException` - if an error occurs during the load operation

  - ### load

    public void load(String fileName) throws ConfigurationException
    Loads the associated file from the given file name. The file name is interpreted in the context of the already set location (e.g. if it is a relative file name, a base path is applied if available). The underlying location is not changed.
    Parameters:
      `fileName` - the name of the file to be loaded
    Throws:
      `ConfigurationException` - if an error occurs

  - ### load

    public void load(URL url) throws ConfigurationException
    Loads the associated file from the specified URL. The location stored in this object is not changed.
    Parameters:
      `url` - the URL of the file to be loaded
    Throws:
      `ConfigurationException` - if an error occurs

  - ### locate

    public boolean locate()
    Locates the referenced file if necessary and ensures that the associated `FileLocator` is fully initialized. When accessing the referenced file the information stored in the associated `FileLocator` is used. If this information is incomplete (e.g. only the file name is set), an attempt to locate the file may have to be performed on each access. By calling this method such an attempt is performed once, and the results of a successful localization are stored. Hence, later access to the referenced file can be more efficient. Also, all properties pointing to the referenced file in this object's `FileLocator` are set (i.e. the URL, the base path, and the file name). If the referenced file cannot be located, result is false. This means that the information in the current `FileLocator` is insufficient or wrong. If the `FileLocator` is already fully defined, it is not changed.
    Returns:
      a flag whether the referenced file could be located successfully
    See Also:
      - `FileLocatorUtils.fullyInitializedLocator(FileLocator)`

  - ### removeFileHandlerListener

    public void removeFileHandlerListener(FileHandlerListener l)
    Removes the specified listener from this object.
    Parameters:
      `l` - the listener to be removed

  - ### resetFileSystem

    public void resetFileSystem()
    Resets the `FileSystem` used by this object. It is set to the default file system.

  - ### save

    public void save() throws ConfigurationException
    Saves the associated file to the current location set for this object. Before this method can be called a valid location must have been set.
    Throws:
      `ConfigurationException` - if an error occurs or no location has been set yet

  - ### save

    public void save(File file) throws ConfigurationException
    Saves the associated file to the specified `File`. The file is created automatically if it doesn't exist. This does not change the location of this object (use `setFile(java.io.File)` if you need it).
    Parameters:
      `file` - the target file
    Throws:
      `ConfigurationException` - if an error occurs during the save operation

  - ### save

    public void save(OutputStream out) throws ConfigurationException
    Saves the associated file to the specified stream using the encoding returned by `getEncoding()`.
    Parameters:
      `out` - the output stream
    Throws:
      `ConfigurationException` - if an error occurs during the save operation

  - ### save

    public void save(OutputStream out, String encoding) throws ConfigurationException
    Saves the associated file to the specified stream using the specified encoding. If the encoding is null, the default encoding is used.
    Parameters:
      `out` - the output stream
      `encoding` - the encoding to be used, `null` to use the default encoding
    Throws:
      `ConfigurationException` - if an error occurs during the save operation

  - ### save

    public void save(String fileName) throws ConfigurationException
    Saves the associated file to the specified file name. This does not change the location of this object (use `setFileName(String)` if you need it).
    Parameters:
      `fileName` - the file name
    Throws:
      `ConfigurationException` - if an error occurs during the save operation

  - ### save

    public void save(URL url) throws ConfigurationException
    Saves the associated file to the specified URL. This does not change the location of this object (use `setURL(URL)` if you need it).
    Parameters:
      `url` - the URL
    Throws:
      `ConfigurationException` - if an error occurs during the save operation

  - ### save

    public void save(Writer out) throws ConfigurationException
    Saves the associated file to the given `Writer`.
    Parameters:
      `out` - the `Writer`
    Throws:
      `ConfigurationException` - if an error occurs during the save operation

  - ### setBasePath

    public void setBasePath(String basePath)
    Sets the base path. The base path is typically either a path to a directory or a URL. Together with the value passed to the `setFileName()` method it defines the location of the configuration file to be loaded. The strategies for locating the file are quite tolerant. For instance if the file name is already an absolute path or a fully defined URL, the base path will be ignored. The base path can also be a URL, in which case the file name is interpreted in this URL's context. If other methods are used for determining the location of the associated file (e.g. `setFile()` or `setURL()`), the base path is automatically set. Setting the base path using this method automatically sets the URL to null because it has to be determined anew based on the file name and the base path.
    Parameters:
      `basePath` - the base path.

  - ### setEncoding

    public void setEncoding(String encoding)
    Sets the encoding of the associated file. The encoding applies if binary files are loaded. Note that in this case setting an encoding is recommended; otherwise the platform's default encoding is used.
    Parameters:
      `encoding` - the encoding of the associated file

  - ### setFile

    public void setFile(File file)
    Sets the location of the associated file as a `File` object. The passed in `File` is made absolute if it is not yet. Then the file's path component becomes the base path and its name component becomes the file name.
    Parameters:
      `file` - the location of the associated file

  - ### setFileLocator

    public void setFileLocator(FileLocator locator)
    Sets the file to be accessed by this `FileHandler` as a `FileLocator` object.
    Parameters:
      `locator` - the `FileLocator` with the definition of the file to be accessed (must not be null
    Throws:
      `IllegalArgumentException` - if the `FileLocator` is null

  - ### setFileName

    public void setFileName(String fileName)
    Sets the name of the file. The passed in file name can contain a relative path. It must be used when referring files with relative paths from classpath. Use `setPath()` to set a full qualified file name. The URL is set to null as it has to be determined anew based on the file name and the base path.
    Parameters:
      `fileName` - the name of the file

  - ### setFileSystem

    public void setFileSystem(FileSystem fileSystem)
    Sets the `FileSystem` to be used by this object when locating files. If a null value is passed in, the file system is reset to the default file system.
    Parameters:
      `fileSystem` - the `FileSystem`

  - ### setLocationStrategy

    public void setLocationStrategy(FileLocationStrategy strategy)
    Sets the `FileLocationStrategy` to be applied when accessing the associated file. The strategy is stored in the underlying `FileLocator`. The argument can be null; this causes the default `FileLocationStrategy` to be used.
    Parameters:
      `strategy` - the `FileLocationStrategy`
    See Also:
      - `FileLocatorUtils.DEFAULT_LOCATION_STRATEGY`

  - ### setPath

    public void setPath(String path)
    Sets the location of the associated file as a full or relative path name. The passed in path should represent a valid file name on the file system. It must not be used to specify relative paths for files that exist in classpath, either plain file system or compressed archive, because this method expands any relative path to an absolute one which may end in an invalid absolute path for classpath references.
    Parameters:
      `path` - the full path name of the associated file

  - ### setURL

    public void setURL(URL url)
    Sets the location of the associated file as a URL. For loading this can be an arbitrary URL with a supported protocol. If the file is to be saved, too, a URL with the "file" protocol should be provided. This method sets the file name and the base path to null. They have to be determined anew based on the new URL.
    Parameters:
      `url` - the location of the file as URL

  - ### setURL

    public void setURL(URL url, URLConnectionOptions urlConnectionOptions)
    Sets the location of the associated file as a URL. For loading this can be an arbitrary URL with a supported protocol. If the file is to be saved, too, a URL with the "file" protocol should be provided. This method sets the file name and the base path to null. They have to be determined anew based on the new URL.
    Parameters:
      `url` - the location of the file as URL
      `urlConnectionOptions` - URL connection options
    Since:
      2.8.0