proyal 2002/07/22 14:21:12
Added: docs/excalibur/configuration configuration-merger.html
index.html
Log:
Adding configuration to site
Revision Changes Path
1.1
jakarta-avalon-site/docs/excalibur/configuration/configuration-merger.html
Index: configuration-merger.html
===================================================================
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN"
"http://www.w3.org/TR/html4/loose.dtd";>
<html><head><META http-equiv="Content-Type" content="text/html;
charset=ISO-8859-1"><link rel="stylesheet" href="skin/tigris.css"
type="text/css"><link rel="stylesheet" href="skin/site.css"
type="text/css"><link media="print" rel="stylesheet" href="skin/print.css"
type="text/css"><meta value="Avalon Documentation Team" name="author"><meta
value="[email protected]" name="email"><title>Configuration
Merger</title></head><body class="composite" marginheight="0"
marginwidth="0"><div id="banner"><table width="100%" cellpadding="8"
cellspacing="0" border="0"><tbody><tr><td align="left"><a
href="http://jakarta.apache.org/";><img border="0"
src="images/jakarta-logo.gif"></a></td><td align="right"><a
href="http://jakarta.apache.org/avalon/";><img border="0"
src="images/header.gif"></a></td></tr></tbody></table></div><div
id="breadcrumbs"><script src="skin/breadcrumbs.js" language="JavaScript"
type="text/javascript"></script></div><table id="main" width="100%"
cellpadding="8" cellspacing="0" border="0"><tbody><tr valign="top"><td
id="leftcol"><div id="navcolumn"><div><strong>About</strong><div><a
href="index.html">Overview</a></div><div><a
href="configuration-merger.html">Configuration Merger</a></div><div><a
href="http://jakarta.apache.org/avalon/excalibur/index.html";>Excalibur
Home</a></div><div><a
href="http://jakarta.apache.org/builds/jakarta-avalon-excalibur/release";>Download</a></div><div><a
href="api">API Docs</a></div></div></div></td><td><div id="bodycol"><div
class="app"><div align="center"><h1>Configuration
Merger</h1><h2></h2></div><div class="h3">
<div class="h3"><h3>What is the Configuration Merger?</h3></div>
<p>
The Configuration Merger can take two Configurations, a <i>base</i>
and a
<i>layer</i>. It will then <b>merge</b> the layer onto the base
</p>
<div class="h3"><h3>Why not CascadingConfiguration?</h3></div>
<p>There was a
<a
href="http://marc.theaimsgroup.com/?t=101359616800001&r=1&w=2";>long thread</a>
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:
<pre>
Layer: <a><b x="1"/></a>
Base: <a><b/></a>
Result: <a><b x="1"/><b/></a>
</pre>
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>
<div class="h3"><h3>Merging children in a deterministic manner</h3></div>
<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? <b>metadata</b>
</p>
<p>
The ConfigurationMerger will use a specially named attribute,
<i>excalibur-configuration:merge</i>, 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:
<pre>
<a><b x="1"
excalibur-configuration:merge="true"/></a>
</pre>
the result will be:
<pre>
<a><b x="1"/></a>
</pre>
</p>
<p>
The <i>excalibur-configuration:merge</i> 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 <b>single</b> child in both
the
layer and base with the same getName(). With complex configurations
this could cause
a problem.
</p>
<div class="h4"><h4>What if there are multiple children with the same
getName()</h4></div>
<p>
There is a solution. It is possible to define a <b>key attibute</b>
using the magic attribute
<i>excalibur-configuration:key-attribute</i>
</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.
<pre>
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>
</pre>
Thus in order to merge <b x="1"/>, the name must be the same
<b>and</b> the <i>x</i> attribute must have the same value.
</p>
<div id="authors" align="right">by <a href="mailto:[EMAIL
PROTECTED]">Peter
Royal</a></div></div></div></div></td></tr></tbody></table><div
id="footer"><table width="100%" cellpadding="4" cellspacing="0"
border="0"><tbody><tr><td align="left">Copyright © 1999-2002 Apache
Software Foundation. All Rights Reserved.</td><td></td><td
align="right"><script language="JavaScript">
<!--
document.write("last modified: " +
document.lastModified);
// -->
</script></td></tr></tbody></table></div></body></html>
1.1
jakarta-avalon-site/docs/excalibur/configuration/index.html
Index: index.html
===================================================================
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN"
"http://www.w3.org/TR/html4/loose.dtd";>
<html><head><META http-equiv="Content-Type" content="text/html;
charset=ISO-8859-1"><link rel="stylesheet" href="skin/tigris.css"
type="text/css"><link rel="stylesheet" href="skin/site.css"
type="text/css"><link media="print" rel="stylesheet" href="skin/print.css"
type="text/css"><meta value="Avalon Documentation Team" name="author"><meta
value="[email protected]" name="email"><title>Excalibur
Configuration - Overview</title></head><body class="composite" marginheight="0"
marginwidth="0"><div id="banner"><table width="100%" cellpadding="8"
cellspacing="0" border="0"><tbody><tr><td align="left"><a
href="http://jakarta.apache.org/";><img border="0"
src="images/jakarta-logo.gif"></a></td><td align="right"><a
href="http://jakarta.apache.org/avalon/";><img border="0"
src="images/header.gif"></a></td></tr></tbody></table></div><div
id="breadcrumbs"><script src="skin/breadcrumbs.js" language="JavaScript"
type="text/javascript"></script></div><table id="main" width="100%"
cellpadding="8" cellspacing="0" border="0"><tbody><tr valign="top"><td
id="leftcol"><div id="navcolumn"><div><strong>About</strong><div><a
href="index.html">Overview</a></div><div><a
href="configuration-merger.html">Configuration Merger</a></div><div><a
href="http://jakarta.apache.org/avalon/excalibur/index.html";>Excalibur
Home</a></div><div><a
href="http://jakarta.apache.org/builds/jakarta-avalon-excalibur/release";>Download</a></div><div><a
href="api">API Docs</a></div></div></div></td><td><div id="bodycol"><div
class="app"><div align="center"><h1>Excalibur Configuration -
Overview</h1><h2></h2></div><div class="h3">
<div class="h3"><h3>Introduction</h3></div>
<p>
The Configuration package contains extensions to the Avalon Framework
supporting configuration management.
</p>
<div class="h3"><h3>Resources</h3></div>
<div class="h4"><h4>CascadingConfiguration</h4></div>
<p>
Provides support for the creation of a base and default parent relationship
between two configuration instances. This is helpful when you have a default
configuration together with a configuration that contains overriding values.
The level of cascading of configurations is arbitary. The
CascadingConfiguration
implementation impements the classic Configuration interface and delegates
invocations to the base configuration. If the delegate operation fails, the
implementation will attempt to resolve the invocation against the parent
configuration. Both base and parent configuration reference can be classic or
cascading enabling the creation of complex configuration graphs.
</p>
<div class="h4"><h4>ConfigurationUtil</h4></div>
<p>
Provides a static list operation that is helpful in debugging. The list
operation generates a simple string representation of a configuration.
</p>
<p>
Also provides a branch operation to take a Configuration object and rename it
but
retain all attributes and children
</p>
<div class="h4"><h4>ConfigurationMerger</h4></div>
<p>
Similar to the CascadingConfiguration in that it takes two Configuration's and
makes one. The ConfigurationMerger can take a "layer" and a "base" and merge
the layer with the base. The ConfigurationMerger goes a step farther than the
CascadingConfiguration in that it provides a consistent view of
Configuration.getChildren() based off of meta-attributes that can exist in the
layer.
</p>
<div id="authors" align="right">by <a href="mailto:[EMAIL
PROTECTED]">Stephen McConnell</a>, <a href="mailto:[EMAIL
PROTECTED]">Peter
Royal</a></div></div></div></div></td></tr></tbody></table><div
id="footer"><table width="100%" cellpadding="4" cellspacing="0"
border="0"><tbody><tr><td align="left">Copyright © 1999-2002 Apache
Software Foundation. All Rights Reserved.</td><td></td><td
align="right"><script language="JavaScript">
<!--
document.write("last modified: " +
document.lastModified);
// -->
</script></td></tr></tbody></table></div></body></html>
--
To unsubscribe, e-mail: <mailto:[EMAIL PROTECTED]>
For additional commands, e-mail: <mailto:[EMAIL PROTECTED]>
