merging doc updates from master
diff --git a/.github/workflows/coverage.yml b/.github/workflows/coverage.yml
index 68d62f6..00b779d 100644
--- a/.github/workflows/coverage.yml
+++ b/.github/workflows/coverage.yml
@@ -30,17 +30,12 @@
steps:
- uses: actions/checkout@v3
- - uses: actions/cache@v3.0.4
- with:
- path: ~/.m2/repository
- key: ${{ runner.os }}-maven-${{ hashFiles('**/pom.xml') }}
- restore-keys: |
- ${{ runner.os }}-maven-
- name: Set up JDK ${{ matrix.java }}
uses: actions/setup-java@v3
with:
distribution: adopt
java-version: ${{ matrix.java }}
+ cache: 'maven'
- name: Build with Maven
run: mvn -V test jacoco:report --file pom.xml --no-transfer-progress
diff --git a/.github/workflows/maven.yml b/.github/workflows/maven.yml
index 8dad900..7344daf 100644
--- a/.github/workflows/maven.yml
+++ b/.github/workflows/maven.yml
@@ -32,18 +32,13 @@
steps:
- uses: actions/checkout@v3
- - uses: actions/cache@v3.0.4
- with:
- path: ~/.m2/repository
- key: ${{ runner.os }}-maven-${{ hashFiles('**/pom.xml') }}
- restore-keys: |
- ${{ runner.os }}-maven-
- name: Set up JDK ${{ matrix.java }}
uses: actions/setup-java@v3
with:
distribution: 'temurin'
java-version: ${{ matrix.java }}
+ cache: 'maven'
- name: Build with Maven
run: mvn -V -Ddoclint=none --file pom.xml --no-transfer-progress
-# For Java 11, you can be more strict: -DadditionalJOption=-Xdoclint/package:-org.apache.commons.configuration2.plist
\ No newline at end of file
+# For Java 11, you can be more strict: -DadditionalJOption=-Xdoclint/package:-org.apache.commons.configuration2.plist
diff --git a/README.md b/README.md
index f10d8bd..a4b01b7 100644
--- a/README.md
+++ b/README.md
@@ -46,7 +46,7 @@
[](https://github.com/apache/commons-configuration/actions)
[](https://app.codecov.io/gh/apache/commons-configuration)
[](https://maven-badges.herokuapp.com/maven-central/org.apache.commons/commons-configuration2/)
-[](https://javadoc.io/doc/org.apache.commons/commons-configuration2/2.8)
+[](https://javadoc.io/doc/org.apache.commons/commons-configuration2/2.8.0)
Tools to assist in the reading of configuration/preferences files in
various formats
@@ -68,7 +68,7 @@
<dependency>
<groupId>org.apache.commons</groupId>
<artifactId>commons-configuration2</artifactId>
- <version>2.8</version>
+ <version>2.8.0</version>
</dependency>
```
diff --git a/RELEASE-NOTES.txt b/RELEASE-NOTES.txt
index 5291654..1539427 100644
--- a/RELEASE-NOTES.txt
+++ b/RELEASE-NOTES.txt
@@ -1,5 +1,5 @@
Apache Commons Configuration
- Version 2.8
+ Version 2.8.0
Release Notes
@@ -21,14 +21,10 @@
New features:
o Implement Iterable in ImmutableNode #74. Thanks to SethiPandi.
-o Add PropertiesConfigurationLayout.getBlankLinesBefore() and deprecate getBlancLinesBefore().
- Thanks to Gary Gregory.
-o Add PropertiesConfigurationLayout.setBlankLinesBefore() and deprecate setBlancLinesBefore().
- Thanks to Gary Gregory.
-o Add PropertiesConfigurationLayout.PropertyLayoutData.getBlankLines() and deprecate
- getBlancLines(). Thanks to Gary Gregory.
-o Add PropertiesConfigurationLayout.PropertyLayoutData.setBlankLines() and deprecate
- setBlancLines(). Thanks to Gary Gregory.
+o Add PropertiesConfigurationLayout.getBlankLinesBefore() and deprecate getBlancLinesBefore(). Thanks to Gary Gregory.
+o Add PropertiesConfigurationLayout.setBlankLinesBefore() and deprecate setBlancLinesBefore(). Thanks to Gary Gregory.
+o Add PropertiesConfigurationLayout.PropertyLayoutData.getBlankLines() and deprecate getBlancLines(). Thanks to Gary Gregory.
+o Add PropertiesConfigurationLayout.PropertyLayoutData.setBlankLines() and deprecate setBlancLines(). Thanks to Gary Gregory.
o CONFIGURATION-789: Add ImmutableConfiguration.getEnum() methods. Thanks to Gary Gregory.
o CONFIGURATION-789: Add ImmutableConfiguration.getDuration() methods. Thanks to Gary Gregory.
@@ -42,27 +38,21 @@
o CONFIGURATION-803: Java 8 lambda improvements and more #112. Thanks to Arturo Bernal.
o CONFIGURATION-804: Redundant local variable #113. Thanks to Arturo Bernal.
o CONFIGURATION-805: Use try with resource #114. Thanks to Arturo Bernal.
-o CONFIGURATION-805: [Javadoc] Specify that typed getList returns null for missing key #100. Thanks to
- Roman Zaynetdinov.
-o Mention EnvironmentConfiguration in the list of configuration sources #45. Thanks to
- Oliver B. Fischer.
+o CONFIGURATION-805: [Javadoc] Specify that typed getList returns null for missing key #100. Thanks to Roman Zaynetdinov.
+o Mention EnvironmentConfiguration in the list of configuration sources #45. Thanks to Oliver B. Fischer.
o CONFIGURATION-808: DefaultListDelimiterHandler.escapeList working only for List>String< #137. Thanks to cigaly.
o Use final #141. Thanks to Arturo Bernal.
o Replace test asserts by simpler but equivalent calls. #139 Thanks to Arturo Bernal.
-o CONFIGURATION-764: Single Variable Interpolation #182. Thanks to Ning Zhang, Matt Juntunen, Bruno P. Kinoshita,
- Gary Gregory.
+o CONFIGURATION-764: Single Variable Interpolation #182. Thanks to Ning Zhang, Matt Juntunen, Bruno P. Kinoshita, Gary Gregory.
o Implement proper concurrency in ConstantLookup. Thanks to Gary Gregory.
-o CONFIGURATION-813: Support new namespace jakarta.mail.* used by javamail 2.0+ (first release October 2020) #186.
- Thanks to Dependabot.
+o CONFIGURATION-813: Support new namespace jakarta.mail.* used by javamail 2.0+ (first release October 2020) #186. Thanks to Dependabot.
Changes:
o Unclosed file handle when reading config from JAR file URL.
- Add and use FileBasedBuilderProperties.setURL(URL, URLConnectionOptions). Thanks to Robin Jansohn,
- Gary Gregory, Rob Spoor.
-o Make default interpolation prefix lookups configurable via system property. Remove dns, url, and
- script lookups from defaults. If these lookups are required for use in AbstractConfiguration
- subclasses, they must be enabled via system property. See
- ConfigurationInterpolator.getDefaultPrefixLookups() for details.
+ Add and use FileBasedBuilderProperties.setURL(URL, URLConnectionOptions). Thanks to Robin Jansohn, Gary Gregory, Rob Spoor.
+o Make default interpolation prefix lookups configurable via system property. Remove dns, url, and script
+ lookups from defaults. If these lookups are required for use in AbstractConfiguration subclasses, they must
+ be enabled via system property. See ConfigurationInterpolator.getDefaultPrefixLookups() for details.
o Bump actions/cache from 2 to 3.0.4 #99, #151, #169. Thanks to Dependabot, Gary Gregory.
o Bump actions/checkout from 1 to 3 #47, #62, #70, #85, #150, #163. Thanks to Dependabot.
o Bump actions/setup-java from 1.4.0 to 3 #63, #65, #73, #174. Thanks to Dependabot, Gary Gregory.
@@ -75,8 +65,7 @@
#165, #172 Thanks to Dependabot, Matt Juntunen, kinow, Gary Gregory.
o Bump commons-parent from 52 to 53. Thanks to Dependabot, Matt Juntunen.
o CONFIGURATION-787: Bump Apache Commons Lang from 3.9 to 3.12.0. Thanks to Gary Gregory.
-o CONFIGURATION-790: Bump com.fasterxml.jackson.core:jackson-databind from 2.10.3 to 2.13.3, #60. Thanks to
- Gary Gregory, Dependabot.
+o CONFIGURATION-790: Bump com.fasterxml.jackson.core:jackson-databind from 2.10.3 to 2.13.3, #60. Thanks to Gary Gregory, Dependabot.
o Bump Slf4j test dependencies:
org.slf4j:slf4j-api 1.7.26 -> 1.7.33,
org.slf4j:slf4j-ext 1.7.26 -> 1.7.33,
@@ -84,16 +73,14 @@
org.slf4j:slf4j-nop 1.7.26 -> 1.7.33. Thanks to Gary Gregory.
o Bump commons-parent from 50 to 52. Thanks to Dependabot.
o Bump mailapi from 1.6.4 to 1.6.7 #48. Thanks to Dependabot, Gary Gregory.
-o Bump spotbugs-maven-plugin from 3.1.12.2 to 4.7.0.0, #55, #75, #79, #93, #116, #183. Thanks to
- Dependabot, Gary Gregory.
+o Bump spotbugs-maven-plugin from 3.1.12.2 to 4.7.0.0, #55, #75, #79, #93, #116, #183. Thanks to Dependabot, Gary Gregory.
o Bump hsqldb from 2.5.0 to 2.5.2 #54, #128. Thanks to Dependabot.
o Bump commons-text from 1.8 to 1.9. Thanks to Gary Gregory.
o Bump servlet-api from 2.4 to 2.5 #58. Thanks to Gary Gregory.
o Bump maven-checkstyle-plugin from 3.1.0 to 3.1.2, #57, #97. Thanks to Gary Gregory.
o Bump commons-pool2 from 2.8.0 to 2.10.0, #61, #124. Thanks to Dependabot, Gary Gregory.
o Bump optional commons-codec from 1.14 to 1.15. Thanks to Gary Gregory.
-o Bump checkstyle from 8.26 to 9.3, #66, #71, #90, #101, #118, #121, #132, #155. Thanks to
- Dependabot, Gary Gregory.
+o Bump checkstyle from 8.26 to 9.3, #66, #71, #90, #101, #118, #121, #132, #155. Thanks to Dependabot, Gary Gregory.
o Bump commons.jacoco.version 0.8.5 to 0.8.8 (Fixes Java 15 builds). Thanks to Gary Gregory.
o Bump tests from commons-pool2 2.10.0 to 2.11.1. Thanks to Gary Gregory.
o Bump tests from commons-dbcp2 2.7.0 to 2.9.0. Thanks to Gary Gregory.
@@ -101,14 +88,14 @@
o Bump commons.japicmp.version from 0.14.1 to 0.15.7. Thanks to Gary Gregory.
o Bump junit from 4.13 to 4.13.2 #78. Thanks to Dependabot, Gary Gregory.
o Bump Apache Commons VFS 2.6.0 -> 2.9.0. Thanks to Gary Gregory.
-o Bump jackson-databind from 2.11.3 to 2.13.2.2 ,#88, #94, #127, #159, #168, #173. Thanks to
- Dependabot.
+o Bump jackson-databind from 2.11.3 to 2.13.2.2 ,#88, #94, #127, #159, #168, #173. Thanks to Dependabot.
o Bump commons.animal-sniffer.version 1.19 -> 1.20. Thanks to Gary Gregory.
o Bump commons.javadoc.version from 3.1.1 to 3.4.0. Thanks to Gary Gregory.
o Bump org.dbunit:dbunit from 2.7.0 to 2.7.3, #167. Thanks to Gary Gregory, Dependabot.
o Bump tests to hamcrest v2.2 #143. Thanks to John Patrick.
o Bump slf4j.version from 1.7.33 to 1.7.36 #166. Thanks to Dependabot.
o Bump mailapi from 1.6.6 to 2.0.1 #186. Thanks to Dependabot.
+o Use GitHub Actions setup-java Maven cache property #190. Thanks to sullis.
Historical list of changes: https://commons.apache.org/proper/commons-configuration/changes-report.html
diff --git a/pom.xml b/pom.xml
index 6bbe2e2..e86bb39 100644
--- a/pom.xml
+++ b/pom.xml
@@ -24,7 +24,7 @@
</parent>
<modelVersion>4.0.0</modelVersion>
<artifactId>commons-configuration2</artifactId>
- <version>2.8</version>
+ <version>2.8.0</version>
<name>Apache Commons Configuration</name>
<inceptionYear>2001</inceptionYear>
@@ -560,7 +560,7 @@
<properties>
<commons.componentid>configuration</commons.componentid>
<commons.module.name>org.apache.commons.configuration2</commons.module.name>
- <commons.release.version>2.8</commons.release.version>
+ <commons.release.version>2.8.0</commons.release.version>
<commons.release.desc>(reworked 2.x version)</commons.release.desc>
<commons.release.2.name>commons-configuration-${commons.release.2.version}</commons.release.2.name>
<commons.release.2.version>1.10</commons.release.2.version>
@@ -607,7 +607,7 @@
<!-- Commons Release Plugin -->
<commons.bc.version>2.7</commons.bc.version>
- <commons.rc.version>RC2</commons.rc.version>
+ <commons.rc.version>RC3</commons.rc.version>
<commons.release.isDistModule>true</commons.release.isDistModule>
<commons.distSvnStagingUrl>scm:svn:https://dist.apache.org/repos/dist/dev/commons/${commons.componentid}</commons.distSvnStagingUrl>
<commons.releaseManagerName>Matt Juntunen</commons.releaseManagerName>
diff --git a/src/changes/changes.xml b/src/changes/changes.xml
index 465d5aa..a7dda24 100644
--- a/src/changes/changes.xml
+++ b/src/changes/changes.xml
@@ -21,7 +21,7 @@
<author email="dev@commons.apache.org">Apache Commons Community</author>
</properties>
<body>
- <release version="2.8" date="2022-06-26"
+ <release version="2.8.0" date="2022-07-05"
description="Minor release with new features and updated dependencies.">
<!-- FIX -->
<action issue="CONFIGURATION-753" type="fix" dev="mattjuntunen">
@@ -211,6 +211,9 @@
<action type="update" dev="kinow" due-to="Dependabot">
Bump mailapi from 1.6.6 to 2.0.1 #186.
</action>
+ <action type="update" dev="kinow" due-to="sullis">
+ Use GitHub Actions setup-java Maven cache property #190.
+ </action>
</release>
<release version="2.7" date="2020-03-07"
description="Minor release with new features and updated dependencies.">
diff --git a/src/main/java/org/apache/commons/configuration2/ImmutableConfiguration.java b/src/main/java/org/apache/commons/configuration2/ImmutableConfiguration.java
index 2f38816..a317119 100644
--- a/src/main/java/org/apache/commons/configuration2/ImmutableConfiguration.java
+++ b/src/main/java/org/apache/commons/configuration2/ImmutableConfiguration.java
@@ -318,7 +318,7 @@
* @return The associated Duration if key is found and has valid format, default value otherwise.
* @throws org.apache.commons.configuration2.ex.ConversionException is thrown if the key maps to an object that is not a
* Duration.
- * @since 2.8
+ * @since 2.8.0
*/
default Duration getDuration(final String key) {
final String string = getString(key);
@@ -336,7 +336,7 @@
* @return The associated Duration if key is found and has valid format, default value otherwise.
* @throws org.apache.commons.configuration2.ex.ConversionException is thrown if the key maps to an object that is not a
* Duration.
- * @since 2.8
+ * @since 2.8.0
*/
default Duration getDuration(final String key, final Duration defaultValue) {
final Object value = getProperty(key);
@@ -378,7 +378,7 @@
*
* @throws org.apache.commons.configuration2.ex.ConversionException is thrown if the key maps to an object that is not a
* String.
- * @since 2.8
+ * @since 2.8.0
*/
default <T extends Enum<T>> T getEnum(final String key, final Class<T> enumType) {
try {
@@ -400,7 +400,7 @@
*
* @throws org.apache.commons.configuration2.ex.ConversionException is thrown if the key maps to an object that is not a
* Enum.
- * @since 2.8
+ * @since 2.8.0
*/
default <T extends Enum<T>> T getEnum(final String key, final Class<T> enumType, final T defaultValue) {
final String strValue = getString(key, null);
diff --git a/src/main/java/org/apache/commons/configuration2/PropertiesConfigurationLayout.java b/src/main/java/org/apache/commons/configuration2/PropertiesConfigurationLayout.java
index 6cf2f03..b0f3fe6 100644
--- a/src/main/java/org/apache/commons/configuration2/PropertiesConfigurationLayout.java
+++ b/src/main/java/org/apache/commons/configuration2/PropertiesConfigurationLayout.java
@@ -228,7 +228,7 @@
*
* @param key the property key
* @param number the number of blank lines to add before this property definition
- * @since 2.8
+ * @since 2.8.0
*/
public void setBlankLinesBefore(final String key, final int number) {
fetchLayoutData(key).setBlankLines(number);
@@ -772,7 +772,7 @@
* Returns the number of blank lines before this property.
*
* @return the number of blank lines before this property
- * @since 2.8
+ * @since 2.8.0
*/
public int getBlankLines() {
return blankLines;
@@ -793,7 +793,7 @@
* Sets the number of properties before this property.
*
* @param blankLines the number of properties before this property
- * @since 2.8
+ * @since 2.8.0
*/
public void setBlankLines(final int blankLines) {
this.blankLines = blankLines;
diff --git a/src/main/java/org/apache/commons/configuration2/builder/FileBasedBuilderProperties.java b/src/main/java/org/apache/commons/configuration2/builder/FileBasedBuilderProperties.java
index 218479b..9035660 100644
--- a/src/main/java/org/apache/commons/configuration2/builder/FileBasedBuilderProperties.java
+++ b/src/main/java/org/apache/commons/configuration2/builder/FileBasedBuilderProperties.java
@@ -121,7 +121,7 @@
* @param url the {@code URL} location
* @param urlConnectionOptions options
* @return a reference to this object for method chaining
- * @since 2.8
+ * @since 2.8.0
*/
default T setURL(final URL url, final URLConnectionOptions urlConnectionOptions) {
return setURL(url);
diff --git a/src/main/java/org/apache/commons/configuration2/convert/PropertyConverter.java b/src/main/java/org/apache/commons/configuration2/convert/PropertyConverter.java
index 261c248..255beda 100644
--- a/src/main/java/org/apache/commons/configuration2/convert/PropertyConverter.java
+++ b/src/main/java/org/apache/commons/configuration2/convert/PropertyConverter.java
@@ -48,7 +48,7 @@
/**
* A utility class to convert the configuration properties into any type.
*
- * @since 2.8
+ * @since 2.8.0
*/
public final class PropertyConverter {
@@ -302,7 +302,7 @@
* @param value the value to convert
* @return the converted value
* @throws ConversionException thrown if the value cannot be converted to a Duration
- * @since 2.8
+ * @since 2.8.0
*/
public static Duration toDuration(final Object value) throws ConversionException {
if (value instanceof Duration) {
diff --git a/src/main/java/org/apache/commons/configuration2/interpol/ConfigurationInterpolator.java b/src/main/java/org/apache/commons/configuration2/interpol/ConfigurationInterpolator.java
index ba74a45..a5f859d 100644
--- a/src/main/java/org/apache/commons/configuration2/interpol/ConfigurationInterpolator.java
+++ b/src/main/java/org/apache/commons/configuration2/interpol/ConfigurationInterpolator.java
@@ -95,7 +95,7 @@
* {@link #getDefaultPrefixLookups()} method. Use of this property is only required
* in cases where the set of default lookups must be modified.
*
- * @since 2.8
+ * @since 2.8.0
*/
public static final String DEFAULT_PREFIX_LOOKUPS_PROPERTY =
"org.apache.commons.configuration2.interpol.ConfigurationInterpolator.defaultPrefixLookups";
diff --git a/src/main/java/org/apache/commons/configuration2/io/FileHandler.java b/src/main/java/org/apache/commons/configuration2/io/FileHandler.java
index 98f0941..387b3c5 100644
--- a/src/main/java/org/apache/commons/configuration2/io/FileHandler.java
+++ b/src/main/java/org/apache/commons/configuration2/io/FileHandler.java
@@ -1223,7 +1223,7 @@
*
* @param url the location of the file as URL
* @param urlConnectionOptions URL connection options
- * @since 2.8
+ * @since 2.8.0
*/
public void setURL(final URL url, final URLConnectionOptions urlConnectionOptions) {
new Updater() {
diff --git a/src/main/java/org/apache/commons/configuration2/io/FileSystem.java b/src/main/java/org/apache/commons/configuration2/io/FileSystem.java
index 080df55..20fa4bf 100644
--- a/src/main/java/org/apache/commons/configuration2/io/FileSystem.java
+++ b/src/main/java/org/apache/commons/configuration2/io/FileSystem.java
@@ -57,7 +57,7 @@
* @return TODO
* @throws ConfigurationException TODO
*
- * @since 2.8
+ * @since 2.8.0
*/
public InputStream getInputStream(final URL url, final URLConnectionOptions urlConnectionOptions) throws ConfigurationException {
return getInputStream(url);
diff --git a/src/main/java/org/apache/commons/configuration2/io/URLConnectionOptions.java b/src/main/java/org/apache/commons/configuration2/io/URLConnectionOptions.java
index aab377e..6a45943 100644
--- a/src/main/java/org/apache/commons/configuration2/io/URLConnectionOptions.java
+++ b/src/main/java/org/apache/commons/configuration2/io/URLConnectionOptions.java
@@ -25,7 +25,7 @@
/**
* Carries options and operates on {@link URLConnection}.
*
- * @since 2.8
+ * @since 2.8.0
*/
public final class URLConnectionOptions {
diff --git a/src/main/java/org/apache/commons/configuration2/tree/ImmutableNode.java b/src/main/java/org/apache/commons/configuration2/tree/ImmutableNode.java
index 8b309cc..a23c70f 100644
--- a/src/main/java/org/apache/commons/configuration2/tree/ImmutableNode.java
+++ b/src/main/java/org/apache/commons/configuration2/tree/ImmutableNode.java
@@ -303,7 +303,7 @@
/**
* @return An iterator of {@link #children child nodes.}
- * @since 2.8
+ * @since 2.8.0
*/
@Override
public Iterator<ImmutableNode> iterator() {
diff --git a/src/site/site.xml b/src/site/site.xml
index 9d7dc13..20c4644 100644
--- a/src/site/site.xml
+++ b/src/site/site.xml
@@ -37,7 +37,8 @@
<item name="Release History" href="/changes-report.html"/>
<item name="${project.version}" collapse="true" href="/index.html">
<item name="User's Guide" href="/userguide/user_guide.html"/>
- <item name="Upgrade Guide" href="/userguide/upgradeto2_0.html"/>
+ <item name="Upgrade Guide: 1.x to 2.0" href="/userguide/upgradeto2_0.html"/>
+ <item name="Upgrade Guide: 2.x" href="/userguide/upgradeto2_x.html"/>
<item name="Javadoc" href="/apidocs/index.html"/>
<item name="Runtime Dependencies" href="/dependencies.html"/>
</item>
diff --git a/src/site/xdoc/dependencies.xml b/src/site/xdoc/dependencies.xml
index a94b53c..51e55f9 100644
--- a/src/site/xdoc/dependencies.xml
+++ b/src/site/xdoc/dependencies.xml
@@ -32,12 +32,12 @@
Commons Configuration requires Java 8 or later.
</p>
<p>
- A lot of dependencies are declared in the Maven POM. These are all
- needed during compile time. On runtime however you only need to
- add the dependencies to your classpath that are required by the
- parts of the Commons Configuration package you are using. The
- following table helps you to determine which dependencies you
- have to include based on the components you intend to use:
+ Many dependencies are declared in the Maven POM, all of which
+ are required to build the project. However, at runtime, you only
+ need to add the dependencies to your classpath that are required
+ by the parts of the Commons Configuration package you are using.
+ The following table can help determine which dependencies are required
+ based on the components in use.
</p>
<table>
@@ -51,56 +51,60 @@
<tr>
<td>Core</td>
<td>
- commons-lang<br/>
- commons-logging
+ <a href="https://commons.apache.org/proper/commons-lang/">commons-lang3</a><br/>
+ <a href="https://commons.apache.org/proper/commons-text/">commons-text</a><br />
+ <a href="https://commons.apache.org/proper/commons-logging/">commons-logging</a>
</td>
</tr>
<tr>
<td>Configuration builders</td>
- <td>commons-beanutils</td>
+ <td><a href="https://commons.apache.org/proper/commons-beanutils/">commons-beanutils</a></td>
</tr>
<tr>
<td>
PropertyListConfiguration<br/>
XMLPropertyListConfiguration
</td>
- <td>commons-codec</td>
+ <td><a href="https://commons.apache.org/proper/commons-codec/">commons-codec</a></td>
</tr>
<tr>
<td>JSONConfiguration</td>
- <td>com.fasterxml.jackson.core:jackson-databind</td>
+ <td><a href="https://github.com/FasterXML/jackson-databind">com.fasterxml.jackson.core:jackson-databind</a></td>
</tr>
<tr>
<td>YAMLConfiguration</td>
- <td>org.yaml:snakeyaml</td>
+ <td><a href="https://github.com/snakeyaml/snakeyaml">org.yaml:snakeyaml</a></td>
</tr>
<tr>
<td>ConfigurationDynaBean</td>
- <td>commons-beanutils</td>
+ <td><a href="https://commons.apache.org/proper/commons-beanutils/">commons-beanutils</a></td>
</tr>
<tr>
<td>XPathExpressionEngine</td>
- <td>commons-jxpath</td>
+ <td><a href="https://commons.apache.org/proper/commons-jxpath/">commons-jxpath</a></td>
</tr>
<tr>
<td>CatalogResolver</td>
- <td>xml-resolver</td>
+ <td><a href="https://xerces.apache.org/xml-commons/components/resolver/">xml-resolver</a></td>
</tr>
<tr>
<td>Web configurations</td>
- <td>servlet-api</td>
+ <td><a href="https://javaee.github.io/servlet-spec/">servlet-api</a></td>
</tr>
<tr>
<td>ExprLookup</td>
- <td>commons-jexl</td>
+ <td><a href="https://commons.apache.org/proper/commons-jexl/">commons-jexl</a></td>
</tr>
<tr>
- <td>VFSFileSystem, VFSFileChangedReloadingStrategy</td>
- <td>commons-vfs</td>
+ <td>
+ VFSFileSystem<br />
+ VFSFileChangedReloadingStrategy
+ </td>
+ <td><a href="https://commons.apache.org/proper/commons-vfs/">commons-vfs2</a></td>
</tr>
<tr>
<td>ConfigPropertySource</td>
- <td>spring-core</td>
+ <td><a href="https://spring.io/projects/spring-framework">spring-core</a></td>
</tr>
</tbody>
</table>
diff --git a/src/site/xdoc/download_configuration.xml b/src/site/xdoc/download_configuration.xml
index e4164dd..b446112 100644
--- a/src/site/xdoc/download_configuration.xml
+++ b/src/site/xdoc/download_configuration.xml
@@ -113,32 +113,32 @@
</p>
</subsection>
</section>
- <section name="Apache Commons Configuration 2.8 (reworked 2.x version)">
+ <section name="Apache Commons Configuration 2.8.0 (reworked 2.x version)">
<subsection name="Binaries">
<table>
<tr>
- <td><a href="[preferred]/commons/configuration/binaries/commons-configuration2-2.8-bin.tar.gz">commons-configuration2-2.8-bin.tar.gz</a></td>
- <td><a href="https://www.apache.org/dist/commons/configuration/binaries/commons-configuration2-2.8-bin.tar.gz.sha512">sha512</a></td>
- <td><a href="https://www.apache.org/dist/commons/configuration/binaries/commons-configuration2-2.8-bin.tar.gz.asc">pgp</a></td>
+ <td><a href="[preferred]/commons/configuration/binaries/commons-configuration2-2.8.0-bin.tar.gz">commons-configuration2-2.8.0-bin.tar.gz</a></td>
+ <td><a href="https://www.apache.org/dist/commons/configuration/binaries/commons-configuration2-2.8.0-bin.tar.gz.sha512">sha512</a></td>
+ <td><a href="https://www.apache.org/dist/commons/configuration/binaries/commons-configuration2-2.8.0-bin.tar.gz.asc">pgp</a></td>
</tr>
<tr>
- <td><a href="[preferred]/commons/configuration/binaries/commons-configuration2-2.8-bin.zip">commons-configuration2-2.8-bin.zip</a></td>
- <td><a href="https://www.apache.org/dist/commons/configuration/binaries/commons-configuration2-2.8-bin.zip.sha512">sha512</a></td>
- <td><a href="https://www.apache.org/dist/commons/configuration/binaries/commons-configuration2-2.8-bin.zip.asc">pgp</a></td>
+ <td><a href="[preferred]/commons/configuration/binaries/commons-configuration2-2.8.0-bin.zip">commons-configuration2-2.8.0-bin.zip</a></td>
+ <td><a href="https://www.apache.org/dist/commons/configuration/binaries/commons-configuration2-2.8.0-bin.zip.sha512">sha512</a></td>
+ <td><a href="https://www.apache.org/dist/commons/configuration/binaries/commons-configuration2-2.8.0-bin.zip.asc">pgp</a></td>
</tr>
</table>
</subsection>
<subsection name="Source">
<table>
<tr>
- <td><a href="[preferred]/commons/configuration/source/commons-configuration2-2.8-src.tar.gz">commons-configuration2-2.8-src.tar.gz</a></td>
- <td><a href="https://www.apache.org/dist/commons/configuration/source/commons-configuration2-2.8-src.tar.gz.sha512">sha512</a></td>
- <td><a href="https://www.apache.org/dist/commons/configuration/source/commons-configuration2-2.8-src.tar.gz.asc">pgp</a></td>
+ <td><a href="[preferred]/commons/configuration/source/commons-configuration2-2.8.0-src.tar.gz">commons-configuration2-2.8.0-src.tar.gz</a></td>
+ <td><a href="https://www.apache.org/dist/commons/configuration/source/commons-configuration2-2.8.0-src.tar.gz.sha512">sha512</a></td>
+ <td><a href="https://www.apache.org/dist/commons/configuration/source/commons-configuration2-2.8.0-src.tar.gz.asc">pgp</a></td>
</tr>
<tr>
- <td><a href="[preferred]/commons/configuration/source/commons-configuration2-2.8-src.zip">commons-configuration2-2.8-src.zip</a></td>
- <td><a href="https://www.apache.org/dist/commons/configuration/source/commons-configuration2-2.8-src.zip.sha512">sha512</a></td>
- <td><a href="https://www.apache.org/dist/commons/configuration/source/commons-configuration2-2.8-src.zip.asc">pgp</a></td>
+ <td><a href="[preferred]/commons/configuration/source/commons-configuration2-2.8.0-src.zip">commons-configuration2-2.8.0-src.zip</a></td>
+ <td><a href="https://www.apache.org/dist/commons/configuration/source/commons-configuration2-2.8.0-src.zip.sha512">sha512</a></td>
+ <td><a href="https://www.apache.org/dist/commons/configuration/source/commons-configuration2-2.8.0-src.zip.asc">pgp</a></td>
</tr>
</table>
</subsection>
diff --git a/src/site/xdoc/userguide/howto_basicfeatures.xml b/src/site/xdoc/userguide/howto_basicfeatures.xml
index 4985240..ad06d64 100644
--- a/src/site/xdoc/userguide/howto_basicfeatures.xml
+++ b/src/site/xdoc/userguide/howto_basicfeatures.xml
@@ -207,7 +207,8 @@
<code>${prefix:name}</code>. The prefix tells Commons Configuration that
the variable is to be evaluated in a certain context. We have already seen
that the context is the current configuration instance if the prefix is
- missing. The following other prefix names are supported by default:
+ missing. The following table lists a few of the prefixes supported by default.
+ (See the next section for more details.)
<table border="1">
<tr>
<th>Prefix</th>
@@ -268,10 +269,46 @@
</p>
</subsection>
+ <subsection name="Default interpolation lookups">
+ <p>
+ Commons configuration comes with a number of default prefix interpolators in addition
+ to the few demonstrated above. The full list can be found in the documentation of
+ the <code><a href="../apidocs/org/apache/commons/configuration2/interpol/ConfigurationInterpolator.html#getDefaultPrefixLookups()">
+ ConfigurationInterpolator.getDefaultPrefixLookups()</a></code> method. This method returns a map of
+ standard interpolation lookup objects keyed by prefix, which are enabled by default in all
+ interpolation operations performed through the <code>Configuration</code> interface. Prior to version
+ <code>2.8.0</code>, this map was constant. However, starting in version <code>2.8.0</code>, the lookups
+ included in this map can be optionally configured via system property, allowing users greater control over the
+ types of interpolation performed in their applications. The system property in question is named
+ <code>org.apache.commons.configuration2.interpol.ConfigurationInterpolator.defaultPrefixLookups</code>
+ and is expected to contain a comma-separated list of names from the
+ <code><a href="../apidocs/org/apache/commons/configuration2/interpol/DefaultLookups.html">DefaultLookups</a></code>
+ enum. For example, launching an application with the system property given below will only enable the
+ <code>sys</code> and <code>env</code> lookups.
+ </p>
+<source><![CDATA[
+org.apache.commons.configuration2.interpol.ConfigurationInterpolator.defaultPrefixLookups=SYSTEM_PROPERTIES,ENVIRONMENT
+]]></source>
+ <p>
+ It is also important to note that starting in version <code>2.8.0</code>, several previously enabled
+ default lookups were changed to be disabled by default. These include the
+ <code><a href="../apidocs/org/apache/commons/configuration2/interpol/DefaultLookups.html#DNS">dns</a></code>,
+ <code><a href="../apidocs/org/apache/commons/configuration2/interpol/DefaultLookups.html#URL">url</a></code>, and
+ <code><a href="../apidocs/org/apache/commons/configuration2/interpol/DefaultLookups.html#SCRIPT">script</a></code> lookups.
+ These lookups are still present in the library but must be explicitly enabled by either
+ <ol>
+ <li>listing them in the system property described above (along with all other enabled lookups), or</li>
+ <li>adding them programmatically using the techniques laid out in the next section.</li>
+ </ol>.
+ Users who do not make use of these disabled lookups do not need to make any changes to their code or
+ deployment scripts when upgrading from previous versions to <code>2.8.0</code>.
+ </p>
+ </subsection>
+
<subsection name="Customizing interpolation">
<p>
This sub section goes a bit behind the scenes of interpolation and
- explains some approaches how you can add your own interpolation facilities.
+ explains some approaches for adding your own interpolation facilities.
Under the hood the implementation of interpolation relies on objects
implementing the
<code><a href="../apidocs/org/apache/commons/configuration2/interpol/Lookup.html">
diff --git a/src/site/xdoc/userguide/upgradeto2_0.xml b/src/site/xdoc/userguide/upgradeto2_0.xml
index e1096ac..cac2ebb 100644
--- a/src/site/xdoc/userguide/upgradeto2_0.xml
+++ b/src/site/xdoc/userguide/upgradeto2_0.xml
@@ -19,7 +19,7 @@
<document>
<properties>
- <title>Migration Guide for 2.0</title>
+ <title>Migration Guide: 1.x to 2.0</title>
</properties>
<body>
diff --git a/src/site/xdoc/userguide/upgradeto2_x.xml b/src/site/xdoc/userguide/upgradeto2_x.xml
new file mode 100644
index 0000000..8f3a915
--- /dev/null
+++ b/src/site/xdoc/userguide/upgradeto2_x.xml
@@ -0,0 +1,58 @@
+<?xml version="1.0"?>
+<!--
+ Licensed to the Apache Software Foundation (ASF) under one or more
+ contributor license agreements. See the NOTICE file distributed with
+ this work for additional information regarding copyright ownership.
+ The ASF licenses this file to You under the Apache License, Version 2.0
+ (the "License"); you may not use this file except in compliance with
+ the License. You may obtain a copy of the License at
+
+ http://www.apache.org/licenses/LICENSE-2.0
+
+ Unless required by applicable law or agreed to in writing, software
+ distributed under the License is distributed on an "AS IS" BASIS,
+ WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ See the License for the specific language governing permissions and
+ limitations under the License.
+-->
+
+<document>
+
+ <properties>
+ <title>Migration Guide: 2.x</title>
+ </properties>
+
+<body>
+ <section name="Migration Guide Between 2.x Versions">
+ <p>
+ This document aims to assist with the migration between different versions
+ within the 2.x line. While all Commons Configuration artifacts maintain binary
+ compatibility with previous versions with the same major number, there are
+ some behavioral and/or configuration differences that may need to be addressed when
+ upgrading.
+ </p>
+
+ <subsection name="v2.8.0">
+ <p>
+ Version 2.8.0 of <em>Commons Configuration</em> introduced a change in the variable interpolation lookups
+ included by default. In previous versions, all lookups defined in the
+ <code><a href="../apidocs/org/apache/commons/configuration2/interpol/DefaultLookups.html">DefaultLookups</a></code>
+ enum were included by default. With version 2.8.0, some of these lookups are disabled.
+ Specifically, the
+ <code><a href="../apidocs/org/apache/commons/configuration2/interpol/DefaultLookups.html#DNS">dns</a></code>,
+ <code><a href="../apidocs/org/apache/commons/configuration2/interpol/DefaultLookups.html#URL">url</a></code>, and
+ <code><a href="../apidocs/org/apache/commons/configuration2/interpol/DefaultLookups.html#SCRIPT">script</a></code>
+ lookups must now be enabled explicitly. As described in the
+ <a href="howto_basicfeatures.html#Default_interpolation_lookups">user guide</a>, this can be done either
+ programmatically or through a system property. If the behavior of previous versions must be maintained exactly
+ without changes to the code, then the following system property can be used:
+<source>
+org.apache.commons.configuration2.interpol.ConfigurationInterpolator.defaultPrefixLookups=BASE64_DECODER,BASE64_ENCODER,CONST,DATE,DNS,ENVIRONMENT,FILE,JAVA,LOCAL_HOST,PROPERTIES,RESOURCE_BUNDLE,SCRIPT,SYSTEM_PROPERTIES,URL,URL_DECODER,URL_ENCODER,XML
+</source>
+ If the disabled lookups listed above are not used by the target application, then no changes are required.
+ </p>
+ </subsection>
+ </section>
+</body>
+
+</document>
\ No newline at end of file
diff --git a/src/site/xdoc/userguide/user_guide.xml b/src/site/xdoc/userguide/user_guide.xml
index 0413dbf..a99edcf 100644
--- a/src/site/xdoc/userguide/user_guide.xml
+++ b/src/site/xdoc/userguide/user_guide.xml
@@ -50,6 +50,7 @@
<li><a href="howto_basicfeatures.html#Handling_of_missing_properties">Handling of missing properties</a></li>
<li><a href="howto_basicfeatures.html#List_handling">List handling</a></li>
<li><a href="howto_basicfeatures.html#Variable_Interpolation">Variable Interpolation</a></li>
+ <li><a href="howto_basicfeatures.html#Default_interpolation_lookups">Default interpolation lookups</a></li>
<li><a href="howto_basicfeatures.html#Customizing_interpolation">Customizing interpolation</a></li>
<li><a href="howto_basicfeatures.html#Using_Expressions">Using Expressions</a></li>
<li><a href="howto_basicfeatures.html#Data_type_conversions">Data type conversions</a></li>
