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 <[email protected]> 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>
