commons-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From ebo...@apache.org
Subject cvs commit: jakarta-commons/configuration/xdocs overview.xml
Date Mon, 25 Oct 2004 14:12:02 GMT
ebourg      2004/10/25 07:12:02

  Modified:    configuration/xdocs overview.xml
  Log:
  documentation update:
  - removed the references to the unit tests, this is discouraging for new users
  - more examples
  - replaced "digester file" by "configuration descriptor" since digester is just an implementation
detail
  
  Revision  Changes    Path
  1.7       +70 -54    jakarta-commons/configuration/xdocs/overview.xml
  
  Index: overview.xml
  ===================================================================
  RCS file: /home/cvs/jakarta-commons/configuration/xdocs/overview.xml,v
  retrieving revision 1.6
  retrieving revision 1.7
  diff -u -r1.6 -r1.7
  --- overview.xml	22 Oct 2004 01:40:48 -0000	1.6
  +++ overview.xml	25 Oct 2004 14:12:02 -0000	1.7
  @@ -1,25 +1,25 @@
   <?xml version="1.0"?>
   
   <document>
  -
  - <properties>
  -  <title>Configuration Overview</title>
  -  <author email="epugh@upstate.com">Eric Pugh</author>
  - </properties>
  -
  -<body>
  +  <properties>
  +    <title>Configuration Overview</title>
  +    <author email="epugh@upstate.com">Eric Pugh</author>
  +    <author email="smanux@lfjr.net">Emmanuel Bourg</author>
  +  </properties>
  +  <body>
   
       <section name="Using Configuration">
         <p>
  -        The best way to learn how to use Configuration is to look at the various testcases
  -        that it comes with.  This will demonstrate how a Configuration object is populated
  -        from multiple different sources.
  +        One of the strength of Commons Configuration is its ability to mix configurations
  +        from heterogeneous sources, this section will introduce you to the different configurations
  +        available and will show you how to combine them.
         </p>
  +
         <subsection name="Configuration Sources">
         <p>
  -        Currently there are quite a number of different sources of Configuration objects.
 But,
  +        Currently there are quite a number of different sources of Configuration objects.
But,
           by just using a Configuration object versus a specific type like XMLConfiguration
or
  -        JNDIConfiguration, you are sheltered from the mechanics of actually retrieving
the 
  +        JNDIConfiguration, you are sheltered from the mechanics of actually retrieving
the
           configuration values. These various sources include:
           <ul>
             <li>
  @@ -39,61 +39,74 @@
                 Using a key in the JNDI tree, can retrieve values as configuration properties.
             </li>
             <li>
  +              <strong>SystemConfiguration</strong>
  +              A configuration using the system properties
  +          </li>
  +          <li>
                 <strong>ConfigurationConverter</strong>
                 Takes a java.util.Properties or an o.a.c.collections.ExtendedProperties
                 and converts it to a Configuration object.
             </li>
          </ul>
  -        
  +
         </p>
         </subsection>
  +
         <subsection name="Mixing Configuration Sources">
         <p>
  -        Often you want to provide a base set of configuration values, but allow the user
to easily 
  +        Often you want to provide a base set of configuration values, but allow the user
to easily
           override them for their specific environment.  Well one way is to hard code the
default
           values into your code, and have then provide a property file that overrides this.
 However,
  -        this is a very rigid way of doing things.  Instead, with the CompositeConfiguration
you can
  -        provide many different ways of setting up a configuration.  You can either do it
