Author: oheger
Date: Mon Oct 5 20:01:32 2015
New Revision: 1706911
URL: http://svn.apache.org/viewvc?rev=1706911&view=rev
Log:
[CONFIGURATION-612] Changed return type of configuration builders.
All configuration builders now return the base interface ImmutableConfiguration
rather than Configuration. Thanks to Jon Weygand for the patch.
Modified:
commons/proper/configuration/trunk/src/main/java/org/apache/commons/configuration2/builder/BasicConfigurationBuilder.java
commons/proper/configuration/trunk/src/main/java/org/apache/commons/configuration2/builder/BuilderConfigurationWrapperFactory.java
commons/proper/configuration/trunk/src/main/java/org/apache/commons/configuration2/builder/ConfigurationBuilder.java
commons/proper/configuration/trunk/src/main/java/org/apache/commons/configuration2/builder/ConfigurationBuilderResultCreatedEvent.java
commons/proper/configuration/trunk/src/main/java/org/apache/commons/configuration2/builder/combined/MultiFileConfigurationBuilderProvider.java
commons/proper/configuration/trunk/src/site/xdoc/userguide/howto_utilities.xml
Modified:
commons/proper/configuration/trunk/src/main/java/org/apache/commons/configuration2/builder/BasicConfigurationBuilder.java
URL:
http://svn.apache.org/viewvc/commons/proper/configuration/trunk/src/main/java/org/apache/commons/configuration2/builder/BasicConfigurationBuilder.java?rev=1706911&r1=1706910&r2=1706911&view=diff
==============================================================================
---
commons/proper/configuration/trunk/src/main/java/org/apache/commons/configuration2/builder/BasicConfigurationBuilder.java
(original)
+++
commons/proper/configuration/trunk/src/main/java/org/apache/commons/configuration2/builder/BasicConfigurationBuilder.java
Mon Oct 5 20:01:32 2015
@@ -22,8 +22,8 @@ import java.util.HashMap;
import java.util.Iterator;
import java.util.Map;
-import org.apache.commons.configuration2.Configuration;
import org.apache.commons.configuration2.ConfigurationUtils;
+import org.apache.commons.configuration2.ImmutableConfiguration;
import org.apache.commons.configuration2.Initializable;
import org.apache.commons.configuration2.beanutils.BeanDeclaration;
import org.apache.commons.configuration2.beanutils.BeanHelper;
@@ -41,21 +41,21 @@ import org.apache.commons.configuration2
/**
* <p>
* An implementation of the {@code ConfigurationBuilder} interface which is
able
- * to create different concrete {@code Configuration} implementations based on
+ * to create different concrete {@code ImmutableConfiguration} implementations
based on
* reflection.
* </p>
* <p>
* When constructing an instance of this class the concrete
- * {@code Configuration} implementation class has to be provided. Then
- * properties for the new {@code Configuration} instance can be set. The first
+ * {@code ImmutableConfiguration} implementation class has to be provided. Then
+ * properties for the new {@code ImmutableConfiguration} instance can be set.
The first
* call to {@code getConfiguration()} creates and initializes the new
- * {@code Configuration} object. It is cached and returned by subsequent calls.
+ * {@code ImmutableConfiguration} object. It is cached and returned by
subsequent calls.
* This cache - and also the initialization properties set so far - can be
* flushed by calling one of the {@code reset()} methods. That way other
- * {@code Configuration} instances with different properties can be created.
+ * {@code ImmutableConfiguration} instances with different properties can be
created.
* </p>
* <p>
- * If the newly created {@code Configuration} object implements the
+ * If the newly created {@code ImmutableConfiguration} object implements the
* {@code Initializable} interface, its {@code initialize()} method is called
* after all initialization properties have been set. This way a concrete
* implementation class can perform arbitrary initialization steps.
@@ -73,10 +73,10 @@ import org.apache.commons.configuration2
* injection framework -, the fluent API approach may not be suitable. For
those
* use cases it is also possible to pass in all initialization parameters as a
* map. The keys of the map have to match initialization properties of the
- * {@code Configuration} object to be created, the values are the corresponding
+ * {@code ImmutableConfiguration} object to be created, the values are the
corresponding
* property values. For instance, the key <em>throwExceptionOnMissing</em> in
* the map will cause the method {@code setThrowExceptionOnMissing()} on the
- * {@code Configuration} object to be called with the corresponding value as
+ * {@code ImmutableConfiguration} object to be called with the corresponding
value as
* parameter.</li>
* </ul>
* <p>
@@ -97,16 +97,16 @@ import org.apache.commons.configuration2
* properties and call {@code getConfiguration()}. However, the intended use
* case is that the builder is configured by a single thread first. Then
* {@code getConfiguration()} can be called concurrently, and it is guaranteed
- * that always the same {@code Configuration} instance is returned until the
+ * that always the same {@code ImmutableConfiguration} instance is returned
until the
* builder is reset.
* </p>
*
* @version $Id$
* @since 2.0
- * @param <T> the concrete type of {@code Configuration} objects created by
this
+ * @param <T> the concrete type of {@code ImmutableConfiguration} objects
created by this
* builder
*/
-public class BasicConfigurationBuilder<T extends Configuration> implements
+public class BasicConfigurationBuilder<T extends ImmutableConfiguration>
implements
ConfigurationBuilder<T>
{
/** The class of the objects produced by this builder instance. */
@@ -165,7 +165,7 @@ public class BasicConfigurationBuilder<T
* @param resCls the result class (must not be <b>null</b>
* @param params a map with initialization parameters
* @param allowFailOnInit a flag whether exceptions on initializing a newly
- * created {@code Configuration} object are allowed
+ * created {@code ImmutableConfiguration} object are allowed
* @throws IllegalArgumentException if the result class is <b>null</b>
*/
public BasicConfigurationBuilder(Class<? extends T> resCls,
@@ -325,7 +325,7 @@ public class BasicConfigurationBuilder<T
/**
* Clears an existing result object. An invocation of this method causes a
- * new {@code Configuration} object to be created the next time
+ * new {@code ImmutableConfiguration} object to be created the next time
* {@link #getConfiguration()} is called.
*/
public void resetResult()
Modified:
commons/proper/configuration/trunk/src/main/java/org/apache/commons/configuration2/builder/BuilderConfigurationWrapperFactory.java
URL:
http://svn.apache.org/viewvc/commons/proper/configuration/trunk/src/main/java/org/apache/commons/configuration2/builder/BuilderConfigurationWrapperFactory.java?rev=1706911&r1=1706910&r2=1706911&view=diff
==============================================================================
---
commons/proper/configuration/trunk/src/main/java/org/apache/commons/configuration2/builder/BuilderConfigurationWrapperFactory.java
(original)
+++
commons/proper/configuration/trunk/src/main/java/org/apache/commons/configuration2/builder/BuilderConfigurationWrapperFactory.java
Mon Oct 5 20:01:32 2015
@@ -20,8 +20,8 @@ import java.lang.reflect.InvocationHandl
import java.lang.reflect.Method;
import java.lang.reflect.Proxy;
-import org.apache.commons.configuration2.Configuration;
import org.apache.commons.configuration2.ConfigurationUtils;
+import org.apache.commons.configuration2.ImmutableConfiguration;
import org.apache.commons.configuration2.event.EventSource;
/**
@@ -30,8 +30,8 @@ import org.apache.commons.configuration2
* {@link ConfigurationBuilder}.
* </p>
* <p>
- * Using this class special {@code Configuration} proxies can be created that
- * delegate all method invocations to another {@code Configuration} obtained
+ * Using this class special {@code ImmutableConfiguration} proxies can be
created that
+ * delegate all method invocations to another {@code ImmutableConfiguration}
obtained
* from a {@code ConfigurationBuilder}. For instance, if there is a
* configuration {@code c} wrapping the builder {@code builder}, the call
* {@code c.getString(myKey)} is transformed to
@@ -39,7 +39,7 @@ import org.apache.commons.configuration2
* </p>
* <p>
* There are multiple use cases for such a constellation. One example is that
- * client code can continue working with {@code Configuration} objects while
+ * client code can continue working with {@code ImmutableConfiguration}
objects while
* under the hood builders are used. Another example is that dynamic
* configurations can be realized in a transparent way: a client holds a single
* configuration (proxy) object, but the underlying builder may return a
@@ -75,7 +75,7 @@ public class BuilderConfigurationWrapper
}
/**
- * Creates a wrapper {@code Configuration} on top of the specified
+ * Creates a wrapper {@code ImmutableConfiguration} on top of the specified
* {@code ConfigurationBuilder}. This implementation delegates to
* {@link #createBuilderConfigurationWrapper(Class, ConfigurationBuilder,
EventSourceSupport)}
* .
@@ -89,9 +89,9 @@ public class BuilderConfigurationWrapper
* @return the wrapper configuration
* @throws IllegalArgumentException if a required parameter is missing
* @throws
org.apache.commons.configuration2.ex.ConfigurationRuntimeException if an error
- * occurs when creating the result {@code Configuration}
+ * occurs when creating the result {@code ImmutableConfiguration}
*/
- public <T extends Configuration> T createBuilderConfigurationWrapper(
+ public <T extends ImmutableConfiguration> T
createBuilderConfigurationWrapper(
Class<T> ifcClass, ConfigurationBuilder<? extends T> builder)
{
return createBuilderConfigurationWrapper(ifcClass, builder,
@@ -100,7 +100,7 @@ public class BuilderConfigurationWrapper
/**
* Returns the level of {@code EventSource} support used when generating
- * {@code Configuration} objects.
+ * {@code ImmutableConfiguration} objects.
*
* @return the level of {@code EventSource} support
*/
@@ -110,9 +110,9 @@ public class BuilderConfigurationWrapper
}
/**
- * Returns a {@code Configuration} object which wraps the specified
+ * Returns a {@code ImmutableConfiguration} object which wraps the
specified
* {@code ConfigurationBuilder}. Each access of the configuration is
- * delegated to a corresponding call on the {@code Configuration} object
+ * delegated to a corresponding call on the {@code ImmutableConfiguration}
object
* managed by the builder. This is a convenience method which allows
* creating wrapper configurations without having to instantiate this
class.
*
@@ -126,9 +126,9 @@ public class BuilderConfigurationWrapper
* @return the wrapper configuration
* @throws IllegalArgumentException if a required parameter is missing
* @throws
org.apache.commons.configuration2.ex.ConfigurationRuntimeException if an error
- * occurs when creating the result {@code Configuration}
+ * occurs when creating the result {@code ImmutableConfiguration}
*/
- public static <T extends Configuration> T
createBuilderConfigurationWrapper(
+ public static <T extends ImmutableConfiguration> T
createBuilderConfigurationWrapper(
Class<T> ifcClass, ConfigurationBuilder<? extends T> builder,
EventSourceSupport evSrcSupport)
{
@@ -177,11 +177,11 @@ public class BuilderConfigurationWrapper
/**
* <p>
* An enumeration class with different options for supporting the
- * {@code EventSource} interface in generated {@code Configuration}
proxies.
+ * {@code EventSource} interface in generated {@code
ImmutableConfiguration} proxies.
* </p>
* <p>
* Using literals of this class it is possible to specify that a
- * {@code Configuration} object returned by
+ * {@code ImmutableConfiguration} object returned by
* {@code BuilderConfigurationWrapperFactory} also implements the
* {@code EventSource} interface and how this implementation should work.
* See the documentation of the single constants for more details.
@@ -191,7 +191,7 @@ public class BuilderConfigurationWrapper
{
/**
* No support of the {@code EventSource} interface. If this option is
- * set, {@code Configuration} objects generated by
+ * set, {@code ImmutableConfiguration} objects generated by
* {@code BuilderConfigurationWrapperFactory} do not implement the
* {@code EventSource} interface.
*/
@@ -199,7 +199,7 @@ public class BuilderConfigurationWrapper
/**
* Dummy support of the {@code EventSource} interface. This option
- * causes {@code Configuration} objects generated by
+ * causes {@code ImmutableConfiguration} objects generated by
* {@code BuilderConfigurationWrapperFactory} to implement the
* {@code EventSource} interface, however, this implementation consists
* only of empty dummy methods without real functionality.
@@ -209,7 +209,7 @@ public class BuilderConfigurationWrapper
/**
* {@code EventSource} support is implemented by delegating to the
* associated {@code ConfigurationBuilder} object. If this option is
- * used, generated {@code Configuration} objects provide a fully
+ * used, generated {@code ImmutableConfiguration} objects provide a
fully
* functional implementation of {@code EventSource} by delegating to
the
* builder. Because the {@code ConfigurationBuilder} interface extends
* {@code EventSource} this delegation is always possible.
@@ -226,7 +226,7 @@ public class BuilderConfigurationWrapper
InvocationHandler
{
/** The wrapped builder. */
- private final ConfigurationBuilder<? extends Configuration> builder;
+ private final ConfigurationBuilder<? extends ImmutableConfiguration>
builder;
/** The level of {@code EventSource} support. */
private final EventSourceSupport eventSourceSupport;
@@ -239,7 +239,7 @@ public class BuilderConfigurationWrapper
* @param evSrcSupport the level of {@code EventSource} support
*/
public BuilderConfigurationWrapperInvocationHandler(
- ConfigurationBuilder<? extends Configuration> wrappedBuilder,
+ ConfigurationBuilder<? extends ImmutableConfiguration>
wrappedBuilder,
EventSourceSupport evSrcSupport)
{
builder = wrappedBuilder;
Modified:
commons/proper/configuration/trunk/src/main/java/org/apache/commons/configuration2/builder/ConfigurationBuilder.java
URL:
http://svn.apache.org/viewvc/commons/proper/configuration/trunk/src/main/java/org/apache/commons/configuration2/builder/ConfigurationBuilder.java?rev=1706911&r1=1706910&r2=1706911&view=diff
==============================================================================
---
commons/proper/configuration/trunk/src/main/java/org/apache/commons/configuration2/builder/ConfigurationBuilder.java
(original)
+++
commons/proper/configuration/trunk/src/main/java/org/apache/commons/configuration2/builder/ConfigurationBuilder.java
Mon Oct 5 20:01:32 2015
@@ -16,33 +16,40 @@
*/
package org.apache.commons.configuration2.builder;
-import org.apache.commons.configuration2.Configuration;
+import org.apache.commons.configuration2.ImmutableConfiguration;
import org.apache.commons.configuration2.event.EventSource;
import org.apache.commons.configuration2.ex.ConfigurationException;
/**
* <p>
- * Definition of an interface for objects that can create {@link Configuration}
- * objects of a specific type.
+ * Definition of an interface for objects that can create {@link
ImmutableConfiguration}
+ * or {@link org.apache.commons.configuration2.Configuration Configuration}
objects of a
+ * specific type.
* </p>
* <p>
- * This interface defines an abstract way of creating a {@code Configuration}
+ * This interface defines an abstract way of creating a {@code
ImmutableConfiguration}
* object. It does not assume any specific way of how this is done; this is
* completely in the responsibility of an implementation class. There is just a
* single method that returns the configuration constructed by this builder.
* </p>
+ * <p>
+ * Note: {@code ImmutableConfiguration} is just the base interface for all
configuration
+ * objects. So that the return type of the {@code getConfiguration()} method is
+ * {@code ImmutableConfiguration} does not mean that only immutable
configurations can
+ * be created.
+ * </p>
*
* @version $Id$
* @since 2.0
- * @param <T> the concrete type of the {@code Configuration} class produced by
+ * @param <T> the concrete type of the {@code ImmutableConfiguration} class
produced by
* this builder
*/
-public interface ConfigurationBuilder<T extends Configuration> extends
EventSource
+public interface ConfigurationBuilder<T extends ImmutableConfiguration>
extends EventSource
{
/**
* Returns the configuration provided by this builder. An implementation
has
* to perform all necessary steps for creating and initializing a
- * {@code Configuration} object.
+ * {@code ImmutableConfiguration} object.
*
* @return the configuration
* @throws ConfigurationException if an error occurs
Modified:
commons/proper/configuration/trunk/src/main/java/org/apache/commons/configuration2/builder/ConfigurationBuilderResultCreatedEvent.java
URL:
http://svn.apache.org/viewvc/commons/proper/configuration/trunk/src/main/java/org/apache/commons/configuration2/builder/ConfigurationBuilderResultCreatedEvent.java?rev=1706911&r1=1706910&r2=1706911&view=diff
==============================================================================
---
commons/proper/configuration/trunk/src/main/java/org/apache/commons/configuration2/builder/ConfigurationBuilderResultCreatedEvent.java
(original)
+++
commons/proper/configuration/trunk/src/main/java/org/apache/commons/configuration2/builder/ConfigurationBuilderResultCreatedEvent.java
Mon Oct 5 20:01:32 2015
@@ -16,7 +16,7 @@
*/
package org.apache.commons.configuration2.builder;
-import org.apache.commons.configuration2.Configuration;
+import org.apache.commons.configuration2.ImmutableConfiguration;
import org.apache.commons.configuration2.event.EventType;
/**
@@ -27,7 +27,7 @@ import org.apache.commons.configuration2
* <p>
* Events of this type are fired in the {@code getConfiguration()} method of a
* configuration builder each time a new result object is created. At the time
- * the event is fired, no lock is held. The newly created {@code Configuration}
+ * the event is fired, no lock is held. The newly created {@code
ImmutableConfiguration}
* object is available as a property of this event.
* </p>
* <p>
@@ -52,7 +52,7 @@ public class ConfigurationBuilderResultC
"RESULT_CREATED");
/** The newly created configuration object. */
- private final Configuration configuration;
+ private final ImmutableConfiguration configuration;
/**
* Creates a new instance of {@code ConfigurationBuilderResultCreatedEvent}
@@ -61,14 +61,14 @@ public class ConfigurationBuilderResultC
* @param source the {@code ConfigurationBuilder} object which triggered
* this event (must not be <b>null</b>)
* @param evType the type of this event (must not be <b>null</b>)
- * @param createdConfiguration the newly created {@code Configuration}
+ * @param createdConfiguration the newly created {@code
ImmutableConfiguration}
* object (must not be <b>null</b>)
* @throws IllegalArgumentException if a required parameter is null
*/
public ConfigurationBuilderResultCreatedEvent(
ConfigurationBuilder<?> source,
EventType<? extends ConfigurationBuilderResultCreatedEvent> evType,
- Configuration createdConfiguration)
+ ImmutableConfiguration createdConfiguration)
{
super(source, evType);
if (createdConfiguration == null)
@@ -80,11 +80,11 @@ public class ConfigurationBuilderResultC
}
/**
- * Returns the newly created {@code Configuration} object.
+ * Returns the newly created {@code ImmutableConfiguration} object.
*
- * @return the newly created {@code Configuration}
+ * @return the newly created {@code ImmutableConfiguration}
*/
- public Configuration getConfiguration()
+ public ImmutableConfiguration getConfiguration()
{
return configuration;
}
Modified:
commons/proper/configuration/trunk/src/main/java/org/apache/commons/configuration2/builder/combined/MultiFileConfigurationBuilderProvider.java
URL:
http://svn.apache.org/viewvc/commons/proper/configuration/trunk/src/main/java/org/apache/commons/configuration2/builder/combined/MultiFileConfigurationBuilderProvider.java?rev=1706911&r1=1706910&r2=1706911&view=diff
==============================================================================
---
commons/proper/configuration/trunk/src/main/java/org/apache/commons/configuration2/builder/combined/MultiFileConfigurationBuilderProvider.java
(original)
+++
commons/proper/configuration/trunk/src/main/java/org/apache/commons/configuration2/builder/combined/MultiFileConfigurationBuilderProvider.java
Mon Oct 5 20:01:32 2015
@@ -118,7 +118,7 @@ public class MultiFileConfigurationBuild
Class ifcClass =
HierarchicalConfiguration.class.isAssignableFrom(configClass)
? HierarchicalConfiguration.class
: Configuration.class;
- return BuilderConfigurationWrapperFactory
+ return (Configuration) BuilderConfigurationWrapperFactory
.createBuilderConfigurationWrapper(ifcClass, builder,
EventSourceSupport.BUILDER);
}
Modified:
commons/proper/configuration/trunk/src/site/xdoc/userguide/howto_utilities.xml
URL:
http://svn.apache.org/viewvc/commons/proper/configuration/trunk/src/site/xdoc/userguide/howto_utilities.xml?rev=1706911&r1=1706910&r2=1706911&view=diff
==============================================================================
---
commons/proper/configuration/trunk/src/site/xdoc/userguide/howto_utilities.xml
(original)
+++
commons/proper/configuration/trunk/src/site/xdoc/userguide/howto_utilities.xml
Mon Oct 5 20:01:32 2015
@@ -309,13 +309,16 @@ String value = config.getString("myKey")
<code>Configuration</code> objects were the only source of configuration
data. So applications using this version probably pass around objects of
this type. This makes the migration to the new configuration builders
- harder.
+ harder. Further, such configurations are mutable. Should one wish to
+ establish a boundary between the consumer consuming the configuration
+ and another part of the system modifying the configuration, 2.0 has
+ introduced an <code>ImmutableConfiguration</code>.
</p>
<p>
There is one helper class which can simplify this migration:
<code><a
href="../apidocs/org/apache/commons/configuration2/builder/BuilderConfigurationWrapperFactory.html">
BuilderConfigurationWrapperFactory</a></code>. This class is capable of
- creating special proxy objects implementing the
<code>Configuration</code>
+ creating special proxy objects implementing the
<code>ImmutableConfiguration</code>
interface which behind the scenes delegate to the managed configuration
object of a configuration builder. For instance, if a wrapper
configuration
named <em>config</em> has been created for the configuration builder
@@ -356,4 +359,4 @@ Configuration config = wrapperFactory.cr
</section>
</body>
-</document>
\ No newline at end of file
+</document>
