You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@commons.apache.org by ma...@apache.org on 2022/06/30 03:35:57 UTC
[commons-configuration] 02/03: adding documentation for interpolation changes
This is an automated email from the ASF dual-hosted git repository.
mattjuntunen pushed a commit to branch master
in repository https://gitbox.apache.org/repos/asf/commons-configuration.git
commit fe09a3c6308da151526478f2192a5af240b2c347
Author: Matt Juntunen <ma...@apache.org>
AuthorDate: Wed Jun 29 23:35:09 2022 -0400
adding documentation for interpolation changes
---
src/site/site.xml | 3 +-
src/site/xdoc/userguide/howto_basicfeatures.xml | 41 ++++++++++++++++-
src/site/xdoc/userguide/upgradeto2_0.xml | 2 +-
src/site/xdoc/userguide/upgradeto2_x.xml | 58 +++++++++++++++++++++++++
src/site/xdoc/userguide/user_guide.xml | 1 +
5 files changed, 101 insertions(+), 4 deletions(-)
diff --git a/src/site/site.xml b/src/site/site.xml
index 9d7dc13e..20c46445 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/userguide/howto_basicfeatures.xml b/src/site/xdoc/userguide/howto_basicfeatures.xml
index 4985240e..ad06d649 100644
--- a/src/site/xdoc/userguide/howto_basicfeatures.xml
+++ b/src/site/xdoc/userguide/howto_basicfeatures.xml
@@ -207,7 +207,8 @@ application.title = ${application.name} ${application.version}
<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 @@ java.home = ${env:JAVA_HOME}
</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 e1096acf..cac2ebb8 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 00000000..8f3a9154
--- /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 0413dbf2..a99edcf0 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>