This is an automated email from the ASF dual-hosted git repository.
ggregory pushed a commit to branch master
in repository https://gitbox.apache.org/repos/asf/commons-configuration.git
The following commit(s) were added to refs/heads/master by this push:
new 07a563f Sort methods.
07a563f is described below
commit 07a563f02be3f0d6ee24b32858e2130f897edba9
Author: Gary Gregory <[email protected]>
AuthorDate: Sun May 31 12:08:33 2020 -0400
Sort methods.
---
.../configuration2/ImmutableConfiguration.java | 796 ++++++++++-----------
1 file changed, 398 insertions(+), 398 deletions(-)
diff --git
a/src/main/java/org/apache/commons/configuration2/ImmutableConfiguration.java
b/src/main/java/org/apache/commons/configuration2/ImmutableConfiguration.java
index b78b66f..48607e3 100644
---
a/src/main/java/org/apache/commons/configuration2/ImmutableConfiguration.java
+++
b/src/main/java/org/apache/commons/configuration2/ImmutableConfiguration.java
@@ -53,97 +53,133 @@ import
org.apache.commons.configuration2.ex.ConversionException;
public interface ImmutableConfiguration
{
/**
- * Checks if the configuration is empty.
+ * Checks if the configuration contains the specified key.
*
- * @return {@code true} if the configuration contains no property,
- * {@code false} otherwise.
+ * @param key the key whose presence in this configuration is to be tested
+ *
+ * @return {@code true} if the configuration contains a value for this
+ * key, {@code false} otherwise
*/
- boolean isEmpty();
+ boolean containsKey(String key);
/**
- * Returns the number of keys stored in this configuration. Note that a
- * concrete implementation is not guaranteed to be efficient; for some
- * implementations it may be expensive to determine the size. Especially,
if
- * you just want to check whether a configuration is empty, it is
preferable
- * to use the {@link #isEmpty()} method.
+ * Gets an object of the specified type associated with the given
+ * configuration key. If the key doesn't map to an existing object, the
+ * method returns null unless
+ * {@link AbstractConfiguration#isThrowExceptionOnMissing()} is set to
+ * {@code true}.
*
- * @return the number of keys stored in this configuration
+ * @param <T> the target type of the value
+ * @param cls the target class of the value
+ * @param key the key of the value
+ * @return the value of the requested type for the key
+ * @throws java.util.NoSuchElementException if the key doesn't map to an
existing
+ * object and {@code throwExceptionOnMissing=true}
+ * @throws org.apache.commons.configuration2.ex.ConversionException if the
value is not compatible with the
+ * requested type
+ * @since 2.0
*/
- int size();
+ <T> T get(Class<T> cls, String key);
/**
- * Checks if the configuration contains the specified key.
+ * Gets an object of the specified type associated with the given
+ * configuration key using a default value. If the key doesn't map to an
+ * existing object, the default value is returned.
*
- * @param key the key whose presence in this configuration is to be tested
+ * @param <T> the target type of the value
+ * @param cls the target class of the value
+ * @param key the key of the value
+ * @param defaultValue the default value
*
- * @return {@code true} if the configuration contains a value for this
- * key, {@code false} otherwise
+ * @return the value of the requested type for the key
+ *
+ * @throws org.apache.commons.configuration2.ex.ConversionException if the
value is not
+ * compatible with the requested type
+ *
+ * @since 2.0
*/
- boolean containsKey(String key);
+ <T> T get(Class<T> cls, String key, T defaultValue);
/**
- * Gets a property from the configuration. This is the most basic get
- * method for retrieving values of properties. In a typical implementation
- * of the {@code Configuration} interface the other get methods (that
- * return specific data types) will internally make use of this method. On
- * this level variable substitution is not yet performed. The returned
- * object is an internal representation of the property value for the
passed
- * in key. It is owned by the {@code Configuration} object. So a caller
- * should not modify this object. It cannot be guaranteed that this object
- * will stay constant over time (i.e. further update operations on the
- * configuration may change its internal state).
+ * Gets an array of typed objects associated with the given configuration
key.
+ * If the key doesn't map to an existing object, an empty list is returned.
*
- * @param key property to retrieve
- * @return the value to which this configuration maps the specified key, or
- * null if the configuration contains no mapping for this key.
+ * @param cls the type expected for the elements of the array
+ * @param key The configuration key.
+ * @return The associated array if the key is found, and the value
compatible with the type specified.
+ *
+ * @throws org.apache.commons.configuration2.ex.ConversionException is
thrown if the key maps to an object that
+ * is not compatible with a list of the specified class.
+ *
+ * @since 2.0
*/
- Object getProperty(String key);
+ Object getArray(Class<?> cls, String key);
/**
- * Gets the list of the keys contained in the configuration that match the
- * specified prefix. For instance, if the configuration contains the
- * following keys:<br>
- * {@code db.user, db.pwd, db.url, window.xpos, window.ypos},<br>
- * an invocation of {@code getKeys("db");}<br>
- * will return the keys below:<br>
- * {@code db.user, db.pwd, db.url}.<br>
- * Note that the prefix itself is included in the result set if there is a
- * matching key. The exact behavior - how the prefix is actually
- * interpreted - depends on a concrete implementation.
+ * Gets an array of typed objects associated with the given configuration
key.
+ * If the key doesn't map to an existing object, the default value is
returned.
*
- * @param prefix The prefix to test against.
- * @return An Iterator of keys that match the prefix.
- * @see #getKeys()
+ * @param cls the type expected for the elements of the array
+ * @param key the configuration key.
+ * @param defaultValue the default value
+ * @return The associated array if the key is found, and the value
compatible with the type specified.
+ *
+ * @throws org.apache.commons.configuration2.ex.ConversionException is
thrown if the key maps to an object that
+ * is not compatible with an array of the specified class.
+ * @throws IllegalArgumentException if the default value is not an array
of the specified type
+ *
+ * @since 2.0
+ * @deprecated This method should not be used any more because its
signature
+ * does not allow type-safe invocations; use {@link #get(Class, String,
Object)}
+ * instead which offers the same functionality; for instance, to query for
an
+ * array of ints use
+ * {@code int[] result = config.get(int[].class, "myArrayKey",
someDefault);}.
*/
- Iterator<String> getKeys(String prefix);
+ @Deprecated
+ Object getArray(Class<?> cls, String key, Object defaultValue);
/**
- * Gets the list of the keys contained in the configuration. The returned
- * iterator can be used to obtain all defined keys. It does not allow
- * removing elements from this configuration via its {@code remove()}
- * method. Note that the keys of this configuration are returned in a form,
- * so that they can be directly evaluated; escaping of special characters
- * (if necessary) has already been performed.
+ * Gets a {@link BigDecimal} associated with the given configuration key.
*
- * @return An Iterator.
+ * @param key The configuration key.
+ * @return The associated BigDecimal if key is found and has valid format
*/
- Iterator<String> getKeys();
+ BigDecimal getBigDecimal(String key);
/**
- * Gets a list of properties associated with the given configuration key.
This method
- * expects the given key to have an arbitrary number of String values,
each of which
- * is of the form {@code key=value}. These strings are split at the equals
sign, and
- * the key parts will become keys of the returned {@code Properties}
object, the value
- * parts become values.
+ * Gets a {@link BigDecimal} associated with the given configuration key.
+ * If the key doesn't map to an existing object, the default value
+ * is returned.
+ *
+ * @param key The configuration key.
+ * @param defaultValue The default value.
+ *
+ * @return The associated BigDecimal if key is found and has valid
+ * format, default value otherwise.
+ */
+ BigDecimal getBigDecimal(String key, BigDecimal defaultValue);
+
+ /**
+ * Gets a {@link BigInteger} associated with the given configuration key.
*
* @param key The configuration key.
- * @return The associated properties if key is found.
- * @throws org.apache.commons.configuration2.ex.ConversionException is
thrown if the
- * key maps to an object that is not a String/List.
- * @throws IllegalArgumentException if one of the tokens is malformed
(does not contain
- * an equals sign).
+ *
+ * @return The associated BigInteger if key is found and has valid format
*/
- Properties getProperties(String key);
+ BigInteger getBigInteger(String key);
+
+ /**
+ * Gets a {@link BigInteger} associated with the given configuration key.
+ * If the key doesn't map to an existing object, the default value
+ * is returned.
+ *
+ * @param key The configuration key.
+ * @param defaultValue The default value.
+ *
+ * @return The associated BigInteger if key is found and has valid
+ * format, default value otherwise.
+ */
+ BigInteger getBigInteger(String key, BigInteger defaultValue);
/**
* Gets a boolean associated with the given configuration key.
@@ -214,6 +250,54 @@ public interface ImmutableConfiguration
Byte getByte(String key, Byte defaultValue);
/**
+ * Gets a collection of typed objects associated with the given
configuration
+ * key. This method works like
+ * {@link #getCollection(Class, String, Collection, Collection)} passing in
+ * <b>null</b> as default value.
+ *
+ * @param <T> the element type of the result list
+ * @param cls the the element class of the result list
+ * @param key the configuration key
+ * @param target the target collection (may be <b>null</b>)
+ * @return the collection to which data was added
+ * @throws org.apache.commons.configuration2.ex.ConversionException if the
conversion is not possible
+ * @since 2.0
+ */
+ <T> Collection<T> getCollection(Class<T> cls, String key,
+ Collection<T> target);
+
+ /**
+ * Gets a collection of typed objects associated with the given
configuration
+ * key using the values in the specified default collection if the key does
+ * not map to an existing object. This method is similar to
+ * {@code getList()}, however, it allows specifying a target collection.
+ * Results are added to this collection. This is useful if the data
+ * retrieved should be added to a specific kind of collection, e.g. a set
to
+ * remove duplicates. The return value is as follows:
+ * <ul>
+ * <li>If the key does not map to an existing object and the default value
+ * is <b>null</b>, the method returns <b>null</b>.</li>
+ * <li>If the target collection is not <b>null</b> and data has been added
+ * (either from the resolved property value or from the default
collection),
+ * the target collection is returned.</li>
+ * <li>If the target collection is <b>null</b> and data has been added
+ * (either from the resolved property value or from the default
collection),
+ * return value is the target collection created by this method.</li>
+ * </ul>
+ *
+ * @param <T> the element type of the result list
+ * @param cls the the element class of the result list
+ * @param key the configuration key
+ * @param target the target collection (may be <b>null</b>)
+ * @param defaultValue the default value (may be <b>null</b>)
+ * @return the collection to which data was added
+ * @throws org.apache.commons.configuration2.ex.ConversionException if the
conversion is not possible
+ * @since 2.0
+ */
+ <T> Collection<T> getCollection(Class<T> cls, String key,
+ Collection<T> target, Collection<T> defaultValue);
+
+ /**
* Gets a double associated with the given configuration key.
*
* @param key The configuration key.
@@ -248,37 +332,113 @@ public interface ImmutableConfiguration
Double getDouble(String key, Double defaultValue);
/**
- * Gets a float associated with the given configuration key.
+ * Gets the value of a string property that is stored in encoded form in
this
+ * configuration using a default {@code ConfigurationDecoder}. This method
+ * works like the method with the same name, but it uses a default
+ * {@code ConfigurationDecoder} associated with this configuration. It
+ * depends on a specific implementation how this default decoder is
+ * obtained.
*
- * @param key The configuration key.
- * @return The associated float.
- * @throws org.apache.commons.configuration2.ex.ConversionException is
thrown if the
- * key maps to an object that is not a Float.
+ * @param key the configuration key
+ * @return the plain string value of the specified encoded property
*/
- float getFloat(String key);
+ String getEncodedString(String key);
/**
- * Gets a float associated with the given configuration key. If the key
doesn't map to
- * an existing object, the default value is returned.
+ * Gets the value of a string property that is stored in encoded form in
this
+ * configuration. This method obtains the value of the string property
+ * identified by the given key. This value is then passed to the provided
+ * {@code ConfigurationDecoder}. The value returned by the
+ * {@code ConfigurationDecoder} is passed to the caller. If the key is not
+ * associated with a value, the decoder is not invoked; depending on this
+ * configuration's settings either <b>null</b> is returned or an exception
+ * is thrown.
*
- * @param key The configuration key.
- * @param defaultValue The default value.
- * @return The associated float.
- * @throws org.apache.commons.configuration2.ex.ConversionException is
thrown if the
- * key maps to an object that is not a Float.
+ * @param key the configuration key
+ * @param decoder the {@code ConfigurationDecoder} (must not be
<b>null</b>)
+ * @return the plain string value of the specified encoded property
+ * @throws IllegalArgumentException if a <b>null</b> decoder is passed
*/
- float getFloat(String key, float defaultValue);
+ String getEncodedString(String key, ConfigurationDecoder decoder);
/**
- * Gets a {@link Float} associated with the given configuration key. If
the key doesn't
- * map to an existing object, the default value is returned.
+ * Gets an enum associated with the given configuration key.
*
+ * @param <T> The enum type whose constant is to be returned.
+ * @param enumType the {@code Class} object of the enum type from which to
return a constant
* @param key The configuration key.
- * @param defaultValue The default value.
- * @return The associated float if key is found and has valid format,
default value
- * otherwise.
- * @throws org.apache.commons.configuration2.ex.ConversionException is
thrown if the
- * key maps to an object that is not a Float.
+ * @return The associated enum.
+ *
+ * @throws org.apache.commons.configuration2.ex.ConversionException is
thrown if the key maps to an object that
+ * is not a String.
+ * @since 2.8
+ */
+ default <T extends Enum<T>> T getEnum(String key, Class<T> enumType) {
+ try {
+ return Enum.valueOf(enumType, getString(key));
+ } catch (IllegalArgumentException e) {
+ throw new ConversionException(e);
+ }
+ }
+
+ /**
+ * Gets the enum associated with the given configuration key. If the key
doesn't map to an existing object, the
+ * default value is returned.
+ *
+ * @param <T> The enum type whose constant is to be returned.
+ * @param key The configuration key.
+ * @param enumType the {@code Class} object of the enum type from which to
return a constant
+ * @param defaultValue The default value.
+ * @return The associated enum if key is found and has valid format,
default value otherwise.
+ *
+ * @throws org.apache.commons.configuration2.ex.ConversionException is
thrown if the key maps to an object that is
+ * not a Enum.
+ * @since 2.8
+ */
+ default <T extends Enum<T>> T getEnum(String key, Class<T> enumType, T
defaultValue) {
+ final String strValue = getString(key, null);
+ if (strValue == null) {
+ return defaultValue;
+ }
+ try {
+ return Enum.valueOf(enumType, strValue);
+ } catch (IllegalArgumentException e) {
+ throw new ConversionException(e);
+ }
+ }
+
+ /**
+ * Gets a float associated with the given configuration key.
+ *
+ * @param key The configuration key.
+ * @return The associated float.
+ * @throws org.apache.commons.configuration2.ex.ConversionException is
thrown if the
+ * key maps to an object that is not a Float.
+ */
+ float getFloat(String key);
+
+ /**
+ * Gets a float associated with the given configuration key. If the key
doesn't map to
+ * an existing object, the default value is returned.
+ *
+ * @param key The configuration key.
+ * @param defaultValue The default value.
+ * @return The associated float.
+ * @throws org.apache.commons.configuration2.ex.ConversionException is
thrown if the
+ * key maps to an object that is not a Float.
+ */
+ float getFloat(String key, float defaultValue);
+
+ /**
+ * Gets a {@link Float} associated with the given configuration key. If
the key doesn't
+ * map to an existing object, the default value is returned.
+ *
+ * @param key The configuration key.
+ * @param defaultValue The default value.
+ * @return The associated float if key is found and has valid format,
default value
+ * otherwise.
+ * @throws org.apache.commons.configuration2.ex.ConversionException is
thrown if the
+ * key maps to an object that is not a Float.
*/
Float getFloat(String key, Float defaultValue);
@@ -318,6 +478,107 @@ public interface ImmutableConfiguration
Integer getInteger(String key, Integer defaultValue);
/**
+ * Gets the list of the keys contained in the configuration. The returned
+ * iterator can be used to obtain all defined keys. It does not allow
+ * removing elements from this configuration via its {@code remove()}
+ * method. Note that the keys of this configuration are returned in a form,
+ * so that they can be directly evaluated; escaping of special characters
+ * (if necessary) has already been performed.
+ *
+ * @return An Iterator.
+ */
+ Iterator<String> getKeys();
+
+ /**
+ * Gets the list of the keys contained in the configuration that match the
+ * specified prefix. For instance, if the configuration contains the
+ * following keys:<br>
+ * {@code db.user, db.pwd, db.url, window.xpos, window.ypos},<br>
+ * an invocation of {@code getKeys("db");}<br>
+ * will return the keys below:<br>
+ * {@code db.user, db.pwd, db.url}.<br>
+ * Note that the prefix itself is included in the result set if there is a
+ * matching key. The exact behavior - how the prefix is actually
+ * interpreted - depends on a concrete implementation.
+ *
+ * @param prefix The prefix to test against.
+ * @return An Iterator of keys that match the prefix.
+ * @see #getKeys()
+ */
+ Iterator<String> getKeys(String prefix);
+
+ /**
+ * Gets a list of typed objects associated with the given configuration key
+ * returning an empty list if the key doesn't map to an existing object.
+ *
+ * @param <T> the type expected for the elements of the list
+ * @param cls the class expected for the elements of the list
+ * @param key The configuration key.
+ * @return The associated list if the key is found.
+ *
+ * @throws org.apache.commons.configuration2.ex.ConversionException is
thrown if the key maps to an object that
+ * is not compatible with a list of the specified class.
+ *
+ * @since 2.0
+ */
+ <T> List<T> getList(Class<T> cls, String key);
+
+ /**
+ * Gets a list of typed objects associated with the given configuration key
+ * returning the specified default value if the key doesn't map to an
+ * existing object. This method recursively retrieves all values stored
+ * for the passed in key, i.e. if one of these values is again a complex
+ * object like an array or a collection (which may be the case for some
+ * concrete subclasses), all values are extracted and added to the
+ * resulting list - performing a type conversion if necessary.
+ *
+ * @param <T> the type expected for the elements of the list
+ * @param cls the class expected for the elements of the list
+ * @param key the configuration key.
+ * @param defaultValue the default value.
+ * @return The associated List.
+ *
+ * @throws org.apache.commons.configuration2.ex.ConversionException is
thrown if the key maps to an object that
+ * is not compatible with a list of the specified class.
+ *
+ * @since 2.0
+ */
+ <T> List<T> getList(Class<T> cls, String key, List<T> defaultValue);
+
+ /**
+ * Gets a List of the values associated with the given configuration key.
+ * This method is different from the generic {@code getList()} method in
+ * that it does not recursively obtain all values stored for the specified
+ * property key. Rather, only the first level of the hierarchy is
processed.
+ * So the resulting list may contain complex objects like arrays or
+ * collections - depending on the storage structure used by a concrete
+ * subclass. If the key doesn't map to an existing object, an empty List is
+ * returned.
+ *
+ * @param key The configuration key.
+ * @return The associated List.
+ *
+ * @throws org.apache.commons.configuration2.ex.ConversionException is
thrown if the key maps to an
+ * object that is not a List.
+ */
+ List<Object> getList(String key);
+
+ /**
+ * Gets a List of strings associated with the given configuration key.
+ * If the key doesn't map to an existing object, the default value
+ * is returned.
+ *
+ * @param key The configuration key.
+ * @param defaultValue The default value.
+ * @return The associated List of strings.
+ *
+ * @throws org.apache.commons.configuration2.ex.ConversionException is
thrown if the key maps to an
+ * object that is not a List.
+ * @see #getList(Class, String, List)
+ */
+ List<Object> getList(String key, List<?> defaultValue);
+
+ /**
* Gets a long associated with the given configuration key.
*
* @param key The configuration key.
@@ -357,6 +618,40 @@ public interface ImmutableConfiguration
Long getLong(String key, Long defaultValue);
/**
+ * Gets a list of properties associated with the given configuration key.
This method
+ * expects the given key to have an arbitrary number of String values,
each of which
+ * is of the form {@code key=value}. These strings are split at the equals
sign, and
+ * the key parts will become keys of the returned {@code Properties}
object, the value
+ * parts become values.
+ *
+ * @param key The configuration key.
+ * @return The associated properties if key is found.
+ * @throws org.apache.commons.configuration2.ex.ConversionException is
thrown if the
+ * key maps to an object that is not a String/List.
+ * @throws IllegalArgumentException if one of the tokens is malformed
(does not contain
+ * an equals sign).
+ */
+ Properties getProperties(String key);
+
+ /**
+ * Gets a property from the configuration. This is the most basic get
+ * method for retrieving values of properties. In a typical implementation
+ * of the {@code Configuration} interface the other get methods (that
+ * return specific data types) will internally make use of this method. On
+ * this level variable substitution is not yet performed. The returned
+ * object is an internal representation of the property value for the
passed
+ * in key. It is owned by the {@code Configuration} object. So a caller
+ * should not modify this object. It cannot be guaranteed that this object
+ * will stay constant over time (i.e. further update operations on the
+ * configuration may change its internal state).
+ *
+ * @param key property to retrieve
+ * @return the value to which this configuration maps the specified key, or
+ * null if the configuration contains no mapping for this key.
+ */
+ Object getProperty(String key);
+
+ /**
* Gets a short associated with the given configuration key.
*
* @param key The configuration key.
@@ -395,49 +690,6 @@ public interface ImmutableConfiguration
Short getShort(String key, Short defaultValue);
/**
- * Gets a {@link BigDecimal} associated with the given configuration key.
- *
- * @param key The configuration key.
- * @return The associated BigDecimal if key is found and has valid format
- */
- BigDecimal getBigDecimal(String key);
-
- /**
- * Gets a {@link BigDecimal} associated with the given configuration key.
- * If the key doesn't map to an existing object, the default value
- * is returned.
- *
- * @param key The configuration key.
- * @param defaultValue The default value.
- *
- * @return The associated BigDecimal if key is found and has valid
- * format, default value otherwise.
- */
- BigDecimal getBigDecimal(String key, BigDecimal defaultValue);
-
- /**
- * Gets a {@link BigInteger} associated with the given configuration key.
- *
- * @param key The configuration key.
- *
- * @return The associated BigInteger if key is found and has valid format
- */
- BigInteger getBigInteger(String key);
-
- /**
- * Gets a {@link BigInteger} associated with the given configuration key.
- * If the key doesn't map to an existing object, the default value
- * is returned.
- *
- * @param key The configuration key.
- * @param defaultValue The default value.
- *
- * @return The associated BigInteger if key is found and has valid
- * format, default value otherwise.
- */
- BigInteger getBigInteger(String key, BigInteger defaultValue);
-
- /**
* Gets a string associated with the given configuration key.
*
* @param key The configuration key.
@@ -464,82 +716,6 @@ public interface ImmutableConfiguration
String getString(String key, String defaultValue);
/**
- * Gets the value of a string property that is stored in encoded form in
this
- * configuration. This method obtains the value of the string property
- * identified by the given key. This value is then passed to the provided
- * {@code ConfigurationDecoder}. The value returned by the
- * {@code ConfigurationDecoder} is passed to the caller. If the key is not
- * associated with a value, the decoder is not invoked; depending on this
- * configuration's settings either <b>null</b> is returned or an exception
- * is thrown.
- *
- * @param key the configuration key
- * @param decoder the {@code ConfigurationDecoder} (must not be
<b>null</b>)
- * @return the plain string value of the specified encoded property
- * @throws IllegalArgumentException if a <b>null</b> decoder is passed
- */
- String getEncodedString(String key, ConfigurationDecoder decoder);
-
- /**
- * Gets the value of a string property that is stored in encoded form in
this
- * configuration using a default {@code ConfigurationDecoder}. This method
- * works like the method with the same name, but it uses a default
- * {@code ConfigurationDecoder} associated with this configuration. It
- * depends on a specific implementation how this default decoder is
- * obtained.
- *
- * @param key the configuration key
- * @return the plain string value of the specified encoded property
- */
- String getEncodedString(String key);
-
- /**
- * Gets an enum associated with the given configuration key.
- *
- * @param <T> The enum type whose constant is to be returned.
- * @param enumType the {@code Class} object of the enum type from which to
return a constant
- * @param key The configuration key.
- * @return The associated enum.
- *
- * @throws org.apache.commons.configuration2.ex.ConversionException is
thrown if the key maps to an object that
- * is not a String.
- * @since 2.8
- */
- default <T extends Enum<T>> T getEnum(String key, Class<T> enumType) {
- try {
- return Enum.valueOf(enumType, getString(key));
- } catch (IllegalArgumentException e) {
- throw new ConversionException(e);
- }
- }
-
- /**
- * Gets the enum associated with the given configuration key. If the key
doesn't map to an existing object, the
- * default value is returned.
- *
- * @param <T> The enum type whose constant is to be returned.
- * @param key The configuration key.
- * @param enumType the {@code Class} object of the enum type from which to
return a constant
- * @param defaultValue The default value.
- * @return The associated enum if key is found and has valid format,
default value otherwise.
- *
- * @throws org.apache.commons.configuration2.ex.ConversionException is
thrown if the key maps to an object that is
- * not a Enum.
- * @since 2.8
- */
- default <T extends Enum<T>> T getEnum(String key, Class<T> enumType, T
defaultValue) {
- final String strValue = getString(key, null);
- if (strValue == null) {
- return defaultValue;
- }
- try {
- return Enum.valueOf(enumType, strValue);
- } catch (IllegalArgumentException e) {
- throw new ConversionException(e);
- }
- }
-
- /**
* Gets 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
*
@@ -552,201 +728,6 @@ public interface ImmutableConfiguration
String[] getStringArray(String key);
/**
- * Gets a List of the values associated with the given configuration key.
- * This method is different from the generic {@code getList()} method in
- * that it does not recursively obtain all values stored for the specified
- * property key. Rather, only the first level of the hierarchy is
processed.
- * So the resulting list may contain complex objects like arrays or
- * collections - depending on the storage structure used by a concrete
- * subclass. If the key doesn't map to an existing object, an empty List is
- * returned.
- *
- * @param key The configuration key.
- * @return The associated List.
- *
- * @throws org.apache.commons.configuration2.ex.ConversionException is
thrown if the key maps to an
- * object that is not a List.
- */
- List<Object> getList(String key);
-
- /**
- * Gets a List of strings associated with the given configuration key.
- * If the key doesn't map to an existing object, the default value
- * is returned.
- *
- * @param key The configuration key.
- * @param defaultValue The default value.
- * @return The associated List of strings.
- *
- * @throws org.apache.commons.configuration2.ex.ConversionException is
thrown if the key maps to an
- * object that is not a List.
- * @see #getList(Class, String, List)
- */
- List<Object> getList(String key, List<?> defaultValue);
-
- /**
- * Gets an object of the specified type associated with the given
- * configuration key. If the key doesn't map to an existing object, the
- * method returns null unless
- * {@link AbstractConfiguration#isThrowExceptionOnMissing()} is set to
- * {@code true}.
- *
- * @param <T> the target type of the value
- * @param cls the target class of the value
- * @param key the key of the value
- * @return the value of the requested type for the key
- * @throws java.util.NoSuchElementException if the key doesn't map to an
existing
- * object and {@code throwExceptionOnMissing=true}
- * @throws org.apache.commons.configuration2.ex.ConversionException if the
value is not compatible with the
- * requested type
- * @since 2.0
- */
- <T> T get(Class<T> cls, String key);
-
- /**
- * Gets an object of the specified type associated with the given
- * configuration key using a default value. If the key doesn't map to an
- * existing object, the default value is returned.
- *
- * @param <T> the target type of the value
- * @param cls the target class of the value
- * @param key the key of the value
- * @param defaultValue the default value
- *
- * @return the value of the requested type for the key
- *
- * @throws org.apache.commons.configuration2.ex.ConversionException if the
value is not
- * compatible with the requested type
- *
- * @since 2.0
- */
- <T> T get(Class<T> cls, String key, T defaultValue);
-
- /**
- * Gets an array of typed objects associated with the given configuration
key.
- * If the key doesn't map to an existing object, an empty list is returned.
- *
- * @param cls the type expected for the elements of the array
- * @param key The configuration key.
- * @return The associated array if the key is found, and the value
compatible with the type specified.
- *
- * @throws org.apache.commons.configuration2.ex.ConversionException is
thrown if the key maps to an object that
- * is not compatible with a list of the specified class.
- *
- * @since 2.0
- */
- Object getArray(Class<?> cls, String key);
-
- /**
- * Gets an array of typed objects associated with the given configuration
key.
- * If the key doesn't map to an existing object, the default value is
returned.
- *
- * @param cls the type expected for the elements of the array
- * @param key the configuration key.
- * @param defaultValue the default value
- * @return The associated array if the key is found, and the value
compatible with the type specified.
- *
- * @throws org.apache.commons.configuration2.ex.ConversionException is
thrown if the key maps to an object that
- * is not compatible with an array of the specified class.
- * @throws IllegalArgumentException if the default value is not an array
of the specified type
- *
- * @since 2.0
- * @deprecated This method should not be used any more because its
signature
- * does not allow type-safe invocations; use {@link #get(Class, String,
Object)}
- * instead which offers the same functionality; for instance, to query for
an
- * array of ints use
- * {@code int[] result = config.get(int[].class, "myArrayKey",
someDefault);}.
- */
- @Deprecated
- Object getArray(Class<?> cls, String key, Object defaultValue);
-
- /**
- * Gets a list of typed objects associated with the given configuration key
- * returning an empty list if the key doesn't map to an existing object.
- *
- * @param <T> the type expected for the elements of the list
- * @param cls the class expected for the elements of the list
- * @param key The configuration key.
- * @return The associated list if the key is found.
- *
- * @throws org.apache.commons.configuration2.ex.ConversionException is
thrown if the key maps to an object that
- * is not compatible with a list of the specified class.
- *
- * @since 2.0
- */
- <T> List<T> getList(Class<T> cls, String key);
-
- /**
- * Gets a list of typed objects associated with the given configuration key
- * returning the specified default value if the key doesn't map to an
- * existing object. This method recursively retrieves all values stored
- * for the passed in key, i.e. if one of these values is again a complex
- * object like an array or a collection (which may be the case for some
- * concrete subclasses), all values are extracted and added to the
- * resulting list - performing a type conversion if necessary.
- *
- * @param <T> the type expected for the elements of the list
- * @param cls the class expected for the elements of the list
- * @param key the configuration key.
- * @param defaultValue the default value.
- * @return The associated List.
- *
- * @throws org.apache.commons.configuration2.ex.ConversionException is
thrown if the key maps to an object that
- * is not compatible with a list of the specified class.
- *
- * @since 2.0
- */
- <T> List<T> getList(Class<T> cls, String key, List<T> defaultValue);
-
- /**
- * Gets a collection of typed objects associated with the given
configuration
- * key. This method works like
- * {@link #getCollection(Class, String, Collection, Collection)} passing in
- * <b>null</b> as default value.
- *
- * @param <T> the element type of the result list
- * @param cls the the element class of the result list
- * @param key the configuration key
- * @param target the target collection (may be <b>null</b>)
- * @return the collection to which data was added
- * @throws org.apache.commons.configuration2.ex.ConversionException if the
conversion is not possible
- * @since 2.0
- */
- <T> Collection<T> getCollection(Class<T> cls, String key,
- Collection<T> target);
-
- /**
- * Gets a collection of typed objects associated with the given
configuration
- * key using the values in the specified default collection if the key does
- * not map to an existing object. This method is similar to
- * {@code getList()}, however, it allows specifying a target collection.
- * Results are added to this collection. This is useful if the data
- * retrieved should be added to a specific kind of collection, e.g. a set
to
- * remove duplicates. The return value is as follows:
- * <ul>
- * <li>If the key does not map to an existing object and the default value
- * is <b>null</b>, the method returns <b>null</b>.</li>
- * <li>If the target collection is not <b>null</b> and data has been added
- * (either from the resolved property value or from the default
collection),
- * the target collection is returned.</li>
- * <li>If the target collection is <b>null</b> and data has been added
- * (either from the resolved property value or from the default
collection),
- * return value is the target collection created by this method.</li>
- * </ul>
- *
- * @param <T> the element type of the result list
- * @param cls the the element class of the result list
- * @param key the configuration key
- * @param target the target collection (may be <b>null</b>)
- * @param defaultValue the default value (may be <b>null</b>)
- * @return the collection to which data was added
- * @throws org.apache.commons.configuration2.ex.ConversionException if the
conversion is not possible
- * @since 2.0
- */
- <T> Collection<T> getCollection(Class<T> cls, String key,
- Collection<T> target, Collection<T> defaultValue);
-
- /**
* Return a decorator immutable Configuration containing every key from
the current
* Configuration that starts with the specified prefix. The prefix is
* removed from the keys in the subset. For example, if the configuration
@@ -773,5 +754,24 @@ public interface ImmutableConfiguration
*/
ImmutableConfiguration immutableSubset(String prefix);
+ /**
+ * Checks if the configuration is empty.
+ *
+ * @return {@code true} if the configuration contains no property,
+ * {@code false} otherwise.
+ */
+ boolean isEmpty();
+
+ /**
+ * Returns the number of keys stored in this configuration. Note that a
+ * concrete implementation is not guaranteed to be efficient; for some
+ * implementations it may be expensive to determine the size. Especially,
if
+ * you just want to check whether a configuration is empty, it is
preferable
+ * to use the {@link #isEmpty()} method.
+ *
+ * @return the number of keys stored in this configuration
+ */
+ int size();
+
}
