You are viewing a plain text version of this content. The canonical link for it is here.
Posted to cvs@avalon.apache.org by pr...@apache.org on 2002/07/19 20:32:19 UTC
cvs commit: jakarta-avalon-excalibur/configuration/src/xdocs configuration-merger.xml
proyal 2002/07/19 11:32:19
Added: configuration/src/xdocs configuration-merger.xml
Log:
Docs on Configuration Merger
Revision Changes Path
1.1 jakarta-avalon-excalibur/configuration/src/xdocs/configuration-merger.xml
Index: configuration-merger.xml
===================================================================
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE document SYSTEM "dtd/document-v10.dtd">
<document>
<header>
<title>Configuration Merger</title>
<authors>
<person name="Peter Royal" email="proyal@apache.org"/>
</authors>
</header>
<body>
<s1 title="What is the Configuration Merger?">
<p>
The Configuration Merger can take two Configurations, a <em>base</em> and a
<em>layer</em>. It will then <strong>merge</strong> the layer onto the base
</p>
</s1>
<s1 title="Why not CascadingConfiguration?">
<p>There was a
<link href="http://marc.theaimsgroup.com/?t=101359616800001&r=1&w=2">long thread</link>
on what the rules for cascading should be.
</p>
<p>
The CascadingConfiguration did not attempt to handle the specific case
mentioned in the link above, which is namely the following situation:
<source>
Layer: <a><b x="1"/></a>
Base: <a><b/></a>
Result: <a><b x="1"/><b/></a>
</source>
when using Configuration.getChild(name), CascadingConfiguration would do the
right thing, but it didn't even attempt to when using
Configuration.getChildren. We need a sane result from getChildren because we
serialize the merged configurations when validating them. In the above
example, the result expected should probably be the same as the layer.
</p>
</s1>
<s1 title="Merging children in a deterministic manner">
<p>
But how do we know that's what the user wants? We don't (at least I'm missing
the ESP module for my computer). The answer? <strong>metadata</strong>
</p>
<p>
The ConfigurationMerger will use a specially named attribute,
<em>excalibur-configuration:merge</em>, to control the merging of layer
children with base children. For the example above, you will get the result above. But with
the magic attribute on the layer:
<source>
<a><b x="1" excalibur-configuration:merge="true"/></a>
</source>
the result will be:
<source>
<a><b x="1"/></a>
</source>
</p>
<p>
The <em>excalibur-configuration:merge</em> attribute is removed during the merge,
since it metadata only needed to merge. Why is it removed? In case you are merging
two configurations and then need to serialize the result for validation, you don't
want merge metadata breaking that
</p>
<p>
A limitation is that there can only be a <strong>single</strong> child in both the
layer and base with the same getName(). With complex configurations this could cause
a problem.
</p>
<s2 title="What if there are multiple children with the same getName()">
<p>
There is a solution. It is possible to define a <strong>key attibute</strong>
using the magic attribute <em>excalibur-configuration:key-attribute</em>
</p>
<p>
When using a key attribute, the two items to merge must not only have the same
name, they must also have the same value for the key attribute.
<source>
Layer:
<a>
<b x="1" excalibur-configuration:merge="true" excalibur-configuration:key-attribute="x">
<c>
</b>
<b x="2"/>
</a>
Base:
<a>
<b x="1"/>
<b x="2"/>
</a>
</source>
Thus in order to merge <b x="1"/>, the name must be the same
<strong>and</strong> the <em>x</em> attribute must have the same value.
</p>
</s2>
</s1>
</body>
<footer>
<legal>
Copyright (c) @year@ The Jakarta Apache Project All rights reserved.
$Revision: 1.1 $ $Date: 2002/07/19 18:32:19 $
</legal>
</footer>
</document>
--
To unsubscribe, e-mail: <ma...@jakarta.apache.org>
For additional commands, e-mail: <ma...@jakarta.apache.org>