org.apache.commons.configuration2.builder.FileBasedConfigurationBuilder Maven / Gradle / Ivy
Go to download
Show more of this group Show more artifacts with this name
Show all versions of commons-configuration2 Show documentation
Show all versions of commons-configuration2 Show documentation
Tools to assist in the reading of configuration/preferences files in
various formats
/*
* Licensed to the Apache Software Foundation (ASF) under one or more
* contributor license agreements. See the NOTICE file distributed with
* this work for additional information regarding copyright ownership.
* The ASF licenses this file to You under the Apache License, Version 2.0
* (the "License"); you may not use this file except in compliance with
* the License. You may obtain a copy of the License at
*
* http://www.apache.org/licenses/LICENSE-2.0
*
* Unless required by applicable law or agreed to in writing, software
* distributed under the License is distributed on an "AS IS" BASIS,
* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
* See the License for the specific language governing permissions and
* limitations under the License.
*/
package org.apache.commons.configuration2.builder;
import java.util.List;
import java.util.Map;
import java.util.concurrent.ConcurrentHashMap;
import org.apache.commons.configuration2.FileBasedConfiguration;
import org.apache.commons.configuration2.PropertiesConfiguration;
import org.apache.commons.configuration2.XMLPropertiesConfiguration;
import org.apache.commons.configuration2.event.ConfigurationEvent;
import org.apache.commons.configuration2.ex.ConfigurationException;
import org.apache.commons.configuration2.io.FileHandler;
import org.apache.commons.lang3.ClassUtils;
import org.apache.commons.lang3.StringUtils;
/**
*
* A specialized {@code ConfigurationBuilder} implementation which can handle
* configurations read from a {@link FileHandler}.
*
*
* This class extends its base class by the support of a
* {@link FileBasedBuilderParametersImpl} object, and especially of the
* {@link FileHandler} contained in this object. When the builder creates a new
* object the resulting {@code Configuration} instance is associated with the
* {@code FileHandler}. If the {@code FileHandler} has a location set, the
* {@code Configuration} is directly loaded from this location.
*
*
* The {@code FileHandler} is kept by this builder and can be queried later on.
* It can be used for instance to save the current {@code Configuration} after
* it was modified. Some care has to be taken when changing the location of the
* {@code FileHandler}: The new location is recorded and also survives an
* invocation of the {@code resetResult()} method. However, when the builder's
* initialization parameters are reset by calling {@code resetParameters()} the
* location is reset, too.
*
*
* @since 2.0
* @param the concrete type of {@code Configuration} objects created by this
* builder
*/
public class FileBasedConfigurationBuilder
extends BasicConfigurationBuilder
{
/** A map for storing default encodings for specific configuration classes. */
private static final Map, String> DEFAULT_ENCODINGS =
initializeDefaultEncodings();
/** Stores the FileHandler associated with the current configuration. */
private FileHandler currentFileHandler;
/** A specialized listener for the auto save mechanism. */
private AutoSaveListener autoSaveListener;
/** A flag whether the builder's parameters were reset. */
private boolean resetParameters;
/**
* Creates a new instance of {@code FileBasedConfigurationBuilder} which
* produces result objects of the specified class.
*
* @param resCls the result class (must not be null
* @throws IllegalArgumentException if the result class is null
*/
public FileBasedConfigurationBuilder(final Class resCls)
{
super(resCls);
}
/**
* Creates a new instance of {@code FileBasedConfigurationBuilder} which
* produces result objects of the specified class and sets initialization
* parameters.
*
* @param resCls the result class (must not be null
* @param params a map with initialization parameters
* @throws IllegalArgumentException if the result class is null
*/
public FileBasedConfigurationBuilder(final Class resCls,
final Map params)
{
super(resCls, params);
}
/**
* Creates a new instance of {@code FileBasedConfigurationBuilder} which
* produces result objects of the specified class and sets initialization
* parameters and the allowFailOnInit flag.
*
* @param resCls the result class (must not be null
* @param params a map with initialization parameters
* @param allowFailOnInit the allowFailOnInit flag
* @throws IllegalArgumentException if the result class is null
*/
public FileBasedConfigurationBuilder(final Class resCls,
final Map params, final boolean allowFailOnInit)
{
super(resCls, params, allowFailOnInit);
}
/**
* Returns 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.
*
* @param configClass the configuration class in question
* @return the default encoding for this class (may be null)
*/
public static String getDefaultEncoding(final Class configClass)
{
String enc = DEFAULT_ENCODINGS.get(configClass);
if (enc != null || configClass == null)
{
return enc;
}
final List> superclasses =
ClassUtils.getAllSuperclasses(configClass);
for (final Class cls : superclasses)
{
enc = DEFAULT_ENCODINGS.get(cls);
if (enc != null)
{
return enc;
}
}
final List> interfaces = ClassUtils.getAllInterfaces(configClass);
for (final Class cls : interfaces)
{
enc = DEFAULT_ENCODINGS.get(cls);
if (enc != null)
{
return enc;
}
}
return null;
}
/**
* 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.
*
* @param configClass the name of the configuration class (must not be
* null)
* @param encoding the default encoding for this class
* @throws IllegalArgumentException if the class is null
*/
public static void setDefaultEncoding(final Class configClass, final String encoding)
{
if (configClass == null)
{
throw new IllegalArgumentException(
"Configuration class must not be null!");
}
if (encoding == null)
{
DEFAULT_ENCODINGS.remove(configClass);
}
else
{
DEFAULT_ENCODINGS.put(configClass, encoding);
}
}
/**
* {@inheritDoc} This method is overridden here to change the result type.
*/
@Override
public FileBasedConfigurationBuilder configure(
final BuilderParameters... params)
{
super.configure(params);
return this;
}
/**
* Returns the {@code FileHandler} associated with this builder. If already
* a result object has been created, this {@code FileHandler} can be used to
* save it. Otherwise, the {@code FileHandler} from the initialization
* parameters is returned (which is not associated with a {@code FileBased}
* object). Result is never null.
*
* @return the {@code FileHandler} associated with this builder
*/
public synchronized FileHandler getFileHandler()
{
return (currentFileHandler != null) ? currentFileHandler
: fetchFileHandlerFromParameters();
}
/**
* {@inheritDoc} This implementation just records the fact that new
* parameters have been set. This means that the next time a result object
* is created, the {@code FileHandler} has to be initialized from
* initialization parameters rather than reusing the existing one.
*/
@Override
public synchronized BasicConfigurationBuilder setParameters(
final Map params)
{
super.setParameters(params);
resetParameters = true;
return this;
}
/**
* 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 current {@code FileHandler}.
* The file handler is then used to store the configuration.
*
* @throws ConfigurationException if an error occurs
*/
public void save() throws ConfigurationException
{
getFileHandler().save();
}
/**
* Returns a flag whether auto save mode is currently active.
*
* @return true if auto save is enabled, false otherwise
*/
public synchronized boolean isAutoSave()
{
return autoSaveListener != null;
}
/**
* 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.
*
* @param enabled true if auto save mode is to be enabled,
* false otherwise
*/
public synchronized void setAutoSave(final boolean enabled)
{
if (enabled)
{
installAutoSaveListener();
}
else
{
removeAutoSaveListener();
}
}
/**
* {@inheritDoc} This implementation deals with the creation and
* initialization of a {@code FileHandler} associated with the new result
* object.
*/
@Override
protected void initResultInstance(final T obj) throws ConfigurationException
{
super.initResultInstance(obj);
final FileHandler srcHandler =
(currentFileHandler != null && !resetParameters) ? currentFileHandler
: fetchFileHandlerFromParameters();
currentFileHandler = new FileHandler(obj, srcHandler);
if (autoSaveListener != null)
{
autoSaveListener.updateFileHandler(currentFileHandler);
}
initFileHandler(currentFileHandler);
resetParameters = false;
}
/**
* Initializes the new current {@code FileHandler}. When a new result object
* is created, a new {@code FileHandler} 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.
*
* @param handler the new current {@code FileHandler}
* @throws ConfigurationException if an error occurs
*/
protected void initFileHandler(final FileHandler handler)
throws ConfigurationException
{
initEncoding(handler);
if (handler.isLocationDefined())
{
handler.locate();
handler.load();
}
}
/**
* Obtains the {@code FileHandler} from this builder's parameters. If no
* {@code FileBasedBuilderParametersImpl} 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.
*
* @return the {@code FileHandler} from initialization parameters
*/
private FileHandler fetchFileHandlerFromParameters()
{
FileBasedBuilderParametersImpl fileParams =
FileBasedBuilderParametersImpl.fromParameters(getParameters(),
false);
if (fileParams == null)
{
fileParams = new FileBasedBuilderParametersImpl();
addParameters(fileParams.getParameters());
}
return fileParams.getFileHandler();
}
/**
* Installs the listener for the auto save mechanism if it is not yet
* active.
*/
private void installAutoSaveListener()
{
if (autoSaveListener == null)
{
autoSaveListener = new AutoSaveListener(this);
addEventListener(ConfigurationEvent.ANY, autoSaveListener);
autoSaveListener.updateFileHandler(getFileHandler());
}
}
/**
* Removes the listener for the auto save mechanism if it is currently
* active.
*/
private void removeAutoSaveListener()
{
if (autoSaveListener != null)
{
removeEventListener(ConfigurationEvent.ANY, autoSaveListener);
autoSaveListener.updateFileHandler(null);
autoSaveListener = null;
}
}
/**
* 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.
*
* @param handler the handler to be initialized
*/
private void initEncoding(final FileHandler handler)
{
if (StringUtils.isEmpty(handler.getEncoding()))
{
final String encoding = getDefaultEncoding(getResultClass());
if (encoding != null)
{
handler.setEncoding(encoding);
}
}
}
/**
* Creates a map with default encodings for configuration classes and
* populates it with default entries.
*
* @return the map with default encodings
*/
private static Map, String> initializeDefaultEncodings()
{
final Map, String> enc = new ConcurrentHashMap<>();
enc.put(PropertiesConfiguration.class,
PropertiesConfiguration.DEFAULT_ENCODING);
enc.put(XMLPropertiesConfiguration.class,
XMLPropertiesConfiguration.DEFAULT_ENCODING);
return enc;
}
}