org.apache.commons.digester
Class ExtendedBaseRules
- Rules
public class ExtendedBaseRules
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:
- Parent Match - Will match child elements of a particular
kind of parent. This is useful if a parent has a particular method
to call.
"a/b/c/?"
matches any child whose parent matches
"a/b/c"
. Exact parent rules take precedence over
standard wildcard tail endings.
"*/a/b/c/?"
matches any child whose parent matches
"*/a/b/c". The longest matching still applies to parent
matches but the length excludes the '?', which effectively means
that standard wildcard matches with the same level of depth are
chosen in preference.
Ancester Match - Will match elements who parentage includes
a particular sequence of elements.
"a/b/*"
matches any element whose parentage path starts with
'a' then 'b'. Exact parent and parent match rules take precedence. The longest
ancester match will take precedence.
"*/a/b/*"
matches any elements whose parentage path contains
an element 'a' followed by an element 'b'. The longest matching still applies
but the length excludes the '*' at the end.
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.
- Pattern
"!*/a/b"
matches whenever an 'b' element
is inside an 'a'.
- Pattern
"!a/b/?"
matches any child of a parent
matching "a/b"
.
- Pattern
"!*/a/b/?"
matches any child of a parent
matching "!*/a/b"
- Pattern
"!a/b/*"
matches any element whose parentage path starts with
"a" then "b".
- Pattern
"!*/a/b/*"
matches any elements whose parentage path contains
'a/b'
Wild Match
- Pattern
"*"
matches every pattern that isn't matched
by any other basic rule.
- Pattern
"!*"
matches every pattern.
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.
private int | counter - Counts the entry number for the rules.
|
private Map | order - The decision algorithm used (unfortunately) doesn't preserve the entry
order.
|
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.
|
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.
add
public void add(String pattern,
Rule rule)
Register a new Rule instance matching the specified pattern.
- add in interface Rules
- add in interface RulesBase
pattern
- Nesting pattern to be matched for this Rulerule
- 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.
- match in interface Rules
- match in interface RulesBase
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