You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@commons.apache.org by gg...@apache.org on 2024/03/17 13:24:04 UTC
(commons-configuration) branch master updated (15b07437 -> 43f4dab0)
This is an automated email from the ASF dual-hosted git repository.
ggregory pushed a change to branch master
in repository https://gitbox.apache.org/repos/asf/commons-configuration.git
from 15b07437 Better description
new 7d7d399d [CONFIGURATION-840] More tests
new 041094f8 [CONFIGURATION-840] More tests
new aeba79ef Sort interface members
new 06df1136 Use Apache in the doc
new a1777588 Remove unnecessary file
new 43f4dab0 [CONFIGURATION-841] StackOverflowError calling ListDelimiterHandler.flatten(Object, int) with a cyclical object tree
The 6 revisions listed above as "new" are entirely new to this
repository and will be described in separate emails. The revisions
listed as "add" were already present in the repository and have only
been added to this reference.
Summary of changes:
src/changes/changes.xml | 3 +-
src/conf/CommonsConfiguration.xsd | 2 +-
src/conf/README | 4 -
.../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/AbstractListDelimiterHandler.java | 40 ++++++-
.../convert/ListDelimiterHandler.java | 58 ++++------
.../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 ++++++-------
.../TestPropertiesConfiguration.java | 120 +++++++++++++++++++--
26 files changed, 644 insertions(+), 533 deletions(-)
delete mode 100644 src/conf/README
(commons-configuration) 02/06: [CONFIGURATION-840] More tests
Posted by gg...@apache.org.
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 041094f820d1cfe0a2787c4ba194a3215d927b26
Author: Gary Gregory <ga...@gmail.com>
AuthorDate: Sat Mar 16 18:29:08 2024 -0400
[CONFIGURATION-840] More tests
---
.../TestPropertiesConfiguration.java | 46 ++++++++++++++++------
1 file changed, 35 insertions(+), 11 deletions(-)
diff --git a/src/test/java/org/apache/commons/configuration2/TestPropertiesConfiguration.java b/src/test/java/org/apache/commons/configuration2/TestPropertiesConfiguration.java
index bfd415b7..40462bed 100644
--- a/src/test/java/org/apache/commons/configuration2/TestPropertiesConfiguration.java
+++ b/src/test/java/org/apache/commons/configuration2/TestPropertiesConfiguration.java
@@ -56,11 +56,10 @@ import java.nio.charset.StandardCharsets;
import java.nio.file.FileSystems;
import java.nio.file.Files;
import java.nio.file.Paths;
-import java.sql.SQLException;
-import java.sql.SQLWarning;
import java.util.ArrayDeque;
import java.util.ArrayList;
import java.util.Arrays;
+import java.util.Collection;
import java.util.Collections;
import java.util.HashSet;
import java.util.Iterator;
@@ -88,6 +87,8 @@ import org.apache.commons.lang3.mutable.MutableObject;
import org.junit.jupiter.api.BeforeEach;
import org.junit.jupiter.api.Test;
import org.junit.jupiter.api.io.TempDir;
+import org.junit.jupiter.params.ParameterizedTest;
+import org.junit.jupiter.params.provider.ValueSource;
/**
* Test for loading and saving properties files.
@@ -439,7 +440,7 @@ public class TestPropertiesConfiguration {
assertFalse(conf.containsKey("!comment"));
}
- private void testCompress840(final Iterable<?> object) {
+ private Collection<?> testCompress840(final Iterable<?> object) {
final PropertiesConfiguration configuration = new PropertiesConfiguration();
final ListDelimiterHandler listDelimiterHandler = configuration.getListDelimiterHandler();
listDelimiterHandler.flatten(object, 0);
@@ -449,6 +450,20 @@ public class TestPropertiesConfiguration {
listDelimiterHandler.parse(object);
configuration.addProperty("foo", object);
configuration.toString();
+ return listDelimiterHandler.flatten(object, Integer.MAX_VALUE);
+ }
+
+ @ParameterizedTest
+ @ValueSource(ints = { 0, 2, 4, 8, 16 })
+ public void testCompress840ArrayList(final int size) {
+ final ArrayList<Object> object = new ArrayList<>();
+ for (int i = 0; i < size; i++) {
+ object.add(i);
+ }
+ final Collection<?> result = testCompress840(object);
+ assertNotNull(result);
+ assertEquals(size, result.size());
+ assertEquals(object, result);
}
@Test
@@ -477,16 +492,25 @@ public class TestPropertiesConfiguration {
testCompress840(bcs);
}
- @Test
- public void testCompress840Path() {
- testCompress840(FileSystems.getDefault().getPath("foo"));
- testCompress840(FileSystems.getDefault().getPath("foo", "bar"));
+ @ParameterizedTest
+ @ValueSource(ints = { 0, 2, 4, 8, 16 })
+ public void testCompress840Path(final int size) {
+ final PriorityQueue<Object> object = new PriorityQueue<>();
+ for (int i = 0; i < size; i++) {
+ object.add(FileSystems.getDefault().getPath("foo"));
+ object.add(FileSystems.getDefault().getPath("foo", "bar"));
+ }
+ testCompress840(object);
}
- @Test
- public void testCompress840PriorityQueue() {
- testCompress840(new PriorityQueue<>());
- testCompress840(new PriorityQueue<>(Arrays.asList(FileSystems.getDefault().getPath("foo"))));
+ @ParameterizedTest
+ @ValueSource(ints = { 0, 2, 4, 8, 16 })
+ public void testCompress840PriorityQueue(final int size) {
+ final PriorityQueue<Object> object = new PriorityQueue<>();
+ for (int i = 0; i < size; i++) {
+ object.add(FileSystems.getDefault().getPath("foo"));
+ }
+ testCompress840(object);
}
/**
(commons-configuration) 04/06: Use Apache in the doc
Posted by gg...@apache.org.
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 06df1136d2d525daf00bc6bd4bd15f5ead217f46
Author: Gary Gregory <ga...@gmail.com>
AuthorDate: Sun Mar 17 08:16:03 2024 -0400
Use Apache in the doc
---
src/conf/CommonsConfiguration.xsd | 2 +-
1 file changed, 1 insertion(+), 1 deletion(-)
diff --git a/src/conf/CommonsConfiguration.xsd b/src/conf/CommonsConfiguration.xsd
index 1b881518..2e1cb344 100644
--- a/src/conf/CommonsConfiguration.xsd
+++ b/src/conf/CommonsConfiguration.xsd
@@ -24,7 +24,7 @@
<xs:schema xmlns:xs="http://www.w3.org/2001/XMLSchema" elementFormDefault="qualified" attributeFormDefault="unqualified">
<xs:element name="configuration">
<xs:annotation>
- <xs:documentation>Commons Configuration v0.1</xs:documentation>
+ <xs:documentation>Apache Commons Configuration</xs:documentation>
</xs:annotation>
<xs:complexType>
<xs:complexContent>
(commons-configuration) 01/06: [CONFIGURATION-840] More tests
Posted by gg...@apache.org.
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 7d7d399d0598cb0ca5f81891de34694178156dab
Author: Gary Gregory <ga...@gmail.com>
AuthorDate: Sat Mar 16 18:16:32 2024 -0400
[CONFIGURATION-840] More tests
---
.../convert/AbstractListDelimiterHandler.java | 40 +++++++++++++--
.../convert/ListDelimiterHandler.java | 31 +++---------
.../TestPropertiesConfiguration.java | 58 ++++++++++++++++++----
3 files changed, 92 insertions(+), 37 deletions(-)
diff --git a/src/main/java/org/apache/commons/configuration2/convert/AbstractListDelimiterHandler.java b/src/main/java/org/apache/commons/configuration2/convert/AbstractListDelimiterHandler.java
index 5fbcd7f9..e4ab1554 100644
--- a/src/main/java/org/apache/commons/configuration2/convert/AbstractListDelimiterHandler.java
+++ b/src/main/java/org/apache/commons/configuration2/convert/AbstractListDelimiterHandler.java
@@ -16,9 +16,13 @@
*/
package org.apache.commons.configuration2.convert;
+import java.lang.reflect.Array;
+import java.nio.file.Path;
import java.util.ArrayList;
import java.util.Collection;
import java.util.Iterator;
+import java.util.LinkedList;
+import java.util.Set;
/**
* <p>
@@ -42,15 +46,45 @@ public abstract class AbstractListDelimiterHandler implements ListDelimiterHandl
* @param target the target collection
* @param iterator the iterator to process
* @param limit a limit for the number of elements to extract
+ * @param dejaVue Previously visited objects.
*/
- static void flattenIterator(final ListDelimiterHandler handler, final Collection<Object> target, final Iterator<?> iterator, final int limit) {
+ static void flattenIterator(final ListDelimiterHandler handler, final Collection<Object> target, final Iterator<?> iterator, final int limit,
+ Set<Object> dejaVue) {
int size = target.size();
while (size < limit && iterator.hasNext()) {
- target.addAll(handler.flatten(iterator.next(), limit - size));
- size = target.size();
+ final Object next = iterator.next();
+ if (!dejaVue.contains(next)) {
+ target.addAll(flatten(handler, next, limit - size, dejaVue));
+ size = target.size();
+ }
}
}
+ static Collection<?> flatten(final ListDelimiterHandler handler, final Object value, final int limit, final Set<Object> dejaVu) {
+ dejaVu.add(value);
+ if (value instanceof String) {
+ return handler.split((String) value, true);
+ }
+ final Collection<Object> result = new LinkedList<>();
+ if (value instanceof Path) {
+ // Don't handle as an Iterable.
+ result.add(value);
+ } else if (value instanceof Iterable) {
+ AbstractListDelimiterHandler.flattenIterator(handler, result, ((Iterable<?>) value).iterator(), limit, dejaVu);
+ } else if (value instanceof Iterator) {
+ AbstractListDelimiterHandler.flattenIterator(handler, result, (Iterator<?>) value, limit, dejaVu);
+ } else if (value != null) {
+ if (value.getClass().isArray()) {
+ for (int len = Array.getLength(value), idx = 0, size = 0; idx < len && size < limit; idx++, size = result.size()) {
+ result.addAll(handler.flatten(Array.get(value, idx), limit - size));
+ }
+ } else {
+ result.add(value);
+ }
+ }
+ return result;
+ }
+
/**
* {@inheritDoc} This implementation checks whether the object to be escaped is a string. If yes, it delegates to
* {@link #escapeString(String)}, otherwise no escaping is performed. Eventually, the passed in transformer is invoked
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 d0fc1ef0..fb194049 100644
--- a/src/main/java/org/apache/commons/configuration2/convert/ListDelimiterHandler.java
+++ b/src/main/java/org/apache/commons/configuration2/convert/ListDelimiterHandler.java
@@ -16,12 +16,11 @@
*/
package org.apache.commons.configuration2.convert;
-import java.lang.reflect.Array;
-import java.nio.file.Path;
import java.util.Collection;
-import java.util.Iterator;
-import java.util.LinkedList;
+import java.util.Collections;
+import java.util.IdentityHashMap;
import java.util.List;
+import java.util.Set;
/**
* <p>
@@ -118,27 +117,9 @@ public interface ListDelimiterHandler {
* @since 2.9.0
*/
default Collection<?> flatten(final Object value, final int limit) {
- if (value instanceof String) {
- return split((String) value, true);
- }
- final Collection<Object> result = new LinkedList<>();
- if (value instanceof Path) {
- // Don't handle as an Iterable.
- result.add(value);
- } else if (value instanceof Iterable) {
- AbstractListDelimiterHandler.flattenIterator(this, result, ((Iterable<?>) value).iterator(), limit);
- } else if (value instanceof Iterator) {
- AbstractListDelimiterHandler.flattenIterator(this, result, (Iterator<?>) value, limit);
- } else if (value != null) {
- if (value.getClass().isArray()) {
- for (int len = Array.getLength(value), idx = 0, size = 0; idx < len && size < limit; idx++, size = result.size()) {
- result.addAll(flatten(Array.get(value, idx), limit - size));
- }
- } else {
- result.add(value);
- }
- }
- return result;
+ final Set<Object> dejaVu = Collections.newSetFromMap(new IdentityHashMap<>());
+ dejaVu.add(value);
+ return AbstractListDelimiterHandler.flatten(this, value, limit, dejaVu);
}
}
diff --git a/src/test/java/org/apache/commons/configuration2/TestPropertiesConfiguration.java b/src/test/java/org/apache/commons/configuration2/TestPropertiesConfiguration.java
index 52fd5bc0..bfd415b7 100644
--- a/src/test/java/org/apache/commons/configuration2/TestPropertiesConfiguration.java
+++ b/src/test/java/org/apache/commons/configuration2/TestPropertiesConfiguration.java
@@ -33,6 +33,8 @@ import static org.junit.jupiter.api.Assertions.assertSame;
import static org.junit.jupiter.api.Assertions.assertThrows;
import static org.junit.jupiter.api.Assertions.assertTrue;
+import java.beans.beancontext.BeanContextServicesSupport;
+import java.beans.beancontext.BeanContextSupport;
import java.io.BufferedReader;
import java.io.ByteArrayInputStream;
import java.io.File;
@@ -53,8 +55,9 @@ import java.net.URLStreamHandler;
import java.nio.charset.StandardCharsets;
import java.nio.file.FileSystems;
import java.nio.file.Files;
-import java.nio.file.Path;
import java.nio.file.Paths;
+import java.sql.SQLException;
+import java.sql.SQLWarning;
import java.util.ArrayDeque;
import java.util.ArrayList;
import java.util.Arrays;
@@ -62,6 +65,7 @@ import java.util.Collections;
import java.util.HashSet;
import java.util.Iterator;
import java.util.List;
+import java.util.PriorityQueue;
import java.util.Properties;
import java.util.Set;
@@ -435,20 +439,56 @@ public class TestPropertiesConfiguration {
assertFalse(conf.containsKey("!comment"));
}
- @Test
- public void testCompress840() {
+ private void testCompress840(final Iterable<?> object) {
final PropertiesConfiguration configuration = new PropertiesConfiguration();
- final Path path = FileSystems.getDefault().getPath("bar");
final ListDelimiterHandler listDelimiterHandler = configuration.getListDelimiterHandler();
- listDelimiterHandler.flatten(path, 0);
+ listDelimiterHandler.flatten(object, 0);
// Stack overflow:
- listDelimiterHandler.flatten(path, 1);
- listDelimiterHandler.flatten(path, Integer.MAX_VALUE);
- listDelimiterHandler.parse(path);
- configuration.addProperty("foo", path);
+ listDelimiterHandler.flatten(object, 1);
+ listDelimiterHandler.flatten(object, Integer.MAX_VALUE);
+ listDelimiterHandler.parse(object);
+ configuration.addProperty("foo", object);
configuration.toString();
}
+ @Test
+ public void testCompress840BeanContextServicesSupport() {
+ testCompress840(new BeanContextServicesSupport());
+ testCompress840(new BeanContextServicesSupport(new BeanContextServicesSupport()));
+ final BeanContextSupport bcs = new BeanContextSupport();
+ final BeanContextServicesSupport bcss = new BeanContextServicesSupport();
+ bcs.add(FileSystems.getDefault().getPath("bar"));
+ bcss.add(bcs);
+ testCompress840(bcss);
+ bcss.add(FileSystems.getDefault().getPath("bar"));
+ testCompress840(bcss);
+ bcss.add(bcss);
+ testCompress840(bcss);
+ }
+
+ @Test
+ public void testCompress840BeanContextSupport() {
+ testCompress840(new BeanContextSupport());
+ testCompress840(new BeanContextSupport(new BeanContextSupport()));
+ final BeanContextSupport bcs = new BeanContextSupport();
+ bcs.add(FileSystems.getDefault().getPath("bar"));
+ testCompress840(bcs);
+ bcs.add(bcs);
+ testCompress840(bcs);
+ }
+
+ @Test
+ public void testCompress840Path() {
+ testCompress840(FileSystems.getDefault().getPath("foo"));
+ testCompress840(FileSystems.getDefault().getPath("foo", "bar"));
+ }
+
+ @Test
+ public void testCompress840PriorityQueue() {
+ testCompress840(new PriorityQueue<>());
+ testCompress840(new PriorityQueue<>(Arrays.asList(FileSystems.getDefault().getPath("foo"))));
+ }
+
/**
* Tests copying another configuration into the test configuration. This test ensures that the layout object is informed
* about the newly added properties.
(commons-configuration) 06/06: [CONFIGURATION-841] StackOverflowError calling ListDelimiterHandler.flatten(Object, int) with a cyclical object tree
Posted by gg...@apache.org.
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 43f4dab021e9acb8db390db2ae80aa0cee4f9ee4
Author: Gary Gregory <ga...@gmail.com>
AuthorDate: Sun Mar 17 09:23:59 2024 -0400
[CONFIGURATION-841] StackOverflowError calling
ListDelimiterHandler.flatten(Object, int) with a cyclical object tree
---
src/changes/changes.xml | 3 +-
.../convert/ListDelimiterHandler.java | 5 +--
.../TestPropertiesConfiguration.java | 38 ++++++++++++++++++++++
3 files changed, 41 insertions(+), 5 deletions(-)
diff --git a/src/changes/changes.xml b/src/changes/changes.xml
index 82dfd261..7645c202 100644
--- a/src/changes/changes.xml
+++ b/src/changes/changes.xml
@@ -26,7 +26,8 @@
<release version="2.10.1" date="YYYY-MM-DD" description="Minor release with new features and updated dependencies.">
<!-- FIX -->
<action type="fix" issue="CONFIGURATION-840" dev="ggregory" due-to="Gary Gregory">StackOverflowError adding property in AbstractListDelimiterHandler.flattenIterator().</action>
- <action type="fix" issue="CONFIGURATION-840" dev="ggregory" due-to="Bob Marinier, Gary Gregory">Version 2.10.0 fails java.lang.module.FindException: Module servlet.api not found.</action>
+ <action type="fix" issue="CONFIGURATION-840" dev="ggregory" due-to="Bob Marinier, Gary Gregory">java.lang.module.FindException: Module servlet.api not found.</action>
+ <action type="fix" issue="CONFIGURATION-841" dev="ggregory" due-to="Gary Gregory">StackOverflowError calling ListDelimiterHandler.flatten(Object, int) with a cyclical object tree.</action>
<!-- UPDATE -->
<action type="update" dev="ggregory" due-to="Dependabot">Bump jackson-databind from 2.16.1 to 2.17.0 #297, #303, #326, #331, #340, #378.</action>
<action type="update" dev="ggregory" due-to="Dependabot">Bump log4j.version from 2.23.0 to 2.23.1 #379.</action>
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 902e9cd3..61b2407b 100644
--- a/src/main/java/org/apache/commons/configuration2/convert/ListDelimiterHandler.java
+++ b/src/main/java/org/apache/commons/configuration2/convert/ListDelimiterHandler.java
@@ -20,7 +20,6 @@ import java.util.Collection;
import java.util.Collections;
import java.util.IdentityHashMap;
import java.util.List;
-import java.util.Set;
/**
* <p>
@@ -94,9 +93,7 @@ public interface ListDelimiterHandler {
* @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);
+ return AbstractListDelimiterHandler.flatten(this, value, limit, Collections.newSetFromMap(new IdentityHashMap<>()));
}
/**
diff --git a/src/test/java/org/apache/commons/configuration2/TestPropertiesConfiguration.java b/src/test/java/org/apache/commons/configuration2/TestPropertiesConfiguration.java
index 40462bed..da85e4bb 100644
--- a/src/test/java/org/apache/commons/configuration2/TestPropertiesConfiguration.java
+++ b/src/test/java/org/apache/commons/configuration2/TestPropertiesConfiguration.java
@@ -466,6 +466,22 @@ public class TestPropertiesConfiguration {
assertEquals(object, result);
}
+ @ParameterizedTest
+ @ValueSource(ints = { 0, 2, 4, 8, 16 })
+ public void testCompress840ArrayListCycle(final int size) {
+ final ArrayList<Object> object = new ArrayList<>();
+ for (int i = 0; i < size; i++) {
+ object.add(i);
+ object.add(object);
+ object.add(new ArrayList<>(object));
+ }
+ final Collection<?> result = testCompress840(object);
+ assertNotNull(result);
+ assertEquals(size, result.size());
+ object.add(object);
+ testCompress840(object);
+ }
+
@Test
public void testCompress840BeanContextServicesSupport() {
testCompress840(new BeanContextServicesSupport());
@@ -492,6 +508,28 @@ public class TestPropertiesConfiguration {
testCompress840(bcs);
}
+ @ParameterizedTest
+ @ValueSource(ints = { 0, 2, 4, 8, 16 })
+ public void testCompress840Exception(final int size) {
+ final ArrayList<Object> object = new ArrayList<>();
+ final Exception bottom = new Exception();
+ object.add(bottom);
+ Exception top = bottom;
+ for (int i = 0; i < size; i++) {
+ object.add(i);
+ top = new Exception(top);
+ object.add(top);
+ }
+ if (bottom != top) {
+ // direct self-causation is not allowed.
+ bottom.initCause(top);
+ }
+ final Collection<?> result = testCompress840(object);
+ assertNotNull(result);
+ assertEquals(size * 2 + 1, result.size());
+ assertEquals(object, result);
+ }
+
@ParameterizedTest
@ValueSource(ints = { 0, 2, 4, 8, 16 })
public void testCompress840Path(final int size) {
(commons-configuration) 03/06: Sort interface members
Posted by gg...@apache.org.
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 <ga...@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);
}
(commons-configuration) 05/06: Remove unnecessary file
Posted by gg...@apache.org.
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 a17775880e6adca1a4d616519d66a395d7d21c03
Author: Gary Gregory <ga...@gmail.com>
AuthorDate: Sun Mar 17 08:16:52 2024 -0400
Remove unnecessary file
---
src/conf/README | 4 ----
1 file changed, 4 deletions(-)
diff --git a/src/conf/README b/src/conf/README
deleted file mode 100644
index bd219a8a..00000000
--- a/src/conf/README
+++ /dev/null
@@ -1,4 +0,0 @@
-DO NOT DELETE THESE FILES!
-
-They're used by the unit tests for testing various Configuration implementations.
-