oheger 2004/11/19 11:25:47
Modified: configuration/src/test/org/apache/commons/configuration
TestConfigurationFactory.java
configuration/conf testDigesterOptionalConfiguration.xml
configuration/xdocs howto_configurationfactory.xml
configuration/src/java/org/apache/commons/configuration
ConfigurationFactory.java
Added: configuration/conf testDigesterOptionalConfigurationEx.xml
Log:
Optional configurations: Renamed attribute from required to optional, added
additional unit test and section in ConfigurationFactory howto
Revision Changes Path
1.19 +14 -1
jakarta-commons/configuration/src/test/org/apache/commons/configuration/TestConfigurationFactory.java
Index: TestConfigurationFactory.java
===================================================================
RCS file:
/home/cvs/jakarta-commons/configuration/src/test/org/apache/commons/configuration/TestConfigurationFactory.java,v
retrieving revision 1.18
retrieving revision 1.19
diff -u -r1.18 -r1.19
--- TestConfigurationFactory.java 19 Nov 2004 01:56:30 -0000 1.18
+++ TestConfigurationFactory.java 19 Nov 2004 19:25:47 -0000 1.19
@@ -47,6 +47,8 @@
new File("conf/testDigesterConfiguration3.xml");
private File testDigesterFileOptional =
new File("conf/testDigesterOptionalConfiguration.xml");
+ private File testDigesterFileOptionalEx =
+ new File("conf/testDigesterOptionalConfigurationEx.xml");
private File testDigesterBadXML = new
File("conf/testDigesterBadXML.xml");
@@ -259,6 +261,17 @@
Configuration config = factory.getConfiguration();
assertTrue(config.getBoolean("test.boolean"));
assertEquals("value", config.getProperty("element"));
+
+ factory.setConfigurationURL(testDigesterFileOptionalEx.toURL());
+ try
+ {
+ config = factory.getConfiguration();
+ fail("Unexisting properties loaded!");
+ }
+ catch(ConfigurationException cex)
+ {
+ // fine
+ }
}
private void checkUnionConfig() throws Exception
1.2 +7 -7
jakarta-commons/configuration/conf/testDigesterOptionalConfiguration.xml
Index: testDigesterOptionalConfiguration.xml
===================================================================
RCS file:
/home/cvs/jakarta-commons/configuration/conf/testDigesterOptionalConfiguration.xml,v
retrieving revision 1.1
retrieving revision 1.2
diff -u -r1.1 -r1.2
--- testDigesterOptionalConfiguration.xml 14 Nov 2004 19:06:32 -0000
1.1
+++ testDigesterOptionalConfiguration.xml 19 Nov 2004 19:25:47 -0000
1.2
@@ -4,14 +4,14 @@
<configuration>
<properties fileName="test.properties"/>
- <xml fileName="test.xml" required="true"/>
- <hierarchicalXml fileName="nonExistingHierarchicalXML1.xml"
required="false"/>
- <properties fileName="nonExistingProperties1.properties" required="no"/>
- <xml fileName="nonExistingXML1.xml" required="false"/>
+ <xml fileName="test.xml" optional="false"/>
+ <hierarchicalXml fileName="nonExistingHierarchicalXML1.xml"
optional="true"/>
+ <properties fileName="nonExistingProperties1.properties" optional="yes"/>
+ <xml fileName="nonExistingXML1.xml" optional="true"/>
<additional>
- <properties fileName="nonExistingProperties2.properties" required="no"/>
- <hierarchicalXml fileName="nonExistingHierarchicalXML2.xml"
required="false"/>
- <xml fileName="nonExistingXML2.xml" required="false"/>
+ <properties fileName="nonExistingProperties2.properties" optional="yes"/>
+ <hierarchicalXml fileName="nonExistingHierarchicalXML2.xml"
optional="true"/>
+ <xml fileName="nonExistingXML2.xml" optional="true"/>
</additional>
</configuration>
1.1
jakarta-commons/configuration/conf/testDigesterOptionalConfigurationEx.xml
Index: testDigesterOptionalConfigurationEx.xml
===================================================================
<?xml version="1.0" encoding="ISO-8859-1" ?>
<!-- Configuration test file that is used to test whether invalid
file names cause exceptions to be thrown -->
<configuration>
<!-- This should not cause an exception -->
<properties fileName="unexisting.properties" optional="true"/>
<!-- But this should! -->
<properties fileName="unexisting.properties"/>
</configuration>
1.5 +44 -0
jakarta-commons/configuration/xdocs/howto_configurationfactory.xml
Index: howto_configurationfactory.xml
===================================================================
RCS file:
/home/cvs/jakarta-commons/configuration/xdocs/howto_configurationfactory.xml,v
retrieving revision 1.4
retrieving revision 1.5
diff -u -r1.4 -r1.5
--- howto_configurationfactory.xml 22 Oct 2004 01:40:48 -0000 1.4
+++ howto_configurationfactory.xml 19 Nov 2004 19:25:47 -0000 1.5
@@ -231,6 +231,50 @@
still be returned from the second file (the
defaults file).
</p>
</subsection>
+ <subsection name="Optional configuration sources">
+ <p>
+ The example above with two configuration
sources - one for user
+ settings and one with default values - raises
an interesting
+ question: What will happen if the user has not
defined specific
+ properties yet? Or what if a new user starts
our application for
+ the first time and thus no user specific
properties exist?
+ </p>
+ <p>
+ The default behavior of
<code>ConfigurationFactory</code> is to
+ throw a <code>ConfigurationException</code>
exception if one of
+ the sources defined in the configuration
definition file cannot
+ be loaded. For our example this behavior is not
desired: the
+ properties file with specific user settings is
not required. If it
+ cannot be loaded, the example application will
still work because
+ a complete set of configuration properties is
defined in the
+ second file.
+ </p>
+ <p>
+ <code>ConfigurationFactory</code> supports such
optional
+ configuration sources. For this purpose in the
definition of a
+ (file based) configuration source the
<code>optional</code>
+ attribute can be placed. An example of this is
shown below:
+ </p>
+ <source><![CDATA[
+<?xml version="1.0" encoding="ISO-8859-1" ?>
+
+<configuration>
+ <properties fileName="usersettings.properties" optional="true"/>
+ <properties fileName="default.properties"/>
+</configuration>
+]]></source>
+ <p>
+ In this configuration definition file the first
properties file
+ with user specific settings is marked as
optional. This means that
+ if it cannot be loaded,
<code>ConfigurationFactory</code> will
+ not throw an exception, but only write a
warning message to its
+ logger. Note that the <code>optional</code>
attribute is absent
+ for the second properties file. Thus it is
mandatory, and the
+ <code>getConfiguration()</code> method of
+ <code>ConfigurationFactory</code> would throw
an exception if it
+ could not be found.
+ </p>
+ </subsection>
</section>
</body>
1.19 +4 -4
jakarta-commons/configuration/src/java/org/apache/commons/configuration/ConfigurationFactory.java
Index: ConfigurationFactory.java
===================================================================
RCS file:
/home/cvs/jakarta-commons/configuration/src/java/org/apache/commons/configuration/ConfigurationFactory.java,v
retrieving revision 1.18
retrieving revision 1.19
diff -u -r1.18 -r1.19
--- ConfigurationFactory.java 14 Nov 2004 19:06:32 -0000 1.18
+++ ConfigurationFactory.java 19 Nov 2004 19:25:47 -0000 1.19
@@ -59,7 +59,7 @@
private static final String SEC_ADDITIONAL = SEC_ROOT + "additional/";
/** Constant for the optional attribute.*/
- private static final String ATTR_REQUIRED = "required";
+ private static final String ATTR_OPTIONAL = "optional";
/** Constant for the fileName attribute.*/
private static final String ATTR_FILENAME = "fileName";
@@ -499,8 +499,8 @@
}
catch(ConfigurationException cex)
{
- if(attributes.getValue(ATTR_REQUIRED) == null
- ||
!PropertyConverter.toBoolean(attributes.getValue(ATTR_REQUIRED)).booleanValue())
+ if(attributes.getValue(ATTR_OPTIONAL) != null
+ &&
PropertyConverter.toBoolean(attributes.getValue(ATTR_OPTIONAL)).booleanValue())
{
log.warn("Could not load optional configuration " +
conf.getFileName());
}
---------------------------------------------------------------------
To unsubscribe, e-mail: [EMAIL PROTECTED]
For additional commands, e-mail: [EMAIL PROTECTED]
