|
||||||||||
PREV CLASS NEXT CLASS | FRAMES NO FRAMES | |||||||||
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD |
java.lang.Object | +--org.apache.commons.digester.Rule | +--org.apache.commons.digester.SetNestedPropertiesRule
Rule implementation that sets properties on the object at the top of the stack, based on child elements with names matching properties on that object.
Example input that can be processed by this rule:
[widget] [height]7[/height] [width]8[/width] [label]Hello, world[/label] [/widget]
This rule supports custom mapping of attribute names to property names.
The default mapping for particular attributes can be overridden by using
SetNestedPropertiesRule(String[] elementNames,
String[] propertyNames)
.
This allows child elements to be mapped to properties with different names.
Certain elements can also be marked to be ignored.
A very similar effect can be achieved using a combination of the
BeanPropertySetterRule
and the ExtendedBaseRules
rules manager; this Rule
, however, works fine with the default
RulesBase
rules manager.
Implementation Notes
This class works by creating its own simple Rules implementation. When begin is invoked on this rule, the digester's current rules object is replaced by a custom one. When end is invoked for this rule, the original rules object is restored. The digester rules objects therefore behave in a stack-like manner.
For each child element encountered, the custom Rules implementation ensures that a special AnyChildRule instance is included in the matches returned to the digester, and it is this rule instance that is responsible for setting the appropriate property on the target object (if such a property exists). The effect is therefore like a "trailing wildcard pattern". The custom Rules implementation also returns the matches provided by the underlying Rules implementation for the same pattern, so other rules are not "disabled" during processing of a SetNestedPropertiesRule.
Nested Class Summary | |
private class |
SetNestedPropertiesRule.AnyChildRule
|
private class |
SetNestedPropertiesRule.AnyChildRules
Private Rules implementation |
Field Summary | |
private boolean |
allowUnknownChildElements
|
private SetNestedPropertiesRule.AnyChildRule |
anyChildRule
|
private java.util.HashMap |
elementNames
|
private org.apache.commons.logging.Log |
log
|
private SetNestedPropertiesRule.AnyChildRules |
newRules
|
private Rules |
oldRules
|
private static java.lang.String |
PROP_IGNORE
Dummy object that can be placed in collections to indicate an ignored property when null cannot be used for that purpose. |
private boolean |
trimData
|
Fields inherited from class org.apache.commons.digester.Rule |
digester, namespaceURI |
Constructor Summary | |
SetNestedPropertiesRule()
Base constructor. |
|
SetNestedPropertiesRule(java.lang.String[] elementNames,
java.lang.String[] propertyNames)
Constructor allows element->property mapping to be overriden. |
|
SetNestedPropertiesRule(java.lang.String elementName,
java.lang.String propertyName)
Convenience constructor overrides the mapping for just one property. |
Method Summary | |
void |
addAlias(java.lang.String elementName,
java.lang.String propertyName)
Add an additional element name to property name mapping. |
void |
begin(java.lang.String namespace,
java.lang.String name,
org.xml.sax.Attributes attributes)
Process the beginning of this element. |
void |
body(java.lang.String bodyText)
This is only invoked after all child elements have been processed, so we can remove the custom Rules object that does the child-element-matching. |
boolean |
getAllowUnknownChildElements()
See setAllowUnknownChildElements(boolean) . |
boolean |
getTrimData()
See setTrimData(boolean) . |
void |
setAllowUnknownChildElements(boolean allowUnknownChildElements)
When set to true, any child element for which there is no corresponding object property will cause an error to be reported. |
void |
setDigester(Digester digester)
Invoked when rule is added to digester. |
void |
setTrimData(boolean trimData)
When set to true, any text within child elements will have leading and trailing whitespace removed before assignment to the target object. |
java.lang.String |
toString()
Render a printable version of this Rule. |
Methods inherited from class org.apache.commons.digester.Rule |
begin, body, end, end, finish, getDigester, getNamespaceURI, setNamespaceURI |
Methods inherited from class java.lang.Object |
clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait |
Field Detail |
private static final java.lang.String PROP_IGNORE
private org.apache.commons.logging.Log log
private SetNestedPropertiesRule.AnyChildRule anyChildRule
private SetNestedPropertiesRule.AnyChildRules newRules
private Rules oldRules
private boolean trimData
private boolean allowUnknownChildElements
private java.util.HashMap elementNames
Constructor Detail |
public SetNestedPropertiesRule()
public SetNestedPropertiesRule(java.lang.String elementName, java.lang.String propertyName)
Convenience constructor overrides the mapping for just one property.
For details about how this works, see
SetNestedPropertiesRule(String[] elementNames,
String[] propertyNames)
.
elementName
- map the child element to matchpropertyName
- to a property with this namepublic SetNestedPropertiesRule(java.lang.String[] elementNames, java.lang.String[] propertyNames)
Constructor allows element->property mapping to be overriden.
Two arrays are passed in. One contains the element names and the other the property names. The element name / property name pairs are match by position In order words, the first string in the element name list matches to the first string in the property name list and so on.
If a property name is null or the element name has no matching property name, then this indicates that the element should be ignored.
The following constructs a rule that maps the alt-city
element to the city
property and the alt-state
to the state
property.
All other child elements are mapped as usual using exact name matching.
SetNestedPropertiesRule(
new String[] {"alt-city", "alt-state"},
new String[] {"city", "state"});
The following constructs a rule that maps the class
element to the className
property.
The element ignore-me
is not mapped.
All other elements are mapped as usual using exact name matching.
SetPropertiesRule(
new String[] {"class", "ignore-me"},
new String[] {"className"});
elementNames
- names of elements to mappropertyNames
- names of properties mapped toMethod Detail |
public void setDigester(Digester digester)
setDigester
in class Rule
public void setTrimData(boolean trimData)
public boolean getTrimData()
setTrimData(boolean)
.
public void setAllowUnknownChildElements(boolean allowUnknownChildElements)
public boolean getAllowUnknownChildElements()
setAllowUnknownChildElements(boolean)
.
public void begin(java.lang.String namespace, java.lang.String name, org.xml.sax.Attributes attributes) throws java.lang.Exception
begin
in class Rule
namespace
- is the namespace this attribute is in, or nullname
- is the name of the current xml elementattributes
- is the attribute list of this element
java.lang.Exception
public void body(java.lang.String bodyText) throws java.lang.Exception
body
in class Rule
bodyText
- The text of the body of this element
java.lang.Exception
public void addAlias(java.lang.String elementName, java.lang.String propertyName)
Add an additional element name to property name mapping. This is intended to be used from the xml rules.
public java.lang.String toString()
toString
in class java.lang.Object
|
||||||||||
PREV CLASS NEXT CLASS | FRAMES NO FRAMES | |||||||||
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD |