org.apache.commons.digester
Class ExtendedBaseRules

java.lang.Object
  extended by org.apache.commons.digester.RulesBase
      extended by org.apache.commons.digester.ExtendedBaseRules
All Implemented Interfaces:
Rules

public class ExtendedBaseRules
extends RulesBase

Extension of RulesBase for complex schema.

This is an extension of the basic pattern matching scheme intended to improve support for mapping complex xml-schema. It is intended to be a minimal extension of the standard rules big enough to support complex schema but without the full generality offered by more exotic matching pattern rules.

When should you use this rather than the original?

This pattern-matching engine is complex and slower than the basic default RulesBase class, but offers more functionality:

Universal Match Patterns

The default RulesBase pattern-matching engine always attempts to find the "best matching pattern", and will ignore rules associated with other patterns that match but are not "as good". As an example, if the pattern "a/b/c" is associated with rules 1 and 2, and "*/c" is associated with rules 3 and 4 then element "a/b/c" will cause only rules 1 and 2 to execute. Rules 3 and 4 do have matching patterns, but because the patterns are shorter and include wildcard characters they are regarded as being "not as good" as a direct match. In general, exact patterns are better than wildcard patterns, and among multiple patterns with wildcards, the longest is preferred. See the RulesBase class for more information.

This feature of preferring "better" patterns can be a powerful tool. However it also means that patterns can interact in unexpected ways.

When using the ExtendedBaseRules, any pattern prefixed with '!' bypasses the "best match" feature. Even if there is an exact match or a longer wildcard match, patterns prefixed by '!' will still be tested to see if they match, and if so their associated Rule objects will be included in the set of rules to be executed in the normal manner.

Parent Match Patterns

These will match direct child elements of a particular parent element.

Ancestor Match Patterns

These will match elements whose parentage includes a particular sequence of elements.

Completely Wild Patterns

Pattern "*" matches every pattern that isn't matched by any other basic rule.

Pattern "!*" matches every pattern.

Using The Extended Rules

By default, a Digester instance uses a RulesBase instance as its pattern matching engine. To use an ExtendedBaseRules instance, call the Digester.setRules method before adding any Rule objects to the digester instance:

     Digester digester = new Digester();
     digester.setRules( new ExtendedBaseRules() );
 

The most important thing to remember when using the extended rules is that universal and non-universal patterns are completely independent. Universal patterns are never affected by the addition of new patterns or the removal of existing ones. Non-universal patterns are never affected by the addition of new universal patterns or the removal of existing universal patterns. As in the basic matching rules, non-universal (basic) patterns can be affected by the addition of new non-universal patterns or the removal of existing non-universal patterns, because only rules associated with the "best matching" pattern for each xml element are executed.

This means that you can use universal patterns to build up the simple parts of your structure - for example defining universal creation and property setting rules. More sophisticated and complex mapping will require non-universal patterns and this might mean that some of the universal rules will need to be replaced by a series of special cases using non-universal rules. But by using universal rules as your backbone, these additions should not break your existing rules.


Field Summary
 
Fields inherited from class org.apache.commons.digester.RulesBase
cache, digester, namespaceURI, rules
 
Constructor Summary
ExtendedBaseRules()
           
 
Method Summary
 void add(String pattern, Rule rule)
          Register a new Rule instance matching the specified pattern.
 List match(String namespace, String pattern)
          Return a List of all registered Rule instances that match the specified nesting pattern, or a zero-length List if there are no matches.
 
Methods inherited from class org.apache.commons.digester.RulesBase
clear, getDigester, getNamespaceURI, lookup, match, rules, setDigester, setNamespaceURI
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Constructor Detail

ExtendedBaseRules

public ExtendedBaseRules()
Method Detail

add

public void add(String pattern,
                Rule rule)
Register a new Rule instance matching the specified pattern.

Specified by:
add in interface Rules
Overrides:
add in class RulesBase
Parameters:
pattern - Nesting pattern to be matched for this Rule
rule - Rule instance to be registered

match

public List match(String namespace,
                  String pattern)
Return a List of all registered Rule instances that match the specified nesting pattern, or a zero-length List if there are no matches. If more than one Rule instance matches, they must be returned in the order originally registered through the add() method.

Specified by:
match in interface Rules
Overrides:
match in class RulesBase
Parameters:
pattern - Nesting pattern to be matched
namespace - Namespace URI for which to select matching rules, or null to match regardless of namespace URI


Copyright © 2001-2009 The Apache Software Foundation. All Rights Reserved.