Package org.apache.commons.configuration2.io

# Class FileLocatorUtils

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

public final class FileLocatorUtils extends Object

A utility class providing helper methods related to locating files.

The methods of this class are used behind the scenes when retrieving configuration files based on different criteria, for example URLs, files, or more complex search strategies. They also implement functionality required by the default `FileSystem` implementations. Most methods are intended to be used internally only by other classes in the `io` package.

Since:
  2.0

- ## Field Summary

  Fields
  Modifier and Type
  Field
  Description
  `static final FileSystem`
  `DEFAULT_FILE_SYSTEM`
  Constant for the default `FileSystem`.
  `static final FileLocationStrategy`
  `DEFAULT_LOCATION_STRATEGY`
  Constant for the default `FileLocationStrategy`.

- ## Method Summary

  Modifier and Type
  Method
  Description
  `static File`
  `fileFromURL(URL url)`
  Tries to convert the specified URL to a file object.
  `static FileLocator.FileLocatorBuilder`
  `fileLocator()`
  Returns an uninitialized `FileLocatorBuilder` which can be used for the creation of a `FileLocator` object.
  `static FileLocator.FileLocatorBuilder`
  `fileLocator(FileLocator src)`
  Returns a `FileLocatorBuilder` which is already initialized with the properties of the passed in `FileLocator`.
  `static FileLocator`
  `fromMap(Map<String,?> map)`
  Creates a new `FileLocator` object with the properties defined in the given map.
  `static FileLocator`
  `fullyInitializedLocator(FileLocator locator)`
  Returns a `FileLocator` object based on the passed in one whose location is fully defined.
  `static boolean`
  `isFullyInitialized(FileLocator locator)`
  Returns a flag whether all components of the given `FileLocator` describing the referenced file are defined.
  `static boolean`
  `isLocationDefined(FileLocator locator)`
  Checks whether the specified `FileLocator` contains enough information to locate a file.
  `static URL`
  `locate(FileLocator locator)`
  Locates the provided `FileLocator`, returning a URL for accessing the referenced file.
  `static URL`
  `locateOrThrow(FileLocator locator)`
  Tries to locate the file referenced by the passed in `FileLocator`.
  `static void`
  `put(FileLocator locator, Map<String,Object> map)`
  Stores the specified `FileLocator` in the given map.

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

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

- ## Field Details

  - ### DEFAULT_FILE_SYSTEM

    public static final FileSystem DEFAULT_FILE_SYSTEM
    Constant for the default `FileSystem`. This file system is used by operations of this class if no specific file system is provided. An instance of `DefaultFileSystem` is used.

  - ### DEFAULT_LOCATION_STRATEGY

    public static final FileLocationStrategy DEFAULT_LOCATION_STRATEGY
    Constant for the default `FileLocationStrategy`. This strategy is used by the `locate()` method if the passed in `FileLocator` does not define its own location strategy. The default location strategy is roughly equivalent to the search algorithm used in version 1.x of Commons Configuration (there it was hard-coded though). It behaves in the following way when passed a `FileLocator`:
    - If the `FileLocator` has a defined URL, this URL is used as the file's URL (without any further checks).
    - Otherwise, base path and file name stored in the `FileLocator` are passed to the current `FileSystem`'s `locateFromURL()` method. If this results in a URL, it is returned.
    - Otherwise, if the locator's file name is an absolute path to an existing file, the URL of this file is returned.
    - Otherwise, the concatenation of base path and file name is constructed. If this path points to an existing file, its URL is returned.
    - Otherwise, a sub directory of the current user's home directory as defined by the base path is searched for the referenced file. If the file can be found there, its URL is returned.
    - Otherwise, the base path is ignored, and the file name is searched in the current user's home directory. If the file can be found there, its URL is returned.
    - Otherwise, a resource with the name of the locator's file name is searched in the classpath. If it can be found, its URL is returned.
    - Otherwise, the strategy gives up and returns null indicating that the file cannot be resolved.

