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
The following commit(s) were added to refs/heads/master by this push:
new 2102c20c Port site from Doxia 1 to 2
2102c20c is described below
commit 2102c20c2c28e9fe8eca7e33d044f568cf91fdce
Author: Gary D. Gregory <[email protected]>
AuthorDate: Fri Feb 7 10:42:14 2025 -0500
Port site from Doxia 1 to 2
Fix HTML
---
src/site/xdoc/userguide/howto_basicfeatures.xml | 19 +++++--
src/site/xdoc/userguide/howto_beans.xml | 17 ++++--
src/site/xdoc/userguide/howto_builders.xml | 11 +++-
src/site/xdoc/userguide/howto_combinedbuilder.xml | 19 +++----
.../xdoc/userguide/howto_combinedconfiguration.xml | 11 ++--
.../userguide/howto_compositeconfiguration.xml | 5 +-
src/site/xdoc/userguide/howto_concurrency.xml | 9 ++-
src/site/xdoc/userguide/howto_events.xml | 66 ++++++++++++----------
src/site/xdoc/userguide/howto_filebased.xml | 17 ++++--
src/site/xdoc/userguide/howto_hierarchical.xml | 12 ++--
src/site/xdoc/userguide/howto_multitenant.xml | 9 +--
src/site/xdoc/userguide/howto_properties.xml | 8 ++-
12 files changed, 119 insertions(+), 84 deletions(-)
diff --git a/src/site/xdoc/userguide/howto_basicfeatures.xml
b/src/site/xdoc/userguide/howto_basicfeatures.xml
index ad06d649..406d9106 100644
--- a/src/site/xdoc/userguide/howto_basicfeatures.xml
+++ b/src/site/xdoc/userguide/howto_basicfeatures.xml
@@ -16,8 +16,9 @@
limitations under the License.
-->
-<document>
-
+<document xmlns="http://maven.apache.org/XDOC/2.0";
+ xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance";
+ xsi:schemaLocation="http://maven.apache.org/XDOC/2.0
https://maven.apache.org/xsd/xdoc-2.0.xsd";>
<properties>
<title>Basic Features</title>
<author email="[email protected]">Oliver Heger</author>
@@ -209,6 +210,7 @@ application.title = ${application.name}
${application.version}
that the context is the current configuration instance if the prefix is
missing. The following table lists a few of the prefixes supported by
default.
(See the next section for more details.)
+ </p>
<table border="1">
<tr>
<th>Prefix</th>
@@ -237,6 +239,7 @@ application.title = ${application.name}
${application.version}
This is indicated by the <code>env</code> prefix.</td>
</tr>
</table>
+ <p>
Here are some examples (again using properties syntax):
</p>
<source><![CDATA[
@@ -249,6 +252,7 @@ java.home = ${env:JAVA_HOME}
<p>
Below is some more information related to variable interpolation users
should be aware of:
+ </p>
<ul>
<li>If a variable cannot be resolved, e.g. because the name is invalid
or an unknown prefix is used, it won't be replaced, but is returned as
@@ -266,7 +270,6 @@ java.home = ${env:JAVA_HOME}
exception is the generic <code>getProperty()</code> method which
returns the raw property value.</li>
</ul>
- </p>
</subsection>
<subsection name="Default interpolation lookups">
@@ -296,10 +299,12 @@
org.apache.commons.configuration2.interpol.ConfigurationInterpolator.defaultPref
<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
+ </p>
<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>.
+ </ol>
+ <p>
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>
@@ -495,6 +500,7 @@ int theAnswer = config.getInt("answer");
work in the same way: they obtain the actual value of the property and
attempt a data type conversion if necessary. In addition, there are
generic methods for accessing properties in specific data types:
+ </p>
<dl>
<dt><T> get(Class<T> cls, String key);</dt>
<dd>Obtains the value of the specified property and tries to convert it
@@ -506,6 +512,7 @@ int theAnswer = config.getInt("answer");
to the specified target type. If the key cannot be resolved, the
specified default value is returned (which may be <b>null</b>).</dd>
</dl>
+ <p>
In fact, all specialized <code>get()</code> methods are based on these
generic methods.
</p>
@@ -527,6 +534,7 @@ int[] result = config.getInt(int[].class, "myIntArrayKey");
necessary because the element type of the collection cannot be
determined automatically as in case of arrays). These are the following
ones:
+ </p>
<dl>
<dt><T> List<T> getList(Class<T> cls, String
key);</dt>
<dd>Returns a list of the specified element class.</dd>
@@ -537,7 +545,6 @@ int[] result = config.getInt(int[].class, "myIntArrayKey");
be stored in a different collection type, e.g. a set to remove
duplicates.</dd>
</dl>
- </p>
<p>
These methods obtain all values stored for the property with the
passed in key. For each value a conversion to the desired target type is
@@ -594,6 +601,7 @@ int[] result = config.getInt(int[].class, "myIntArrayKey");
conversions. <code>DefaultConversionHandler</code> has some protected
methods which can be overridden by subclasses in order to extend data
type
conversions:
+ </p>
<dl>
<dt><code>convertValue()</code></dt>
<dd>This is the main conversion method for single values. It is called
@@ -630,7 +638,6 @@ int[] result = config.getInt(int[].class, "myIntArrayKey");
in order to gain more control over the whole conversion process, this
method is a good candidate for overriding.</dd>
</dl>
- </p>
<p>
After a custom <code>ConversionHandler</code> implementation has been
created, it can be installed at a configuration instance by using the
diff --git a/src/site/xdoc/userguide/howto_beans.xml
b/src/site/xdoc/userguide/howto_beans.xml
index 155201d8..7c026a11 100644
--- a/src/site/xdoc/userguide/howto_beans.xml
+++ b/src/site/xdoc/userguide/howto_beans.xml
@@ -16,8 +16,9 @@
limitations under the License.
-->
-<document>
-
+<document xmlns="http://maven.apache.org/XDOC/2.0";
+ xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance";
+ xsi:schemaLocation="http://maven.apache.org/XDOC/2.0
https://maven.apache.org/xsd/xdoc-2.0.xsd";>
<properties>
<title>Declaring Beans Howto</title>
</properties>
@@ -70,6 +71,7 @@
</p>
<p>
On the Java side three entities are involved in the creation of a bean:
+ </p>
<ul>
<li>A <em>bean factory</em>: This is an object that implements the
<code><a
href="../apidocs/org/apache/commons/configuration2/beanutils/BeanFactory.html">BeanFactory</a></code>
@@ -89,6 +91,7 @@
one of the <code>createBean()</code> methods of
<code>BeanHelper</code>.
That's it!</li>
</ul>
+ <p>
For all of the interfaces mentioned above default implementations are
provided, which in many cases can be used out of the box.
</p>
@@ -157,6 +160,7 @@ public class DefaultWindowManager implements WindowManager
This XML document contains a valid bean declaration starting with the
<code>windowManager</code> element and including its sub elements. Note
the following points:
+ </p>
<ul>
<li>The (fully-qualified) class of the bean is specified using the
<code>config-class</code> attribute. (Attributes starting with the
@@ -171,6 +175,7 @@ public class DefaultWindowManager implements WindowManager
element; indeed it could even have further sub elements defining
bean properties of the <code>WindowStyleDefinition</code> class.</li>
</ul>
+ <p>
The basic structure of a bean declaration should have become clear by
this example.
</p>
@@ -206,6 +211,7 @@ WindowManager wm = (WindowManager)
BeanHelper.INSTANCE.createBean(decl);
declaration are evaluated and set on the newly created bean. The
<code>BeanFactory</code> to be used is determined based on the
bean helper's configuration:
+ </p>
<ul>
<li>A <code>BeanHelper</code> can be configured with a number of
<code>BeanFactory</code> objects that are registered under a specific
@@ -217,6 +223,7 @@ WindowManager wm = (WindowManager)
BeanHelper.INSTANCE.createBean(decl);
<code>BeanFactory</code> is set. This one is used if no specific
factory is referenced by the bean declaration.</li>
</ul>
+ <p>
If an application does not need special bean factories, it can use the
default <code>BeanHelper</code> instance which is available via the
static <code>INSTANCE</code> member field (as shown in the example
@@ -381,11 +388,11 @@ public class MyBean
As was pointed out in the introduction of this chapter, support for
creating
beans is focused on the basics. But there are some possibilities of
hooking
in and add custom extensions. This can be done in the following ways:
+ </p>
<ul>
<li>By defining a custom <code>BeanDeclaration</code>
implementation</li>
<li>By providing a custom <code>BeanFactory</code>
implementation</li>
</ul>
- </p>
<p>
A specialized bean declaration is needed when you have to deal with
configuration files that contain bean declarations in a different
format
@@ -394,6 +401,7 @@ public class MyBean
data and extract the required information to create the bean. Basically
your <code><a
href="../apidocs/org/apache/commons/configuration2/beanutils/BeanDeclaration.html">BeanDeclaration</a></code>
implementation must be able to provide the following data:
+ </p>
<ul>
<li>The name of the class for which an instance is to be
created.</li>
<li>The name of the bean factory that is used to create the bean.
Here
@@ -413,7 +421,6 @@ public class MyBean
processed bean (the names of these properties are again obtained from
the keys of the map).</li>
</ul>
- </p>
<p>
While creating a custom <code>BeanDeclaration</code> implementation
allows you to adapt the format of bean declarations in configuration
files,
@@ -421,6 +428,7 @@ public class MyBean
specialized implementation of the
<code><a
href="../apidocs/org/apache/commons/configuration2/beanutils/BeanFactory.html">BeanFactory</a></code>
interface. For this purpose the following steps are necessary:
+ </p>
<ol>
<li>Create a class implementing the <code>BeanFactory</code>
interface.
This interface is quite simple. It defines one method for creating an
@@ -432,7 +440,6 @@ public class MyBean
factory that should be used for creating the bean (unless this
factory
is used as the <code>BeanHelper</code>'s default bean factory).</li>
</ol>
- </p>
<p>
We will provide an example that covers all these steps. This example
deals with a <em>singleton</em> factory, i.e. an implementation of
diff --git a/src/site/xdoc/userguide/howto_builders.xml
b/src/site/xdoc/userguide/howto_builders.xml
index 8667be13..9605b7e8 100644
--- a/src/site/xdoc/userguide/howto_builders.xml
+++ b/src/site/xdoc/userguide/howto_builders.xml
@@ -16,8 +16,9 @@
limitations under the License.
-->
-<document>
-
+<document xmlns="http://maven.apache.org/XDOC/2.0";
+ xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance";
+ xsi:schemaLocation="http://maven.apache.org/XDOC/2.0
https://maven.apache.org/xsd/xdoc-2.0.xsd";>
<properties>
<title>Creating Configurations</title>
</properties>
@@ -85,6 +86,7 @@
builder implementations and defines a framework for creating and
initializing configuration objects. The functionality provided is as
follows:
+ </p>
<ul>
<li>When an instance of <code>BasicConfigurationBuilder</code> is
constructed the class of the <code>Configuration</code> implementation
@@ -107,6 +109,7 @@
instance to be created the next time <code>getConfiguration()</code>
is invoked.</li>
</ul>
+ <p>
Note that these methods are all properly synchronized so that the builder
class is thread-safe.
</p>
@@ -191,6 +194,7 @@ XMLBuilderParams xmlParams = params.xml()
now a short overview over the existing parameter objects and the
corresponding methods in the <code>Parameters</code> class should be
sufficient:
+ </p>
<table>
<tr>
<th><code>Parameters</code> method</th>
@@ -261,7 +265,6 @@ XMLBuilderParams xmlParams = params.xml()
DatabaseConfiguration</a></code>.</td>
</tr>
</table>
- </p>
<p>
After a parameters object has been created and initialized via its fluent
<code>set()</code> methods, it can be passed to a configuration builder's
@@ -359,6 +362,7 @@ XMLBuilderParams xmlParams = params.xml()
implementations in place that we want to register on a
<code>Parameters</code>
object. (The next section will focus on the implementation of handlers.)
In this example the following is to be achieved:
+ </p>
<ul>
<li>There is a <code>CommonDefaultsHandler</code> class setting
default initialization parameters to be applied for all configuration
@@ -371,6 +375,7 @@ XMLBuilderParams xmlParams = params.xml()
properties. This is implemented by a handler class called
<code>PropertiesDefaultHandler</code>.</li>
</ul>
+ <p>
The code for this initialization could look as follows:
</p>
<source><![CDATA[
diff --git a/src/site/xdoc/userguide/howto_combinedbuilder.xml
b/src/site/xdoc/userguide/howto_combinedbuilder.xml
index 5bbedf4b..95a8ed4e 100644
--- a/src/site/xdoc/userguide/howto_combinedbuilder.xml
+++ b/src/site/xdoc/userguide/howto_combinedbuilder.xml
@@ -16,8 +16,9 @@
limitations under the License.
-->
-<document>
-
+<document xmlns="http://maven.apache.org/XDOC/2.0";
+ xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance";
+ xsi:schemaLocation="http://maven.apache.org/XDOC/2.0
https://maven.apache.org/xsd/xdoc-2.0.xsd";>
<properties>
<title>Combining Configuration Sources</title>
</properties>
@@ -43,6 +44,7 @@
<code>CombinedConfigurationBuilder</code> is the option of choice for
applications that have to deal with multiple configuration sources. It
provides the following features:
+ </p>
<ul>
<li>Various configuration sources can be combined to a single
<a href="howto_combinedconfiguration.html">
@@ -57,7 +59,6 @@
<li><code>CombinedConfigurationBuilder</code> is extensible. Custom
configuration sources can be added.</li>
</ul>
- </p>
<p>
This document starts with some explanations of
<code>CombinedConfigurationBuilder</code> basics. Then the
<em>configuration
@@ -585,7 +586,6 @@ CombinedConfigurationBuilder builder =
configs.combinedBuilder("path/to/definiti
file to be loaded or further flags). Below is a list of all
tags which can be used out of the box:
</p>
- <p>
<dl>
<dt>properties</dt>
<dd>With this element properties files can be included. The name of
@@ -668,7 +668,6 @@ CombinedConfigurationBuilder builder =
configs.combinedBuilder("path/to/definiti
</ul>
</dd>
</dl>
- </p>
<p>
In the declaration of a configuration source it is possible to set
properties on the corresponding configuration objects. Configuration
@@ -714,7 +713,6 @@ CombinedConfigurationBuilder builder =
configs.combinedBuilder("path/to/definiti
<code>CombinedConfigurationBuilder</code> when it creates the objects.
These attributes are listed in the following table:
</p>
- <p>
<table border="1">
<tr>
<th>Attribute</th>
@@ -769,7 +767,6 @@ CombinedConfigurationBuilder builder =
configs.combinedBuilder("path/to/definiti
have any effect).</td>
</tr>
</table>
- </p>
<p>
<em>Note:</em> In older versions of Commons Configuration the attributes
<code>config-at</code> and <code>config-optional</code> were named
@@ -867,6 +864,7 @@ CombinedConfigurationBuilder builder =
configs.combinedBuilder("path/to/definiti
<p>
There are some more tags for specific use cases which can occur in the
header section of a configuration declaration:
+ </p>
<dl>
<dt>providers</dt>
<dd>This tag can be used to define new tags for including custom
@@ -916,7 +914,6 @@ CombinedConfigurationBuilder builder =
configs.combinedBuilder("path/to/definiti
variable name is passed to the lookup object, and the custom
implementation
can compute a suitable value.</dd>
</dl>
- </p>
<p>
<em>Note:</em> From time to time the question is raised whether there is
a
document type definition or a schema defining exactly the structure of a
@@ -1150,6 +1147,7 @@ trigger.start();
<code><a
href="../apidocs/org/apache/commons/configuration2/builder/combined/BaseConfigurationBuilderProvider.html">
BaseConfigurationBuilderProvider</a></code> class. When creating an
instance the following information has to be passed:
+ </p>
<ul>
<li>The fully-qualified name of the configuration builder class to be
used for the associated configuration source.</li>
@@ -1164,9 +1162,11 @@ trigger.start();
<li>A collection with parameter object classes supported by this
builder.</li>
</ul>
+ <p>
With this information, <code>BaseConfigurationBuilderProvider</code> can
create and configure a correct configuration builder object for a
specific
configuration source. In detail, it performs the following steps:
+ </p>
<ul>
<li>It determines the builder class to be used based on the presence
and
value of the <code>config-reload</code> attribute; this means that
either
@@ -1178,7 +1178,6 @@ trigger.start();
<li>The initialized parameter objects are passed to the configuration
builder's <code>configure()</code> method.</li>
</ul>
- </p>
<p>
For most cases, the functionality provided by
<code>BaseConfigurationBuilderProvider</code> should be sufficient. So
@@ -1302,6 +1301,7 @@ CombinedConfiguration config = builder.getConfiguration();
defined by the
<code><a
href="../apidocs/org/apache/commons/configuration2/builder/CombinedBuilderProperties.html">
CombinedBuilderProperties</a></code> interface. This includes
+ </p>
<ul>
<li>the configuration builder for obtaining the definition
configuration</li>
<li>the parameters object for the configuration builder for obtaining
the
@@ -1323,7 +1323,6 @@ CombinedConfiguration config = builder.getConfiguration();
<li>controlling the inheritance of builder parameters to child
configuration builders (see below).</li>
</ul>
- </p>
<p>
Specifying default settings for the configuration sources to be included
is a convenient feature. Often the configuration files to be included
diff --git a/src/site/xdoc/userguide/howto_combinedconfiguration.xml
b/src/site/xdoc/userguide/howto_combinedconfiguration.xml
index b669c456..401f0527 100644
--- a/src/site/xdoc/userguide/howto_combinedconfiguration.xml
+++ b/src/site/xdoc/userguide/howto_combinedconfiguration.xml
@@ -16,8 +16,9 @@
limitations under the License.
-->
-<document>
-
+<document xmlns="http://maven.apache.org/XDOC/2.0";
+ xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance";
+ xsi:schemaLocation="http://maven.apache.org/XDOC/2.0
https://maven.apache.org/xsd/xdoc-2.0.xsd";>
<properties>
<title>Combined Configurations</title>
<author email="[email protected]">Oliver Heger</author>
@@ -34,7 +35,6 @@
<a href="howto_compositeconfiguration.html#Composite Configuration
Details">previous
section</a>. There are the following differences however:
</p>
- <p>
<ul>
<li>A <code>CombinedConfiguration</code> is a truly
<a href="howto_xml.html#Hierarchical properties">hierarchical
@@ -55,7 +55,6 @@
configuration.</li>
<li>There is no concept of an <em>in memory configuration</em>.</li>
</ul>
- </p>
<subsection name="How it works">
<p>
@@ -435,6 +434,7 @@
]]></source></td><td width="60%">
<p>
The features that are significant in this file are:
+ </p>
<ul>
<li>In the gui section each of the child elements only appears once.
The level element
merges the attributes from the two files and uses the element value
of the first file.</li>
@@ -448,7 +448,6 @@
was not merged in this case.</li>
<li>Again, only Channel 3 from the first file was included.</li>
</ul>
- </p>
<p>
How the Channel elements ended up may not at first be obvious. The
<code>OverrideCombiner</code>
simply noticed that the Channels element had three child elements
named Channel and
@@ -662,6 +661,7 @@
]]></source></td><td width="60%">
<p>
The features that are significant in this file are:
+ </p>
<ul>
<li>In the gui section the elements were merged.</li>
<li>In the net section the elements were merged, with the exception
of the urls.</li>
@@ -672,7 +672,6 @@
<li>Channel 1 and Channel 2 were merged</li>
<li>Both Channel 3 elements appear as they were determined to not be
the same.</li>
</ul>
- </p>
<p>
When merging elements attributes play a critical role. If an element
has an attribute that
appears in both sources, the value of that attribute must be the same
for the elements to be
diff --git a/src/site/xdoc/userguide/howto_compositeconfiguration.xml
b/src/site/xdoc/userguide/howto_compositeconfiguration.xml
index 3bda1953..dad6f36a 100644
--- a/src/site/xdoc/userguide/howto_compositeconfiguration.xml
+++ b/src/site/xdoc/userguide/howto_compositeconfiguration.xml
@@ -16,8 +16,9 @@
limitations under the License.
-->
-<document>
-
+<document xmlns="http://maven.apache.org/XDOC/2.0";
+ xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance";
+ xsi:schemaLocation="http://maven.apache.org/XDOC/2.0
https://maven.apache.org/xsd/xdoc-2.0.xsd";>
<properties>
<title>Composite Configuration Details</title>
<author email="[email protected]">Eric Pugh</author>
diff --git a/src/site/xdoc/userguide/howto_concurrency.xml
b/src/site/xdoc/userguide/howto_concurrency.xml
index 311351f4..14567468 100644
--- a/src/site/xdoc/userguide/howto_concurrency.xml
+++ b/src/site/xdoc/userguide/howto_concurrency.xml
@@ -16,8 +16,9 @@
limitations under the License.
-->
-<document>
-
+<document xmlns="http://maven.apache.org/XDOC/2.0";
+ xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance";
+ xsi:schemaLocation="http://maven.apache.org/XDOC/2.0
https://maven.apache.org/xsd/xdoc-2.0.xsd";>
<properties>
<title>Configurations and Concurrent Access</title>
</properties>
@@ -76,6 +77,7 @@
<code>ReentrantReadWriteLock</code> class from the JDK. It implements
the typical behavior desired when accessing a configuration in a
multi-threaded environment:
+ </p>
<ul>
<li>An arbitrary number of threads can read the configuration
simultaneously.</li>
@@ -83,7 +85,6 @@
so if a thread changes configuration data, all other threads (readers
and writers) are blocked until the update operation is complete.</li>
</ul>
- </p>
<p>
The synchronizer associated with a Configuration can be changed at any
time by calling the <code>setSynchronizer()</code> method. The following
@@ -229,7 +230,6 @@ finally
corner cases which may occur when some of the more advanced configuration
classes are involved.
</p>
- <p>
<ul>
<li>All hierarchical configurations derived from
<code><a
href="../apidocs/org/apache/commons/configuration2/BaseHierarchicalConfiguration.html">
@@ -285,7 +285,6 @@ finally
actually only a single <code>Synchronizer</code> controlling the
access to all involved configurations.</li>
</ul>
- </p>
</subsection>
<subsection name="Read-only configurations">
diff --git a/src/site/xdoc/userguide/howto_events.xml
b/src/site/xdoc/userguide/howto_events.xml
index 3539a623..b42d5961 100644
--- a/src/site/xdoc/userguide/howto_events.xml
+++ b/src/site/xdoc/userguide/howto_events.xml
@@ -16,8 +16,9 @@
limitations under the License.
-->
-<document>
-
+<document xmlns="http://maven.apache.org/XDOC/2.0";
+ xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance";
+ xsi:schemaLocation="http://maven.apache.org/XDOC/2.0
https://maven.apache.org/xsd/xdoc-2.0.xsd";>
<properties>
<title>Configuration Events Howto</title>
<author email="[email protected]">Oliver Heger</author>
@@ -54,6 +55,7 @@
Users who are familiar with JavaFX will recognize some similarities to
the event mechanism used in this UI library. In the generation of
notifications the following components are involved:
+ </p>
<ul>
<li>An <em>event</em> object which contains all information about a
specific change which has happened.</li>
@@ -64,7 +66,6 @@
<li>An event listener which is invoked with an event object when
something happens for which it has been registered.</li>
</ul>
- </p>
<p>
The type parameters in the methods of the <code>EventSource</code>
interface ensure a type-safe registration of event listeners. As we will
@@ -83,6 +84,7 @@
<p>
<em>Commons Configuration</em> provides the following implementations of
the <code>Event Source</code> interface:
+ </p>
<dl>
<dt>Configuration objects</dt>
<dd>Each configuration allows registering event listeners and generates
@@ -95,7 +97,6 @@
<dd>Here events are generated when a change in a monitored
configuration
source was detected.</dd>
</dl>
- </p>
<p>
In the following sections these event sources are discussed in more
detail. But first we have to elaborate a bit more on the hierarchical
@@ -129,18 +130,20 @@
As an example, below is an excerpt of the hierarchy of event types for
events related to configuration updates (the full hierarchy is described
in a later section):
- <ul>
- <li>Event.ANY</li>
+ </p>
+ <ul>
+ <li>Event.ANY
<ul>
- <li>ConfigurationEvent.ANY</li>
- <ul>
- <li>ConfigurationEvent.ADD_PROPERTY</li>
- <li>ConfigurationEvent.SET_PROPERTY</li>
- <li>...</li>
- </ul>
+ <li>ConfigurationEvent.ANY
+ <ul>
+ <li>ConfigurationEvent.ADD_PROPERTY</li>
+ <li>ConfigurationEvent.SET_PROPERTY</li>
+ <li>...</li>
+ </ul>
+ </li>
</ul>
- </ul>
- </p>
+ </li>
+ </ul>
<p>
An <code>EventListener<ConfigurationEvent></code> can be
registered for the generic event type <code>ConfigurationEvent.ANY</code>
@@ -185,6 +188,7 @@ config.addEventListener(ConfigurationEvent.ADD_PROPERTY,
listener);
the properties inherited from the <code>Event</code> base class, a
configuration event contains all information available about the
modification:
+ </p>
<ul>
<li>If available, the name of the property whose modification caused
the
event.</li>
@@ -195,6 +199,7 @@ config.addEventListener(ConfigurationEvent.ADD_PROPERTY,
listener);
is performed. This allows event listeners to react at the correct point
of time.</li>
</ul>
+ <p>
Depending on the concrete event type not all of this data may be
available.
</p>
<p>
@@ -204,14 +209,13 @@ config.addEventListener(ConfigurationEvent.ADD_PROPERTY,
listener);
hierarchy of these event types is listed below, together with a
description of the specific types and their available properties:
</p>
- <p>
- <ul>
- <li><strong>Event.ANY</strong></li>
+ <ul>
+ <li><strong>Event.ANY</strong>
<ul>
<li><strong>ConfigurationEvent.ANY</strong> is a placeholder for all
types
of configuration update events. A listener registered for this
event type is actually invoked for each manipulation of the source
- configuration.</li>
+ configuration.
<ul>
<li><strong>ADD_PROPERTY</strong> A property was added to the
configuration. The event object contains the name of the affected
@@ -228,7 +232,7 @@ config.addEventListener(ConfigurationEvent.ADD_PROPERTY,
listener);
<li><strong>ANY_HIERARCHICAL</strong> This is a common super type
for all events specific to hierarchical configurations. The event
types derived from this type correspond to the special update
- methods supported by hierarchical configurations.</li>
+ methods supported by hierarchical configurations.
<ul>
<li><strong>ADD_NODES</strong> A collection of nodes was added to
a hierarchical configuration. The event contains the key passed
@@ -243,10 +247,12 @@ config.addEventListener(ConfigurationEvent.ADD_PROPERTY,
listener);
contains the original event object as it was sent by the subnode
configuration.</li>
</ul>
+ </li>
</ul>
+ </li>
</ul>
- </ul>
- </p>
+ </li>
+ </ul>
<p>
After all the theory about the different event types, let's come to a
concrete example. Implementing an event listener for configuration
@@ -341,10 +347,11 @@ config.clearProperty("removedProperty"); // but this one
will
exception causing this event.
</p>
<p>
- <code>ConfigurationErrorEvent</code> defines some new event type
constants.
+ <code>ConfigurationErrorEvent</code> defines some new event type constants.
They build up the following hierarchy:
- <ul>
- <li><strong>Event.ANY</strong></li>
+ </p>
+ <ul>
+ <li><strong>Event.ANY</strong>
<ul>
<li><strong>ConfigurationErrorEvent.ANY</strong> The common super
type
of all error events. An event listener registered for this type can
@@ -359,8 +366,8 @@ config.clearProperty("removedProperty"); // but this one
will
update method (e.g. <em>ConfigurationEvent.ADD_PROPERTY</em> if a
property could not be added).</li>
</ul>
- </ul>
- </p>
+ </li>
+ </ul>
<p>
We could now continue the example from the previous section and make our
sample logging event listener also capable of tracing error events.
@@ -396,6 +403,7 @@ config.clearProperty("removedProperty"); // but this one
will
<a href="howto_builders.html">Configuration builders</a> also offer
support for the event mechanism in <em>Commons Configuration</em>. There
are the following aspects:
+ </p>
<ul>
<li>Configuration builders can generate events themselves; for
instance,
events are fired when a managed configuration is created or reset.</li>
@@ -411,7 +419,6 @@ config.clearProperty("removedProperty"); // but this one
will
ensures that all listeners are automatically added to a newly created
configuration instance and removed from an obsolete instance.</li>
</ul>
- </p>
<p>
For the events generated by a configuration builder a new event class is
introduced: <code><a
href="../apidocs/org/apache/commons/configuration2/builder/ConfigurationBuilderEvent.html">
@@ -434,8 +441,9 @@ config.clearProperty("removedProperty"); // but this one
will
The full hierarchy of event types related to configuration builders is
shown below. As usual, <code>EventType</code> constants are defined in
the event classes:
+ </p>
<ul>
- <li>Event.ANY</li>
+ <li>Event.ANY
<ul>
<li><strong>ConfigurationBuilderEvent.ANY</strong> A common super
type
for all events produced by a configuration builder. An event listener
@@ -462,8 +470,8 @@ config.clearProperty("removedProperty"); // but this one
will
obtained from the event so that specific initializations can be
performed.</li>
</ul>
+ </li>
</ul>
- </p>
<p>
As an example of how to use event listeners for builders we are going to
make use of the <em>RESULT_CREATED</em> event type: every time a managed
diff --git a/src/site/xdoc/userguide/howto_filebased.xml
b/src/site/xdoc/userguide/howto_filebased.xml
index e7ad160b..af46e909 100644
--- a/src/site/xdoc/userguide/howto_filebased.xml
+++ b/src/site/xdoc/userguide/howto_filebased.xml
@@ -16,8 +16,9 @@
limitations under the License.
-->
-<document>
-
+<document xmlns="http://maven.apache.org/XDOC/2.0";
+ xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance";
+ xsi:schemaLocation="http://maven.apache.org/XDOC/2.0
https://maven.apache.org/xsd/xdoc-2.0.xsd";>
<properties>
<title>File-based Configurations</title>
<author email="[email protected]">Oliver Heger</author>
@@ -58,6 +59,7 @@
FileBasedBuilderProperties</a></code> interface can be passed to the
builder's <code>configure()</code> method. Using this interface the
location of the file to be loaded can be provided in multiple ways:
+ </p>
<ul>
<li>With the <code>setFile()</code> method the data file can be
specified as a <code>java.io.File</code> object.</li>
@@ -69,6 +71,7 @@
<li>With <code>setPath()</code> an absolute path to the file to be
loaded can be provided.</li>
</ul>
+ <p>
A parameters object for file-based configurations is typically
obtained
from a <code><a
href="../apidocs/org/apache/commons/configuration2/builder/fluent/Parameters.html">
Parameters</a></code> instance. Here the <code>fileBased()</code>
method
@@ -308,6 +311,7 @@ PropertyListConfiguration config =
builder.getConfiguration();
<p>
<code>FileHandler</code> has the two methods <code>load()</code> and
<code>save()</code>. They work as follows:
+ </p>
<ul>
<li>The location of the managed file is evaluated, and a
corresponding
stream is opened. Depending on the way the location was specified,
@@ -318,7 +322,6 @@ PropertyListConfiguration config =
builder.getConfiguration();
<code>FileBased</code>'s <code>read()</code> or
<code>write()</code>
method.</li>
</ul>
- </p>
<p>
Next to these simple <code>load()</code> and <code>save()</code>
methods a number of overloaded methods exists which expect additional
@@ -329,6 +332,7 @@ PropertyListConfiguration config =
builder.getConfiguration();
methods for all the supported variants for defining a file. When
making use of these methods the following points have to be kept in
mind:
+ </p>
<ul>
<li>The location stored in the <code>FileHandler</code> instance is
not changed; it is completely by-passed by these methods. Only
@@ -345,7 +349,6 @@ PropertyListConfiguration config =
builder.getConfiguration();
<code>clear()</code> method first to ensure that old properties are
wiped out.</li>
</ul>
- </p>
<p>
When constructing a <code>FileHandler</code> instance the
<code>FileBased</code> object it operates on has to be passed to the
@@ -412,10 +415,12 @@ handler.save(out);
<p>
<em>Commons Configuration</em> provides two mechanisms to customize
the
way configuration files are accessed:
+ </p>
<ul>
<li>File systems</li>
<li>File location strategies</li>
</ul>
+ <p>
They are described in the following sub sections.
</p>
</subsection>
@@ -514,7 +519,6 @@ URL locate(FileSystem fileSystem, FileLocator locator);
following table describes the available
<code>FileLocationStrategy</code>
implementations:
</p>
- <p>
<table>
<tr>
<th>Location Strategy class</th>
@@ -609,15 +613,16 @@ URL locate(FileSystem fileSystem, FileLocator locator);
</td>
</tr>
</table>
- </p>
<p>
As an example, consider that an application wants configuration files
to be looked up (in this order)
+ </p>
<ul>
<li>by their URL</li>
<li>by the file system (which will evaluate base path and file
name)</li>
<li>on the classpath</li>
</ul>
+ <p>
Then a concrete location strategy could be constructed as follows:
</p>
<source><![CDATA[
diff --git a/src/site/xdoc/userguide/howto_hierarchical.xml
b/src/site/xdoc/userguide/howto_hierarchical.xml
index 589b6424..accc3b85 100644
--- a/src/site/xdoc/userguide/howto_hierarchical.xml
+++ b/src/site/xdoc/userguide/howto_hierarchical.xml
@@ -16,8 +16,9 @@
limitations under the License.
-->
-<document>
-
+<document xmlns="http://maven.apache.org/XDOC/2.0";
+ xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance";
+ xsi:schemaLocation="http://maven.apache.org/XDOC/2.0
https://maven.apache.org/xsd/xdoc-2.0.xsd";>
<properties>
<title>Hierarchical Configurations</title>
</properties>
@@ -47,6 +48,7 @@
but the information provided here (especially the rules for accessing
properties) applies to other hierarchical configurations as well.
Examples for other hierarchical configuration classes are
+ </p>
<ul>
<li><code><a
href="../apidocs/org/apache/commons/configuration2/CombinedConfiguration.html">
CombinedConfiguration</a></code></li>
@@ -59,8 +61,6 @@
<li><code><a
href="../apidocs/org/apache/commons/configuration2/YAMLConfiguration.html">
YAMLConfiguration</a></code></li>
</ul>
- </p>
-
<subsection name="Accessing properties in hierarchical configurations">
<p>
We will start with a simple XML document to show some basics
@@ -133,6 +133,7 @@ List<Object> buttons = config.getList("buttons.name");
This listing demonstrates some important points about constructing the
keys for accessing properties in hierarchical configuration sources and
about
features of <code>HierarchicalConfiguration</code> in general:
+ </p>
<ul>
<li>
Nested elements are accessed using a dot notation. In
@@ -181,7 +182,6 @@ List<Object> buttons = config.getList("buttons.name");
using list splitting is rather untypical for this format.
</li>
</ul>
- </p>
<p>
The next section will show how data in a more complex XML
document can be processed.
@@ -323,6 +323,7 @@ if(prop instanceof Collection)
<p>
We will now provide some configuration keys and show the results
of a <code>getProperty()</code> call with these keys as arguments.
+ </p>
<dl>
<dt><code>tables.table(0).name</code></dt>
<dd>
@@ -368,7 +369,6 @@ if(prop instanceof Collection)
values [<em>long, long</em>].
</dd>
</dl>
- </p>
<p>
These examples should make the usage of indices quite clear.
Because each configuration key can contain an arbitrary number
diff --git a/src/site/xdoc/userguide/howto_multitenant.xml
b/src/site/xdoc/userguide/howto_multitenant.xml
index 7a4bf690..2ffdfdc2 100644
--- a/src/site/xdoc/userguide/howto_multitenant.xml
+++ b/src/site/xdoc/userguide/howto_multitenant.xml
@@ -16,8 +16,9 @@
limitations under the License.
-->
-<document>
-
+<document xmlns="http://maven.apache.org/XDOC/2.0";
+ xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance";
+ xsi:schemaLocation="http://maven.apache.org/XDOC/2.0
https://maven.apache.org/xsd/xdoc-2.0.xsd";>
<properties>
<title>Mutli-tenant Configurations</title>
<author email="[email protected]">Ralph Goers</author>
@@ -132,6 +133,7 @@
In this example configuration definition file for a
<code>CombinedConfigurationBuilder</code> two configuration sources
are declared:
+ </p>
<ul>
<li>A multi-file source with a file pattern containing a system
property. This means that depending on the current value of this
@@ -143,7 +145,6 @@
default values in case no configuration file could be loaded by the
multi-file source.</li>
</ul>
- </p>
<p>
Of special importance is the declaration of the result configuration
in form of the <code><result></code> element in the
<em>header</em>
@@ -184,6 +185,7 @@
configuration type are defined by the
<code><a
href="../apidocs/org/apache/commons/configuration2/builder/MultiFileBuilderProperties.html">
MultiFileBuilderProperties</a></code> interface. They include
+ </p>
<ul>
<li>The pattern string for determining the name of the
configuration file to be loaded. This is of course the most
@@ -195,7 +197,6 @@
configuration files to be loaded are XML documents, validation
could be enabled via these parameters.</li>
</ul>
- </p>
<p>
Below is a code fragment demonstrating the set up of a
<code>MultiFileConfigurationBuilder</code> which loads configuration
diff --git a/src/site/xdoc/userguide/howto_properties.xml
b/src/site/xdoc/userguide/howto_properties.xml
index ad073bad..64ed2613 100644
--- a/src/site/xdoc/userguide/howto_properties.xml
+++ b/src/site/xdoc/userguide/howto_properties.xml
@@ -16,7 +16,9 @@
limitations under the License.
-->
-<document>
+<document xmlns="http://maven.apache.org/XDOC/2.0";
+ xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance";
+ xsi:schemaLocation="http://maven.apache.org/XDOC/2.0
https://maven.apache.org/xsd/xdoc-2.0.xsd";>
<properties>
<title>Properties files</title>
<author email="[email protected]">Emmanuel Bourg</author>
@@ -331,6 +333,7 @@ config.dirs = \\\\share2
control over the output of properties files is needed. The following
list describes these methods (note that corresponding get methods are
of course also provided):
+ </p>
<ul>
<li><code>setComment()</code><br/>
With this method a comment can be set for a specified property. When
@@ -378,6 +381,7 @@ config.dirs = \\\\share2
platform-specific line separator is used (e.g. <code>\n</code> on
Unix).
</li>
</ul>
+ <p>
The default settings of <code>PropertiesConfigurationLayout</code> are
chosen in a way that most of the original layout of a properties file
is retained. With the methods listed above specific layout restrictions
@@ -532,6 +536,7 @@ Configuration config = builder.getConfiguration();
settings specific to properties files which are defined by the
<code><a
href="../apidocs/org/apache/commons/configuration2/builder/PropertiesBuilderProperties.html">
PropertiesBuilderProperties</a></code> interface. These include
+ </p>
<ul>
<li>A flag whether <a href="#Includes">include files</a> are
supported.
This is <strong>true</strong> by default, but can be switched off if
@@ -540,7 +545,6 @@ Configuration config = builder.getConfiguration();
<li>A custom <a href="#Custom_properties_readers_and_writers">I/O
factory</a>.</li>
</ul>
- </p>
<p>
A parameters object for a properties configuration can be obtained
using
the <code>properties()</code> method of a
