Class FileLocatorUtils
- java.lang.Object
-
- org.apache.commons.configuration2.io.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 theio
package.- Since:
- 2.0
-
-
Field Summary
Fields Modifier and Type Field Description static FileSystem
DEFAULT_FILE_SYSTEM
Constant for the defaultFileSystem
.static FileLocationStrategy
DEFAULT_LOCATION_STRATEGY
Constant for the defaultFileLocationStrategy
.private static java.lang.String
FILE_SCHEME
Constant for the file URL protocolprivate static org.apache.commons.logging.Log
LOG
The logger.private static java.lang.String
PROP_BASE_PATH
Property key for the base path.private static java.lang.String
PROP_ENCODING
Property key for the encoding.private static java.lang.String
PROP_FILE_NAME
Property key for the file name.private static java.lang.String
PROP_FILE_SYSTEM
Property key for the file system.private static java.lang.String
PROP_SOURCE_URL
Property key for the source URL.private static java.lang.String
PROP_STRATEGY
Property key for the location strategy.
-
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 initializedFileLocator
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 uninitializedFileLocatorBuilder
which can be used for the creation of aFileLocator
object.static FileLocator.FileLocatorBuilder
fileLocator(FileLocator src)
Returns aFileLocatorBuilder
which is already initialized with the properties of the passed inFileLocator
.static FileLocator
fromMap(java.util.Map<java.lang.String,?> map)
Creates a newFileLocator
object with the properties defined in the given map.static FileLocator
fullyInitializedLocator(FileLocator locator)
Returns aFileLocator
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-nullFileSystem
object from the passed inFileLocator
.(package private) static FileLocationStrategy
getLocationStrategy(FileLocator locator)
Gets a non nullFileLocationStrategy
object from the passed inFileLocator
.private static FileLocationStrategy
initDefaultLocationStrategy()
Creates the default location strategy.static boolean
isFullyInitialized(FileLocator locator)
Returns a flag whether all components of the givenFileLocator
describing the referenced file are defined.static boolean
isLocationDefined(FileLocator locator)
Checks whether the specifiedFileLocator
contains enough information to locate a file.static java.net.URL
locate(FileLocator locator)
Locates the providedFileLocator
, returning a URL for accessing the referenced file.static java.net.URL
locateOrThrow(FileLocator locator)
Tries to locate the file referenced by the passed inFileLocator
.static void
put(FileLocator locator, java.util.Map<java.lang.String,java.lang.Object> map)
Stores the specifiedFileLocator
in the given map.(package private) static java.net.URL
toURL(java.io.File file)
Convert the specified file into an URL.
-
-
-
Field Detail
-
DEFAULT_FILE_SYSTEM
public static final FileSystem DEFAULT_FILE_SYSTEM
Constant for the defaultFileSystem
. This file system is used by operations of this class if no specific file system is provided. An instance ofDefaultFileSystem
is used.
-
DEFAULT_LOCATION_STRATEGY
public static final FileLocationStrategy DEFAULT_LOCATION_STRATEGY
Constant for the defaultFileLocationStrategy
. This strategy is used by thelocate()
method if the passed inFileLocator
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 aFileLocator
:- 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 currentFileSystem
'slocateFromURL()
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.
- If the
-
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
-
-
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 extendedext
- 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 togetURL()
does not seem to be a valid URL.- Parameters:
basePath
- the base pathfileName
- 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 initializedFileLocator
based on the specified URL.- Parameters:
src
- the sourceFileLocator
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 uninitializedFileLocatorBuilder
which can be used for the creation of aFileLocator
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 aFileLocatorBuilder
which is already initialized with the properties of the passed inFileLocator
. This builder can be used to create aFileLocator
object which shares properties of the original locator (e.g. theFileSystem
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 sourceFileLocator
(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 newFileLocator
object with the properties defined in the given map. The map must be conform to the structure generated by theput(FileLocator, Map)
method; unexpected data can causeClassCastException
exceptions. The map can be null, then an uninitializedFileLocator
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 aFileLocator
object based on the passed in one whose location is fully defined. This method ensures that all components of theFileLocator
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 newFileLocator
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
- theFileLocator
to be completed- Returns:
- a
FileLocator
with a fully initialized location if possible or null
- If the
-
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 usingjava.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 pathfileName
- 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-nullFileSystem
object from the passed inFileLocator
. If the passed inFileLocator
has aFileSystem
object, it is returned. Otherwise, result is the defaultFileSystem
.- Parameters:
locator
- theFileLocator
(may be null)- Returns:
- the
FileSystem
to be used for thisFileLocator
-
getLocationStrategy
static FileLocationStrategy getLocationStrategy(FileLocator locator)
Gets a non nullFileLocationStrategy
object from the passed inFileLocator
. If theFileLocator
is not null and has aFileLocationStrategy
defined, this strategy is returned. Otherwise, result is the defaultFileLocationStrategy
.- Parameters:
locator
- theFileLocator
- Returns:
- the
FileLocationStrategy
for thisFileLocator
-
initDefaultLocationStrategy
private static FileLocationStrategy initDefaultLocationStrategy()
Creates the default location strategy. This method creates a combined location strategy as described in the comment of theDEFAULT_LOCATION_STRATEGY
member field.- Returns:
- the default
FileLocationStrategy
-
isFullyInitialized
public static boolean isFullyInitialized(FileLocator locator)
Returns a flag whether all components of the givenFileLocator
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 alocate()
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 definedFileLocator
, it can be used directly to identify the file. If the passed inFileLocator
is null, result is false.- Parameters:
locator
- theFileLocator
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 specifiedFileLocator
contains enough information to locate a file. This is the case if a file name or a URL is defined. If the passed inFileLocator
is null, result is false.- Parameters:
locator
- theFileLocator
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 providedFileLocator
, returning a URL for accessing the referenced file. This method uses aFileLocationStrategy
to locate the file the passed inFileLocator
points to. If theFileLocator
contains itself aFileLocationStrategy
, it is used. Otherwise, the defaultFileLocationStrategy
is applied. The strategy is passed the locator and aFileSystem
. The resulting URL is returned. If theFileLocator
is null, result is null.- Parameters:
locator
- theFileLocator
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 inFileLocator
. If this fails, an exception is thrown. This method works likelocate(FileLocator)
; however, in case of a failed location attempt an exception is thrown.- Parameters:
locator
- theFileLocator
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 specifiedFileLocator
in the given map. With thefromMap(Map)
method a newFileLocator
with the same properties as the original one can be created.- Parameters:
locator
- theFileLocator
to be storedmap
- the map in which to store theFileLocator
(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
-
-