diff --git a/src/site/xdoc/userguide/howto_reloading.xml b/src/site/xdoc/userguide/howto_reloading.xml index 2c53b15f34..8a5d358484 100644 --- a/src/site/xdoc/userguide/howto_reloading.xml +++ b/src/site/xdoc/userguide/howto_reloading.xml @@ -16,8 +16,9 @@ limitations under the License. --> - - + Reloading @@ -58,6 +59,7 @@ a configuration source actively for changes; it only has to be able to detect a change when it is triggered. This is reflected in the methods defined by the ReloadingDetector interface: +

-

The next component taking part in reloading is an instance of the @@ -249,6 +250,7 @@ trigger.start(); parameters for file-based configurations and defined by the FileBasedBuilderProperties interface: +

  • The ReloadingDetectorFactory to be used when the reloading @@ -263,7 +265,6 @@ trigger.start(); value can be used to improve performance if there are many accesses to a configuration builder in short intervals.
-

@@ -294,6 +295,7 @@ trigger.start();

So the recipe to activate reloading for a builder instance is as follows: +

  • Create and initialize the builder instance as usual.
  • Create a ReloadingDetector which is able to monitor @@ -311,7 +313,6 @@ trigger.start(); of time (e.g. initiate a corresponding trigger as described earlier in this chapter.
-

diff --git a/src/site/xdoc/userguide/howto_utilities.xml b/src/site/xdoc/userguide/howto_utilities.xml index 1719bf1e33..43b402dbef 100644 --- a/src/site/xdoc/userguide/howto_utilities.xml +++ b/src/site/xdoc/userguide/howto_utilities.xml @@ -16,8 +16,9 @@ limitations under the License. --> - - + Utility classes and Tips and Tricks Howto Oliver Heger @@ -41,6 +42,7 @@ AbstractConfiguration class (which serves as the base class for most of the configuration implementations shipped with this library) provides two methods implementing a basic copy operation: +

-

These methods work fine if the target configuration is not a hierarchical configuration. If a hierarchical configuration is to be copied into @@ -58,6 +59,7 @@ properties of the source configuration, but the specific parent-child relations will probably be lost. If a hierarchical configuration needs to be copied, there are the following options: +

-

@@ -364,12 +365,13 @@ Configuration config = wrapperFactory.createBuilderConfigurationWrapper( with Spring's PropertiesLoaderSupport. This allows a configuration object to behave +

  • like a normal java.util.Properties object which can be passed on to
  • setProperties() method allowing PropertyOverrideConfigurer and
  • PropertyPlaceholderConfigurer to take advantage of Commons Configuration.
- +

Previously this functionality was provided by the spring-modules-jakarta-commons library (CommonsConfigurationFactoryBean). As this library is no longer maintained, this is now supported directly by Commons Configuration. If you've used this with Commons Configuration 1.x, just replace the spring-modules-jakarta-commons classname with diff --git a/src/site/xdoc/userguide/howto_xml.xml b/src/site/xdoc/userguide/howto_xml.xml index f39d269351..0b315a736c 100644 --- a/src/site/xdoc/userguide/howto_xml.xml +++ b/src/site/xdoc/userguide/howto_xml.xml @@ -16,8 +16,9 @@ limitations under the License. --> - - + XML Configurations @@ -260,6 +261,7 @@ XMLConfiguration config = builder.getConfiguration(); XMLBuilderProperties interface defines settings specific to XML configurations. This includes +

  • a custom DocumentBuilder
  • a custom EntityResolver
    • @@ -267,7 +269,6 @@ XMLConfiguration config = builder.getConfiguration(); validation is to be performed
  • the public and the system ID of the document when it is written
-

A parameters object for an XML configuration can be obtained using the xml() method of a diff --git a/src/site/xdoc/userguide/overview.xml b/src/site/xdoc/userguide/overview.xml index a1eb3b7602..342f3f7fa7 100644 --- a/src/site/xdoc/userguide/overview.xml +++ b/src/site/xdoc/userguide/overview.xml @@ -16,7 +16,9 @@ limitations under the License. --> - + Configuration Overview Eric Pugh @@ -45,6 +47,7 @@ by just using a Configuration object versus a specific type like XMLConfiguration or JNDIConfiguration, you are sheltered from the mechanics of actually retrieving the configuration values. These various sources include: +

  • EnvironmentConfiguration @@ -90,8 +93,6 @@ and converts it to a Configuration object.
- -

@@ -124,6 +125,7 @@ overloaded variants of all methods that allow to specify a default value, which will be returned if the property cannot be found. The following data types are supported out of the box: +

  • BigDecimal
  • BigInteger
    • @@ -136,6 +138,7 @@
  • short
  • String
+

The names of these methods start with get followed by their data type. The getString() method for instance will return String values, getInt() will operate on integers. @@ -164,6 +167,7 @@

For manipulating properties or their values the following methods can be used: +

addProperty()
Adds a new property to the configuration. If this property already @@ -178,7 +182,6 @@
clear()
Wipes out the whole configuration
-

diff --git a/src/site/xdoc/userguide/quick_start.xml b/src/site/xdoc/userguide/quick_start.xml index fc857ffd67..e521f9ee26 100644 --- a/src/site/xdoc/userguide/quick_start.xml +++ b/src/site/xdoc/userguide/quick_start.xml @@ -16,8 +16,9 @@ limitations under the License. --> - - + Quick start diff --git a/src/site/xdoc/userguide/upgradeto2_0.xml b/src/site/xdoc/userguide/upgradeto2_0.xml index cac2ebb80f..967360bc5d 100644 --- a/src/site/xdoc/userguide/upgradeto2_0.xml +++ b/src/site/xdoc/userguide/upgradeto2_0.xml @@ -16,8 +16,9 @@ limitations under the License. --> - - + Migration Guide: 1.x to 2.0 @@ -31,7 +32,6 @@ areas in which major changes have been implemented; here problems are likely to be encountered during migration. It has the following content:

-

-

@@ -207,6 +206,7 @@ config.setListDelimiter(';'); ]]>