- ## Method Details

  - ### fileFromURL

    public static File fileFromURL(URL url)
    Tries to convert the specified URL to a file object. If this fails, null is returned.
    Parameters:
      `url` - the URL
    Returns:
      the resulting file object

  - ### fileLocator

    public static FileLocator.FileLocatorBuilder fileLocator()
    Returns an uninitialized `FileLocatorBuilder` which can be used for the creation of a `FileLocator` object. This method provides a convenient way to create file locators using a fluent API as in the following example:

         FileLocator locator = FileLocatorUtils.fileLocator().basePath(myBasePath).fileName("test.xml").create();

    Returns:
      a builder object for defining a `FileLocator`

  - ### fileLocator

    public static FileLocator.FileLocatorBuilder fileLocator(FileLocator src)
    Returns a `FileLocatorBuilder` which is already initialized with the properties of the passed in `FileLocator`. This builder can be used to create a `FileLocator` object which shares properties of the original locator (for example the `FileSystem` or the encoding), but points to a different file. An example use case is as follows:

         FileLocator loc1 = ...
         FileLocator loc2 = FileLocatorUtils.fileLocator(loc1)
             .setFileName("anotherTest.xml")
             .create();

    Parameters:
      `src` - the source `FileLocator` (may be null)
    Returns:
      an initialized builder object for defining a `FileLocator`

  - ### fromMap

    public static FileLocator fromMap(Map<String,?> map)
    Creates a new `FileLocator` object with the properties defined in the given map. The map must be conform to the structure generated by the `put(FileLocator, Map)` method; unexpected data can cause `ClassCastException` exceptions. The map can be null, then an uninitialized `FileLocator` is returned.
    Parameters:
      `map` - the map
    Returns:
      the new `FileLocator`
    Throws:
      `ClassCastException` - if the map contains invalid data

  - ### fullyInitializedLocator

    public static FileLocator fullyInitializedLocator(FileLocator locator)
    Returns a `FileLocator` object based on the passed in one whose location is fully defined. This method ensures that all components of the `FileLocator` pointing to the file are set in a consistent way. In detail it behaves as follows:
    - If the `FileLocator` has already all components set which define the file, it is returned unchanged. Note: It is not checked whether all components are really consistent!
    - `locate(FileLocator)` is called to determine a unique URL pointing to the referenced file. If this is successful, a new `FileLocator` is created as a copy of the passed in one, but with all components pointing to the file derived from this URL.
    - Otherwise, result is null.
    Parameters:
      `locator` - the `FileLocator` to be completed
    Returns:
      a `FileLocator` with a fully initialized location if possible or null

  - ### isFullyInitialized

    public static boolean isFullyInitialized(FileLocator locator)
    Returns a flag whether all components of the given `FileLocator` describing the referenced file are defined. In order to reference a file, it is not necessary that all components are filled in (for instance, the URL alone is sufficient). For some use cases however, it might be of interest to have different methods for accessing the referenced file. Also, depending on the filled out properties, there is a subtle difference how the file is accessed: If only the file name is set (and optionally the base path), each time the file is accessed a `locate()` operation has to be performed to uniquely identify the file. If however the URL is determined once based on the other components and stored in a fully defined `FileLocator`, it can be used directly to identify the file. If the passed in `FileLocator` is null, result is false.
    Parameters:
      `locator` - the `FileLocator` to be checked (may be null)
    Returns:
      a flag whether all components describing the referenced file are initialized

  - ### isLocationDefined

    public static boolean isLocationDefined(FileLocator locator)
    Checks whether the specified `FileLocator` contains enough information to locate a file. This is the case if a file name or a URL is defined. If the passed in `FileLocator` is null, result is false.
    Parameters:
      `locator` - the `FileLocator` to check
    Returns:
      a flag whether a file location is defined by this `FileLocator`

  - ### locate

    public static URL locate(FileLocator locator)
    Locates the provided `FileLocator`, returning a URL for accessing the referenced file. This method uses a `FileLocationStrategy` to locate the file the passed in `FileLocator` points to. If the `FileLocator` contains itself a `FileLocationStrategy`, it is used. Otherwise, the default `FileLocationStrategy` is applied. The strategy is passed the locator and a `FileSystem`. The resulting URL is returned. If the `FileLocator` is null, result is null.
    Parameters:
      `locator` - the `FileLocator` to be resolved
    Returns:
      the URL pointing to the referenced file or null if the `FileLocator` could not be resolved
    See Also:
      - `DEFAULT_LOCATION_STRATEGY`

  - ### locateOrThrow

    public static URL locateOrThrow(FileLocator locator) throws ConfigurationException
    Tries to locate the file referenced by the passed in `FileLocator`. If this fails, an exception is thrown. This method works like `locate(FileLocator)`; however, in case of a failed location attempt an exception is thrown.
    Parameters:
      `locator` - the `FileLocator` to be resolved
    Returns:
      the URL pointing to the referenced file
    Throws:
      `ConfigurationException` - if the file cannot be resolved

  - ### put

    public static void put(FileLocator locator, Map<String,Object> map)
    Stores the specified `FileLocator` in the given map. With the `fromMap(Map)` method a new `FileLocator` with the same properties as the original one can be created.
    Parameters:
      `locator` - the `FileLocator` to be stored
      `map` - the map in which to store the `FileLocator` (must not be null)
    Throws:
      `IllegalArgumentException` - if the map is null