You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@commons.apache.org by si...@apache.org on 2010/08/31 10:40:06 UTC
svn commit: r991120 - in /commons/proper/digester/trunk/src/site: site.xml
xdoc/xmlrules.xml
Author: simonetripodi
Date: Tue Aug 31 08:40:06 2010
New Revision: 991120
URL: http://svn.apache.org/viewvc?rev=991120&view=rev
Log:
added xmlrules description
Added:
commons/proper/digester/trunk/src/site/xdoc/xmlrules.xml (with props)
Modified:
commons/proper/digester/trunk/src/site/site.xml
Modified: commons/proper/digester/trunk/src/site/site.xml
URL: http://svn.apache.org/viewvc/commons/proper/digester/trunk/src/site/site.xml?rev=991120&r1=991119&r2=991120&view=diff
==============================================================================
--- commons/proper/digester/trunk/src/site/site.xml (original)
+++ commons/proper/digester/trunk/src/site/site.xml Tue Aug 31 08:40:06 2010
@@ -36,6 +36,7 @@
<item name="Core APIs" href="/core.html"/>
<item name="Plugins" href="/plugins.html"/>
<item name="Substitution" href="/substitution.html"/>
+ <item name="XML Rules" href="/xmlrules.html"/>
<item name="FAQ" href="/faq.html"/>
</menu>
Added: commons/proper/digester/trunk/src/site/xdoc/xmlrules.xml
URL: http://svn.apache.org/viewvc/commons/proper/digester/trunk/src/site/xdoc/xmlrules.xml?rev=991120&view=auto
==============================================================================
--- commons/proper/digester/trunk/src/site/xdoc/xmlrules.xml (added)
+++ commons/proper/digester/trunk/src/site/xdoc/xmlrules.xml Tue Aug 31 08:40:06 2010
@@ -0,0 +1,245 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<!--
+Licensed to the Apache Software Foundation (ASF) under one or more
+contributor license agreements. See the NOTICE file distributed with
+this work for additional information regarding copyright ownership.
+The ASF licenses this file to You under the Apache License, Version 2.0
+(the "License"); you may not use this file except in compliance with
+the License. You may obtain a copy of the License at
+
+ http://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing, software
+distributed under the License is distributed on an "AS IS" BASIS,
+WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+See the License for the specific language governing permissions and
+limitations under the License.
+-->
+<document xmlns="http://maven.apache.org/XDOC/2.0"
+ xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
+ xsi:schemaLocation="http://maven.apache.org/XDOC/2.0 http://maven.apache.org/xsd/xdoc-2.0.xsd">
+ <properties>
+ <title>Download Commons Digester</title>
+ <author email="dev@commons.apache.org">Commons Documentation Team</author>
+ </properties>
+ <body>
+ <section name="Documentation for org.apache.commons.digester.xmlrules">
+ <p>The <code>xmlrules</code> package provides for XML-based definition of
+rules for <code>Digester</code>. This improves maintainability of Java code,
+as rules are now defined in XML and read into <code>Digester</code> at run-time.
+</p>
+
+ <subsection name="Introduction">
+ <p>This is a brief overview of the digester-rules-in-XML feature. Briefly,
+this feature lets you define Digester rules in XML, instead of
+creating and initializing the Rules objects programmatically, which can become
+tedious. In addition, it allows for including of one XML rules file within
+another, inclusion of programmatically created rule sets within an XML file
+(via reflection), and recursively nested matching pattern specifications.
+</p>
+ </subsection>
+
+ <subsection name="Overview of digester-rules.dtd">
+ <p>A DTD, named <code>digester-rules.dtd</code> has been defined to help in the
+understanding of how the loader operates.
+</p>
+<p>
+The DTD is distributed in the <code>commons-digester.jar</code>. It can be found at
+<code>org/apache/commons/digester/xmlrules/digester-rules.dtd</code>. It is not available
+for download from the Apache website since users are best advised to use a copy stored
+on their local system.
+</p>
+
+<p>Digester input documents wishing to cite this DTD should include the
+following DOCTYPE declaration:</p>
+<source>
+ <!DOCTYPE digester-rules PUBLIC
+ "-//Jakarta Apache //DTD digester-rules XML V1.0//EN"
+ "digester-rules.dtd">
+</source>
+ </subsection>
+
+ <subsection name="Rule elements">
+ <p>The DTD defines an element type corresponding to each predefined Digester
+rule. Each rule element type includes attributes for values needed to
+initialize the rule, and an optional <code>pattern</code> attribute
+specifying the pattern to associate with the rule.</p>
+<p>The <code>DigesterLoader</code> adds the rules to the digester in the order in
+which they occur in the XML.</p>
+<p>The use of each rule element type should be self-explanatory, if you compare
+them to the API documentation for the <code>Digester</code> rules classes.
+</p>
+ </subsection>
+
+ <subsection name="Defining matching patterns">
+ <p>The matching pattern is a simple, xpath-like string which the
+<code>Digester</code> uses to determine which elements to apply each rule to.
+See the <code>Digester</code> <a href="/core.html">documentation</a> for
+more details.</p>
+<p>
+There are two methods for associating patterns to rules in the XML file. One
+is for each rule element to directly define its pattern in a
+<code>pattern</code> attribute. An example would like something like:</p>
+<source>
+ <digester-rules>
+ <object-create-rule pattern="*/foo" classname="Foo"/>
+ <set-properties-rule pattern="*/foo"/>
+ </digester-rules>
+</source>
+<p>
+In the above example, an <code>ObjectCreateRule</code> is created and
+associated with the pattern "*/foo"; then a <code>SetPropertiesRule</code> is
+created and associated with the pattern "*/foo".</p>
+<p>The other method is to nest rules elements inside a
+<code><pattern></code> element. In this way, the same pattern can be
+defined for a group of rules. The following example has the same effect as the
+previous example:</p>
+<source>
+ <digester-rules>
+ <pattern value="*/foo">
+ <object-create-rule classname="Foo"/>
+ <set-properties-rule/>
+ </pattern>
+ </digester-rules>
+</source>
+<p>Pattern elements can be recursively nested. If patterns are nested, the pattern
+string is formed by concatenating all the patterns together. Example:</p>
+<source>
+ <digester-rules>
+ <pattern value="*/foo">
+ <pattern value="bar">
+ <object-create-rule classname="Foobar"/>
+ <set-properties-rule/>
+ </pattern>
+ </pattern>
+ </digester-rules>
+</source>
+<p>
+In the above example, an <code>ObjectCreateRule</code> and a
+<code>SetPropertiesRule</code> are associated with the matching pattern
+"*/foo/bar".</p>
+<p>The use of pattern elements and the use of the pattern attribute inside rules
+elements can be freely mixed. The next example has the same effect as the
+previous example:</p>
+<source>
+ <digester-rules>
+ <pattern value="*/foo">
+ <object-create-rule pattern="bar" classname="Foobar"/>
+ <set-properties-rule pattern="bar"/>
+ </pattern>
+ </digester-rules>
+</source>
+ </subsection>
+
+ <subsection name="Including rules XML files within other rules XML files">
+ <p>
+The <code><include></code> element lets you include one rules file within
+another. With respect to pattern concatenation, the <code>DigesterLoader</code>
+behaves as if the include file was 'macro-expanded'. Example:</p>
+<source>
+ File rules1.xml:
+ <?xml version="1.0"?>
+ <!DOCTYPE digester-rules SYSTEM "digester-rules.dtd">
+
+ <digester-rules>
+ <pattern value="root/foo">
+ <object-create-rule classname="Foo"/>
+
+ <include path="rules2.xml"/>
+ </pattern>
+ </digester-rules>
+
+
+ File rules2.xml:
+ <?xml version="1.0"?>
+ <!DOCTYPE digester-rules SYSTEM "digester-rules.dtd">
+
+ <digester-rules>
+ <pattern value="bar">
+ <object-create-rule classname="Bar"/>
+ </pattern>
+ </digester-rules>
+</source>
+<p>
+Parsing rule1.xml would result in a <code>Digester</code> initialized with these
+pattern/rule pairs:</p>
+<source>
+ root/foo -> ObjectCreateRule(Foo)
+
+ root/foo/bar -> ObjectCreateRule(Bar)
+</source>
+<p>Note that the pattern for the 'bar' rule has been prepended with the 'root/foo'
+pattern. If rule2.xml was parsed by itself, it would yield a <code>Digester</code>
+initialized with this pattern/rule:</p>
+<source>
+ bar -> ObjectCreateRule(Bar)
+</source>
+ </subsection>
+
+ <subsection name="Including programmatically-created rules">
+ <p>Sometimes rules cannot be easily defined via XML. Rule sets that are created
+programmatically can still be included within a digester-rules XML file. This
+is done by using an <code><include></code> element with a
+<code>class</code> attribute, containing the name of a class that implements
+<code>org.apache.commons.digester.xmlrules.DigesterRulesSource</code>.
+This interface defines one method, <code>getRules(Digester)</code>, which
+creates rules and adds them to the supplied Digester. The pattern concatenation
+works exactly as if the rules had been included from an XML file. Example:</p>
+<source>
+ File rules3.xml:
+ <?xml version="1.0"?>
+ <!DOCTYPE digester-rules SYSTEM "digester-rules.dtd">
+
+ <digester-rules>
+ <pattern value="root/foo">
+ <object-create-rule classname="Foo"/>
+
+ <include class="BarRuleCreator"/>
+ </pattern>
+ </digester-rules>
+</source>
+<p>BarRuleCreator class definition:</p>
+<source>
+ public class BarRuleCreator implements DigesterRulesSource {
+ public void getRules(Digester digester) {
+ digester.addObjectCreate("bar", "Bar");
+ }
+ }
+</source>
+<p>
+Parsing rules3.xml yields the same results as rules1.xml above:
+</p>
+<source>
+ root/foo -> ObjectCreateRule(Foo)
+
+ root/foo/bar -> ObjectCreateRule(Bar)
+</source>
+ </subsection>
+
+ <subsection name="Creating a digester from XML">
+ <p><code>FromXmlRuleSet</code> is a <code>RuleSet</code> implementation that
+initializes its <code>Digester</code> from rules defined in an XML file. The
+path to the XML file is passed to constructor.</p>
+<p>Alternatively, the convenience class <code>DigesterLoader</code> defines a
+static method,
+<code>Digester createDigester(String rulesXml) throws DigesterLoaderException</code>".
+When passing the name of the file that contains your digester rules, this
+method returns a <code>Digester</code> instance initialized with the rules.</p>
+<p>To add your own rules, you need to:</p>
+<ul>
+<li>Update the DTD<br />You should add an element type for your rule. The
+element should have an attribute corresponding to each of the rule's
+initialization parameters.
+</li>
+<li>Define an <code>ObjectCreationFactory</code>
+</li>
+<li>Extend <code>DigesterRuleParser</code><br /><code>DigesterRuleParser</code>
+is a <code>RuleSet</code> for parsing a rules XML file. You should extend this,
+and override the <code>addRuleInstances()</code> method to add the rules for
+parsing your new element. Look in DigesterRuleParser.java to see how its done.
+</li>
+</ul>
+ </subsection>
+ </section>
+ </body>
+</document>
Propchange: commons/proper/digester/trunk/src/site/xdoc/xmlrules.xml
------------------------------------------------------------------------------
svn:eol-style = native
Propchange: commons/proper/digester/trunk/src/site/xdoc/xmlrules.xml
------------------------------------------------------------------------------
svn:keywords = Date Revision Author HeadURL Id
Propchange: commons/proper/digester/trunk/src/site/xdoc/xmlrules.xml
------------------------------------------------------------------------------
svn:mime-type = text/xml