While this code is easy to write, there are some non-obvious problems: +

  • Some settings influence the loading of the configuration data. In this example, the definition of the list delimiter and the @@ -219,7 +219,6 @@ config.setListDelimiter(';');
  • The various set methods are not thread-safe; if this configuration instance is to be accessed from another thread, there may be problems.
-

To overcome these problems, Commons Configuration uses a different approach for the creation of configuration objects based on @@ -310,11 +309,11 @@ PropertiesConfiguration config = builder.getConfiguration(); creating a combined configuration out of multiple sources: +

  • The already deprecated ConfigurationFactory class
  • The DefaultConfigurationBuilder class
-

The former has been removed. The functionality provided by DefaultConfigurationBuilder is still available, but the @@ -411,6 +410,7 @@ PropertiesConfiguration config = builder.getConfiguration(); thread, there is no need for any synchronization. Typical usage modes are reflected by different default implementations of the Synchronizer interface: +

  • NoOpSynchronizer does not use any synchronization at all. @@ -420,6 +420,7 @@ PropertiesConfiguration config = builder.getConfiguration(); ReadWriteSynchronizer implements synchronization based on a read/write lock.
+

Note that the default option is NoOpSynchronizer. This means that configuration objects are not thread-safe per default! You have to change the synchronizer in order to make them safe for concurrent access. @@ -444,6 +445,7 @@ PropertiesConfiguration config = builder.getConfiguration();

There are some other changes on classes with the goal to make them well-behaving citizens in a concurrent environment. This includes: +

  • Some classes have been made immutable, passing all information to the constructor rather than using bean-style properties for their @@ -457,7 +459,6 @@ PropertiesConfiguration config = builder.getConfiguration(); CONFIGURATION-486 for further details.
-

Please refer to Configurations and Concurrent Access for a full description of this complex topic. diff --git a/src/site/xdoc/userguide/upgradeto2_x.xml b/src/site/xdoc/userguide/upgradeto2_x.xml index 8f3a9154b1..6ce5115538 100644 --- a/src/site/xdoc/userguide/upgradeto2_x.xml +++ b/src/site/xdoc/userguide/upgradeto2_x.xml @@ -16,8 +16,9 @@ limitations under the License. --> - - + Migration Guide: 2.x diff --git a/src/site/xdoc/userguide/user_guide.xml b/src/site/xdoc/userguide/user_guide.xml index a99edcf0e4..8f0860d766 100644 --- a/src/site/xdoc/userguide/user_guide.xml +++ b/src/site/xdoc/userguide/user_guide.xml @@ -16,8 +16,9 @@ limitations under the License. --> - - + Commons Configuration User's Guide @@ -38,14 +39,15 @@