Class FileBasedConfigurationBuilder<T extends FileBasedConfiguration>
- java.lang.Object
-
- org.apache.commons.configuration2.builder.BasicConfigurationBuilder<T>
-
- org.apache.commons.configuration2.builder.FileBasedConfigurationBuilder<T>
-
- Type Parameters:
T
- the concrete type ofConfiguration
objects created by this builder
- All Implemented Interfaces:
ConfigurationBuilder<T>
,EventSource
- Direct Known Subclasses:
ReloadingFileBasedConfigurationBuilder
public class FileBasedConfigurationBuilder<T extends FileBasedConfiguration> extends BasicConfigurationBuilder<T>
A specialized
ConfigurationBuilder
implementation which can handle configurations read from aFileHandler
.This class extends its base class by the support of a
FileBasedBuilderParametersImpl
object, and especially of theFileHandler
contained in this object. When the builder creates a new object the resultingConfiguration
instance is associated with theFileHandler
. If theFileHandler
has a location set, theConfiguration
is directly loaded from this location.The
FileHandler
is kept by this builder and can be queried later on. It can be used for instance to save the currentConfiguration
after it was modified. Some care has to be taken when changing the location of theFileHandler
: The new location is recorded and also survives an invocation of theresetResult()
method. However, when the builder's initialization parameters are reset by callingresetParameters()
the location is reset, too.- Since:
- 2.0
-
-
Field Summary
Fields Modifier and Type Field Description private AutoSaveListener
autoSaveListener
A specialized listener for the auto save mechanism.private FileHandler
currentFileHandler
Stores the FileHandler associated with the current configuration.private static java.util.Map<java.lang.Class<?>,java.lang.String>
DEFAULT_ENCODINGS
A map for storing default encodings for specific configuration classes.private boolean
resetParameters
A flag whether the builder's parameters were reset.
-
Constructor Summary
Constructors Constructor Description FileBasedConfigurationBuilder(java.lang.Class<? extends T> resCls)
Creates a new instance ofFileBasedConfigurationBuilder
which produces result objects of the specified class.FileBasedConfigurationBuilder(java.lang.Class<? extends T> resCls, java.util.Map<java.lang.String,java.lang.Object> params)
Creates a new instance ofFileBasedConfigurationBuilder
which produces result objects of the specified class and sets initialization parameters.FileBasedConfigurationBuilder(java.lang.Class<? extends T> resCls, java.util.Map<java.lang.String,java.lang.Object> params, boolean allowFailOnInit)
Creates a new instance ofFileBasedConfigurationBuilder
which produces result objects of the specified class and sets initialization parameters and the allowFailOnInit flag.
-
Method Summary
All Methods Static Methods Instance Methods Concrete Methods Modifier and Type Method Description FileBasedConfigurationBuilder<T>
configure(BuilderParameters... params)
Appends the content of the specifiedBuilderParameters
objects to the current initialization parameters.private FileHandler
fetchFileHandlerFromParameters()
Obtains theFileHandler
from this builder's parameters.static java.lang.String
getDefaultEncoding(java.lang.Class<?> configClass)
Gets the default encoding for the specified configuration class.FileHandler
getFileHandler()
Gets theFileHandler
associated with this builder.private void
initEncoding(FileHandler handler)
Initializes the encoding of the specified file handler.protected void
initFileHandler(FileHandler handler)
Initializes the new currentFileHandler
.private static java.util.Map<java.lang.Class<?>,java.lang.String>
initializeDefaultEncodings()
Creates a map with default encodings for configuration classes and populates it with default entries.protected void
initResultInstance(T obj)
Initializes a newly created result object.private void
installAutoSaveListener()
Installs the listener for the auto save mechanism if it is not yet active.boolean
isAutoSave()
Gets a flag whether auto save mode is currently active.private void
removeAutoSaveListener()
Removes the listener for the auto save mechanism if it is currently active.void
save()
Convenience method which saves the associated configuration.void
setAutoSave(boolean enabled)
Enables or disables auto save mode.static void
setDefaultEncoding(java.lang.Class<?> configClass, java.lang.String encoding)
Sets a default encoding for a specific configuration class.BasicConfigurationBuilder<T>
setParameters(java.util.Map<java.lang.String,java.lang.Object> params)
Sets the initialization parameters of this builder.-
Methods inherited from class org.apache.commons.configuration2.builder.BasicConfigurationBuilder
addEventListener, addParameters, connectToReloadingController, copyEventListeners, copyEventListeners, createResult, createResultDeclaration, createResultInstance, fetchBeanHelper, fireBuilderEvent, getConfiguration, getParameters, getResultClass, getResultDeclaration, installEventListener, isAllowFailOnInit, removeEventListener, reset, resetParameters, resetResult
-
-
-
-
Field Detail
-
DEFAULT_ENCODINGS
private static final java.util.Map<java.lang.Class<?>,java.lang.String> DEFAULT_ENCODINGS
A map for storing default encodings for specific configuration classes.
-
currentFileHandler
private FileHandler currentFileHandler
Stores the FileHandler associated with the current configuration.
-
autoSaveListener
private AutoSaveListener autoSaveListener
A specialized listener for the auto save mechanism.
-
resetParameters
private boolean resetParameters
A flag whether the builder's parameters were reset.
-
-
Constructor Detail
-
FileBasedConfigurationBuilder
public FileBasedConfigurationBuilder(java.lang.Class<? extends T> resCls)
Creates a new instance ofFileBasedConfigurationBuilder
which produces result objects of the specified class.- Parameters:
resCls
- the result class (must not be null- Throws:
java.lang.IllegalArgumentException
- if the result class is null
-
FileBasedConfigurationBuilder
public FileBasedConfigurationBuilder(java.lang.Class<? extends T> resCls, java.util.Map<java.lang.String,java.lang.Object> params)
Creates a new instance ofFileBasedConfigurationBuilder
which produces result objects of the specified class and sets initialization parameters.- Parameters:
resCls
- the result class (must not be nullparams
- a map with initialization parameters- Throws:
java.lang.IllegalArgumentException
- if the result class is null
-
FileBasedConfigurationBuilder
public FileBasedConfigurationBuilder(java.lang.Class<? extends T> resCls, java.util.Map<java.lang.String,java.lang.Object> params, boolean allowFailOnInit)
Creates a new instance ofFileBasedConfigurationBuilder
which produces result objects of the specified class and sets initialization parameters and the allowFailOnInit flag.- Parameters:
resCls
- the result class (must not be nullparams
- a map with initialization parametersallowFailOnInit
- the allowFailOnInit flag- Throws:
java.lang.IllegalArgumentException
- if the result class is null
-
-
Method Detail
-
getDefaultEncoding
public static java.lang.String getDefaultEncoding(java.lang.Class<?> configClass)
Gets the default encoding for the specified configuration class. If an encoding has been set for the specified class (or one of its super classes), it is returned. Otherwise, result is null.- Parameters:
configClass
- the configuration class in question- Returns:
- the default encoding for this class (may be null)
-
initializeDefaultEncodings
private static java.util.Map<java.lang.Class<?>,java.lang.String> initializeDefaultEncodings()
Creates a map with default encodings for configuration classes and populates it with default entries.- Returns:
- the map with default encodings
-
setDefaultEncoding
public static void setDefaultEncoding(java.lang.Class<?> configClass, java.lang.String encoding)
Sets a default encoding for a specific configuration class. This encoding is used if an instance of this configuration class is to be created and no encoding has been set in the parameters object for this builder. The encoding passed here not only applies to the specified class but also to its sub classes. If the encoding is null, it is removed.- Parameters:
configClass
- the name of the configuration class (must not be null)encoding
- the default encoding for this class- Throws:
java.lang.IllegalArgumentException
- if the class is null
-
configure
public FileBasedConfigurationBuilder<T> configure(BuilderParameters... params)
Appends the content of the specifiedBuilderParameters
objects to the current initialization parameters. Calling this method multiple times will create a union of the parameters provided. This method is overridden here to change the result type.- Overrides:
configure
in classBasicConfigurationBuilder<T extends FileBasedConfiguration>
- Parameters:
params
- an arbitrary number of objects with builder parameters- Returns:
- a reference to this builder for method chaining
-
fetchFileHandlerFromParameters
private FileHandler fetchFileHandlerFromParameters()
Obtains theFileHandler
from this builder's parameters. If noFileBasedBuilderParametersImpl
object is found in this builder's parameters, a new one is created now and stored. This makes it possible to change the location of the associated file even if no parameters object was provided.- Returns:
- the
FileHandler
from initialization parameters
-
getFileHandler
public FileHandler getFileHandler()
Gets theFileHandler
associated with this builder. If already a result object has been created, thisFileHandler
can be used to save it. Otherwise, theFileHandler
from the initialization parameters is returned (which is not associated with aFileBased
object). Result is never null.- Returns:
- the
FileHandler
associated with this builder
-
initEncoding
private void initEncoding(FileHandler handler)
Initializes the encoding of the specified file handler. If already an encoding is set, it is used. Otherwise, the default encoding for the result configuration class is obtained and set.- Parameters:
handler
- the handler to be initialized
-
initFileHandler
protected void initFileHandler(FileHandler handler) throws ConfigurationException
Initializes the new currentFileHandler
. When a new result object is created, a newFileHandler
is created, too, and associated with the result object. This new handler is passed to this method. If a location is defined, the result object is loaded from this location. Note: This method is called from a synchronized block.- Parameters:
handler
- the new currentFileHandler
- Throws:
ConfigurationException
- if an error occurs
-
initResultInstance
protected void initResultInstance(T obj) throws ConfigurationException
Initializes a newly created result object. This is the second step of the process of producing a result object for this builder. This implementation uses theBeanHelper
class to initialize the object's property based on theBeanDeclaration
returned byBasicConfigurationBuilder.getResultDeclaration()
. Note: This method is invoked in a synchronized block. This is required because internal state is accessed. Sub classes must not call this method without proper synchronization. This implementation deals with the creation and initialization of aFileHandler
associated with the new result object.- Overrides:
initResultInstance
in classBasicConfigurationBuilder<T extends FileBasedConfiguration>
- Parameters:
obj
- the object to be initialized- Throws:
ConfigurationException
- if an error occurs
-
installAutoSaveListener
private void installAutoSaveListener()
Installs the listener for the auto save mechanism if it is not yet active.
-
isAutoSave
public boolean isAutoSave()
Gets a flag whether auto save mode is currently active.- Returns:
- true if auto save is enabled, false otherwise
-
removeAutoSaveListener
private void removeAutoSaveListener()
Removes the listener for the auto save mechanism if it is currently active.
-
save
public void save() throws ConfigurationException
Convenience method which saves the associated configuration. This method expects that the managed configuration has already been created and that a valid file location is available in the currentFileHandler
. The file handler is then used to store the configuration.- Throws:
ConfigurationException
- if an error occurs
-
setAutoSave
public void setAutoSave(boolean enabled)
Enables or disables auto save mode. If auto save mode is enabled, every update of the managed configuration causes it to be saved automatically; so changes are directly written to disk.- Parameters:
enabled
- true if auto save mode is to be enabled, false otherwise
-
setParameters
public BasicConfigurationBuilder<T> setParameters(java.util.Map<java.lang.String,java.lang.Object> params)
Sets the initialization parameters of this builder. Already existing parameters are replaced by the content of the given map. This implementation just records the fact that new parameters have been set. This means that the next time a result object is created, theFileHandler
has to be initialized from initialization parameters rather than reusing the existing one.- Overrides:
setParameters
in classBasicConfigurationBuilder<T extends FileBasedConfiguration>
- Parameters:
params
- the new initialization parameters of this builder; can be null, then all initialization parameters are removed- Returns:
- a reference to this builder for method chaining
-
-