Class FileLocatorUtils
java.lang.Object
org.apache.commons.configuration2.io.FileLocatorUtils
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
FieldsModifier and TypeFieldDescriptionstatic final FileSystemConstant for the defaultFileSystem.static final FileLocationStrategyConstant for the defaultFileLocationStrategy. -
Method Summary
Modifier and TypeMethodDescriptionstatic FilefileFromURL(URL url) Tries to convert the specified URL to a file object.Returns an uninitializedFileLocatorBuilderwhich can be used for the creation of aFileLocatorobject.fileLocator(FileLocator src) Returns aFileLocatorBuilderwhich is already initialized with the properties of the passed inFileLocator.static FileLocatorCreates a newFileLocatorobject with the properties defined in the given map.static FileLocatorfullyInitializedLocator(FileLocator locator) Returns aFileLocatorobject based on the passed in one whose location is fully defined.static booleanisFullyInitialized(FileLocator locator) Returns a flag whether all components of the givenFileLocatordescribing the referenced file are defined.static booleanisLocationDefined(FileLocator locator) Checks whether the specifiedFileLocatorcontains enough information to locate a file.static URLlocate(FileLocator locator) Locates the providedFileLocator, returning a URL for accessing the referenced file.static URLlocateOrThrow(FileLocator locator) Tries to locate the file referenced by the passed inFileLocator.static voidput(FileLocator locator, Map<String, Object> map) Stores the specifiedFileLocatorin the given map.
-
Field Details
-
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 ofDefaultFileSystemis used. -
DEFAULT_LOCATION_STRATEGY
Constant for the defaultFileLocationStrategy. This strategy is used by thelocate()method if the passed inFileLocatordoes 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
FileLocatorhas 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
FileLocatorare 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
-
-
Method Details
-
fileFromURL
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
Returns an uninitializedFileLocatorBuilderwhich can be used for the creation of aFileLocatorobject. 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
Returns aFileLocatorBuilderwhich is already initialized with the properties of the passed inFileLocator. This builder can be used to create aFileLocatorobject which shares properties of the original locator (for example theFileSystemor 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
Creates a newFileLocatorobject 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 causeClassCastExceptionexceptions. The map can be null, then an uninitializedFileLocatoris returned.- Parameters:
map- the map- Returns:
- the new
FileLocator - Throws:
ClassCastException- if the map contains invalid data
-
fullyInitializedLocator
Returns aFileLocatorobject based on the passed in one whose location is fully defined. This method ensures that all components of theFileLocatorpointing to the file are set in a consistent way. In detail it behaves as follows:- If the
FileLocatorhas 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 newFileLocatoris 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- theFileLocatorto be completed- Returns:
- a
FileLocatorwith a fully initialized location if possible or null
- If the
-
isFullyInitialized
Returns a flag whether all components of the givenFileLocatordescribing 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 inFileLocatoris null, result is false.- Parameters:
locator- theFileLocatorto be checked (may be null)- Returns:
- a flag whether all components describing the referenced file are initialized
-
isLocationDefined
Checks whether the specifiedFileLocatorcontains enough information to locate a file. This is the case if a file name or a URL is defined. If the passed inFileLocatoris null, result is false.- Parameters:
locator- theFileLocatorto check- Returns:
- a flag whether a file location is defined by this
FileLocator
-
locate
Locates the providedFileLocator, returning a URL for accessing the referenced file. This method uses aFileLocationStrategyto locate the file the passed inFileLocatorpoints to. If theFileLocatorcontains itself aFileLocationStrategy, it is used. Otherwise, the defaultFileLocationStrategyis applied. The strategy is passed the locator and aFileSystem. The resulting URL is returned. If theFileLocatoris null, result is null.- Parameters:
locator- theFileLocatorto be resolved- Returns:
- the URL pointing to the referenced file or null if the
FileLocatorcould not be resolved - See Also:
-
locateOrThrow
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- theFileLocatorto be resolved- Returns:
- the URL pointing to the referenced file
- Throws:
ConfigurationException- if the file cannot be resolved
-
put
Stores the specifiedFileLocatorin the given map. With thefromMap(Map)method a newFileLocatorwith the same properties as the original one can be created.- Parameters:
locator- theFileLocatorto be storedmap- the map in which to store theFileLocator(must not be null)- Throws:
IllegalArgumentException- if the map is null
-