public class FileHandler extends Object
A class that manages persistence of an associated FileBased
object.
Instances of this class can be used to load and save arbitrary objects implementing the FileBased
interface
in a convenient way from and to various locations. At construction time the FileBased
object to manage is
passed in. Basically, this object is assigned a location from which it is loaded and to which it can be saved. The
following possibilities exist to specify such a location:
setURL()
a full URL to the configuration source can be specified. This is the most
flexible way. Note that the save()
methods support only file: URLs.setFile()
method allows to specify the configuration source as a file. This can be either a
relative or an absolute file. In the former case the file is resolved based on the current directory.setPath()
method a full path to a configuration file can be
provided as a string.setBasePath()
method. The file name, non surprisingly, defines the name of the
configuration file.
An instance stores a location. The load()
and save()
methods that do not take an argument make use of
this internal location. Alternatively, it is also possible to use overloaded variants of load()
and
save()
which expect a location. In these cases the location specified takes precedence over the internal one;
the internal location is not changed.
The actual position of the file to be loaded is determined by a FileLocationStrategy
based on the location
information that has been provided. By providing a custom location strategy the algorithm for searching files can be
adapted. Save operations require more explicit information. They cannot rely on a location strategy because the file
to be written may not yet exist. So there may be some differences in the way location information is interpreted by
load and save operations. In order to avoid this, the following approach is recommended:
setXXX()
methods to define the location of the file to be loaded.locate()
method. This method resolves the referenced file (if possible) and fills out all
supported location information.save()
can be called. This method now has sufficient information to store the file at the
correct location.
When loading or saving a FileBased
object some additional functionality is performed if the object implements
one of the following interfaces:
FileLocatorAware
: In this case an object with the current file location is injected before the load or
save operation is executed. This is useful for FileBased
objects that depend on their current location, e.g.
to resolve relative path names.SynchronizerSupport
: If this interface is implemented, load and save operations obtain a write lock on
the FileBased
object before they access it. (In case of a save operation, a read lock would probably be
sufficient, but because of the possible injection of a FileLocator
object it is not allowed to perform
multiple save operations in parallel; therefore, by obtaining a write lock, we are on the safe side.)This class is thread-safe.
Constructor and Description |
---|
FileHandler()
Creates a new instance of
FileHandler which is not associated with a FileBased object and thus does
not have a content. |
FileHandler(FileBased obj)
Creates a new instance of
FileHandler and sets the managed FileBased object. |
FileHandler(FileBased obj,
FileHandler c)
Creates a new instance of
FileHandler which is associated with the given FileBased object and the
location defined for the given FileHandler object. |
Modifier and Type | Method and Description |
---|---|
void |
addFileHandlerListener(FileHandlerListener l)
Adds a listener to this
FileHandler . |
void |
clearLocation()
Clears the location of this
FileHandler . |
static FileHandler |
fromMap(Map<String,?> map)
Creates a new
FileHandler instance from properties stored in a map. |
String |
getBasePath()
Return the base path.
|
FileBased |
getContent()
Returns the
FileBased object associated with this FileHandler . |
String |
getEncoding()
Returns the encoding of the associated file.
|
File |
getFile()
Returns the location of the associated file as a
File object. |
FileLocator |
getFileLocator()
Returns a
FileLocator object with the specification of the file stored by this FileHandler . |
String |
getFileName()
Return the name of the file.
|
FileSystem |
getFileSystem()
Returns the
FileSystem to be used by this object when locating files. |
FileLocationStrategy |
getLocationStrategy()
Returns the
FileLocationStrategy to be applied when accessing the associated file. |
String |
getPath()
Returns the full path to the associated file.
|
URL |
getURL()
Returns the location of the associated file as a URL.
|
boolean |
isLocationDefined()
Tests whether a location is defined for this
FileHandler . |
void |
load()
Loads the associated file from the underlying location.
|
void |
load(File file)
Loads the associated file from the specified
File . |
void |
load(InputStream in)
Loads the associated file from the specified stream, using the encoding returned by
getEncoding() . |
void |
load(InputStream in,
String encoding)
Loads the associated file from the specified stream, using the specified encoding.
|
void |
load(Reader in)
Loads the associated file from the specified reader.
|
void |
load(String fileName)
Loads the associated file from the given file name.
|
void |
load(URL url)
Loads the associated file from the specified URL.
|
boolean |
locate()
Locates the referenced file if necessary and ensures that the associated
FileLocator is fully initialized. |
void |
removeFileHandlerListener(FileHandlerListener l)
Removes the specified listener from this object.
|
void |
resetFileSystem()
Resets the
FileSystem used by this object. |
void |
save()
Saves the associated file to the current location set for this object.
|
void |
save(File file)
Saves the associated file to the specified
File . |
void |
save(OutputStream out)
Saves the associated file to the specified stream using the encoding returned by
getEncoding() . |
void |
save(OutputStream out,
String encoding)
Saves the associated file to the specified stream using the specified encoding.
|
void |
save(String fileName)
Saves the associated file to the specified file name.
|
void |
save(URL url)
Saves the associated file to the specified URL.
|
void |
save(Writer out)
Saves the associated file to the given
Writer . |
void |
setBasePath(String basePath)
Sets the base path.
|
void |
setEncoding(String encoding)
Sets the encoding of the associated file.
|
void |
setFile(File file)
Sets the location of the associated file as a
File object. |
void |
setFileLocator(FileLocator locator)
Sets the file to be accessed by this
FileHandler as a FileLocator object. |
void |
setFileName(String fileName)
Set the name of the file.
|
void |
setFileSystem(FileSystem fileSystem)
Sets the
FileSystem to be used by this object when locating files. |
void |
setLocationStrategy(FileLocationStrategy strategy)
Sets the
FileLocationStrategy to be applied when accessing the associated file. |
void |
setPath(String path)
Sets the location of the associated file as a full or relative path name.
|
void |
setURL(URL url)
Sets the location of the associated file as a URL.
|
void |
setURL(URL url,
URLConnectionOptions urlConnectionOptions)
Sets the location of the associated file as a URL.
|
public FileHandler()
FileHandler
which is not associated with a FileBased
object and thus does
not have a content. Objects of this kind can be used to define a file location, but it is not possible to actually
load or save data.public FileHandler(FileBased obj)
FileHandler
and sets the managed FileBased
object.obj
- the file-based object to managepublic FileHandler(FileBased obj, FileHandler c)
FileHandler
which is associated with the given FileBased
object and the
location defined for the given FileHandler
object. A copy of the location of the given FileHandler
is
created. This constructor is a possibility to associate a file location with a FileBased
object.obj
- the FileBased
object to managec
- the FileHandler
from which to copy the location (must not be null)IllegalArgumentException
- if the FileHandler
is nullpublic static FileHandler fromMap(Map<String,?> map)
FileHandler
instance from properties stored in a map. This method tries to extract a
FileLocator
from the map. A new FileHandler
is created based on this FileLocator
.map
- the map (may be null)FileHandler
FileLocatorUtils.fromMap(Map)
public void addFileHandlerListener(FileHandlerListener l)
FileHandler
. It is notified about property changes and IO operations.l
- the listener to be added (must not be null)IllegalArgumentException
- if the listener is nullpublic void clearLocation()
FileHandler
. Afterwards this handler does not point to any valid file.public String getBasePath()
public final FileBased getContent()
FileBased
object associated with this FileHandler
.FileBased
objectpublic String getEncoding()
public File getFile()
File
object. If the base path is a URL with a protocol
different than "file", or the file is within a compressed archive, the return value will not point to a
valid file object.File
object; this can be nullpublic FileLocator getFileLocator()
FileLocator
object with the specification of the file stored by this FileHandler
. Note that
this method returns the internal data managed by this FileHandler
as it was defined. This is not necessarily
the same as the data returned by the single access methods like getFileName()
or getURL()
: These
methods try to derive missing data from other values that have been set.FileLocator
with the referenced filepublic String getFileName()
public FileSystem getFileSystem()
FileSystem
to be used by this object when locating files. Result is never null; if no file
system has been set, the default file system is returned.FileSystem
public FileLocationStrategy getLocationStrategy()
FileLocationStrategy
to be applied when accessing the associated file. This method never returns
null. If a FileLocationStrategy
has been set, it is returned. Otherwise, result is the default
FileLocationStrategy
.FileLocationStrategy
to be usedpublic String getPath()
File
path only if this location is
based on a file on the local disk. If the file was loaded from a packed archive, the returned value is the string
form of the URL from which the file was loaded.public URL getURL()
public boolean isLocationDefined()
FileHandler
.public void load() throws ConfigurationException
ConfigurationException
- if loading of the configuration failspublic void load(File file) throws ConfigurationException
File
.file
- the file to loadConfigurationException
- if an error occurspublic void load(InputStream in) throws ConfigurationException
getEncoding()
.in
- the input streamConfigurationException
- if an error occurs during the load operationpublic void load(InputStream in, String encoding) throws ConfigurationException
in
- the input streamencoding
- the encoding used, null
to use the default encodingConfigurationException
- if an error occurs during the load operationpublic void load(Reader in) throws ConfigurationException
in
- the readerConfigurationException
- if an error occurs during the load operationpublic void load(String fileName) throws ConfigurationException
fileName
- the name of the file to be loadedConfigurationException
- if an error occurspublic void load(URL url) throws ConfigurationException
url
- the URL of the file to be loadedConfigurationException
- if an error occurspublic boolean locate()
FileLocator
is fully initialized.
When accessing the referenced file the information stored in the associated FileLocator
is used. If this
information is incomplete (e.g. only the file name is set), an attempt to locate the file may have to be performed on
each access. By calling this method such an attempt is performed once, and the results of a successful localization
are stored. Hence, later access to the referenced file can be more efficient. Also, all properties pointing to the
referenced file in this object's FileLocator
are set (i.e. the URL, the base path, and the file name). If the
referenced file cannot be located, result is false. This means that the information in the current
FileLocator
is insufficient or wrong. If the FileLocator
is already fully defined, it is not changed.FileLocatorUtils.fullyInitializedLocator(FileLocator)
public void removeFileHandlerListener(FileHandlerListener l)
l
- the listener to be removedpublic void resetFileSystem()
FileSystem
used by this object. It is set to the default file system.public void save() throws ConfigurationException
ConfigurationException
- if an error occurs or no location has been set yetpublic void save(File file) throws ConfigurationException
File
. The file is created automatically if it doesn't exist. This
does not change the location of this object (use setFile(java.io.File)
if you need it).file
- the target fileConfigurationException
- if an error occurs during the save operationpublic void save(OutputStream out) throws ConfigurationException
getEncoding()
.out
- the output streamConfigurationException
- if an error occurs during the save operationpublic void save(OutputStream out, String encoding) throws ConfigurationException
out
- the output streamencoding
- the encoding to be used, null
to use the default encodingConfigurationException
- if an error occurs during the save operationpublic void save(String fileName) throws ConfigurationException
setFileName(String)
if you need it).fileName
- the file nameConfigurationException
- if an error occurs during the save operationpublic void save(URL url) throws ConfigurationException
setURL(URL)
if you need it).url
- the URLConfigurationException
- if an error occurs during the save operationpublic void save(Writer out) throws ConfigurationException
Writer
.out
- the Writer
ConfigurationException
- if an error occurs during the save operationpublic void setBasePath(String basePath)
setFileName()
method it defines the location of the configuration file to be loaded. The strategies
for locating the file are quite tolerant. For instance if the file name is already an absolute path or a fully
defined URL, the base path will be ignored. The base path can also be a URL, in which case the file name is
interpreted in this URL's context. If other methods are used for determining the location of the associated file
(e.g. setFile()
or setURL()
), the base path is automatically set. Setting the base path using this
method automatically sets the URL to null because it has to be determined anew based on the file name and the
base path.basePath
- the base path.public void setEncoding(String encoding)
encoding
- the encoding of the associated filepublic void setFile(File file)
File
object. The passed in File
is made absolute if it
is not yet. Then the file's path component becomes the base path and its name component becomes the file name.file
- the location of the associated filepublic void setFileLocator(FileLocator locator)
FileHandler
as a FileLocator
object.locator
- the FileLocator
with the definition of the file to be accessed (must not be nullIllegalArgumentException
- if the FileLocator
is nullpublic void setFileName(String fileName)
setPath()
to set a full qualified file name. The URL is set to
null as it has to be determined anew based on the file name and the base path.fileName
- the name of the filepublic void setFileSystem(FileSystem fileSystem)
FileSystem
to be used by this object when locating files. If a null value is passed in, the
file system is reset to the default file system.fileSystem
- the FileSystem
public void setLocationStrategy(FileLocationStrategy strategy)
FileLocationStrategy
to be applied when accessing the associated file. The strategy is stored in the
underlying FileLocator
. The argument can be null; this causes the default FileLocationStrategy
to be used.strategy
- the FileLocationStrategy
FileLocatorUtils.DEFAULT_LOCATION_STRATEGY
public void setPath(String path)
path
- the full path name of the associated filepublic void setURL(URL url)
url
- the location of the file as URLpublic void setURL(URL url, URLConnectionOptions urlConnectionOptions)
url
- the location of the file as URLurlConnectionOptions
- URL connection optionsCopyright © 2001–2022 The Apache Software Foundation. All rights reserved.