You are viewing a plain text version of this content. The canonical link for it is here.
Posted to dev@commons.apache.org by ep...@apache.org on 2004/03/28 21:58:30 UTC
cvs commit: jakarta-commons/configuration/xdocs howto_configurationfactory.xml howto_xml.xml
epugh 2004/03/28 11:58:30
Modified: configuration/xdocs howto_configurationfactory.xml
howto_xml.xml
Log:
Documentation fixes from Oliver Heger. Thanks!
Revision Changes Path
1.2 +0 -397 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.1
retrieving revision 1.2
diff -u -r1.1 -r1.2
--- howto_configurationfactory.xml 24 Feb 2004 13:08:03 -0000 1.1
+++ howto_configurationfactory.xml 28 Mar 2004 19:58:30 -0000 1.2
@@ -246,403 +246,6 @@
</p>
</subsection>
</section>
-
- <section name="Hierarchical properties">
- <p>
- The XML document we used so far was quite simple. Because of its
- tree-like nature XML documents can represent data that is
- structured in many ways. This section explains how to deal with
- such structured documents.
- </p>
- <subsection name="Structured XML">
- <p>
- Consider the following scenario: An application operates on
- database tables and wants to load a definition of the database
- schema from its configuration. A XML document provides this
- information. It could look as follows:
- </p>
- <source>
-<![CDATA[
-<?xml version="1.0" encoding="ISO-8859-1" ?>
-
-<database>
- <tables>
- <table tableType="system">
- <name>users</name>
- <fields>
- <field>
- <name>uid</name>
- <type>long</type>
- </field>
- <field>
- <name>uname</name>
- <type>java.lang.String</type>
- </field>
- <field>
- <name>firstName</name>
- <type>java.lang.String</type>
- </field>
- <field>
- <name>lastName</name>
- <type>java.lang.String</type>
- </field>
- <field>
- <name>email</name>
- <type>java.lang.String</type>
- </field>
- </fields>
- </table>
- <table tableType="application">
- <name>documents</name>
- <fields>
- <field>
- <name>docid</name>
- <type>long</type>
- </field>
- <field>
- <name>name</name>
- <type>java.lang.String</type>
- </field>
- <field>
- <name>creationDate</name>
- <type>java.util.Date</type>
- </field>
- <field>
- <name>authorID</name>
- <type>long</type>
- </field>
- <field>
- <name>version</name>
- <type>int</type>
- </field>
- </fields>
- </table>
- </tables>
-</database>
-]]>
- </source>
- <p>
- This XML is quite self explanatory; there is an arbitrary number
- of table elements, each of it has a name and a list of fields.
- A field in turn consists of a name and a data type.
- To access the data stored in this document it must be included
- in the configuration definition file:
- </p>
- <source>
-<![CDATA[
-<?xml version="1.0" encoding="ISO-8859-1" ?>
-
-<configuration>
- <properties fileName="usergui.properties"/>
- <dom4j fileName="gui.xml"/>
- <dom4j fileName="tables.xml"/>
-</configuration>
-]]>
- </source>
- <p>
- The additional <code>dom4j</code> element causes the document
- with the table definitions to be loaded. When we now want to
- read some of the properties we face a problem: the syntax for
- constructing configuration keys we learned so far is not
- powerful enough to access all of the data stored in the tables
- document.
- </p>
- <p>
- Because the document contains a list of tables some properties
- are defined more than once. E.g. the configuration key
- <code>tables.table.name</code> refers to a <code>name</code>
- element inside a <code>table</code> element inside a
- <code>tables</code> element. This constellation happens to
- occur twice in the tables document.
- </p>
- <p>
- Multiple definitions of a property do not cause problems and are
- supported by all classes of Configuration. If such a property
- is queried using <code>getProperty()</code>, the method
- recognizes that there are multiple values for that property and
- returns a collection with all these values. So we could write
- </p>
- <source>
-<![CDATA[
-Object prop = config.getProperty("tables.table.name");
-if(prop instanceof Collection)
-{
- System.out.println("Number of tables: " + ((Collection) prop).size());
-}
-]]>
- </source>
- <p>
- An alternative to this code would be the <code>getList()</code>
- method of <code>Configuration</code>. If a property is known to
- have multiple values (as is the table name property in this example),
- <code>getList()</code> allows to retrieve all values at once.
- <b>Note:</b> it is NOT legal to call <code>getString()</code>
- or one of the other getter methods on a property with multiple
- values; as the entire list is attempted to be returned.
- </p>
- </subsection>
- <subsection name="Accessing structured properties">
- <p>
- Okay, we can obtain a list with the name of all defined
- tables. In the same way we can retrieve a list with the names
- of all table fields: just pass the key
- <code>tables.table.fields.field.name</code> to the
- <code>getList()</code> method. In our example this list
- would contain 10 elements, the names of all fields of all tables.
- This is fine, but how do we know, which field belongs to
- which table?
- </p>
- <p>
- The answer is, with our actual approach we have no chance to
- obtain this knowledge! If XML documents are loaded this way,
- their exact structure is lost. Though all field names are found
- and stored the information which field belongs to which table
- is not saved. Fortunately Configuration provides a way of
- dealing with structured XML documents. To enable this feature
- the configuration definition file has to be slightly altered.
- It becomes:
- </p>
- <source>
-<![CDATA[
-<?xml version="1.0" encoding="ISO-8859-1" ?>
-
-<configuration>
- <properties fileName="usergui.properties"/>
- <dom4j fileName="gui.xml"/>
- <dom4j className="org.apache.commons.configuration.HierarchicalDOM4JConfiguration"
- fileName="tables.xml"/>
-</configuration>
-]]>
- </source>
- <p>
- Note the additional <code>className</code> attribute of the last
- <code>dom4j</code> element. This attribute tells the configuration
- factory that not the default class for processing XML documents
- should be used, but the class <code>HierarchicalDOM4JConfiguration</code>.
- As the name implies this class is capable of saving the
- hierarchy of XML documents thus keeping their structure.
- </p>
- <p>
- When working with such hierarchical properties configuration keys
- used to query properties support an extended syntax. All components
- of a key can be appended by a numerical value in parentheses that
- determines the index of the affected property. This is explained best
- by some examples:
- </p>
- <p>
- We will now provide some configuration keys and show the results
- of a <code>getProperty()</code> call with these keys as arguments.
- <dl>
- <dt><code>tables.table(0).name</code></dt>
- <dd>
- Returns the name of the first table (all indices are 0 based),
- in this example the string <em>users</em>.
- </dd>
- <dt><code>tables.table(0)[@tableType]</code></dt>
- <dd>
- Returns the value of the tableType attribute of the first
- table (<em>system</em>).
- </dd>
- <dt><code>tables.table(1).name</code></dt>
- <dd>
- Analogous to the first example returns the name of the
- second table (<em>documents</em>).
- </dd>
- <dt><code>tables.table(2).name</code></dt>
- <dd>
- Here the name of a third table is queried, but because there
- are only two tables result is <b>null</b>. The fact that a
- <b>null</b> value is returned for invalid indices can be used
- to find out how many values are defined for a certain property:
- just increment the index in a loop as long as valid objects
- are returned.
- </dd>
- <dt><code>tables.table(1).fields.field.name</code></dt>
- <dd>
- Returns a collection with the names of all fields that
- belong to the second table. With such kind of keys it is
- now possible to find out, which fields belong to which table.
- </dd>
- <dt><code>tables.table(1).fields.field(2).name</code></dt>
- <dd>
- The additional index after field selects a certain field.
- This expression represents the name of the third field in
- the second table (<em>creationDate</em>).
- </dd>
- <dt><code>tables.table.fields.field(0).type</code></dt>
- <dd>
- This key may be a bit unusual but nevertheless completely
- valid. It selects the data types of the first fields in all
- tables. So here a collection would be returned with the
- 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
- of indices it is possible to navigate through complex structures of
- XML documents; each XML element can be uniquely identified.
- So at the end of this section we can draw the following facit:
- For simple XML documents that define only some simple properties
- and do not have a complex structure the default XML configuration
- class is suitable. If documents are more complex and their structure
- is important, the hierarchy aware class should be used, which is
- enabled by an additional <code>className</code> attribute as
- shown in the example configuration definition file above.
- </p>
- </subsection>
- </section>
-
- <section name="Union configuration">
- <p>
- In an earlier section about the configuration definition file for
- <code>ConfigurationFactory</code> it was stated that configuration
- files included first can override properties in configuraton files
- included later and an example use case for this behaviour was given.
- There may be times when there are other requirements.
- </p>
- <p>
- Let's continue the example with the application that somehow process
- database tables and that reads the definitions of the affected tables from
- its configuration. Now consider that this application grows larger and
- must be maintained by a team of developers. Each developer works on
- a separated set of tables. In such a scenario it would be problematic
- if the definitions for all tables would be kept in a single file. It can be
- expected that this file needs to be changed very often and thus can be
- a bottleneck for team development when it is nearly steadily checked
- out. It would be much better if each developer had an associated file
- with table definitions and all these information could be linked together
- at the end.
- </p>
- <p>
- <code>ConfigurationFactory</code> provides support for such a use case,
- too. It is possible to specify in the configuration definition file that
- from a set of configuration sources a logic union configuration is to be
- constructed. Then all properties defined in the provided sources are
- collected and can be accessed as if they had been defined in a single
- source. To demonstrate this feature let us assume that a developer of
- the database application has defined a specific XML file with a table
- definition named <code>tasktables.xml</code>:
- </p>
- <source>
-<![CDATA[
-<?xml version="1.0" encoding="ISO-8859-1" ?>
-
-<config>
- <table tableType="application">
- <name>tasks</name>
- <fields>
- <field>
- <name>taskid</name>
- <type>long</type>
- </field>
- <field>
- <name>name</name>
- <type>java.lang.String</type>
- </field>
- <field>
- <name>description</name>
- <type>java.lang.String</type>
- </field>
- <field>
- <name>responsibleID</name>
- <type>long</type>
- </field>
- <field>
- <name>creatorID</name>
- <type>long</type>
- </field>
- <field>
- <name>startDate</name>
- <type>java.util.Date</type>
- </field>
- <field>
- <name>endDate</name>
- <type>java.util.Date</type>
- </field>
- </fields>
- </table>
-</config>
-]]>
- </source>
- <p>
- This file defines the structure of an additional table, which should be
- added to the so far existing table definitions. To achieve this the
- configuration definition file has to be changed: A new section is added
- that contains the include elements of all configuration sources which
- are to be combined.
- </p>
- <source>
-<![CDATA[
-<?xml version="1.0" encoding="ISO-8859-1" ?>
-<!-- Configuration definition file that demonstrates the
- override and additional sections -->
-
-<configuration>
- <override>
- <properties fileName="usergui.properties"/>
- <dom4j fileName="gui.xml"/>
- </override>
-
- <additional>
- <dom4j className="org.apache.commons.configuration.HierarchicalDOM4JConfiguration"
- fileName="tables.xml"/>
- <dom4j className="org.apache.commons.configuration.HierarchicalDOM4JConfiguration"
- fileName="tasktables.xml" at="tables"/>
- </additional>
-</configuration>
-]]>
- </source>
- <p>
- Compared to the older versions of this file a couple of changes has been
- done. One major difference is that the elements for including configuration
- sources are no longer direct children of the root element, but are now
- contained in either an <code>override</code> or <code>additional</code>
- section. The names of these sections already imply their purpose.
- </p>
- <p>
- The <code>override</code> section is not strictly necessary. Elements in
- this section are treated as if they were children of the root element, i.e.
- properties in the included configuration sources override properties in
- sources included later. So the <code>override</code> tags could have
- been ommitted, but for sake of clearity it is recommended to use them
- when there is also an <code>additional</code> section.
- </p>
- <p>
- It is the <code>additonal</code> section that introduces a new behaviour.
- All configuration sources listed here are combined to a union configuration.
- In our example we have put two <code>dom4j</code> elements in this area
- that load the available files with database table definitions. The syntax
- of elements in the <code>additional</code> section is analogous to the
- syntax described so far. The only difference is an additionally supported
- <code>at</code> attribute that specifies the position in the logic union
- configuration where the included properties are to be added. In this
- example we set the <code>at</code> attribute of the second element to
- <em>tables</em>. This is because the file starts with a <code>table</code>
- element, but to be compatible with the other table definition file should be
- accessable under the key <code>tables.table</code>.
- </p>
- <p>
- After these modifications have been performed the configuration obtained
- from the <code>ConfigurationFactory</code> will allow access to three
- database tables. A call of <code>config.getString("tables.table(2).name");</code>
- will result in a value of <em>tasks</em>. In an analogous way it is possible
- to retrieve the fields of the third table.
- </p>
- <p>
- Note that it is also possible to override properties defined in an
- <code>additonal</code> section. This can be done by placing a
- configuration source in the <code>override</code> section that defines
- properties that are also defined in one of the sources listed in the
- <code>additional</code> section. The example does not make use of that.
- Note also that the order of the <code>override</code> and
- <code>additional</code> sections in a configuration definition file does
- not matter. Sources in an <code>override</code> section are always treated with
- higher priority (otherwise they could not override the values of other
- sources).
- </p>
- </section>
</body>
</document>
1.2 +7 -10 jakarta-commons/configuration/xdocs/howto_xml.xml
Index: howto_xml.xml
===================================================================
RCS file: /home/cvs/jakarta-commons/configuration/xdocs/howto_xml.xml,v
retrieving revision 1.1
retrieving revision 1.2
diff -u -r1.1 -r1.2
--- howto_xml.xml 8 Mar 2004 23:21:31 -0000 1.1
+++ howto_xml.xml 28 Mar 2004 19:58:30 -0000 1.2
@@ -8,7 +8,7 @@
</properties>
<body>
- <section name="Using a XML based Configurations">
+ <section name="Using XML based Configurations">
<p>
This section explains how to use Hierarchical
and Structured XML datasets.
@@ -18,7 +18,7 @@
<section name="Hierarchical properties">
<p>
- The XML document we used so far was quite simple. Because of its
+ The XML document we used in the section about composite configuration was quite simple. Because of its
tree-like nature XML documents can represent data that is
structured in many ways. This section explains how to deal with
such structured documents.
@@ -178,14 +178,13 @@
<configuration>
<properties fileName="usergui.properties"/>
<dom4j fileName="gui.xml"/>
- <dom4j className="org.apache.commons.configuration.HierarchicalDOM4JConfiguration"
- fileName="tables.xml"/>
+ <hierarchicalDom4j fileName="tables.xml"/>
</configuration>
]]>
</source>
<p>
- Note the additional <code>className</code> attribute of the last
- <code>dom4j</code> element. This attribute tells the configuration
+ Note that one <code>dom4j</code> element was replaced by a
+ <code>hierarchicalDom4j</code> element. This element tells the configuration
factory that not the default class for processing XML documents
should be used, but the class <code>HierarchicalDOM4JConfiguration</code>.
As the name implies this class is capable of saving the
@@ -355,10 +354,8 @@
</override>
<additional>
- <dom4j className="org.apache.commons.configuration.HierarchicalDOM4JConfiguration"
- fileName="tables.xml"/>
- <dom4j className="org.apache.commons.configuration.HierarchicalDOM4JConfiguration"
- fileName="tasktables.xml" at="tables"/>
+ <hierarchicalDom4j fileName="tables.xml"/>
+ <hierarchicalDom4j fileName="tasktables.xml" at="tables"/>
</additional>
</configuration>
]]>
---------------------------------------------------------------------
To unsubscribe, e-mail: commons-dev-unsubscribe@jakarta.apache.org
For additional commands, e-mail: commons-dev-help@jakarta.apache.org