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]>
