org.apache.commons.digester

Class SetNestedPropertiesRule


public class SetNestedPropertiesRule
extends Rule

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.

Since:
1.6

Nested Class Summary

private class
SetNestedPropertiesRule.AnyChildRule
private class
SetNestedPropertiesRule.AnyChildRules
Private Rules implementation

Field Summary

private static 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
allowUnknownChildElements
private SetNestedPropertiesRule.AnyChildRule
anyChildRule
private HashMap
elementNames
private Log
log
private SetNestedPropertiesRule.AnyChildRules
newRules
private Rules
oldRules
private boolean
trimData

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

digester, namespaceURI

Constructor Summary

SetNestedPropertiesRule()
Base constructor.
SetNestedPropertiesRule(String elementName, String propertyName)
Convenience constructor overrides the mapping for just one property.
SetNestedPropertiesRule(String[] elementNames, String[] propertyNames)
Constructor allows element->property mapping to be overriden.

Method Summary

void
addAlias(String elementName, String propertyName)
Add an additional element name to property name mapping.
void
begin(String namespace, String name, Attributes attributes)
Process the beginning of this element.
void
body(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.
String
toString()
Render a printable version of this Rule.

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

begin, begin, body, body, end, end, finish, getDigester, getNamespaceURI, setDigester, setNamespaceURI

Field Details

PROP_IGNORE

private static final String PROP_IGNORE
Dummy object that can be placed in collections to indicate an ignored property when null cannot be used for that purpose.


allowUnknownChildElements

private boolean allowUnknownChildElements


anyChildRule

private SetNestedPropertiesRule.AnyChildRule anyChildRule


elementNames

private HashMap elementNames


log

private Log log


newRules

private SetNestedPropertiesRule.AnyChildRules newRules


oldRules

private Rules oldRules


trimData

private boolean trimData

Constructor Details

SetNestedPropertiesRule

public SetNestedPropertiesRule()
Base constructor.


SetNestedPropertiesRule

public SetNestedPropertiesRule(String elementName,
                               String propertyName)
Convenience constructor overrides the mapping for just one property.

For details about how this works, see SetNestedPropertiesRule(String[] elementNames, String[] propertyNames).

Parameters:
elementName - map the child element to match
propertyName - to a property with this name


SetNestedPropertiesRule

public SetNestedPropertiesRule(String[] elementNames,
                               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.

Example One

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"});
 
Example Two

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"});
 

Parameters:
elementNames - names of elements to map
propertyNames - names of properties mapped to

Method Details

addAlias

public void addAlias(String elementName,
                     String propertyName)
Add an additional element name to property name mapping. This is intended to be used from the xml rules.


begin

public void begin(String namespace,
                  String name,
                  Attributes attributes)
            throws Exception
Process the beginning of this element.
Overrides:
begin in interface Rule

Parameters:
namespace - is the namespace this attribute is in, or null
name - is the name of the current xml element
attributes - is the attribute list of this element


body

public void body(String bodyText)
            throws Exception
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.
Overrides:
body in interface Rule


getAllowUnknownChildElements

public boolean getAllowUnknownChildElements()


getTrimData

public boolean getTrimData()


setAllowUnknownChildElements

public 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. The default value of this attribute is false (not allowed).


setDigester

public void setDigester(Digester digester)
Invoked when rule is added to digester.
Overrides:
setDigester in interface Rule


setTrimData

public 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. The default value for this attribute is true.


toString

public String toString()
Render a printable version of this Rule.


Copyright (c) 2001-2004 - Apache Software Foundation