avalon-cvs mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From pro...@apache.org
Subject cvs commit: jakarta-avalon-excalibur/configuration/src/xdocs configuration-merger.xml
Date Fri, 19 Jul 2002 18:32:19 GMT
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&amp;r=1&amp;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: &lt;a&gt;&lt;b x="1"/&gt;&lt;/a&gt;
            Base: &lt;a&gt;&lt;b/&gt;&lt;/a&gt;
            Result: &lt;a&gt;&lt;b x="1"/&gt;&lt;b/&gt;&lt;/a&gt;
          </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>
            &lt;a&gt;&lt;b x="1" excalibur-configuration:merge="true"/&gt;&lt;/a&gt;
          </source>
  
          the result will be:
  
          <source>
            &lt;a&gt;&lt;b x="1"/&gt;&lt;/a&gt;
          </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:
              &lt;a&gt;
                &lt;b x="1" excalibur-configuration:merge="true" excalibur-configuration:key-attribute="x"&gt;
                  &lt;c&gt;
                &lt;/b&gt;
                &lt;b x="2"/&gt;
              &lt;/a&gt;
  
              Base:
              &lt;a&gt;
                &lt;b x="1"/&gt;
                &lt;b x="2"/&gt;
              &lt;/a&gt;
            </source>
  
            Thus in order to merge &lt;b x="1"/&gt;, 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:   <mailto:avalon-cvs-unsubscribe@jakarta.apache.org>
For additional commands, e-mail: <mailto:avalon-cvs-help@jakarta.apache.org>


Mime
View raw message