Class FileLocatorUtils


  • public final class FileLocatorUtils
    extends java.lang.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, e.g. 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
    • Constructor Summary

      Constructors 
      Modifier Constructor Description
      private FileLocatorUtils()
      Private constructor so that no instances can be created.
    • Method Summary

      All Methods Static Methods Concrete Methods 
      Modifier and Type Method Description
      (package private) static java.lang.String appendPath​(java.lang.String path, java.lang.String ext)
      Extends a path by another component.
      (package private) static java.io.File constructFile​(java.lang.String basePath, java.lang.String fileName)
      Helper method for constructing a file object from a base path and a file name.
      (package private) static java.net.URL convertFileToURL​(java.io.File file)
      Tries to convert the specified file to a URL.
      (package private) static java.net.URL convertURIToURL​(java.net.URI uri)
      Tries to convert the specified URI to a URL.
      private static FileLocator createFullyInitializedLocatorFromURL​(FileLocator src, java.net.URL url)
      Creates a fully initialized FileLocator based on the specified URL.
      static java.io.File fileFromURL​(java.net.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​(java.util.Map<java.lang.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.
      (package private) static java.lang.String getBasePath​(java.net.URL url)
      Gets the path without the file name, for example https://xyz.net/foo/bar.xml results in https://xyz.net/foo/
      (package private) static java.net.URL getClasspathResource​(java.lang.String resourceName)
      Tries to find a resource with the given name in the classpath.
      (package private) static java.io.File getFile​(java.lang.String basePath, java.lang.String fileName)
      Tries to convert the specified base path and file name into a file object.
      (package private) static java.lang.String getFileName​(java.net.URL url)
      Extract the file name from the specified URL.
      (package private) static FileSystem getFileSystem​(FileLocator locator)
      Obtains a non-null FileSystem object from the passed in FileLocator.
      (package private) static FileLocationStrategy getLocationStrategy​(FileLocator locator)
      Gets a non null FileLocationStrategy object from the passed in FileLocator.
      private static FileLocationStrategy initDefaultLocationStrategy()
      Creates the default location strategy.
      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 java.net.URL locate​(FileLocator locator)
      Locates the provided FileLocator, returning a URL for accessing the referenced file.
      static java.net.URL locateOrThrow​(FileLocator locator)
      Tries to locate the file referenced by the passed in FileLocator.
      static void put​(FileLocator locator, java.util.Map<java.lang.String,​java.lang.Object> map)
      Stores the specified FileLocator in the given map.
      (package private) static java.net.URL toURL​(java.io.File file)
      Convert the specified file into an URL.
      • Methods inherited from class java.lang.Object

        clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
    • Field Detail

      • 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.
      • FILE_SCHEME

        private static final java.lang.String FILE_SCHEME
        Constant for the file URL protocol
        See Also:
        Constant Field Values
      • LOG

        private static final org.apache.commons.logging.Log LOG
        The logger.
      • PROP_BASE_PATH

        private static final java.lang.String PROP_BASE_PATH
        Property key for the base path.
        See Also:
        Constant Field Values
      • PROP_ENCODING

        private static final java.lang.String PROP_ENCODING
        Property key for the encoding.
        See Also:
        Constant Field Values
      • PROP_FILE_NAME

        private static final java.lang.String PROP_FILE_NAME
        Property key for the file name.
        See Also:
        Constant Field Values
      • PROP_FILE_SYSTEM

        private static final java.lang.String PROP_FILE_SYSTEM
        Property key for the file system.
        See Also:
        Constant Field Values
      • PROP_STRATEGY

        private static final java.lang.String PROP_STRATEGY
        Property key for the location strategy.
        See Also:
        Constant Field Values
      • PROP_SOURCE_URL

        private static final java.lang.String PROP_SOURCE_URL
        Property key for the source URL.
        See Also:
        Constant Field Values
    • Constructor Detail

      • FileLocatorUtils

        private FileLocatorUtils()
        Private constructor so that no instances can be created.
    • Method Detail

      • appendPath

        static java.lang.String appendPath​(java.lang.String path,
                                           java.lang.String ext)
        Extends a path by another component. The given extension is added to the already existing path adding a separator if necessary.
        Parameters:
        path - the path to be extended
        ext - the extension of the path
        Returns:
        the extended path
      • constructFile

        static java.io.File constructFile​(java.lang.String basePath,
                                          java.lang.String fileName)
        Helper method for constructing a file object from a base path and a file name. This method is called if the base path passed to getURL() does not seem to be a valid URL.
        Parameters:
        basePath - the base path
        fileName - the file name (must not be null)
        Returns:
        the resulting file
      • convertFileToURL

        static java.net.URL convertFileToURL​(java.io.File file)
        Tries to convert the specified file to a URL. If this causes an exception, result is null.
        Parameters:
        file - the file to be converted
        Returns:
        the resulting URL or null
      • convertURIToURL

        static java.net.URL convertURIToURL​(java.net.URI uri)
        Tries to convert the specified URI to a URL. If this causes an exception, result is null.
        Parameters:
        uri - the URI to be converted
        Returns:
        the resulting URL or null
      • createFullyInitializedLocatorFromURL

        private static FileLocator createFullyInitializedLocatorFromURL​(FileLocator src,
                                                                        java.net.URL url)
        Creates a fully initialized FileLocator based on the specified URL.
        Parameters:
        src - the source FileLocator
        url - the URL
        Returns:
        the fully initialized FileLocator
      • fileFromURL

        public static java.io.File fileFromURL​(java.net.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 (e.g. 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​(java.util.Map<java.lang.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:
        java.lang.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
      • getBasePath

        static java.lang.String getBasePath​(java.net.URL url)
        Gets the path without the file name, for example https://xyz.net/foo/bar.xml results in https://xyz.net/foo/
        Parameters:
        url - the URL from which to extract the path
        Returns:
        the path component of the passed in URL
      • getClasspathResource

        static java.net.URL getClasspathResource​(java.lang.String resourceName)
        Tries to find a resource with the given name in the classpath.
        Parameters:
        resourceName - the name of the resource
        Returns:
        the URL to the found resource or null if the resource cannot be found
      • getFile

        static java.io.File getFile​(java.lang.String basePath,
                                    java.lang.String fileName)
        Tries to convert the specified base path and file name into a file object. This method is called e.g. by the save() methods of file based configurations. The parameter strings can be relative files, absolute files and URLs as well. This implementation checks first whether the passed in file name is absolute. If this is the case, it is returned. Otherwise further checks are performed whether the base path and file name can be combined to a valid URL or a valid file name. Note: The test if the passed in file name is absolute is performed using java.io.File.isAbsolute(). If the file name starts with a slash, this method will return true on Unix, but false on Windows. So to ensure correct behavior for relative file names on all platforms you should never let relative paths start with a slash. E.g. in a configuration definition file do not use something like that:
         <properties fileName="/subdir/my.properties"/>
         
        Under Windows this path would be resolved relative to the configuration definition file. Under UNIX this would be treated as an absolute path name.
        Parameters:
        basePath - the base path
        fileName - the file name (must not be null)
        Returns:
        the file object (null if no file can be obtained)
      • getFileName

        static java.lang.String getFileName​(java.net.URL url)
        Extract the file name from the specified URL.
        Parameters:
        url - the URL from which to extract the file name
        Returns:
        the extracted file name
      • getFileSystem

        static FileSystem getFileSystem​(FileLocator locator)
        Obtains a non-null FileSystem object from the passed in FileLocator. If the passed in FileLocator has a FileSystem object, it is returned. Otherwise, result is the default FileSystem.
        Parameters:
        locator - the FileLocator (may be null)
        Returns:
        the FileSystem to be used for this FileLocator
      • getLocationStrategy

        static FileLocationStrategy getLocationStrategy​(FileLocator locator)
        Gets a non null FileLocationStrategy object from the passed in FileLocator. If the FileLocator is not null and has a FileLocationStrategy defined, this strategy is returned. Otherwise, result is the default FileLocationStrategy.
        Parameters:
        locator - the FileLocator
        Returns:
        the FileLocationStrategy for this FileLocator
      • initDefaultLocationStrategy

        private static FileLocationStrategy initDefaultLocationStrategy()
        Creates the default location strategy. This method creates a combined location strategy as described in the comment of the DEFAULT_LOCATION_STRATEGY member field.
        Returns:
        the default FileLocationStrategy
      • 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 java.net.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 java.net.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,
                               java.util.Map<java.lang.String,​java.lang.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:
        java.lang.IllegalArgumentException - if the map is null
      • toURL

        static java.net.URL toURL​(java.io.File file)
                           throws java.net.MalformedURLException
        Convert the specified file into an URL. This method is equivalent to file.toURI().toURL(). It was used to work around a bug in the JDK preventing the transformation of a file into an URL if the file name contains a '#' character. See the issue CONFIGURATION-300 for more details. Now that we switched to JDK 1.4 we can directly use file.toURI().toURL().
        Parameters:
        file - the file to be converted into an URL
        Returns:
        a URL
        Throws:
        java.net.MalformedURLException - If the file protocol handler is not found (should not happen) or if an error occurred while constructing the URL