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
commit aeba79ef834e98ae09b8723f4960ae590746a931
Author: Gary Gregory <garydgreg...@gmail.com>
AuthorDate: Sun Mar 17 08:13:16 2024 -0400
Sort interface members
Sort enum members
---
.../commons/configuration2/Configuration.java | 104 +++++++++---------
.../configuration2/HierarchicalConfiguration.java | 90 ++++++++--------
.../ImmutableHierarchicalConfiguration.java | 42 ++++----
.../beanutils/BeanCreationContext.java | 18 ++--
.../configuration2/beanutils/BeanDeclaration.java | 34 +++---
.../builder/BasicBuilderProperties.java | 118 ++++++++++-----------
.../builder/DatabaseBuilderProperties.java | 56 +++++-----
.../builder/PropertiesBuilderProperties.java | 18 ++--
.../builder/XMLBuilderProperties.java | 16 +--
.../combined/CombinedBuilderProperties.java | 76 ++++++-------
.../convert/ListDelimiterHandler.java | 36 +++----
.../configuration2/io/FileHandlerListener.java | 20 ++--
.../configuration2/resolver/EntityRegistry.java | 14 +--
.../configuration2/sync/NoOpSynchronizer.java | 4 +-
.../commons/configuration2/sync/Synchronizer.java | 12 +--
.../configuration2/sync/SynchronizerSupport.java | 18 ++--
.../tree/ConfigurationNodeVisitor.java | 20 ++--
.../configuration2/tree/ExpressionEngine.java | 56 +++++-----
.../commons/configuration2/tree/NodeHandler.java | 108 +++++++++----------
.../configuration2/tree/NodeKeyResolver.java | 50 ++++-----
.../commons/configuration2/tree/NodeModel.java | 76 ++++++-------
21 files changed, 493 insertions(+), 493 deletions(-)
diff --git a/src/main/java/org/apache/commons/configuration2/Configuration.java
b/src/main/java/org/apache/commons/configuration2/Configuration.java
index 32f3b1ca..76e4fe11 100644
--- a/src/main/java/org/apache/commons/configuration2/Configuration.java
+++ b/src/main/java/org/apache/commons/configuration2/Configuration.java
@@ -52,38 +52,6 @@ import
org.apache.commons.configuration2.sync.SynchronizerSupport;
* </p>
*/
public interface Configuration extends ImmutableConfiguration,
SynchronizerSupport {
- /**
- * Return a decorator 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 contains the following
- * properties:
- *
- * <pre>
- * prefix.number = 1
- * prefix.string = Apache
- * prefixed.foo = bar
- * prefix = Jakarta
- * </pre>
- *
- * the Configuration returned by {@code subset("prefix")} will contain the
properties:
- *
- * <pre>
- * number = 1
- * string = Apache
- * = Jakarta
- * </pre>
- *
- * (The key for the value "Jakarta" is an empty string)
- * <p>
- * Since the subset is a decorator and not a modified copy of the initial
Configuration, any change made to the subset
- * is available to the Configuration, and reciprocally.
- *
- * @param prefix The prefix used to select the properties.
- * @return a subset configuration
- *
- * @see SubsetConfiguration
- */
- Configuration subset(String prefix);
-
/**
* Add a property to the configuration. If it already exists then the
value stated here will be added to the
* configuration entry. For example, if the property:
@@ -110,13 +78,9 @@ public interface Configuration extends
ImmutableConfiguration, SynchronizerSuppo
void addProperty(String key, Object value);
/**
- * Sets a property, this will replace any previously set values. Set
values is implicitly a call to clearProperty(key),
- * addProperty(key, value).
- *
- * @param key The key of the property to change
- * @param value The new value
+ * Remove all properties from the configuration.
*/
- void setProperty(String key, Object value);
+ void clear();
/**
* Remove a property from the configuration.
@@ -125,11 +89,6 @@ public interface Configuration extends
ImmutableConfiguration, SynchronizerSuppo
*/
void clearProperty(String key);
- /**
- * Remove all properties from the configuration.
- */
- void clear();
-
/**
* Gets the {@code ConfigurationInterpolator} object used by this {@code
Configuration}. This object is responsible
* for variable substitution.
@@ -138,15 +97,6 @@ public interface Configuration extends
ImmutableConfiguration, SynchronizerSuppo
*/
ConfigurationInterpolator getInterpolator();
- /**
- * Sets the {@code ConfigurationInterpolator} object to be used by this
{@code Configuration}. This object is invoked
- * for each access of a string property in order to substitute variables
which may be contained. The argument can be
- * <b>null</b> to disable interpolation at all.
- *
- * @param ci the new {@code ConfigurationInterpolator}
- */
- void setInterpolator(ConfigurationInterpolator ci);
-
/**
* Creates and installs a new {@code ConfigurationInterpolator} for this
{@code Configuration} based on the passed in
* arguments. This method creates a default {@code
ConfigurationInterpolator} instance and initializes it with the
@@ -160,4 +110,54 @@ public interface Configuration extends
ImmutableConfiguration, SynchronizerSuppo
* @see ConfigurationInterpolator
*/
void installInterpolator(Map<String, ? extends Lookup> prefixLookups,
Collection<? extends Lookup> defLookups);
+
+ /**
+ * Sets the {@code ConfigurationInterpolator} object to be used by this
{@code Configuration}. This object is invoked
+ * for each access of a string property in order to substitute variables
which may be contained. The argument can be
+ * <b>null</b> to disable interpolation at all.
+ *
+ * @param ci the new {@code ConfigurationInterpolator}
+ */
+ void setInterpolator(ConfigurationInterpolator ci);
+
+ /**
+ * Sets a property, this will replace any previously set values. Set
values is implicitly a call to clearProperty(key),
+ * addProperty(key, value).
+ *
+ * @param key The key of the property to change
+ * @param value The new value
+ */
+ void setProperty(String key, Object value);
+
+ /**
+ * Return a decorator 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 contains the following
+ * properties:
+ *
+ * <pre>
+ * prefix.number = 1
+ * prefix.string = Apache
+ * prefixed.foo = bar
+ * prefix = Jakarta
+ * </pre>
+ *
+ * the Configuration returned by {@code subset("prefix")} will contain the
properties:
+ *
+ * <pre>
+ * number = 1
+ * string = Apache
+ * = Jakarta
+ * </pre>
+ *
+ * (The key for the value "Jakarta" is an empty string)
+ * <p>
+ * Since the subset is a decorator and not a modified copy of the initial
Configuration, any change made to the subset
+ * is available to the Configuration, and reciprocally.
+ *
+ * @param prefix The prefix used to select the properties.
+ * @return a subset configuration
+ *
+ * @see SubsetConfiguration
+ */
+ Configuration subset(String prefix);
}
diff --git
a/src/main/java/org/apache/commons/configuration2/HierarchicalConfiguration.java
b/src/main/java/org/apache/commons/configuration2/HierarchicalConfiguration.java
index bd015931..d4075e01 100644
---
a/src/main/java/org/apache/commons/configuration2/HierarchicalConfiguration.java
+++
b/src/main/java/org/apache/commons/configuration2/HierarchicalConfiguration.java
@@ -40,15 +40,6 @@ import
org.apache.commons.configuration2.tree.NodeModelSupport;
* @param <T> the type of the nodes used by this hierarchical configuration
*/
public interface HierarchicalConfiguration<T> extends Configuration,
ImmutableHierarchicalConfiguration, NodeModelSupport<T> {
- /**
- * Sets the expression engine to be used by this configuration. All
property keys this configuration has to deal with
- * will be interpreted by this engine.
- *
- * @param expressionEngine the new expression engine; can be <b>null</b>,
then the default expression engine will be
- * used
- */
- void setExpressionEngine(ExpressionEngine expressionEngine);
-
/**
* Adds a collection of nodes at the specified position of the
configuration tree. This method works similar to
* {@code addProperty()}, but instead of a single property a whole
collection of nodes can be added - and thus complete
@@ -62,6 +53,46 @@ public interface HierarchicalConfiguration<T> extends
Configuration, ImmutableHi
*/
void addNodes(String key, Collection<? extends T> nodes);
+ /**
+ * Returns a list with sub configurations for all child nodes of the node
selected by the given key. This method works
+ * like {@link #immutableChildConfigurationsAt(String)}, but returns a
list with mutable configuration objects. The
+ * configuration objects returned are <strong>not</strong> connected to
the parent configuration.
+ *
+ * @param key the key for selecting the desired parent node
+ * @return a collection with {@code HierarchicalConfiguration} objects for
all child nodes of the selected parent node
+ */
+ List<HierarchicalConfiguration<T>> childConfigurationsAt(String key);
+
+ /**
+ * Returns a list with sub configurations for all child nodes of the node
selected by the given key allowing the caller
+ * to specify the {@code supportUpdates} flag.
+ *
+ * @param key the key for selecting the desired parent node
+ * @param supportUpdates a flag whether the returned sub configuration
should be directly connected to its parent
+ * @return a collection with {@code HierarchicalConfiguration} objects for
all child nodes of the selected parent node
+ */
+ List<HierarchicalConfiguration<T>> childConfigurationsAt(String key,
boolean supportUpdates);
+
+ /**
+ * Removes all values of the property with the given name and of keys that
start with this name. So if there is a
+ * property with the key "foo" and a property with the key
"foo.bar", a call of
+ * {@code clearTree("foo")} would remove both properties.
+ *
+ * @param key the key of the property to be removed
+ */
+ void clearTree(String key);
+
+ /**
+ * Returns a hierarchical subnode configuration for the node specified by
the given key. This is a short form for
+ * {@code configurationAt(key,
+ * <b>false</b>)}.
+ *
+ * @param key the key that selects the sub tree
+ * @return a hierarchical configuration that contains this sub tree
+ * @see SubnodeConfiguration
+ */
+ HierarchicalConfiguration<T> configurationAt(String key);
+
/**
* <p>
* Returns a hierarchical sub configuration object that wraps the
configuration node specified by the given key. This
@@ -93,17 +124,6 @@ public interface HierarchicalConfiguration<T> extends
Configuration, ImmutableHi
*/
HierarchicalConfiguration<T> configurationAt(String key, boolean
supportUpdates);
- /**
- * Returns a hierarchical subnode configuration for the node specified by
the given key. This is a short form for
- * {@code configurationAt(key,
- * <b>false</b>)}.
- *
- * @param key the key that selects the sub tree
- * @return a hierarchical configuration that contains this sub tree
- * @see SubnodeConfiguration
- */
- HierarchicalConfiguration<T> configurationAt(String key);
-
/**
* Returns a list of sub configurations for all configuration nodes
selected by the given key. This method will evaluate
* the passed in key (using the current {@code ExpressionEngine}) and then
create a sub configuration for each returned
@@ -146,31 +166,11 @@ public interface HierarchicalConfiguration<T> extends
Configuration, ImmutableHi
List<HierarchicalConfiguration<T>> configurationsAt(String key, boolean
supportUpdates);
/**
- * Returns a list with sub configurations for all child nodes of the node
selected by the given key. This method works
- * like {@link #immutableChildConfigurationsAt(String)}, but returns a
list with mutable configuration objects. The
- * configuration objects returned are <strong>not</strong> connected to
the parent configuration.
- *
- * @param key the key for selecting the desired parent node
- * @return a collection with {@code HierarchicalConfiguration} objects for
all child nodes of the selected parent node
- */
- List<HierarchicalConfiguration<T>> childConfigurationsAt(String key);
-
- /**
- * Returns a list with sub configurations for all child nodes of the node
selected by the given key allowing the caller
- * to specify the {@code supportUpdates} flag.
- *
- * @param key the key for selecting the desired parent node
- * @param supportUpdates a flag whether the returned sub configuration
should be directly connected to its parent
- * @return a collection with {@code HierarchicalConfiguration} objects for
all child nodes of the selected parent node
- */
- List<HierarchicalConfiguration<T>> childConfigurationsAt(String key,
boolean supportUpdates);
-
- /**
- * Removes all values of the property with the given name and of keys that
start with this name. So if there is a
- * property with the key "foo" and a property with the key
"foo.bar", a call of
- * {@code clearTree("foo")} would remove both properties.
+ * Sets the expression engine to be used by this configuration. All
property keys this configuration has to deal with
+ * will be interpreted by this engine.
*
- * @param key the key of the property to be removed
+ * @param expressionEngine the new expression engine; can be <b>null</b>,
then the default expression engine will be
+ * used
*/
- void clearTree(String key);
+ void setExpressionEngine(ExpressionEngine expressionEngine);
}
diff --git
a/src/main/java/org/apache/commons/configuration2/ImmutableHierarchicalConfiguration.java
b/src/main/java/org/apache/commons/configuration2/ImmutableHierarchicalConfiguration.java
index cc265d3e..4c966b89 100644
---
a/src/main/java/org/apache/commons/configuration2/ImmutableHierarchicalConfiguration.java
+++
b/src/main/java/org/apache/commons/configuration2/ImmutableHierarchicalConfiguration.java
@@ -64,6 +64,27 @@ public interface ImmutableHierarchicalConfiguration extends
ImmutableConfigurati
*/
String getRootElementName();
+ /**
+ * Returns a list of immutable configurations for all direct child
elements of the node selected by the given key. With
+ * this method it is possible to inspect the content of a hierarchical
structure; all children of a given node can be
+ * queried without having to know their exact names. If the passed in key
does not point to a single node, an empty list
+ * is returned. This is also the result if the node referred to by the key
does not have child elements.
+ *
+ * @param key the key for selecting the desired parent node
+ * @return a collection with immutable configurations for all child nodes
of the selected parent node
+ */
+ List<ImmutableHierarchicalConfiguration>
immutableChildConfigurationsAt(String key);
+
+ /**
+ * Returns an immutable hierarchical configuration for the node specified
by the given key. This is a short form for
+ * {@code immutableConfigurationAt(key,
+ * <b>false</b>)}.
+ *
+ * @param key the key that selects the sub tree
+ * @return a hierarchical configuration that contains this sub tree
+ */
+ ImmutableHierarchicalConfiguration immutableConfigurationAt(String key);
+
/**
* <p>
* Returns an immutable hierarchical configuration object that wraps the
configuration node specified by the given key.
@@ -86,16 +107,6 @@ public interface ImmutableHierarchicalConfiguration extends
ImmutableConfigurati
*/
ImmutableHierarchicalConfiguration immutableConfigurationAt(String key,
boolean supportUpdates);
- /**
- * Returns an immutable hierarchical configuration for the node specified
by the given key. This is a short form for
- * {@code immutableConfigurationAt(key,
- * <b>false</b>)}.
- *
- * @param key the key that selects the sub tree
- * @return a hierarchical configuration that contains this sub tree
- */
- ImmutableHierarchicalConfiguration immutableConfigurationAt(String key);
-
/**
* Returns a list of immutable configurations for all configuration nodes
selected by the given key. This method will
* evaluate the passed in key (using the current {@code ExpressionEngine})
and then create an immutable subnode
@@ -122,15 +133,4 @@ public interface ImmutableHierarchicalConfiguration
extends ImmutableConfigurati
* selected by the passed in key
*/
List<ImmutableHierarchicalConfiguration> immutableConfigurationsAt(String
key);
-
- /**
- * Returns a list of immutable configurations for all direct child
elements of the node selected by the given key. With
- * this method it is possible to inspect the content of a hierarchical
structure; all children of a given node can be
- * queried without having to know their exact names. If the passed in key
does not point to a single node, an empty list
- * is returned. This is also the result if the node referred to by the key
does not have child elements.
- *
- * @param key the key for selecting the desired parent node
- * @return a collection with immutable configurations for all child nodes
of the selected parent node
- */
- List<ImmutableHierarchicalConfiguration>
immutableChildConfigurationsAt(String key);
}
diff --git
a/src/main/java/org/apache/commons/configuration2/beanutils/BeanCreationContext.java
b/src/main/java/org/apache/commons/configuration2/beanutils/BeanCreationContext.java
index b58a35d6..6f123179 100644
---
a/src/main/java/org/apache/commons/configuration2/beanutils/BeanCreationContext.java
+++
b/src/main/java/org/apache/commons/configuration2/beanutils/BeanCreationContext.java
@@ -30,6 +30,15 @@ package org.apache.commons.configuration2.beanutils;
*/
public interface BeanCreationContext {
+ /**
+ * Creates a bean based on the given {@code BeanDeclaration}. This method
can be used to create dependent beans needed
+ * for the initialization of the bean that is actually created.
+ *
+ * @param data the {@code BeanDeclaration} describing the bean
+ * @return the bean created based on this declaration
+ */
+ Object createBean(BeanDeclaration data);
+
/**
* Gets the class of the bean to be created.
*
@@ -60,13 +69,4 @@ public interface BeanCreationContext {
* @param data the {@code BeanDeclaration} with initialization data for
this bean
*/
void initBean(Object bean, BeanDeclaration data);
-
- /**
- * Creates a bean based on the given {@code BeanDeclaration}. This method
can be used to create dependent beans needed
- * for the initialization of the bean that is actually created.
- *
- * @param data the {@code BeanDeclaration} describing the bean
- * @return the bean created based on this declaration
- */
- Object createBean(BeanDeclaration data);
}
diff --git
a/src/main/java/org/apache/commons/configuration2/beanutils/BeanDeclaration.java
b/src/main/java/org/apache/commons/configuration2/beanutils/BeanDeclaration.java
index 6218b09d..9dfd3a96 100644
---
a/src/main/java/org/apache/commons/configuration2/beanutils/BeanDeclaration.java
+++
b/src/main/java/org/apache/commons/configuration2/beanutils/BeanDeclaration.java
@@ -41,6 +41,14 @@ import java.util.Map;
*/
public interface BeanDeclaration {
+ /**
+ * Gets the name of the bean class, from which an instance is to be
created. This value must be defined unless a
+ * default class is provided for the bean creation operation.
+ *
+ * @return the name of the bean class
+ */
+ String getBeanClassName();
+
/**
* Gets the name of the {@code BeanFactory} that should be used for
creating the bean instance. This can be
* <b>null</b>, then a default factory will be used.
@@ -58,14 +66,6 @@ public interface BeanDeclaration {
*/
Object getBeanFactoryParameter();
- /**
- * Gets the name of the bean class, from which an instance is to be
created. This value must be defined unless a
- * default class is provided for the bean creation operation.
- *
- * @return the name of the bean class
- */
- String getBeanClassName();
-
/**
* Gets a map with properties that should be initialized on the newly
created bean. The map's keys are the names of
* the properties; the corresponding values are the properties' values.
The return value can be <b>null</b> if no
@@ -75,6 +75,15 @@ public interface BeanDeclaration {
*/
Map<String, Object> getBeanProperties();
+ /**
+ * Gets a collection with constructor arguments. This data is used to
determine the constructor of the bean class to
+ * be invoked. The values of the arguments are passed to the constructor.
An implementation can return <b>null</b> or an
+ * empty collection; then the standard constructor of the bean class is
called.
+ *
+ * @return a collection with the arguments to be passed to the bean
class's constructor
+ */
+ Collection<ConstructorArg> getConstructorArgs();
+
/**
* Gets a map with declarations for beans that should be set as properties
of the newly created bean. This allows for
* complex initialization scenarios: a bean for a bean that contains
complex properties (e.g. other beans) can have
@@ -86,13 +95,4 @@ public interface BeanDeclaration {
* @return a map with nested bean declarations
*/
Map<String, Object> getNestedBeanDeclarations();
-
- /**
- * Gets a collection with constructor arguments. This data is used to
determine the constructor of the bean class to
- * be invoked. The values of the arguments are passed to the constructor.
An implementation can return <b>null</b> or an
- * empty collection; then the standard constructor of the bean class is
called.
- *
- * @return a collection with the arguments to be passed to the bean
class's constructor
- */
- Collection<ConstructorArg> getConstructorArgs();
}
diff --git
a/src/main/java/org/apache/commons/configuration2/builder/BasicBuilderProperties.java
b/src/main/java/org/apache/commons/configuration2/builder/BasicBuilderProperties.java
index 8de3d731..ac19e4e7 100644
---
a/src/main/java/org/apache/commons/configuration2/builder/BasicBuilderProperties.java
+++
b/src/main/java/org/apache/commons/configuration2/builder/BasicBuilderProperties.java
@@ -47,35 +47,50 @@ import org.apache.commons.configuration2.sync.Synchronizer;
*/
public interface BasicBuilderProperties<T> {
/**
- * Sets the <em>logger</em> property. With this property a concrete {@code
ConfigurationLogger} object can be set for
- * the configuration. Thus logging behavior can be controlled.
+ * Sets a {@code BeanHelper} object to be used by the configuration
builder. The {@code BeanHelper} is used to create
+ * the managed configuration instance dynamically. It is not a property of
the configuration as most other properties
+ * defined by this interface. By setting an alternative {@code BeanHelper}
the process of creating configuration
+ * instances via reflection can be adapted. (Some specialized
configuration builder implementations also use a
+ * {@code BeanHelper} to create complex helper objects during construction
of their result object.
+ * {@code CombinedConfigurationBuilder} for instance supports a complex
configuration definition format which may
+ * contain several specialized bean declarations.) If no specific {@code
BeanHelper} is set, the builder uses the
+ * default instance.
*
- * @param log the {@code Log} for the configuration produced by this
builder
+ * @param beanHelper the {@code BeanHelper} to be used by the builder
* @return a reference to this object for method chaining
*/
- T setLogger(ConfigurationLogger log);
+ T setBeanHelper(BeanHelper beanHelper);
/**
- * Sets the value of the <em>throwExceptionOnMissing</em> property. This
property controls the configuration's behavior
- * if missing properties are queried: a value of <b>true</b> causes the
configuration to throw an exception, for a value
- * of <b>false</b> it will return <b>null</b> values. (Note: Methods
returning a primitive data type will always throw
- * an exception if the property is not defined.)
+ * Sets the {@code ConfigurationDecoder} object for this configuration.
This object is called when encoded properties
+ * are queried using the {@code getEncodedString()} method.
*
- * @param b the value of the property
+ * @param decoder the {@code ConfigurationDecoder} to be used
* @return a reference to this object for method chaining
*/
- T setThrowExceptionOnMissing(boolean b);
+ T setConfigurationDecoder(ConfigurationDecoder decoder);
/**
- * Sets the value of the <em>listDelimiterHandler</em> property. This
property defines the object responsible for
- * dealing with list delimiter and escaping characters. Note:
- * {@link org.apache.commons.configuration2.AbstractConfiguration
AbstractConfiguration} does not allow setting this
- * property to <b>null</b>. If the default {@code ListDelimiterHandler} is
to be used, do not call this method.
+ * Sets the {@code ConversionHandler} object for this configuration. This
object is responsible for all data type
+ * conversions required for accessing configuration properties in a
specific target type. If this property is not set, a
+ * default {@code ConversionHandler} is used.
*
- * @param handler the {@code ListDelimiterHandler}
+ * @param handler the {@code ConversionHandler} to be used
* @return a reference to this object for method chaining
*/
- T setListDelimiterHandler(ListDelimiterHandler handler);
+ T setConversionHandler(ConversionHandler handler);
+
+ /**
+ * Adds additional default {@code Lookup} objects (i.e. lookups which are
not associated with a specific prefix) to this
+ * configuration object. Note: This method only takes effect if no {@code
ConfigurationInterpolator} is set using the
+ * {@link #setInterpolator(ConfigurationInterpolator)} method.
+ *
+ * @param lookups a collection with {@code Lookup} objects to be added as
default lookups at the configuration's
+ * {@code ConfigurationInterpolator}
+ * @return a reference to this object for method chaining
+ * @see ConfigurationInterpolator#addDefaultLookups(Collection)
+ */
+ T setDefaultLookups(Collection<? extends Lookup> lookups);
/**
* Sets the {@code ConfigurationInterpolator} to be used for this
configuration. Using this method a custom
@@ -88,28 +103,24 @@ public interface BasicBuilderProperties<T> {
T setInterpolator(ConfigurationInterpolator ci);
/**
- * Sets additional {@code Lookup} objects for specific prefixes for this
configuration object. All {@code Lookup}
- * objects contained in the given map are added to the configuration's
{@code ConfigurationInterpolator}. Note: This
- * method only takes effect if no {@code ConfigurationInterpolator} is set
using the
- * {@link #setInterpolator(ConfigurationInterpolator)} method.
+ * Sets the value of the <em>listDelimiterHandler</em> property. This
property defines the object responsible for
+ * dealing with list delimiter and escaping characters. Note:
+ * {@link org.apache.commons.configuration2.AbstractConfiguration
AbstractConfiguration} does not allow setting this
+ * property to <b>null</b>. If the default {@code ListDelimiterHandler} is
to be used, do not call this method.
*
- * @param lookups a map with {@code Lookup} objects and their associated
prefixes
+ * @param handler the {@code ListDelimiterHandler}
* @return a reference to this object for method chaining
- * @see ConfigurationInterpolator#registerLookups(Map)
*/
- T setPrefixLookups(Map<String, ? extends Lookup> lookups);
+ T setListDelimiterHandler(ListDelimiterHandler handler);
/**
- * Adds additional default {@code Lookup} objects (i.e. lookups which are
not associated with a specific prefix) to this
- * configuration object. Note: This method only takes effect if no {@code
ConfigurationInterpolator} is set using the
- * {@link #setInterpolator(ConfigurationInterpolator)} method.
+ * Sets the <em>logger</em> property. With this property a concrete {@code
ConfigurationLogger} object can be set for
+ * the configuration. Thus logging behavior can be controlled.
*
- * @param lookups a collection with {@code Lookup} objects to be added as
default lookups at the configuration's
- * {@code ConfigurationInterpolator}
+ * @param log the {@code Log} for the configuration produced by this
builder
* @return a reference to this object for method chaining
- * @see ConfigurationInterpolator#addDefaultLookups(Collection)
*/
- T setDefaultLookups(Collection<? extends Lookup> lookups);
+ T setLogger(ConfigurationLogger log);
/**
* Sets the parent {@code ConfigurationInterpolator} for this
configuration's {@code ConfigurationInterpolator}. Setting
@@ -122,6 +133,18 @@ public interface BasicBuilderProperties<T> {
*/
T setParentInterpolator(ConfigurationInterpolator parent);
+ /**
+ * Sets additional {@code Lookup} objects for specific prefixes for this
configuration object. All {@code Lookup}
+ * objects contained in the given map are added to the configuration's
{@code ConfigurationInterpolator}. Note: This
+ * method only takes effect if no {@code ConfigurationInterpolator} is set
using the
+ * {@link #setInterpolator(ConfigurationInterpolator)} method.
+ *
+ * @param lookups a map with {@code Lookup} objects and their associated
prefixes
+ * @return a reference to this object for method chaining
+ * @see ConfigurationInterpolator#registerLookups(Map)
+ */
+ T setPrefixLookups(Map<String, ? extends Lookup> lookups);
+
/**
* Sets the {@code Synchronizer} object for this configuration. This
object is used to protect this configuration
* instance against concurrent access. The concrete {@code Synchronizer}
implementation used determines whether a
@@ -134,36 +157,13 @@ public interface BasicBuilderProperties<T> {
T setSynchronizer(Synchronizer sync);
/**
- * Sets the {@code ConversionHandler} object for this configuration. This
object is responsible for all data type
- * conversions required for accessing configuration properties in a
specific target type. If this property is not set, a
- * default {@code ConversionHandler} is used.
- *
- * @param handler the {@code ConversionHandler} to be used
- * @return a reference to this object for method chaining
- */
- T setConversionHandler(ConversionHandler handler);
-
- /**
- * Sets the {@code ConfigurationDecoder} object for this configuration.
This object is called when encoded properties
- * are queried using the {@code getEncodedString()} method.
- *
- * @param decoder the {@code ConfigurationDecoder} to be used
- * @return a reference to this object for method chaining
- */
- T setConfigurationDecoder(ConfigurationDecoder decoder);
-
- /**
- * Sets a {@code BeanHelper} object to be used by the configuration
builder. The {@code BeanHelper} is used to create
- * the managed configuration instance dynamically. It is not a property of
the configuration as most other properties
- * defined by this interface. By setting an alternative {@code BeanHelper}
the process of creating configuration
- * instances via reflection can be adapted. (Some specialized
configuration builder implementations also use a
- * {@code BeanHelper} to create complex helper objects during construction
of their result object.
- * {@code CombinedConfigurationBuilder} for instance supports a complex
configuration definition format which may
- * contain several specialized bean declarations.) If no specific {@code
BeanHelper} is set, the builder uses the
- * default instance.
+ * Sets the value of the <em>throwExceptionOnMissing</em> property. This
property controls the configuration's behavior
+ * if missing properties are queried: a value of <b>true</b> causes the
configuration to throw an exception, for a value
+ * of <b>false</b> it will return <b>null</b> values. (Note: Methods
returning a primitive data type will always throw
+ * an exception if the property is not defined.)
*
- * @param beanHelper the {@code BeanHelper} to be used by the builder
+ * @param b the value of the property
* @return a reference to this object for method chaining
*/
- T setBeanHelper(BeanHelper beanHelper);
+ T setThrowExceptionOnMissing(boolean b);
}
diff --git
a/src/main/java/org/apache/commons/configuration2/builder/DatabaseBuilderProperties.java
b/src/main/java/org/apache/commons/configuration2/builder/DatabaseBuilderProperties.java
index 18b23190..e9318698 100644
---
a/src/main/java/org/apache/commons/configuration2/builder/DatabaseBuilderProperties.java
+++
b/src/main/java/org/apache/commons/configuration2/builder/DatabaseBuilderProperties.java
@@ -37,65 +37,65 @@ import javax.sql.DataSource;
*/
public interface DatabaseBuilderProperties<T> {
/**
- * Sets the data source for the database configuration. All database
connections are obtained from this data source.
- * This is a mandatory property.
+ * Enables or disable auto commit mode. If enabled, the database
configuration instance performs a commit after each
+ * database update.
*
- * @param src the data source for the database configuration
+ * @param f the value of the auto commit flag
* @return a reference to this object for method chaining
*/
- T setDataSource(DataSource src);
+ T setAutoCommit(boolean f);
/**
- * Sets the name of the table containing configuration data. Database
configuration will access this database table.
- * This is a mandatory property.
+ * Sets the name of this configuration instance. This property is needed
if a single database table contains the data of
+ * multiple configuration instances. Then SQL statements generated by the
configuration contain an additional constraint
+ * filtering the configuration name column for this name.
*
- * @param name the name of the table with configuration data
+ * @param name the name of this configuration instance
* @return a reference to this object for method chaining
*/
- T setTable(String name);
+ T setConfigurationName(String name);
/**
- * Sets the name of the table column containing configuration keys. This
is a mandatory property.
+ * Sets the name of the table column containing the configuration name.
This property is needed if a single database
+ * table contains the data of multiple configuration instances. Then this
column is used as discriminator to select a
+ * specific configuration instance.
*
* @param name the column name
- * @return a reference to this object for method chaining
+ * @return a reference to this method for method chaining
*/
- T setKeyColumn(String name);
+ T setConfigurationNameColumn(String name);
/**
- * Sets the name of the table column containing the configuration property
value. This is a mandatory property.
+ * Sets the data source for the database configuration. All database
connections are obtained from this data source.
+ * This is a mandatory property.
*
- * @param name the column name
+ * @param src the data source for the database configuration
* @return a reference to this object for method chaining
*/
- T setValueColumn(String name);
+ T setDataSource(DataSource src);
/**
- * Sets the name of the table column containing the configuration name.
This property is needed if a single database
- * table contains the data of multiple configuration instances. Then this
column is used as discriminator to select a
- * specific configuration instance.
+ * Sets the name of the table column containing configuration keys. This
is a mandatory property.
*
* @param name the column name
- * @return a reference to this method for method chaining
+ * @return a reference to this object for method chaining
*/
- T setConfigurationNameColumn(String name);
+ T setKeyColumn(String name);
/**
- * Sets the name of this configuration instance. This property is needed
if a single database table contains the data of
- * multiple configuration instances. Then SQL statements generated by the
configuration contain an additional constraint
- * filtering the configuration name column for this name.
+ * Sets the name of the table containing configuration data. Database
configuration will access this database table.
+ * This is a mandatory property.
*
- * @param name the name of this configuration instance
+ * @param name the name of the table with configuration data
* @return a reference to this object for method chaining
*/
- T setConfigurationName(String name);
+ T setTable(String name);
/**
- * Enables or disable auto commit mode. If enabled, the database
configuration instance performs a commit after each
- * database update.
+ * Sets the name of the table column containing the configuration property
value. This is a mandatory property.
*
- * @param f the value of the auto commit flag
+ * @param name the column name
* @return a reference to this object for method chaining
*/
- T setAutoCommit(boolean f);
+ T setValueColumn(String name);
}
diff --git
a/src/main/java/org/apache/commons/configuration2/builder/PropertiesBuilderProperties.java
b/src/main/java/org/apache/commons/configuration2/builder/PropertiesBuilderProperties.java
index a39df09e..b79ab4d3 100644
---
a/src/main/java/org/apache/commons/configuration2/builder/PropertiesBuilderProperties.java
+++
b/src/main/java/org/apache/commons/configuration2/builder/PropertiesBuilderProperties.java
@@ -58,15 +58,6 @@ public interface PropertiesBuilderProperties<T> {
*/
T setIncludesAllowed(boolean f);
- /**
- * Sets the layout object for the properties configuration object. With
this method a custom layout object can be set.
- * If no layout is provided, the configuration will use a default layout.
- *
- * @param layout the {@code PropertiesConfigurationLayout} object to be
used by the configuration
- * @return a reference to this object for method chaining
- */
- T setLayout(PropertiesConfigurationLayout layout);
-
/**
* Sets the {@code IOFactory} to be used by the properties configuration
object. With this method a custom factory for
* input and output streams can be set. This allows customizing the format
of properties read or written by the
@@ -76,4 +67,13 @@ public interface PropertiesBuilderProperties<T> {
* @return a reference to this object for method chaining
*/
T setIOFactory(IOFactory factory);
+
+ /**
+ * Sets the layout object for the properties configuration object. With
this method a custom layout object can be set.
+ * If no layout is provided, the configuration will use a default layout.
+ *
+ * @param layout the {@code PropertiesConfigurationLayout} object to be
used by the configuration
+ * @return a reference to this object for method chaining
+ */
+ T setLayout(PropertiesConfigurationLayout layout);
}
diff --git
a/src/main/java/org/apache/commons/configuration2/builder/XMLBuilderProperties.java
b/src/main/java/org/apache/commons/configuration2/builder/XMLBuilderProperties.java
index 63e95323..a7bf4850 100644
---
a/src/main/java/org/apache/commons/configuration2/builder/XMLBuilderProperties.java
+++
b/src/main/java/org/apache/commons/configuration2/builder/XMLBuilderProperties.java
@@ -61,6 +61,14 @@ public interface XMLBuilderProperties<T> {
*/
T setPublicID(String pubID);
+ /**
+ * Sets the value of the schemaValidation flag. This flag determines
whether DTD or Schema validation should be used.
+ *
+ * @param f the flag value, <b>true</b> for schema validation,
<b>false</b> for DTD validation
+ * @return a reference to this object for method chaining
+ */
+ T setSchemaValidation(boolean f);
+
/**
* Sets the system ID of the DOCTYPE declaration.
*
@@ -76,12 +84,4 @@ public interface XMLBuilderProperties<T> {
* @return a reference to this object for method chaining
*/
T setValidating(boolean f);
-
- /**
- * Sets the value of the schemaValidation flag. This flag determines
whether DTD or Schema validation should be used.
- *
- * @param f the flag value, <b>true</b> for schema validation,
<b>false</b> for DTD validation
- * @return a reference to this object for method chaining
- */
- T setSchemaValidation(boolean f);
}
diff --git
a/src/main/java/org/apache/commons/configuration2/builder/combined/CombinedBuilderProperties.java
b/src/main/java/org/apache/commons/configuration2/builder/combined/CombinedBuilderProperties.java
index fd33ae41..a215f676 100644
---
a/src/main/java/org/apache/commons/configuration2/builder/combined/CombinedBuilderProperties.java
+++
b/src/main/java/org/apache/commons/configuration2/builder/combined/CombinedBuilderProperties.java
@@ -40,23 +40,33 @@ import
org.apache.commons.configuration2.builder.DefaultParametersManager;
*/
public interface CombinedBuilderProperties<T> {
/**
- * Sets a flag whether the child configurations created by a {@code
CombinedConfigurationBuilder} should inherit the
- * settings defined for the builder. This is typically useful because for
configurations coming from homogeneous sources
- * often similar conventions are used. Therefore, this flag is <b>true</b>
per default.
+ * Registers a {@code DefaultParametersHandler} for child configuration
sources. With this method an arbitrary number of
+ * handler objects can be set. When creating builders for child
configuration sources their parameters are initialized
+ * by invoking all matching {@code DefaultParametersHandler}s on them. So,
basically the same mechanism is used for the
+ * initialization of parameters for child configuration sources as for
normal parameter objects.
*
- * @param f the flag whether settings should be inherited by child
configurations
+ * @param <D> the type of the handler to be registered
+ * @param paramClass the parameter class supported by the handler
+ * @param handler the {@code DefaultParametersHandler} to be registered
* @return a reference to this object for method chaining
+ * @see DefaultParametersManager#registerDefaultsHandler(Class,
DefaultParametersHandler)
*/
- T setInheritSettings(boolean f);
+ <D> T registerChildDefaultsHandler(Class<D> paramClass,
DefaultParametersHandler<? super D> handler);
/**
- * Sets the {@code ConfigurationBuilder} for the definition configuration.
This is the configuration which contains the
- * configuration sources that form the combined configuration.
+ * Registers a {@code DefaultParametersHandler} for child configuration
sources derived from the given start class. This
+ * method works like the overloaded variant, but limits the application of
the defaults handler to specific child
+ * configuration sources.
*
- * @param builder the definition {@code ConfigurationBuilder}
+ * @param <D> the type of the handler to be registered
+ * @param paramClass the parameter class supported by the handler
+ * @param handler the {@code DefaultParametersHandler} to be registered
+ * @param startClass an optional start class in the hierarchy of parameter
objects for which this handler should be
+ * applied
* @return a reference to this object for method chaining
+ * @see DefaultParametersManager#registerDefaultsHandler(Class,
DefaultParametersHandler, Class)
*/
- T setDefinitionBuilder(ConfigurationBuilder<? extends
HierarchicalConfiguration<?>> builder);
+ <D> T registerChildDefaultsHandler(Class<D> paramClass,
DefaultParametersHandler<? super D> handler, Class<?> startClass);
/**
* Registers the given {@code ConfigurationBuilderProvider} for the
specified tag name. This means that whenever this
@@ -80,16 +90,6 @@ public interface CombinedBuilderProperties<T> {
*/
T setBasePath(String path);
- /**
- * Sets the parameters object for the definition configuration builder.
This property is evaluated only if the
- * definition configuration builder is not set explicitly (using the
{@link #setDefinitionBuilder(ConfigurationBuilder)}
- * method). In this case, a builder for an XML configuration is created
and configured with this parameters object.
- *
- * @param params the parameters object for the definition configuration
builder
- * @return a reference to this object for method chaining
- */
- T setDefinitionBuilderParameters(BuilderParameters params);
-
/**
* Sets a {@code DefaultParametersManager} object responsible for managing
the default parameter handlers to be applied
* on child configuration sources. When creating builders for child
configuration sources their parameters are
@@ -106,31 +106,31 @@ public interface CombinedBuilderProperties<T> {
T setChildDefaultParametersManager(DefaultParametersManager manager);
/**
- * Registers a {@code DefaultParametersHandler} for child configuration
sources. With this method an arbitrary number of
- * handler objects can be set. When creating builders for child
configuration sources their parameters are initialized
- * by invoking all matching {@code DefaultParametersHandler}s on them. So,
basically the same mechanism is used for the
- * initialization of parameters for child configuration sources as for
normal parameter objects.
+ * Sets the {@code ConfigurationBuilder} for the definition configuration.
This is the configuration which contains the
+ * configuration sources that form the combined configuration.
*
- * @param <D> the type of the handler to be registered
- * @param paramClass the parameter class supported by the handler
- * @param handler the {@code DefaultParametersHandler} to be registered
+ * @param builder the definition {@code ConfigurationBuilder}
* @return a reference to this object for method chaining
- * @see DefaultParametersManager#registerDefaultsHandler(Class,
DefaultParametersHandler)
*/
- <D> T registerChildDefaultsHandler(Class<D> paramClass,
DefaultParametersHandler<? super D> handler);
+ T setDefinitionBuilder(ConfigurationBuilder<? extends
HierarchicalConfiguration<?>> builder);
/**
- * Registers a {@code DefaultParametersHandler} for child configuration
sources derived from the given start class. This
- * method works like the overloaded variant, but limits the application of
the defaults handler to specific child
- * configuration sources.
+ * Sets the parameters object for the definition configuration builder.
This property is evaluated only if the
+ * definition configuration builder is not set explicitly (using the
{@link #setDefinitionBuilder(ConfigurationBuilder)}
+ * method). In this case, a builder for an XML configuration is created
and configured with this parameters object.
*
- * @param <D> the type of the handler to be registered
- * @param paramClass the parameter class supported by the handler
- * @param handler the {@code DefaultParametersHandler} to be registered
- * @param startClass an optional start class in the hierarchy of parameter
objects for which this handler should be
- * applied
+ * @param params the parameters object for the definition configuration
builder
* @return a reference to this object for method chaining
- * @see DefaultParametersManager#registerDefaultsHandler(Class,
DefaultParametersHandler, Class)
*/
- <D> T registerChildDefaultsHandler(Class<D> paramClass,
DefaultParametersHandler<? super D> handler, Class<?> startClass);
+ T setDefinitionBuilderParameters(BuilderParameters params);
+
+ /**
+ * Sets a flag whether the child configurations created by a {@code
CombinedConfigurationBuilder} should inherit the
+ * settings defined for the builder. This is typically useful because for
configurations coming from homogeneous sources
+ * often similar conventions are used. Therefore, this flag is <b>true</b>
per default.
+ *
+ * @param f the flag whether settings should be inherited by child
configurations
+ * @return a reference to this object for method chaining
+ */
+ T setInheritSettings(boolean f);
}
diff --git
a/src/main/java/org/apache/commons/configuration2/convert/ListDelimiterHandler.java
b/src/main/java/org/apache/commons/configuration2/convert/ListDelimiterHandler.java
index fb194049..902e9cd3 100644
---
a/src/main/java/org/apache/commons/configuration2/convert/ListDelimiterHandler.java
+++
b/src/main/java/org/apache/commons/configuration2/convert/ListDelimiterHandler.java
@@ -81,6 +81,24 @@ public interface ListDelimiterHandler {
*/
Object escapeList(List<?> values, ValueTransformer transformer);
+ /**
+ * Extracts all values contained in the specified object up to the given
limit. The passed in object is evaluated (if
+ * necessary in a recursive way). If it is a complex object (e.g. a
collection or an array), all its elements are
+ * processed recursively and added to a target collection. The process
stops if the limit is reached, but depending on
+ * the input object, it might be exceeded. (The limit is just an indicator
to stop the process to avoid unnecessary work
+ * if the caller is only interested in a few values.)
+ *
+ * @param value the value to be processed
+ * @param limit the limit for aborting the processing
+ * @return a "flat" collection containing all primitive values
of the passed in object
+ * @since 2.9.0
+ */
+ default Collection<?> flatten(final Object value, final int limit) {
+ final Set<Object> dejaVu = Collections.newSetFromMap(new
IdentityHashMap<>());
+ dejaVu.add(value);
+ return AbstractListDelimiterHandler.flatten(this, value, limit,
dejaVu);
+ }
+
/**
* Parses the specified value for list delimiters and splits it if
necessary. The passed in object can be either a
* single value or a complex one, e.g. a collection, an array, or an
{@code Iterable}. It is the responsibility of this
@@ -104,22 +122,4 @@ public interface ListDelimiterHandler {
*/
Collection<String> split(String s, boolean trim);
- /**
- * Extracts all values contained in the specified object up to the given
limit. The passed in object is evaluated (if
- * necessary in a recursive way). If it is a complex object (e.g. a
collection or an array), all its elements are
- * processed recursively and added to a target collection. The process
stops if the limit is reached, but depending on
- * the input object, it might be exceeded. (The limit is just an indicator
to stop the process to avoid unnecessary work
- * if the caller is only interested in a few values.)
- *
- * @param value the value to be processed
- * @param limit the limit for aborting the processing
- * @return a "flat" collection containing all primitive values
of the passed in object
- * @since 2.9.0
- */
- default Collection<?> flatten(final Object value, final int limit) {
- final Set<Object> dejaVu = Collections.newSetFromMap(new
IdentityHashMap<>());
- dejaVu.add(value);
- return AbstractListDelimiterHandler.flatten(this, value, limit,
dejaVu);
- }
-
}
diff --git
a/src/main/java/org/apache/commons/configuration2/io/FileHandlerListener.java
b/src/main/java/org/apache/commons/configuration2/io/FileHandlerListener.java
index 9e2e2fb5..91ee3ab0 100644
---
a/src/main/java/org/apache/commons/configuration2/io/FileHandlerListener.java
+++
b/src/main/java/org/apache/commons/configuration2/io/FileHandlerListener.java
@@ -30,27 +30,26 @@ package org.apache.commons.configuration2.io;
*/
public interface FileHandlerListener {
/**
- * Notification that the associated file is about to be loaded. This
method is called immediately before the load
- * operation.
+ * Notification that the associated file has been loaded. This method is
called directly after the load operation.
*
* @param handler the file handler
*/
- void loading(FileHandler handler);
+ void loaded(FileHandler handler);
/**
- * Notification that the associated file has been loaded. This method is
called directly after the load operation.
+ * Notification that the associated file is about to be loaded. This
method is called immediately before the load
+ * operation.
*
* @param handler the file handler
*/
- void loaded(FileHandler handler);
+ void loading(FileHandler handler);
/**
- * Notification that the associated file is about to be saved. This method
is called immediately before the save
- * operation.
+ * Notification that a property of the monitored {@code FileHandler} has
changed.
*
* @param handler the file handler
*/
- void saving(FileHandler handler);
+ void locationChanged(FileHandler handler);
/**
* Notification that the associated file has been saved. This method is
called directly after the save operation.
@@ -60,9 +59,10 @@ public interface FileHandlerListener {
void saved(FileHandler handler);
/**
- * Notification that a property of the monitored {@code FileHandler} has
changed.
+ * Notification that the associated file is about to be saved. This method
is called immediately before the save
+ * operation.
*
* @param handler the file handler
*/
- void locationChanged(FileHandler handler);
+ void saving(FileHandler handler);
}
diff --git
a/src/main/java/org/apache/commons/configuration2/resolver/EntityRegistry.java
b/src/main/java/org/apache/commons/configuration2/resolver/EntityRegistry.java
index 16112557..f744acf4 100644
---
a/src/main/java/org/apache/commons/configuration2/resolver/EntityRegistry.java
+++
b/src/main/java/org/apache/commons/configuration2/resolver/EntityRegistry.java
@@ -25,6 +25,13 @@ import java.util.Map;
* @since 1.7
*/
public interface EntityRegistry {
+ /**
+ * Gets a map with the entity IDs that have been registered using the
{@code registerEntityId()} method.
+ *
+ * @return a map with the registered entity IDs
+ */
+ Map<String, URL> getRegisteredEntities();
+
/**
* <p>
* Registers the specified URL for the specified public identifier.
@@ -44,11 +51,4 @@ public interface EntityRegistry {
* @throws IllegalArgumentException if the public ID is undefined
*/
void registerEntityId(String publicId, URL entityURL);
-
- /**
- * Gets a map with the entity IDs that have been registered using the
{@code registerEntityId()} method.
- *
- * @return a map with the registered entity IDs
- */
- Map<String, URL> getRegisteredEntities();
}
diff --git
a/src/main/java/org/apache/commons/configuration2/sync/NoOpSynchronizer.java
b/src/main/java/org/apache/commons/configuration2/sync/NoOpSynchronizer.java
index a918f0c8..e80c617f 100644
--- a/src/main/java/org/apache/commons/configuration2/sync/NoOpSynchronizer.java
+++ b/src/main/java/org/apache/commons/configuration2/sync/NoOpSynchronizer.java
@@ -42,11 +42,11 @@ public enum NoOpSynchronizer implements Synchronizer {
}
@Override
- public void endRead() {
+ public void beginWrite() {
}
@Override
- public void beginWrite() {
+ public void endRead() {
}
@Override
diff --git
a/src/main/java/org/apache/commons/configuration2/sync/Synchronizer.java
b/src/main/java/org/apache/commons/configuration2/sync/Synchronizer.java
index b94ffe3b..2ee91611 100644
--- a/src/main/java/org/apache/commons/configuration2/sync/Synchronizer.java
+++ b/src/main/java/org/apache/commons/configuration2/sync/Synchronizer.java
@@ -51,12 +51,6 @@ public interface Synchronizer {
*/
void beginRead();
- /**
- * Notifies this {@code Synchronizer} that the current thread has finished
its read operation. This may cause other
- * waiting threads to be granted access to the managed configuration.
- */
- void endRead();
-
/**
* Notifies this {@code Synchronizer} that the current thread is going to
start a write operation on the managed
* configuration. This call may block. For instance, a concrete
implementation may suspend the thread until all read
@@ -64,6 +58,12 @@ public interface Synchronizer {
*/
void beginWrite();
+ /**
+ * Notifies this {@code Synchronizer} that the current thread has finished
its read operation. This may cause other
+ * waiting threads to be granted access to the managed configuration.
+ */
+ void endRead();
+
/**
* Notifies this {@code Synchronizer} that the current thread has finished
its write operation. This may cause other
* waiting threads to be granted access to the managed configuration.
diff --git
a/src/main/java/org/apache/commons/configuration2/sync/SynchronizerSupport.java
b/src/main/java/org/apache/commons/configuration2/sync/SynchronizerSupport.java
index 02f74624..450847dd 100644
---
a/src/main/java/org/apache/commons/configuration2/sync/SynchronizerSupport.java
+++
b/src/main/java/org/apache/commons/configuration2/sync/SynchronizerSupport.java
@@ -42,15 +42,6 @@ public interface SynchronizerSupport {
*/
Synchronizer getSynchronizer();
- /**
- * Sets the {@code Synchronizer} to be used by this object. Calling this
method and setting an appropriate
- * {@code Synchronizer} determines whether this object can be accessed in
a thread-safe way or not. The argument may be
- * <b>null</b>; in this case an implementation should switch to a default
{@code Synchronizer}.
- *
- * @param sync the {@code Synchronizer} for this object
- */
- void setSynchronizer(Synchronizer sync);
-
/**
* Locks this object for the specified mode. This call may block until
this object is released from other lock
* operations. When it returns the caller can access the object in a way
compatible to the specified {@code LockMode}.
@@ -78,6 +69,15 @@ public interface SynchronizerSupport {
*/
void lock(LockMode mode);
+ /**
+ * Sets the {@code Synchronizer} to be used by this object. Calling this
method and setting an appropriate
+ * {@code Synchronizer} determines whether this object can be accessed in
a thread-safe way or not. The argument may be
+ * <b>null</b>; in this case an implementation should switch to a default
{@code Synchronizer}.
+ *
+ * @param sync the {@code Synchronizer} for this object
+ */
+ void setSynchronizer(Synchronizer sync);
+
/**
* Releases a lock of this object that was obtained using the {@link
#lock(LockMode)} method. This method must always be
* called pair-wise with {@code lock()}. The argument must match to the
one passed to the corresponding {@code lock()}
diff --git
a/src/main/java/org/apache/commons/configuration2/tree/ConfigurationNodeVisitor.java
b/src/main/java/org/apache/commons/configuration2/tree/ConfigurationNodeVisitor.java
index f4ee46b8..32d0008e 100644
---
a/src/main/java/org/apache/commons/configuration2/tree/ConfigurationNodeVisitor.java
+++
b/src/main/java/org/apache/commons/configuration2/tree/ConfigurationNodeVisitor.java
@@ -35,12 +35,14 @@ package org.apache.commons.configuration2.tree;
*/
public interface ConfigurationNodeVisitor<T> {
/**
- * Visits the specified node before the children of this node - if
existing - are processed.
+ * Returns a flag whether the current visit process should be aborted.
This method allows a visitor implementation to
+ * state that it does not need any further data. It may be used e.g. by
visitors that search for a certain node in the
+ * hierarchy. After that node was found, there is no need to process the
remaining nodes, too. This method is called
+ * after each visited node. A result of <strong>true</strong> indicates
that the current iteration is to be aborted.
*
- * @param node the node to be visited
- * @param handler the {@code NodeHandler}
+ * @return a flag if the visit process should be stopped
*/
- void visitBeforeChildren(T node, NodeHandler<T> handler);
+ boolean terminate();
/**
* Visits the specified node after after its children - if existing - have
been processed.
@@ -51,12 +53,10 @@ public interface ConfigurationNodeVisitor<T> {
void visitAfterChildren(T node, NodeHandler<T> handler);
/**
- * Returns a flag whether the current visit process should be aborted.
This method allows a visitor implementation to
- * state that it does not need any further data. It may be used e.g. by
visitors that search for a certain node in the
- * hierarchy. After that node was found, there is no need to process the
remaining nodes, too. This method is called
- * after each visited node. A result of <strong>true</strong> indicates
that the current iteration is to be aborted.
+ * Visits the specified node before the children of this node - if
existing - are processed.
*
- * @return a flag if the visit process should be stopped
+ * @param node the node to be visited
+ * @param handler the {@code NodeHandler}
*/
- boolean terminate();
+ void visitBeforeChildren(T node, NodeHandler<T> handler);
}
diff --git
a/src/main/java/org/apache/commons/configuration2/tree/ExpressionEngine.java
b/src/main/java/org/apache/commons/configuration2/tree/ExpressionEngine.java
index 6e51e64a..fc4087fe 100644
--- a/src/main/java/org/apache/commons/configuration2/tree/ExpressionEngine.java
+++ b/src/main/java/org/apache/commons/configuration2/tree/ExpressionEngine.java
@@ -43,34 +43,6 @@ import java.util.List;
* @since 1.3
*/
public interface ExpressionEngine {
- /**
- * Finds the nodes and/or attributes that are matched by the specified
key. This is the main method for interpreting
- * property keys. An implementation must traverse the given root node and
its children to find all results that are
- * matched by the given key. If the key is not correct in the syntax
provided by that implementation, it is free to
- * throw a (runtime) exception indicating this error condition. The passed
in {@code NodeHandler} can be used to gather
- * the required information from the node object.
- *
- * @param <T> the type of the node to be processed
- * @param root the root node of a hierarchy of nodes
- * @param key the key to be evaluated
- * @param handler the {@code NodeHandler} for accessing the node
- * @return a list with the results that are matched by the key (should
never be <b>null</b>)
- */
- <T> List<QueryResult<T>> query(T root, String key, NodeHandler<T> handler);
-
- /**
- * Returns the key for the specified node in the expression language
supported by an implementation. This method is
- * called whenever a property key for a node has to be constructed, e.g.
by the
- * {@link org.apache.commons.configuration2.Configuration#getKeys()
getKeys()} method.
- *
- * @param <T> the type of the node to be processed
- * @param node the node, for which the key must be constructed
- * @param parentKey the key of this node's parent (can be <b>null</b> for
the root node)
- * @param handler the {@code NodeHandler} for accessing the node
- * @return this node's key
- */
- <T> String nodeKey(T node, String parentKey, NodeHandler<T> handler);
-
/**
* Returns the key of an attribute. The passed in {@code parentKey} must
reference the parent node of the attribute. A
* concrete implementation must concatenate this parent key with the
attribute name to a valid key for this attribute.
@@ -95,6 +67,19 @@ public interface ExpressionEngine {
*/
<T> String canonicalKey(T node, String parentKey, NodeHandler<T> handler);
+ /**
+ * Returns the key for the specified node in the expression language
supported by an implementation. This method is
+ * called whenever a property key for a node has to be constructed, e.g.
by the
+ * {@link org.apache.commons.configuration2.Configuration#getKeys()
getKeys()} method.
+ *
+ * @param <T> the type of the node to be processed
+ * @param node the node, for which the key must be constructed
+ * @param parentKey the key of this node's parent (can be <b>null</b> for
the root node)
+ * @param handler the {@code NodeHandler} for accessing the node
+ * @return this node's key
+ */
+ <T> String nodeKey(T node, String parentKey, NodeHandler<T> handler);
+
/**
* Returns information needed for an add operation. This method gets
called when new properties are to be added to a
* configuration. An implementation has to interpret the specified key,
find the parent node for the new elements, and
@@ -107,4 +92,19 @@ public interface ExpressionEngine {
* @return an object with all information needed for the add operation
*/
<T> NodeAddData<T> prepareAdd(T root, String key, NodeHandler<T> handler);
+
+ /**
+ * Finds the nodes and/or attributes that are matched by the specified
key. This is the main method for interpreting
+ * property keys. An implementation must traverse the given root node and
its children to find all results that are
+ * matched by the given key. If the key is not correct in the syntax
provided by that implementation, it is free to
+ * throw a (runtime) exception indicating this error condition. The passed
in {@code NodeHandler} can be used to gather
+ * the required information from the node object.
+ *
+ * @param <T> the type of the node to be processed
+ * @param root the root node of a hierarchy of nodes
+ * @param key the key to be evaluated
+ * @param handler the {@code NodeHandler} for accessing the node
+ * @return a list with the results that are matched by the key (should
never be <b>null</b>)
+ */
+ <T> List<QueryResult<T>> query(T root, String key, NodeHandler<T> handler);
}
diff --git
a/src/main/java/org/apache/commons/configuration2/tree/NodeHandler.java
b/src/main/java/org/apache/commons/configuration2/tree/NodeHandler.java
index 99ad6928..7398d0c5 100644
--- a/src/main/java/org/apache/commons/configuration2/tree/NodeHandler.java
+++ b/src/main/java/org/apache/commons/configuration2/tree/NodeHandler.java
@@ -33,28 +33,31 @@ import java.util.Set;
*/
public interface NodeHandler<T> {
/**
- * Returns the name of the specified node
+ * Gets an unmodifiable set with the names of all attributes of the
specified node.
*
* @param node the node
- * @return the name of this node
+ * @return a set with the names of all attributes of this node
*/
- String nodeName(T node);
+ Set<String> getAttributes(T node);
/**
- * Gets the value of the specified node.
+ * Gets the value of the specified attribute from the given node. If a
concrete {@code NodeHandler} supports
+ * attributes with multiple values, result might be a collection.
*
* @param node the node
- * @return the value of this node
+ * @param name the name of the attribute
+ * @return the value of this attribute
*/
- Object getValue(T node);
+ Object getAttributeValue(T node, String name);
/**
- * Gets the parent of the specified node.
+ * Gets the child with the given index of the specified node.
*
* @param node the node
- * @return the parent node
+ * @param index the index (0-based)
+ * @return the child with the given index
*/
- T getParent(T node);
+ T getChild(T node, int index);
/**
* Gets an unmodifiable list with all children of the specified node.
@@ -73,39 +76,6 @@ public interface NodeHandler<T> {
*/
List<T> getChildren(T node, String name);
- /**
- * Gets an unmodifiable list of all children of the specified node which
are matched by the passed in
- * {@code NodeMatcher} against the provided criterion. This method allows
for advanced queries on a node's children.
- *
- * @param node the node
- * @param matcher the {@code NodeMatcher} defining filter criteria
- * @param criterion the criterion to be matched against; this object is
passed to the {@code NodeMatcher}
- * @param <C> the type of the criterion
- * @return a list with all children matched by the matcher
- */
- <C> List<T> getMatchingChildren(T node, NodeMatcher<C> matcher, C
criterion);
-
- /**
- * Gets the child with the given index of the specified node.
- *
- * @param node the node
- * @param index the index (0-based)
- * @return the child with the given index
- */
- T getChild(T node, int index);
-
- /**
- * Returns the index of the given child node in the list of children of
its parent. This method is the opposite
- * operation of {@link #getChild(Object, int)}. This method returns 0 if
the given node is the first child node with
- * this name, 1 for the second child node and so on. If the node has no
parent node or if it is an attribute, -1 is
- * returned.
- *
- * @param parent the parent node
- * @param child a child node whose index is to be retrieved
- * @return the index of this child node
- */
- int indexOfChild(T parent, T child);
-
/**
* Gets the number of children of the specified node with the given name.
This method exists for performance reasons:
* for some node implementations it may be by far more efficient to count
the children than to query a list of all
@@ -119,6 +89,18 @@ public interface NodeHandler<T> {
*/
int getChildrenCount(T node, String name);
+ /**
+ * Gets an unmodifiable list of all children of the specified node which
are matched by the passed in
+ * {@code NodeMatcher} against the provided criterion. This method allows
for advanced queries on a node's children.
+ *
+ * @param node the node
+ * @param matcher the {@code NodeMatcher} defining filter criteria
+ * @param criterion the criterion to be matched against; this object is
passed to the {@code NodeMatcher}
+ * @param <C> the type of the criterion
+ * @return a list with all children matched by the matcher
+ */
+ <C> List<T> getMatchingChildren(T node, NodeMatcher<C> matcher, C
criterion);
+
/**
* Gets the number of children of the specified node which are matched by
the given {@code NodeMatcher}. This is a
* more generic version of {@link #getChildrenCount(Object, String)}. It
allows checking for arbitrary filter
@@ -133,12 +115,27 @@ public interface NodeHandler<T> {
<C> int getMatchingChildrenCount(T node, NodeMatcher<C> matcher, C
criterion);
/**
- * Gets an unmodifiable set with the names of all attributes of the
specified node.
+ * Gets the parent of the specified node.
*
* @param node the node
- * @return a set with the names of all attributes of this node
+ * @return the parent node
*/
- Set<String> getAttributes(T node);
+ T getParent(T node);
+
+ /**
+ * Gets the root node of the underlying hierarchy.
+ *
+ * @return the current root node
+ */
+ T getRootNode();
+
+ /**
+ * Gets the value of the specified node.
+ *
+ * @param node the node
+ * @return the value of this node
+ */
+ Object getValue(T node);
/**
* Returns a flag whether the passed in node has any attributes.
@@ -149,14 +146,16 @@ public interface NodeHandler<T> {
boolean hasAttributes(T node);
/**
- * Gets the value of the specified attribute from the given node. If a
concrete {@code NodeHandler} supports
- * attributes with multiple values, result might be a collection.
+ * Returns the index of the given child node in the list of children of
its parent. This method is the opposite
+ * operation of {@link #getChild(Object, int)}. This method returns 0 if
the given node is the first child node with
+ * this name, 1 for the second child node and so on. If the node has no
parent node or if it is an attribute, -1 is
+ * returned.
*
- * @param node the node
- * @param name the name of the attribute
- * @return the value of this attribute
+ * @param parent the parent node
+ * @param child a child node whose index is to be retrieved
+ * @return the index of this child node
*/
- Object getAttributeValue(T node, String name);
+ int indexOfChild(T parent, T child);
/**
* Checks whether the specified node is defined. Nodes are
"defined" if they contain any data, e.g. a value,
@@ -168,9 +167,10 @@ public interface NodeHandler<T> {
boolean isDefined(T node);
/**
- * Gets the root node of the underlying hierarchy.
+ * Returns the name of the specified node
*
- * @return the current root node
+ * @param node the node
+ * @return the name of this node
*/
- T getRootNode();
+ String nodeName(T node);
}
diff --git
a/src/main/java/org/apache/commons/configuration2/tree/NodeKeyResolver.java
b/src/main/java/org/apache/commons/configuration2/tree/NodeKeyResolver.java
index 9965ff14..acab1895 100644
--- a/src/main/java/org/apache/commons/configuration2/tree/NodeKeyResolver.java
+++ b/src/main/java/org/apache/commons/configuration2/tree/NodeKeyResolver.java
@@ -33,6 +33,31 @@ import java.util.Map;
* @param <T> the type of the nodes supported by this resolver
*/
public interface NodeKeyResolver<T> {
+ /**
+ * Generates a unique key for the specified node. This method is used if
keys have to be generated for nodes received as
+ * query results. An implementation must generate a canonical key which is
compatible with the current expression
+ * engine. The passed in map can be used by an implementation as cache. It
is created initially by the caller and then
+ * passed in subsequent calls. An implementation may use this to avoid
that keys for nodes already encountered have to
+ * be generated again.
+ *
+ * @param node the node in question
+ * @param cache a map serving as cache
+ * @param handler the {@code NodeHandler}
+ * @return a key for the specified node
+ */
+ String nodeKey(T node, Map<T, String> cache, NodeHandler<T> handler);
+
+ /**
+ * Resolves a key of an add operation. Result is a {@code NodeAddData}
object containing all information for actually
+ * performing the add operation at the specified key.
+ *
+ * @param root the root node
+ * @param key the key to be resolved
+ * @param handler the {@code NodeHandler}
+ * @return a {@code NodeAddData} object to be used for the add operation
+ */
+ NodeAddData<T> resolveAddKey(T root, String key, NodeHandler<T> handler);
+
/**
* Performs a query for the specified key on the given root node. This is
a thin wrapper over the {@code query()} method
* of an {@link ExpressionEngine}.
@@ -56,17 +81,6 @@ public interface NodeKeyResolver<T> {
*/
List<T> resolveNodeKey(T root, String key, NodeHandler<T> handler);
- /**
- * Resolves a key of an add operation. Result is a {@code NodeAddData}
object containing all information for actually
- * performing the add operation at the specified key.
- *
- * @param root the root node
- * @param key the key to be resolved
- * @param handler the {@code NodeHandler}
- * @return a {@code NodeAddData} object to be used for the add operation
- */
- NodeAddData<T> resolveAddKey(T root, String key, NodeHandler<T> handler);
-
/**
* Resolves a key for an update operation. Result is a {@code
NodeUpdateData} object containing all information for
* actually performing the update operation at the specified key using the
provided new value object.
@@ -79,18 +93,4 @@ public interface NodeKeyResolver<T> {
* @return a {@code NodeUpdateData} object to be used for this update
operation
*/
NodeUpdateData<T> resolveUpdateKey(T root, String key, Object newValue,
NodeHandler<T> handler);
-
- /**
- * Generates a unique key for the specified node. This method is used if
keys have to be generated for nodes received as
- * query results. An implementation must generate a canonical key which is
compatible with the current expression
- * engine. The passed in map can be used by an implementation as cache. It
is created initially by the caller and then
- * passed in subsequent calls. An implementation may use this to avoid
that keys for nodes already encountered have to
- * be generated again.
- *
- * @param node the node in question
- * @param cache a map serving as cache
- * @param handler the {@code NodeHandler}
- * @return a key for the specified node
- */
- String nodeKey(T node, Map<T, String> cache, NodeHandler<T> handler);
}
diff --git
a/src/main/java/org/apache/commons/configuration2/tree/NodeModel.java
b/src/main/java/org/apache/commons/configuration2/tree/NodeModel.java
index 21e69296..6dce7223 100644
--- a/src/main/java/org/apache/commons/configuration2/tree/NodeModel.java
+++ b/src/main/java/org/apache/commons/configuration2/tree/NodeModel.java
@@ -39,31 +39,6 @@ import java.util.Collection;
* @param <T> the type of the nodes managed by this model
*/
public interface NodeModel<T> {
- /**
- * Sets a new root node for this model. The whole structure is replaced by
the new node and its children.
- *
- * @param newRoot the new root node to be set (can be <b>null</b>, then an
empty root node is set)
- */
- void setRootNode(T newRoot);
-
- /**
- * Gets a {@code NodeHandler} for dealing with the nodes managed by this
model.
- *
- * @return the {@code NodeHandler}
- */
- NodeHandler<T> getNodeHandler();
-
- /**
- * Adds a new property to this node model consisting of an arbitrary
number of values. The key for the add operation is
- * provided. For each value a new node has to be added. The passed in
resolver is queried for a {@link NodeAddData}
- * object defining the add operation to be performed.
- *
- * @param key the key
- * @param values the values to be added at the position defined by the key
- * @param resolver the {@code NodeKeyResolver}
- */
- void addProperty(String key, Iterable<?> values, NodeKeyResolver<T>
resolver);
-
/**
* Adds a collection of new nodes to this model. This operation
corresponds to the {@code addNodes()} method of the
* {@code HierarchicalConfiguration} interface. The new nodes are either
added to an existing node (if the passed in key
@@ -79,26 +54,22 @@ public interface NodeModel<T> {
void addNodes(String key, Collection<? extends T> nodes,
NodeKeyResolver<T> resolver);
/**
- * Changes the value of a property. This is a more complex operation as it
might involve adding, updating, or deleting
- * nodes and attributes from the model. The object representing the new
value is passed to the {@code NodeKeyResolver}
- * which will produce a corresponding {@link NodeUpdateData} object. Based
on the content of this object, update
- * operations are performed.
+ * Adds a new property to this node model consisting of an arbitrary
number of values. The key for the add operation is
+ * provided. For each value a new node has to be added. The passed in
resolver is queried for a {@link NodeAddData}
+ * object defining the add operation to be performed.
*
* @param key the key
- * @param value the new value for this property (to be evaluated by the
{@code NodeKeyResolver})
+ * @param values the values to be added at the position defined by the key
* @param resolver the {@code NodeKeyResolver}
*/
- void setProperty(String key, Object value, NodeKeyResolver<T> resolver);
+ void addProperty(String key, Iterable<?> values, NodeKeyResolver<T>
resolver);
/**
- * Removes the sub trees defined by the given key from this model. All
nodes selected by this key are retrieved from the
- * specified {@code NodeKeyResolver} and removed from the model.
+ * Removes all data from this model.
*
- * @param key the key selecting the properties to be removed
* @param resolver the {@code NodeKeyResolver}
- * @return an object with information about the data removed
*/
- Object clearTree(String key, NodeKeyResolver<T> resolver);
+ void clear(NodeKeyResolver<T> resolver);
/**
* Clears the value of a property. This method is similar to {@link
#clearTree(String, NodeKeyResolver)}: However, the
@@ -110,11 +81,14 @@ public interface NodeModel<T> {
void clearProperty(String key, NodeKeyResolver<T> resolver);
/**
- * Removes all data from this model.
+ * Removes the sub trees defined by the given key from this model. All
nodes selected by this key are retrieved from the
+ * specified {@code NodeKeyResolver} and removed from the model.
*
+ * @param key the key selecting the properties to be removed
* @param resolver the {@code NodeKeyResolver}
+ * @return an object with information about the data removed
*/
- void clear(NodeKeyResolver<T> resolver);
+ Object clearTree(String key, NodeKeyResolver<T> resolver);
/**
* Gets a representation of the data stored in this model in form of a
nodes hierarchy of {@code ImmutableNode}
@@ -127,4 +101,30 @@ public interface NodeModel<T> {
* @return the root node of an in-memory hierarchy representing the data
stored in this model
*/
ImmutableNode getInMemoryRepresentation();
+
+ /**
+ * Gets a {@code NodeHandler} for dealing with the nodes managed by this
model.
+ *
+ * @return the {@code NodeHandler}
+ */
+ NodeHandler<T> getNodeHandler();
+
+ /**
+ * Changes the value of a property. This is a more complex operation as it
might involve adding, updating, or deleting
+ * nodes and attributes from the model. The object representing the new
value is passed to the {@code NodeKeyResolver}
+ * which will produce a corresponding {@link NodeUpdateData} object. Based
on the content of this object, update
+ * operations are performed.
+ *
+ * @param key the key
+ * @param value the new value for this property (to be evaluated by the
{@code NodeKeyResolver})
+ * @param resolver the {@code NodeKeyResolver}
+ */
+ void setProperty(String key, Object value, NodeKeyResolver<T> resolver);
+
+ /**
+ * Sets a new root node for this model. The whole structure is replaced by
the new node and its children.
+ *
+ * @param newRoot the new root node to be set (can be <b>null</b>, then an
empty root node is set)
+ */
+ void setRootNode(T newRoot);
}
