org.apache.commons.digester

Class ExtendedBaseRules

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?

These rules are complex and slower but offer more functionality. The RulesBase matching set allows interaction between patterns. This allows sophisticated matching schema to be created but it also means that it can be hard to create and debug mappings for complex schema. This extension introduces universal versions of these patterns that always act independently.

Another three kinds of matching pattern are also introduced. The parent matchs allow common method to be easily called for children. The wildcard match allows rules to be specified for all elements.

The additional matching patterns:

  • Ancester Match - Will match elements who parentage includes a particular sequence of elements.
  • Universal Wildcard Match - Any pattern prefixed with '!' bypasses the longest matching rule. Even if there is an exact match or a longer wildcard match, patterns prefixed by '!' will still be tested to see if they match. This can be used for example to specify universal construction rules.
  • Wild Match
  • Using The Extended Rules

    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 effected by the addition of new patterns or the removal of existing ones. Non-universal patterns are never effected 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 effected by the addition of new non-universal patterns or the removal of existing non-universal patterns.

    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

    private int
    counter
    Counts the entry number for the rules.
    private Map
    order
    The decision algorithm used (unfortunately) doesn't preserve the entry order.

    Fields inherited from class org.apache.commons.digester.RulesBase

    cache, digester, namespaceURI, rules

    Method Summary

    void
    add(String pattern, Rule rule)
    Register a new Rule instance matching the specified pattern.
    private boolean
    basicMatch(String key, String pattern)
    Standard match.
    private List
    findExactAncesterMatch(String parentPattern)
    Finds an exact ancester match for given 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.
    private boolean
    parentMatch(String key, String pattern, String parentPattern)
    Matching parent.

    Methods inherited from class org.apache.commons.digester.RulesBase

    add, clear, getDigester, getNamespaceURI, lookup, match, match, rules, setDigester, setNamespaceURI

    Field Details

    counter

    private int counter
    Counts the entry number for the rules.


    order

    private Map order
    The decision algorithm used (unfortunately) doesn't preserve the entry order. This map is used by a comparator which orders the list of matches before it's returned. This map stores the entry number keyed by the rule.

    Method Details

    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 interface RulesBase

    Parameters:
    pattern - Nesting pattern to be matched for this Rule
    rule - Rule instance to be registered


    basicMatch

    private boolean basicMatch(String key,
                               String pattern)
    Standard match. Matches the end of the pattern to the key.


    findExactAncesterMatch

    private List findExactAncesterMatch(String parentPattern)
    Finds an exact ancester match for given pattern


    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 interface RulesBase

    Parameters:
    pattern - Nesting pattern to be matched


    parentMatch

    private boolean parentMatch(String key,
                                String pattern,
                                String parentPattern)
    Matching parent.


    Copyright (c) 2001-2004 - Apache Software Foundation