/*
* 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;
import java.math.BigDecimal;
import java.math.BigInteger;
import java.util.ArrayList;
import java.util.Arrays;
import java.util.Collection;
import java.util.Collections;
import java.util.Iterator;
import java.util.List;
import java.util.Map;
import java.util.NoSuchElementException;
import java.util.Properties;
import java.util.concurrent.atomic.AtomicReference;
import org.apache.commons.configuration2.convert.ConversionHandler;
import org.apache.commons.configuration2.convert.DefaultConversionHandler;
import org.apache.commons.configuration2.convert.DisabledListDelimiterHandler;
import org.apache.commons.configuration2.convert.ListDelimiterHandler;
import org.apache.commons.configuration2.event.BaseEventSource;
import org.apache.commons.configuration2.event.ConfigurationErrorEvent;
import org.apache.commons.configuration2.event.ConfigurationEvent;
import org.apache.commons.configuration2.event.EventListener;
import org.apache.commons.configuration2.ex.ConversionException;
import org.apache.commons.configuration2.interpol.ConfigurationInterpolator;
import org.apache.commons.configuration2.interpol.InterpolatorSpecification;
import org.apache.commons.configuration2.interpol.Lookup;
import org.apache.commons.configuration2.io.ConfigurationLogger;
import org.apache.commons.configuration2.sync.LockMode;
import org.apache.commons.configuration2.sync.NoOpSynchronizer;
import org.apache.commons.configuration2.sync.Synchronizer;
import org.apache.commons.lang3.ClassUtils;
import org.apache.commons.lang3.ObjectUtils;
/**
* <p>Abstract configuration class. Provides basic functionality but does not
* store any data.</p>
* <p>If you want to write your own Configuration class then you should
* implement only abstract methods from this class. A lot of functionality
* needed by typical implementations of the {@code Configuration}
* interface is already provided by this base class. Following is a list of
* features implemented here:</p>
* <ul><li>Data conversion support. The various data types required by the
* {@code Configuration} interface are already handled by this base class.
* A concrete sub class only needs to provide a generic {@code getProperty()}
* method.</li>
* <li>Support for variable interpolation. Property values containing special
* variable tokens (like {@code ${var}}) will be replaced by their
* corresponding values.</li>
* <li>Optional support for string lists. The values of properties to be added to this
* configuration are checked whether they contain a list delimiter character. If
* this is the case and if list splitting is enabled, the string is split and
* multiple values are added for this property. List splitting is controlled
* by a {@link ListDelimiterHandler} object which can be set using the
* {@link #setListDelimiterHandler(ListDelimiterHandler)} method. It is
* disabled per default. To enable this feature, set a suitable
* {@code ListDelimiterHandler}, e.g. an instance of
* {@link org.apache.commons.configuration2.convert.DefaultListDelimiterHandler
* DefaultListDelimiterHandler} configured with the desired list delimiter character.</li>
* <li>Allows specifying how missing properties are treated. Per default the
* get methods returning an object will return <b>null</b> if the searched
* property key is not found (and no default value is provided). With the
* {@code setThrowExceptionOnMissing()} method this behavior can be
* changed to throw an exception when a requested property cannot be found.</li>
* <li>Basic event support. Whenever this configuration is modified registered
* event listeners are notified. Refer to the various {@code EVENT_XXX}
* constants to get an impression about which event types are supported.</li>
* <li>Support for proper synchronization based on the {@link Synchronizer}
* interface.</li>
* </ul>
* <p>
* Most methods defined by the {@code Configuration} interface are already
* implemented in this class. Many method implementations perform basic
* book-keeping tasks (e.g. firing events, handling synchronization), and then
* delegate to other (protected) methods executing the actual work. Subclasses
* override these protected methods to define or adapt behavior. The public
* entry point methods are final to prevent subclasses from breaking basic
* functionality.
* </p>
*
*/
public abstract class AbstractConfiguration extends BaseEventSource implements Configuration
{
/** The list delimiter handler. */
private ListDelimiterHandler listDelimiterHandler;
/** The conversion handler. */
private ConversionHandler conversionHandler;
/**
* Whether the configuration should throw NoSuchElementExceptions or simply
* return null when a property does not exist. Defaults to return null.
*/
private boolean throwExceptionOnMissing;
/** Stores a reference to the object that handles variable interpolation. */
private AtomicReference<ConfigurationInterpolator> interpolator;
/** The object responsible for synchronization. */
private volatile Synchronizer synchronizer;
/** The object used for dealing with encoded property values. */
private ConfigurationDecoder configurationDecoder;
/** Stores the logger.*/
private ConfigurationLogger log;
/**
* Creates a new instance of {@code AbstractConfiguration}.
*/
public AbstractConfiguration()
{
interpolator = new AtomicReference<>();
initLogger(null);
installDefaultInterpolator();
listDelimiterHandler = DisabledListDelimiterHandler.INSTANCE;
conversionHandler = DefaultConversionHandler.INSTANCE;
}
/**
* Returns the {@code ListDelimiterHandler} used by this instance.
*
* @return the {@code ListDelimiterHandler}
* @since 2.0
*/
public ListDelimiterHandler getListDelimiterHandler()
{
return listDelimiterHandler;
}
/**
* <p>
* Sets the {@code ListDelimiterHandler} to be used by this instance. This
* object is invoked every time when dealing with string properties that may
* contain a list delimiter and thus have to be split to multiple values.
* Per default, a {@code ListDelimiterHandler} implementation is set which
* does not support list splitting. This can be changed for instance by
* setting a {@link org.apache.commons.configuration2.convert.DefaultListDelimiterHandler
* DefaultListDelimiterHandler} object.
* </p>
* <p>
* <strong>Warning:</strong> Be careful when changing the list delimiter
* handler when the configuration has already been loaded/populated. List
* handling is typically applied already when properties are added to the
* configuration. If later another handler is set which processes lists
* differently, results may be unexpected; some operations may even cause
* exceptions.
* </p>
*
* @param listDelimiterHandler the {@code ListDelimiterHandler} to be used
* (must not be <b>null</b>)
* @throws IllegalArgumentException if the {@code ListDelimiterHandler} is
* <b>null</b>
* @since 2.0
*/
public void setListDelimiterHandler(
final ListDelimiterHandler listDelimiterHandler)
{
if (listDelimiterHandler == null)
{
throw new IllegalArgumentException(
"List delimiter handler must not be null!");
}
this.listDelimiterHandler = listDelimiterHandler;
}
/**
* Returns the {@code ConversionHandler} used by this instance.
*
* @return the {@code ConversionHandler}
* @since 2.0
*/
public ConversionHandler getConversionHandler()
{
return conversionHandler;
}
/**
* Sets the {@code ConversionHandler} to be used by this instance. The
* {@code ConversionHandler} is responsible for every kind of data type
* conversion. It is consulted by all get methods returning results in
* specific data types. A newly created configuration uses a default
* {@code ConversionHandler} implementation. This can be changed while
* initializing the configuration (e.g. via a builder). Note that access to
* this property is not synchronized.
*
* @param conversionHandler the {@code ConversionHandler} to be used (must
* not be <b>null</b>)
* @throws IllegalArgumentException if the {@code ConversionHandler} is
* <b>null</b>
* @since 2.0
*/
public void setConversionHandler(final ConversionHandler conversionHandler)
{
if (conversionHandler == null)
{
throw new IllegalArgumentException(
"ConversionHandler must not be null!");
}
this.conversionHandler = conversionHandler;
}
/**
* Allows to set the {@code throwExceptionOnMissing} flag. This
* flag controls the behavior of property getter methods that return
* objects if the requested property is missing. If the flag is set to
* <b>false</b> (which is the default value), these methods will return
* <b>null</b>. If set to <b>true</b>, they will throw a
* {@code NoSuchElementException} exception. Note that getter methods
* for primitive data types are not affected by this flag.
*
* @param throwExceptionOnMissing The new value for the property
*/
public void setThrowExceptionOnMissing(final boolean throwExceptionOnMissing)
{
this.throwExceptionOnMissing = throwExceptionOnMissing;
}
/**
* Returns true if missing values throw Exceptions.
*
* @return true if missing values throw Exceptions
*/
public boolean isThrowExceptionOnMissing()
{
return throwExceptionOnMissing;
}
/**
* Returns the {@code ConfigurationInterpolator} object that manages the
* lookup objects for resolving variables.
*
* @return the {@code ConfigurationInterpolator} associated with this
* configuration
* @since 1.4
*/
@Override
public ConfigurationInterpolator getInterpolator()
{
return interpolator.get();
}
/**
* {@inheritDoc} This implementation sets the passed in object without
* further modifications. A <b>null</b> argument is allowed; this disables
* interpolation.
*
* @since 2.0
*/
@Override
public final void setInterpolator(final ConfigurationInterpolator ci)
{
interpolator.set(ci);
}
/**
* {@inheritDoc} This implementation creates a new
* {@code ConfigurationInterpolator} instance and initializes it with the
* given {@code Lookup} objects. In addition, it adds a specialized default
* {@code Lookup} object which queries this {@code Configuration}.
*
* @since 2.0
*/
@Override
public final void installInterpolator(
final Map<String, ? extends Lookup> prefixLookups,
final Collection<? extends Lookup> defLookups)
{
final InterpolatorSpecification spec =
new InterpolatorSpecification.Builder()
.withPrefixLookups(prefixLookups)
.withDefaultLookups(defLookups)
.withDefaultLookup(new ConfigurationLookup(this))
.create();
setInterpolator(ConfigurationInterpolator.fromSpecification(spec));
}
/**
* Registers all {@code Lookup} objects in the given map at the current
* {@code ConfigurationInterpolator} of this configuration. The set of
* default lookup objects (for variables without a prefix) is not modified
* by this method. If this configuration does not have a
* {@code ConfigurationInterpolator}, a new instance is created. Note: This
* method is mainly intended to be used for initializing a configuration
* when it is created by a builder. Normal client code should better call
* {@link #installInterpolator(Map, Collection)} to define the
* {@code ConfigurationInterpolator} in a single step.
*
* @param lookups a map with new {@code Lookup} objects and their prefixes
* (may be <b>null</b>)
* @since 2.0
*/
public void setPrefixLookups(final Map<String, ? extends Lookup> lookups)
{
boolean success;
do
{
// do this in a loop because the ConfigurationInterpolator
// instance may be changed by another thread
final ConfigurationInterpolator ciOld = getInterpolator();
final ConfigurationInterpolator ciNew =
ciOld != null ? ciOld : new ConfigurationInterpolator();
ciNew.registerLookups(lookups);
success = interpolator.compareAndSet(ciOld, ciNew);
} while (!success);
}
/**
* Adds all {@code Lookup} objects in the given collection as default
* lookups (i.e. lookups without a variable prefix) to the
* {@code ConfigurationInterpolator} object of this configuration. In
* addition, it adds a specialized default {@code Lookup} object which
* queries this {@code Configuration}. The set of {@code Lookup} objects
* with prefixes is not modified by this method. If this configuration does
* not have a {@code ConfigurationInterpolator}, a new instance is created.
* Note: This method is mainly intended to be used for initializing a
* configuration when it is created by a builder. Normal client code should
* better call {@link #installInterpolator(Map, Collection)} to define the
* {@code ConfigurationInterpolator} in a single step.
*
* @param lookups the collection with default {@code Lookup} objects to be
* added
* @since 2.0
*/
public void setDefaultLookups(final Collection<? extends Lookup> lookups)
{
boolean success;
do
{
final ConfigurationInterpolator ciOld = getInterpolator();
final ConfigurationInterpolator ciNew =
ciOld != null ? ciOld : new ConfigurationInterpolator();
Lookup confLookup = findConfigurationLookup(ciNew);
if (confLookup == null)
{
confLookup = new ConfigurationLookup(this);
}
else
{
ciNew.removeDefaultLookup(confLookup);
}
ciNew.addDefaultLookups(lookups);
ciNew.addDefaultLookup(confLookup);
success = interpolator.compareAndSet(ciOld, ciNew);
} while (!success);
}
/**
* Sets the specified {@code ConfigurationInterpolator} as the parent of
* this configuration's {@code ConfigurationInterpolator}. If this
* configuration does not have a {@code ConfigurationInterpolator}, a new
* instance is created. Note: This method is mainly intended to be used for
* initializing a configuration when it is created by a builder. Normal
* client code can directly update the {@code ConfigurationInterpolator}.
*
* @param parent the parent {@code ConfigurationInterpolator} to be set
* @since 2.0
*/
public void setParentInterpolator(final ConfigurationInterpolator parent)
{
boolean success;
do
{
final ConfigurationInterpolator ciOld = getInterpolator();
final ConfigurationInterpolator ciNew =
ciOld != null ? ciOld : new ConfigurationInterpolator();
ciNew.setParentInterpolator(parent);
success = interpolator.compareAndSet(ciOld, ciNew);
} while (!success);
}
/**
* Sets the {@code ConfigurationDecoder} for this configuration. This object
* is used by {@link #getEncodedString(String)}.
*
* @param configurationDecoder the {@code ConfigurationDecoder}
* @since 2.0
*/
public void setConfigurationDecoder(
final ConfigurationDecoder configurationDecoder)
{
this.configurationDecoder = configurationDecoder;
}
/**
* Returns the {@code ConfigurationDecoder} used by this instance.
*
* @return the {@code ConfigurationDecoder}
* @since 2.0
*/
public ConfigurationDecoder getConfigurationDecoder()
{
return configurationDecoder;
}
/**
* Creates a clone of the {@code ConfigurationInterpolator} used by this
* instance. This method can be called by {@code clone()} implementations of
* derived classes. Normally, the {@code ConfigurationInterpolator} of a
* configuration instance must not be shared with other instances because it
* contains a specific {@code Lookup} object pointing to the owning
* configuration. This has to be taken into account when cloning a
* configuration. This method creates a new
* {@code ConfigurationInterpolator} for this configuration instance which
* contains all lookup objects from the original
* {@code ConfigurationInterpolator} except for the configuration specific
* lookup pointing to the passed in original configuration. This one is
* replaced by a corresponding {@code Lookup} referring to this
* configuration.
*
* @param orgConfig the original configuration from which this one was
* cloned
* @since 2.0
*/
protected void cloneInterpolator(final AbstractConfiguration orgConfig)
{
interpolator = new AtomicReference<>();
final ConfigurationInterpolator orgInterpolator = orgConfig.getInterpolator();
final List<Lookup> defaultLookups = orgInterpolator.getDefaultLookups();
final Lookup lookup = findConfigurationLookup(orgInterpolator, orgConfig);
if (lookup != null)
{
defaultLookups.remove(lookup);
}
installInterpolator(orgInterpolator.getLookups(), defaultLookups);
}
/**
* Creates a default {@code ConfigurationInterpolator} which is initialized
* with all default {@code Lookup} objects. This method is called by the
* constructor. It ensures that default interpolation works for every new
* configuration instance.
*/
private void installDefaultInterpolator()
{
installInterpolator(
ConfigurationInterpolator.getDefaultPrefixLookups(), null);
}
/**
* Finds a {@code ConfigurationLookup} pointing to this configuration in the
* default lookups of the specified {@code ConfigurationInterpolator}. This
* method is called to ensure that there is exactly one default lookup
* querying this configuration.
*
* @param ci the {@code ConfigurationInterpolator} in question
* @return the found {@code Lookup} object or <b>null</b>
*/
private Lookup findConfigurationLookup(final ConfigurationInterpolator ci)
{
return findConfigurationLookup(ci, this);
}
/**
* Finds a {@code ConfigurationLookup} pointing to the specified
* configuration in the default lookups for the specified
* {@code ConfigurationInterpolator}.
*
* @param ci the {@code ConfigurationInterpolator} in question
* @param targetConf the target configuration of the searched lookup
* @return the found {@code Lookup} object or <b>null</b>
*/
private static Lookup findConfigurationLookup(final ConfigurationInterpolator ci,
final ImmutableConfiguration targetConf)
{
for (final Lookup l : ci.getDefaultLookups())
{
if (l instanceof ConfigurationLookup)
{
if (targetConf == ((ConfigurationLookup) l).getConfiguration())
{
return l;
}
}
}
return null;
}
/**
* Returns the logger used by this configuration object.
*
* @return the logger
* @since 2.0
*/
public ConfigurationLogger getLogger()
{
return log;
}
/**
* Allows setting the logger to be used by this configuration object. This
* method makes it possible for clients to exactly control logging behavior.
* Per default a logger is set that will ignore all log messages. Derived
* classes that want to enable logging should call this method during their
* initialization with the logger to be used. It is legal to pass a
* <b>null</b> logger; in this case, logging will be disabled.
*
* @param log the new logger
* @since 2.0
*/
public void setLogger(final ConfigurationLogger log)
{
initLogger(log);
}
/**
* Adds a special {@link EventListener} object to this configuration that
* will log all internal errors. This method is intended to be used by
* certain derived classes, for which it is known that they can fail on
* property access (e.g. {@code DatabaseConfiguration}).
*
* @since 1.4
*/
public final void addErrorLogListener()
{
addEventListener(ConfigurationErrorEvent.ANY,
event -> getLogger().warn("Internal error", event.getCause()));
}
/**
* Returns the object responsible for synchronizing this configuration. All
* access to this configuration - both read and write access - is controlled
* by this object. This implementation never returns <b>null</b>. If no
* {@code Synchronizer} has been set, a {@link NoOpSynchronizer} is
* returned. So, per default, instances of {@code AbstractConfiguration} are
* not thread-safe unless a suitable {@code Synchronizer} is set!
*
* @return the {@code Synchronizer} used by this instance
* @since 2.0
*/
@Override
public final Synchronizer getSynchronizer()
{
final Synchronizer sync = synchronizer;
return sync != null ? sync : NoOpSynchronizer.INSTANCE;
}
/**
* Sets the object responsible for synchronizing this configuration. This
* method has to be called with a suitable {@code Synchronizer} object when
* initializing this configuration instance in order to make it thread-safe.
*
* @param synchronizer the new {@code Synchronizer}; can be <b>null</b>,
* then this instance uses a {@link NoOpSynchronizer}
* @since 2.0
*/
@Override
public final void setSynchronizer(final Synchronizer synchronizer)
{
this.synchronizer = synchronizer;
}
/**
* {@inheritDoc} This implementation delegates to {@code beginRead()} or
* {@code beginWrite()}, depending on the {@code LockMode} argument.
* Subclasses can override these protected methods to perform additional
* steps when a configuration is locked.
*
* @since 2.0
* @throws NullPointerException if the argument is <b>null</b>
*/
@Override
public final void lock(final LockMode mode)
{
switch (mode)
{
case READ:
beginRead(false);
break;
case WRITE:
beginWrite(false);
break;
default:
throw new IllegalArgumentException("Unsupported LockMode: " + mode);
}
}
/**
* {@inheritDoc} This implementation delegates to {@code endRead()} or
* {@code endWrite()}, depending on the {@code LockMode} argument.
* Subclasses can override these protected methods to perform additional
* steps when a configuration's lock is released.
*
* @throws NullPointerException if the argument is <b>null</b>
*/
@Override
public final void unlock(final LockMode mode)
{
switch (mode)
{
case READ:
endRead();
break;
case WRITE:
endWrite();
break;
default:
throw new IllegalArgumentException("Unsupported LockMode: " + mode);
}
}
/**
* Notifies this configuration's {@link Synchronizer} that a read operation
* is about to start. This method is called by all methods which access this
* configuration in a read-only mode. Subclasses may override it to perform
* additional actions before this read operation. The boolean
* <em>optimize</em> argument can be evaluated by overridden methods in
* derived classes. Some operations which require a lock do not need a fully
* initialized configuration object. By setting this flag to
* <strong>true</strong>, such operations can give a corresponding hint. An
* overridden implementation of {@code beginRead()} can then decide to skip
* some initialization steps. All basic operations in this class (and most
* of the basic {@code Configuration} implementations) call this method with
* a parameter value of <strong>false</strong>. <strong>In any case the
* inherited method must be called! Otherwise, proper synchronization is not
* guaranteed.</strong>
*
* @param optimize a flag whether optimization can be performed
* @since 2.0
*/
protected void beginRead(final boolean optimize)
{
getSynchronizer().beginRead();
}
/**
* Notifies this configuration's {@link Synchronizer} that a read operation
* has finished. This method is called by all methods which access this
* configuration in a read-only manner at the end of their execution.
* Subclasses may override it to perform additional actions after this read
* operation. <strong>In any case the inherited method must be called!
* Otherwise, the read lock will not be released.</strong>
*
* @since 2.0
*/
protected void endRead()
{
getSynchronizer().endRead();
}
/**
* Notifies this configuration's {@link Synchronizer} that an update
* operation is about to start. This method is called by all methods which
* modify this configuration. Subclasses may override it to perform
* additional operations before an update. For a description of the boolean
* <em>optimize</em> argument refer to the documentation of
* {@code beginRead()}. <strong>In any case the inherited method must be
* called! Otherwise, proper synchronization is not guaranteed.</strong>
*
* @param optimize a flag whether optimization can be performed
* @see #beginRead(boolean)
* @since 2.0
*/
protected void beginWrite(final boolean optimize)
{
getSynchronizer().beginWrite();
}
/**
* Notifies this configuration's {@link Synchronizer} that an update
* operation has finished. This method is called by all methods which modify
* this configuration at the end of their execution. Subclasses may override
* it to perform additional operations after an update. <strong>In any case
* the inherited method must be called! Otherwise, the write lock will not
* be released.</strong>
*
* @since 2.0
*/
protected void endWrite()
{
getSynchronizer().endWrite();
}
@Override
public final void addProperty(final String key, final Object value)
{
beginWrite(false);
try
{
fireEvent(ConfigurationEvent.ADD_PROPERTY, key, value, true);
addPropertyInternal(key, value);
fireEvent(ConfigurationEvent.ADD_PROPERTY, key, value, false);
}
finally
{
endWrite();
}
}
/**
* Actually adds a property to this configuration. This method is called by
* {@code addProperty()}. It performs list splitting if necessary and
* delegates to {@link #addPropertyDirect(String, Object)} for every single
* property value.
*
* @param key the key of the property to be added
* @param value the new property value
* @since 2.0
*/
protected void addPropertyInternal(final String key, final Object value)
{
for (final Object obj : getListDelimiterHandler().parse(value))
{
addPropertyDirect(key, obj);
}
}
/**
* Adds a key/value pair to the Configuration. Override this method to
* provide write access to underlying Configuration store.
*
* @param key key to use for mapping
* @param value object to store
*/
protected abstract void addPropertyDirect(String key, Object value);
/**
* interpolate key names to handle ${key} stuff
*
* @param base string to interpolate
*
* @return returns the key name with the ${key} substituted
*/
protected String interpolate(final String base)
{
final Object result = interpolate((Object) base);
return result == null ? null : result.toString();
}
/**
* Returns the interpolated value. This implementation delegates to the
* current {@code ConfigurationInterpolator}. If no
* {@code ConfigurationInterpolator} is set, the passed in value is returned
* without changes.
*
* @param value the value to interpolate
* @return the value with variables substituted
*/
protected Object interpolate(final Object value)
{
final ConfigurationInterpolator ci = getInterpolator();
return ci != null ? ci.interpolate(value) : value;
}
@Override
public Configuration subset(final String prefix)
{
return new SubsetConfiguration(this, prefix, ".");
}
@Override
public ImmutableConfiguration immutableSubset(final String prefix)
{
return ConfigurationUtils.unmodifiableConfiguration(subset(prefix));
}
@Override
public final void setProperty(final String key, final Object value)
{
beginWrite(false);
try
{
fireEvent(ConfigurationEvent.SET_PROPERTY, key, value, true);
setPropertyInternal(key, value);
fireEvent(ConfigurationEvent.SET_PROPERTY, key, value, false);
}
finally
{
endWrite();
}
}
/**
* Actually sets the value of a property. This method is called by
* {@code setProperty()}. It provides a default implementation of this
* functionality by clearing the specified key and delegating to
* {@code addProperty()}. Subclasses should override this method if they can
* provide a more efficient algorithm for setting a property value.
*
* @param key the property key
* @param value the new property value
* @since 2.0
*/
protected void setPropertyInternal(final String key, final Object value)
{
setDetailEvents(false);
try
{
clearProperty(key);
addProperty(key, value);
}
finally
{
setDetailEvents(true);
}
}
/**
* Removes the specified property from this configuration. This
* implementation performs some preparations and then delegates to
* {@code clearPropertyDirect()}, which will do the real work.
*
* @param key the key to be removed
*/
@Override
public final void clearProperty(final String key)
{
beginWrite(false);
try
{
fireEvent(ConfigurationEvent.CLEAR_PROPERTY, key, null, true);
clearPropertyDirect(key);
fireEvent(ConfigurationEvent.CLEAR_PROPERTY, key, null, false);
}
finally
{
endWrite();
}
}
/**
* Removes the specified property from this configuration. This method is
* called by {@code clearProperty()} after it has done some
* preparations. It must be overridden in sub classes.
*
* @param key the key to be removed
*/
protected abstract void clearPropertyDirect(String key);
@Override
public final void clear()
{
beginWrite(false);
try
{
fireEvent(ConfigurationEvent.CLEAR, null, null, true);
clearInternal();
fireEvent(ConfigurationEvent.CLEAR, null, null, false);
}
finally
{
endWrite();
}
}
/**
* Clears the whole configuration. This method is called by {@code clear()}
* after some preparations have been made. This base implementation uses
* the iterator provided by {@code getKeys()} to remove every single
* property. Subclasses should override this method if there is a more
* efficient way of clearing the configuration.
*/
protected void clearInternal()
{
setDetailEvents(false);
boolean useIterator = true;
try
{
final Iterator<String> it = getKeys();
while (it.hasNext())
{
final String key = it.next();
if (useIterator)
{
try
{
it.remove();
}
catch (final UnsupportedOperationException usoex)
{
useIterator = false;
}
}
if (useIterator && containsKey(key))
{
useIterator = false;
}
if (!useIterator)
{
// workaround for Iterators that do not remove the
// property
// on calling remove() or do not support remove() at all
clearProperty(key);
}
}
}
finally
{
setDetailEvents(true);
}
}
/**
* {@inheritDoc} This implementation takes care of synchronization and then
* delegates to {@code getKeysInternal()} for obtaining the actual iterator.
* Note that depending on a concrete implementation, an iteration may fail
* if the configuration is updated concurrently.
*/
@Override
public final Iterator<String> getKeys()
{
beginRead(false);
try
{
return getKeysInternal();
}
finally
{
endRead();
}
}
/**
* {@inheritDoc} This implementation returns keys that either match the
* prefix or start with the prefix followed by a dot ('.'). So the call
* {@code getKeys("db");} will find the keys {@code db},
* {@code db.user}, or {@code db.password}, but not the key
* {@code dbdriver}.
*/
@Override
public final Iterator<String> getKeys(final String prefix)
{
beginRead(false);
try
{
return getKeysInternal(prefix);
}
finally
{
endRead();
}
}
/**
* Actually creates an iterator for iterating over the keys in this
* configuration. This method is called by {@code getKeys()}, it has to be
* defined by concrete subclasses.
*
* @return an {@code Iterator} with all property keys in this configuration
* @since 2.0
*/
protected abstract Iterator<String> getKeysInternal();
/**
* Returns an {@code Iterator} with all property keys starting with the
* specified prefix. This method is called by {@link #getKeys(String)}. It
* is fully implemented by delegating to {@code getKeysInternal()} and
* returning a special iterator which filters for the passed in prefix.
* Subclasses can override it if they can provide a more efficient way to
* iterate over specific keys only.
*
* @param prefix the prefix for the keys to be taken into account
* @return an {@code Iterator} returning the filtered keys
* @since 2.0
*/
protected Iterator<String> getKeysInternal(final String prefix)
{
return new PrefixedKeysIterator(getKeysInternal(), prefix);
}
/**
* {@inheritDoc} This implementation ensures proper synchronization.
* Subclasses have to define the abstract {@code getPropertyInternal()}
* method which is called from here.
*/
@Override
public final Object getProperty(final String key)
{
beginRead(false);
try
{
return getPropertyInternal(key);
}
finally
{
endRead();
}
}
/**
* Actually obtains the value of the specified property. This method is
* called by {@code getProperty()}. Concrete subclasses must define it to
* fetch the value of the desired property.
*
* @param key the key of the property in question
* @return the (raw) value of this property
* @since 2.0
*/
protected abstract Object getPropertyInternal(String key);
/**
* {@inheritDoc} This implementation handles synchronization and delegates
* to {@code isEmptyInternal()}.
*/
@Override
public final boolean isEmpty()
{
beginRead(false);
try
{
return isEmptyInternal();
}
finally
{
endRead();
}
}
/**
* Actually checks whether this configuration contains data. This method is
* called by {@code isEmpty()}. It has to be defined by concrete subclasses.
*
* @return <b>true</b> if this configuration contains no data, <b>false</b>
* otherwise
* @since 2.0
*/
protected abstract boolean isEmptyInternal();
/**
* {@inheritDoc} This implementation handles synchronization and delegates
* to {@code sizeInternal()}.
*/
@Override
public final int size()
{
beginRead(false);
try
{
return sizeInternal();
}
finally
{
endRead();
}
}
/**
* Actually calculates the size of this configuration. This method is called
* by {@code size()} with a read lock held. The base implementation provided
* here calculates the size based on the iterator returned by
* {@code getKeys()}. Sub classes which can determine the size in a more
* efficient way should override this method.
*
* @return the size of this configuration (i.e. the number of keys)
*/
protected int sizeInternal()
{
int size = 0;
for (final Iterator<String> keyIt = getKeysInternal(); keyIt.hasNext(); size++)
{
keyIt.next();
}
return size;
}
/**
* {@inheritDoc} This implementation handles synchronization and delegates
* to {@code containsKeyInternal()}.
*/
@Override
public final boolean containsKey(final String key)
{
beginRead(false);
try
{
return containsKeyInternal(key);
}
finally
{
endRead();
}
}
/**
* Actually checks whether the specified key is contained in this
* configuration. This method is called by {@code containsKey()}. It has to
* be defined by concrete subclasses.
*
* @param key the key in question
* @return <b>true</b> if this key is contained in this configuration,
* <b>false</b> otherwise
* @since 2.0
*/
protected abstract boolean containsKeyInternal(String key);
@Override
public Properties getProperties(final String key)
{
return getProperties(key, null);
}
/**
* Get a list of properties associated with the given configuration key.
*
* @param key The configuration key.
* @param defaults Any default values for the returned
* {@code Properties} object. Ignored if {@code null}.
*
* @return The associated properties if key is found.
*
* @throws ConversionException is thrown if the key maps to an object that
* is not a String/List of Strings.
*
* @throws IllegalArgumentException if one of the tokens is malformed (does
* not contain an equals sign).
*/
public Properties getProperties(final String key, final Properties defaults)
{
/*
* Grab an array of the tokens for this key.
*/
final String[] tokens = getStringArray(key);
/*
* Each token is of the form 'key=value'.
*/
final Properties props = defaults == null ? new Properties() : new Properties(defaults);
for (final String token : tokens)
{
final int equalSign = token.indexOf('=');
if (equalSign > 0)
{
final String pkey = token.substring(0, equalSign).trim();
final String pvalue = token.substring(equalSign + 1).trim();
props.put(pkey, pvalue);
}
else if (tokens.length == 1 && "".equals(token))
{
// Semantically equivalent to an empty Properties
// object.
break;
}
else
{
throw new IllegalArgumentException('\'' + token + "' does not contain an equals sign");
}
}
return props;
}
@Override
public boolean getBoolean(final String key)
{
final Boolean b = convert(Boolean.class, key, null, true);
return checkNonNullValue(key, b).booleanValue();
}
@Override
public boolean getBoolean(final String key, final boolean defaultValue)
{
return getBoolean(key, Boolean.valueOf(defaultValue)).booleanValue();
}
/**
* Obtains the value of the specified key and tries to convert it into a
* {@code Boolean} object. If the property has no value, the passed
* in default value will be used.
*
* @param key the key of the property
* @param defaultValue the default value
* @return the value of this key converted to a {@code Boolean}
* @throws ConversionException if the value cannot be converted to a
* {@code Boolean}
*/
@Override
public Boolean getBoolean(final String key, final Boolean defaultValue)
{
return convert(Boolean.class, key, defaultValue, false);
}
@Override
public byte getByte(final String key)
{
final Byte b = convert(Byte.class, key, null, true);
return checkNonNullValue(key, b).byteValue();
}
@Override
public byte getByte(final String key, final byte defaultValue)
{
return getByte(key, Byte.valueOf(defaultValue)).byteValue();
}
@Override
public Byte getByte(final String key, final Byte defaultValue)
{
return convert(Byte.class, key, defaultValue, false);
}
@Override
public double getDouble(final String key)
{
final Double d = convert(Double.class, key, null, true);
return checkNonNullValue(key, d).doubleValue();
}
@Override
public double getDouble(final String key, final double defaultValue)
{
return getDouble(key, Double.valueOf(defaultValue)).doubleValue();
}
@Override
public Double getDouble(final String key, final Double defaultValue)
{
return convert(Double.class, key, defaultValue, false);
}
@Override
public float getFloat(final String key)
{
final Float f = convert(Float.class, key, null, true);
return checkNonNullValue(key, f).floatValue();
}
@Override
public float getFloat(final String key, final float defaultValue)
{
return getFloat(key, Float.valueOf(defaultValue)).floatValue();
}
@Override
public Float getFloat(final String key, final Float defaultValue)
{
return convert(Float.class, key, defaultValue, false);
}
@Override
public int getInt(final String key)
{
final Integer i = convert(Integer.class, key, null, true);
return checkNonNullValue(key, i).intValue();
}
@Override
public int getInt(final String key, final int defaultValue)
{
return getInteger(key, Integer.valueOf(defaultValue)).intValue();
}
@Override
public Integer getInteger(final String key, final Integer defaultValue)
{
return convert(Integer.class, key, defaultValue, false);
}
@Override
public long getLong(final String key)
{
final Long l = convert(Long.class, key, null, true);
return checkNonNullValue(key, l).longValue();
}
@Override
public long getLong(final String key, final long defaultValue)
{
return getLong(key, Long.valueOf(defaultValue)).longValue();
}
@Override
public Long getLong(final String key, final Long defaultValue)
{
return convert(Long.class, key, defaultValue, false);
}
@Override
public short getShort(final String key)
{
final Short s = convert(Short.class, key, null, true);
return checkNonNullValue(key, s).shortValue();
}
@Override
public short getShort(final String key, final short defaultValue)
{
return getShort(key, Short.valueOf(defaultValue)).shortValue();
}
@Override
public Short getShort(final String key, final Short defaultValue)
{
return convert(Short.class, key, defaultValue, false);
}
/**
* {@inheritDoc}
* @see #setThrowExceptionOnMissing(boolean)
*/
@Override
public BigDecimal getBigDecimal(final String key)
{
return convert(BigDecimal.class, key, null, true);
}
@Override
public BigDecimal getBigDecimal(final String key, final BigDecimal defaultValue)
{
return convert(BigDecimal.class, key, defaultValue, false);
}
/**
* {@inheritDoc}
* @see #setThrowExceptionOnMissing(boolean)
*/
@Override
public BigInteger getBigInteger(final String key)
{
return convert(BigInteger.class, key, null, true);
}
@Override
public BigInteger getBigInteger(final String key, final BigInteger defaultValue)
{
return convert(BigInteger.class, key, defaultValue, false);
}
/**
* {@inheritDoc}
* @see #setThrowExceptionOnMissing(boolean)
*/
@Override
public String getString(final String key)
{
return convert(String.class, key, null, true);
}
@Override
public String getString(final String key, final String defaultValue)
{
final String result = convert(String.class, key, null, false);
return result != null ? result : interpolate(defaultValue);
}
/**
* {@inheritDoc} This implementation delegates to {@link #getString(String)}
* in order to obtain the value of the passed in key. This value is passed
* to the decoder. Because {@code getString()} is used behind the scenes all
* standard features like handling of missing keys and interpolation work as
* expected.
*/
@Override
public String getEncodedString(final String key, final ConfigurationDecoder decoder)
{
if (decoder == null)
{
throw new IllegalArgumentException(
"ConfigurationDecoder must not be null!");
}
final String value = getString(key);
return value != null ? decoder.decode(value) : null;
}
/**
* {@inheritDoc} This implementation makes use of the
* {@code ConfigurationDecoder} set for this configuration. If no such
* object has been set, an {@code IllegalStateException} exception is
* thrown.
*
* @throws IllegalStateException if no {@code ConfigurationDecoder} is set
* @see #setConfigurationDecoder(ConfigurationDecoder)
*/
@Override
public String getEncodedString(final String key)
{
final ConfigurationDecoder decoder = getConfigurationDecoder();
if (decoder == null)
{
throw new IllegalStateException(
"No default ConfigurationDecoder defined!");
}
return getEncodedString(key, decoder);
}
/**
* Get an array of strings associated with the given configuration key.
* If the key doesn't map to an existing object, an empty array is returned.
* When a property is added to a configuration, it is checked whether it
* contains multiple values. This is obvious if the added object is a list
* or an array. For strings the association {@link ListDelimiterHandler} is
* consulted to find out whether the string can be split into multiple
* values.
*
* @param key The configuration key.
* @return The associated string array if key is found.
*
* @throws ConversionException is thrown if the key maps to an
* object that is not a String/List of Strings.
* @see #setListDelimiterHandler(ListDelimiterHandler)
*/
@Override
public String[] getStringArray(final String key)
{
final String[] result = (String[]) getArray(String.class, key);
return result == null ? new String[0] : result;
}
/**
* {@inheritDoc}
* @see #getStringArray(String)
*/
@Override
public List<Object> getList(final String key)
{
return getList(key, new ArrayList<>());
}
@Override
public List<Object> getList(final String key, final List<?> defaultValue)
{
final Object value = getProperty(key);
List<Object> list;
if (value instanceof String)
{
list = new ArrayList<>(1);
list.add(interpolate((String) value));
}
else if (value instanceof List)
{
list = new ArrayList<>();
final List<?> l = (List<?>) value;
// add the interpolated elements in the new list
for (final Object elem : l)
{
list.add(interpolate(elem));
}
}
else if (value == null)
{
// This is okay because we just return this list to the caller
@SuppressWarnings("unchecked")
final
List<Object> resultList = (List<Object>) defaultValue;
list = resultList;
}
else if (value.getClass().isArray())
{
return Arrays.asList((Object[]) value);
}
else if (isScalarValue(value))
{
return Collections.singletonList((Object) value.toString());
}
else
{
throw new ConversionException('\'' + key + "' doesn't map to a List object: " + value + ", a "
+ value.getClass().getName());
}
return list;
}
@Override
public <T> T get(final Class<T> cls, final String key)
{
return convert(cls, key, null, true);
}
/**
* {@inheritDoc} This implementation delegates to the
* {@link ConversionHandler} to perform the actual type conversion.
*/
@Override
public <T> T get(final Class<T> cls, final String key, final T defaultValue)
{
return convert(cls, key, defaultValue, false);
}
@Override
public Object getArray(final Class<?> cls, final String key)
{
return getArray(cls, key, null);
}
/**
* {@inheritDoc} This implementation delegates to the
* {@link ConversionHandler} to perform the actual type conversion. If this
* results in a <b>null</b> result (because the property is undefined), the
* default value is returned. It is checked whether the default value is an
* array with the correct component type. If not, an exception is thrown.
*
* @throws IllegalArgumentException if the default value is not a compatible
* array
*/
@Override
public Object getArray(final Class<?> cls, final String key, final Object defaultValue)
{
return convertToArray(cls, key, defaultValue);
}
@Override
public <T> List<T> getList(final Class<T> cls, final String key)
{
return getList(cls, key, null);
}
/**
* {@inheritDoc} This implementation delegates to the generic
* {@code getCollection()}. As target collection a newly created
* {@code ArrayList} is passed in.
*/
@Override
public <T> List<T> getList(final Class<T> cls, final String key, final List<T> defaultValue)
{
final List<T> result = new ArrayList<>();
if (getCollection(cls, key, result, defaultValue) == null)
{
return null;
}
return result;
}
@Override
public <T> Collection<T> getCollection(final Class<T> cls, final String key,
final Collection<T> target)
{
return getCollection(cls, key, target, null);
}
/**
* {@inheritDoc} This implementation delegates to the
* {@link ConversionHandler} to perform the actual conversion. If no target
* collection is provided, an {@code ArrayList} is created.
*/
@Override
public <T> Collection<T> getCollection(final Class<T> cls, final String key,
final Collection<T> target, final Collection<T> defaultValue)
{
final Object src = getProperty(key);
if (src == null)
{
return handleDefaultCollection(target, defaultValue);
}
final Collection<T> targetCol =
target != null ? target : new ArrayList<>();
getConversionHandler().toCollection(src, cls, getInterpolator(),
targetCol);
return targetCol;
}
/**
* Checks whether the specified object is a scalar value. This method is
* called by {@code getList()} and {@code getStringArray()} if the
* property requested is not a string, a list, or an array. If it returns
* <b>true</b>, the calling method transforms the value to a string and
* returns a list or an array with this single element. This implementation
* returns <b>true</b> if the value is of a wrapper type for a primitive
* type.
*
* @param value the value to be checked
* @return a flag whether the value is a scalar
* @since 1.7
*/
protected boolean isScalarValue(final Object value)
{
return ClassUtils.wrapperToPrimitive(value.getClass()) != null;
}
/**
* Copies the content of the specified configuration into this
* configuration. If the specified configuration contains a key that is also
* present in this configuration, the value of this key will be replaced by
* the new value. <em>Note:</em> This method won't work well when copying
* hierarchical configurations because it is not able to copy information
* about the properties' structure (i.e. the parent-child-relationships will
* get lost). So when dealing with hierarchical configuration objects their
* {@link BaseHierarchicalConfiguration#clone() clone()} methods
* should be used.
*
* @param c the configuration to copy (can be <b>null</b>, then this
* operation will have no effect)
* @since 1.5
*/
public void copy(final Configuration c)
{
if (c != null)
{
c.lock(LockMode.READ);
try
{
for (final Iterator<String> it = c.getKeys(); it.hasNext();)
{
final String key = it.next();
final Object value = encodeForCopy(c.getProperty(key));
setProperty(key, value);
}
}
finally
{
c.unlock(LockMode.READ);
}
}
}
/**
* Appends the content of the specified configuration to this configuration.
* The values of all properties contained in the specified configuration
* will be appended to this configuration. So if a property is already
* present in this configuration, its new value will be a union of the
* values in both configurations. <em>Note:</em> This method won't work
* well when appending hierarchical configurations because it is not able to
* copy information about the properties' structure (i.e. the
* parent-child-relationships will get lost). So when dealing with
* hierarchical configuration objects their
* {@link BaseHierarchicalConfiguration#clone() clone()} methods
* should be used.
*
* @param c the configuration to be appended (can be <b>null</b>, then this
* operation will have no effect)
* @since 1.5
*/
public void append(final Configuration c)
{
if (c != null)
{
c.lock(LockMode.READ);
try
{
for (final Iterator<String> it = c.getKeys(); it.hasNext();)
{
final String key = it.next();
final Object value = encodeForCopy(c.getProperty(key));
addProperty(key, value);
}
}
finally
{
c.unlock(LockMode.READ);
}
}
}
/**
* Returns a configuration with the same content as this configuration, but
* with all variables replaced by their actual values. This method tries to
* clone the configuration and then perform interpolation on all properties.
* So property values of the form {@code ${var}} will be resolved as
* far as possible (if a variable cannot be resolved, it remains unchanged).
* This operation is useful if the content of a configuration is to be
* exported or processed by an external component that does not support
* variable interpolation.
*
* @return a configuration with all variables interpolated
* @throws org.apache.commons.configuration2.ex.ConfigurationRuntimeException if this
* configuration cannot be cloned
* @since 1.5
*/
public Configuration interpolatedConfiguration()
{
// first clone this configuration
final AbstractConfiguration c = (AbstractConfiguration) ConfigurationUtils
.cloneConfiguration(this);
// now perform interpolation
c.setListDelimiterHandler(new DisabledListDelimiterHandler());
for (final Iterator<String> it = getKeys(); it.hasNext();)
{
final String key = it.next();
c.setProperty(key, getList(key));
}
c.setListDelimiterHandler(getListDelimiterHandler());
return c;
}
/**
* Initializes the logger. Supports <b>null</b> input. This method can be
* called by derived classes in order to enable logging.
*
* @param log the logger
* @since 2.0
*/
protected final void initLogger(final ConfigurationLogger log)
{
this.log = log != null ? log : ConfigurationLogger.newDummyLogger();
}
/**
* Encodes a property value so that it can be added to this configuration.
* This method deals with list delimiters. The passed in object has to be
* escaped so that an add operation yields the same result. If it is a list,
* all of its values have to be escaped.
*
* @param value the value to be encoded
* @return the encoded value
*/
private Object encodeForCopy(final Object value)
{
if (value instanceof Collection)
{
return encodeListForCopy((Collection<?>) value);
}
return getListDelimiterHandler().escape(value,
ListDelimiterHandler.NOOP_TRANSFORMER);
}
/**
* Encodes a list with property values so that it can be added to this
* configuration. This method calls {@code encodeForCopy()} for all list
* elements.
*
* @param values the list to be encoded
* @return a list with encoded elements
*/
private Object encodeListForCopy(final Collection<?> values)
{
final List<Object> result = new ArrayList<>(values.size());
for (final Object value : values)
{
result.add(encodeForCopy(value));
}
return result;
}
/**
* Obtains the property value for the specified key and converts it to the
* given target class.
*
* @param <T> the target type of the conversion
* @param cls the target class
* @param key the key of the desired property
* @param defaultValue a default value
* @return the converted value of this property
* @throws ConversionException if the conversion cannot be performed
*/
private <T> T getAndConvertProperty(final Class<T> cls, final String key, final T defaultValue)
{
final Object value = getProperty(key);
try
{
return ObjectUtils.defaultIfNull(
getConversionHandler().to(value, cls, getInterpolator()),
defaultValue);
}
catch (final ConversionException cex)
{
// improve error message
throw new ConversionException(
String.format(
"Key '%s' cannot be converted to class %s. Value is: '%s'.",
key, cls.getName(), String.valueOf(value)), cex.getCause());
}
}
/**
* Helper method for obtaining a property value with a type conversion.
*
* @param <T> the target type of the conversion
* @param cls the target class
* @param key the key of the desired property
* @param defValue a default value
* @param throwOnMissing a flag whether an exception should be thrown for a
* missing value
* @return the converted value
*/
private <T> T convert(final Class<T> cls, final String key, final T defValue,
final boolean throwOnMissing)
{
if (cls.isArray())
{
return cls.cast(convertToArray(cls.getComponentType(), key, defValue));
}
final T result = getAndConvertProperty(cls, key, defValue);
if (result == null)
{
if (throwOnMissing && isThrowExceptionOnMissing())
{
throwMissingPropertyException(key);
}
return defValue;
}
return result;
}
/**
* Performs a conversion to an array result class. This implementation
* delegates to the {@link ConversionHandler} to perform the actual type
* conversion. If this results in a <b>null</b> result (because the property
* is undefined), the default value is returned. It is checked whether the
* default value is an array with the correct component type. If not, an
* exception is thrown.
*
* @param cls the component class of the array
* @param key the configuration key
* @param defaultValue an optional default value
* @return the converted array
* @throws IllegalArgumentException if the default value is not a compatible
* array
*/
private Object convertToArray(final Class<?> cls, final String key, final Object defaultValue)
{
checkDefaultValueArray(cls, defaultValue);
return ObjectUtils.defaultIfNull(getConversionHandler().toArray(
getProperty(key), cls, getInterpolator()), defaultValue);
}
/**
* Checks an object provided as default value for the {@code getArray()}
* method. Throws an exception if this is not an array with the correct
* component type.
*
* @param cls the component class for the array
* @param defaultValue the default value object to be checked
* @throws IllegalArgumentException if this is not a valid default object
*/
private static void checkDefaultValueArray(final Class<?> cls, final Object defaultValue)
{
if (defaultValue != null
&& (!defaultValue.getClass().isArray() || !cls
.isAssignableFrom(defaultValue.getClass()
.getComponentType())))
{
throw new IllegalArgumentException(
"The type of the default value (" + defaultValue.getClass()
+ ")" + " is not an array of the specified class ("
+ cls + ")");
}
}
/**
* Handles the default collection for a collection conversion. This method
* fills the target collection with the content of the default collection.
* Both collections may be <b>null</b>.
*
* @param target the target collection
* @param defaultValue the default collection
* @return the initialized target collection
*/
private static <T> Collection<T> handleDefaultCollection(final Collection<T> target,
final Collection<T> defaultValue)
{
if (defaultValue == null)
{
return null;
}
Collection<T> result;
if (target == null)
{
result = new ArrayList<>(defaultValue);
}
else
{
target.addAll(defaultValue);
result = target;
}
return result;
}
/**
* Checks whether the specified value is <b>null</b> and throws an exception
* in this case. This method is used by conversion methods returning
* primitive Java types. Here values to be returned must not be <b>null</b>.
*
* @param <T> the type of the object to be checked
* @param key the key which caused the problem
* @param value the value to be checked
* @return the passed in value for chaining this method call
* @throws NoSuchElementException if the value is <b>null</b>
*/
private static <T> T checkNonNullValue(final String key, final T value)
{
if (value == null)
{
throwMissingPropertyException(key);
}
return value;
}
/**
* Helper method for throwing an exception for a key that does not map to an
* existing object.
*
* @param key the key (to be part of the error message)
*/
private static void throwMissingPropertyException(final String key)
{
throw new NoSuchElementException(String.format(
"Key '%s' does not map to an existing object!", key));
}
}