manually (see
  -        JUnit testcase "TestCompositeConfiguration.java", or via the ConfigurationFactory
class.
  +        this is a very rigid way of doing things. Instead, with the <code>CompositeConfiguration</code>
  +        you can provide many different ways of setting up a configuration. You can either
do it
  +        manually:
         </p>
  +
  +<source>
  +CompositeConfiguration config = new CompositeConfiguration();
  +config.addConfiguration(new SystemConfiguration());
  +config.addConfiguration(new PropertiesConfiguration("application.properties"));
  +</source>
  +
  +      <p>or via the <code>ConfigurationFactory</code> class:</p>
  +
  +<source>
  +ConfigurationFactory factory = new ConfigurationFactory("config.xml");
  +Configuration config = factory.getConfiguration();
  +</source>
  +
         <p>
  -        Using the ConfigurationFactory, (see the Junit testcase "TestConfigurationFactory.java")
you load
  -        up a digester xml file that specifies how to load up all the Configuration objects.
 Here is 
  -        a sample one using the default digesterRules.xml file:
  +        The <code>config.xml</code> file used in the example above is a configuration
descriptor,
  +        it specifies the Configuration objects to load. Here is an example of descriptor:
         </p>
   
  -      <source><![CDATA[
  +<source><![CDATA[
   <?xml version="1.0" encoding="ISO-8859-1" ?>
   
   <configuration>
  -  <jndi prefix="java:comp/env"/>
  -  <properties fileName="conf/test.properties"/>
  -  <xml fileName="conf/test.xml"/>
  +  <system/>
  +  <properties fileName="application.properties"/>
   </configuration>
   ]]></source>
   
         <p>
  -        What this says is that we are loading up all JNDI values under java:comp/env key,
as well 
  -        as a properties file in conf/test.properties as well as a XML file in conf/test.xml.
  -        Please inspect the test cases and the files in the conf/ directory for more information
on how
  -        to structure your configuration xml file..
  -      </p>
  -      <p>
  -        The order of precedence is first to last.  So in the above example, if there was
a JNDI key
  -        called test.precendence and another one in the XML file called test.precedence,
then the configuration
  -        value from JNDI would be returned, not the one in the XML file.   This allows you
to set up defaults
  -        in properties/xml file, but override them from JNDI or even another XML/properties
file!
  +        What this says is that we are loading up all system properties, as well as the
properties
  +        file <code>application.properties</code>. The order of precedence is
first to last. So in
  +        the above example, if a property is not found in the system properties, it'll be
searched
  +        in the properties file. This allows you to set up default values in a properties
file, and
  +        override them with the system properties.
         </p>
         </subsection>
       </section>
  +
       <section name="Configuration Details">
         <p>
  -      Configuration is done by taking the configuration XML file and using included Digester
rules,
  -      parsing the individual configurations.  Make sure to include the various dependencies
required for
  -      each type of configuration!
  +      Configuration is done by taking the configuration descriptor XML file and parsing
the
  +      individual configurations.  Make sure to include the various <a href="dependencies.html">dependencies</a>
  +      required for each type of configuration!
         </p>
         <subsection name="Classic Properties File">
  -        <source><![CDATA[
  +<source><![CDATA[
     <properties fileName="conf/test.properties"/>
   ]]></source>
   
  @@ -106,10 +119,10 @@
     <xml fileName="conf/test.xml"/>
   ]]></source>
           <p>
  -        The configuration is very similar to the classic properties file.  However, the
xml file must be in a specific
  -        format.  Currently there is no DTD.
  +        The configuration is very similar to the classic properties file.  However, the
xml file
  +        must be in a specific format. Currently there is no DTD.
           </p>
  -        <source><![CDATA[
  +<source><![CDATA[
   <baseElement>
     <element>value</element>
     <element2>
  @@ -123,17 +136,19 @@
   </baseElement>
   ]]></source>
           <p>
  -        In the above example, the root element is ignored.  So to get the value "8", you
would request from your 
  -        Configuration object the key "test.short".  The root element can be called anything.
  +          In the above example, the root element is ignored.  So to get the value "8",
you would
  +          request from your Configuration object the key "<code>test.short</code>".
The root
  +          element can be called anything.
           </p>
  -      </subsection>     
  -      <subsection name="JNDI Properties File">
  +      </subsection>
  +      <subsection name="JNDI Environment Properties">
           <source><![CDATA[
     <jndi prefix="java:comp/env"/>
   ]]></source>
           <p>
  -        This configuration is very useful for setting environment specific settings like
mail servers! The
  -        prefix tells the ConfigurationFactory what the root will be to look up your configuration
settings. 
  +        This configuration is very useful for setting environment specific settings like
mail
  +        servers! The prefix tells the <code>ConfigurationFactory</code> what
the root will be
  +        to look up your configuration settings.
           </p>
           <source><![CDATA[
       <env-entry>
  @@ -141,7 +156,7 @@
           <env-entry-value>127.0.0.1</env-entry-value>
           <env-entry-type>java.lang.String</env-entry-type>
       </env-entry>
  -    
  +
       <env-entry>
           <env-entry-name>test/short</env-entry-name>
           <env-entry-value>80</env-entry-value>
  @@ -149,13 +164,14 @@
       </env-entry>
   ]]></source>
           <p>
  -        <strong>Note!</strong>  If you have a property called "test.short"
with spaces in it, then it will be translated
  -        as the key "test/short".  Therefore, you should NOT use spaces in the name of properties
that
  -        are loaded from JNDI!  If you do want to use them, then make sure to convert in
your web.xml the
  -        "." characters to "/" characters, like in the test.short example above.
  +        <strong>Note!</strong>  If you have a property called "<code>test.short</code>"
with spaces
  +        in it, then it will be translated as the key "<code>test/short</code>".
 Therefore, you
  +        should NOT use spaces in the name of properties that are loaded from JNDI!  If
you do want
  +        to use them, then make sure to convert in your <code>web.xml</code>
the "." characters to
  +        "/" characters, like in the <code>test.short</code> example above.
           </p>
  -      </subsection>     
  +      </subsection>
       </section>
   
  -</body>
  +  </body>
   </document>
  
  
  

---------------------------------------------------------------------
To unsubscribe, e-mail: commons-dev-unsubscribe@jakarta.apache.org
For additional commands, e-mail: commons-dev-help@jakarta.apache.org


Mime
View raw message