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,
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.
Modifier and Type | Field and Description |
---|---|
static FileSystem |
DEFAULT_FILE_SYSTEM
Constant for the default
FileSystem . |
static FileLocationStrategy |
DEFAULT_LOCATION_STRATEGY
Constant for the default
FileLocationStrategy . |
Modifier and Type | Method and 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. |
public static final FileSystem DEFAULT_FILE_SYSTEM
FileSystem
. This file system is used by operations of this class if no specific file
system is provided. An instance of DefaultFileSystem
is used.public static final FileLocationStrategy DEFAULT_LOCATION_STRATEGY
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
:
FileLocator
has a defined URL, this URL is used as the file's URL (without any further
checks).FileLocator
are passed to the current
FileSystem
's locateFromURL()
method. If this results in a URL, it is returned.public static File fileFromURL(URL url)
url
- the URLpublic static FileLocator.FileLocatorBuilder fileLocator()
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();
FileLocator
public static FileLocator.FileLocatorBuilder fileLocator(FileLocator src)
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();
src
- the source FileLocator
(may be null)FileLocator
public static FileLocator fromMap(Map<String,?> map)
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.map
- the mapFileLocator
ClassCastException
- if the map contains invalid datapublic static FileLocator fullyInitializedLocator(FileLocator locator)
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:
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.locator
- the FileLocator
to be completedFileLocator
with a fully initialized location if possible or nullpublic static boolean isFullyInitialized(FileLocator locator)
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.locator
- the FileLocator
to be checked (may be null)public static boolean isLocationDefined(FileLocator locator)
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.locator
- the FileLocator
to checkFileLocator
public static URL locate(FileLocator locator)
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.locator
- the FileLocator
to be resolvedFileLocator
could not be resolvedDEFAULT_LOCATION_STRATEGY
public static URL locateOrThrow(FileLocator locator) throws ConfigurationException
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.locator
- the FileLocator
to be resolvedConfigurationException
- if the file cannot be resolvedpublic static void put(FileLocator locator, Map<String,Object> map)
FileLocator
in the given map. With the fromMap(Map)
method a new
FileLocator
with the same properties as the original one can be created.locator
- the FileLocator
to be storedmap
- the map in which to store the FileLocator
(must not be null)IllegalArgumentException
- if the map is nullCopyright © 2001–2022 The Apache Software Foundation. All rights reserved.