Overview | Package | Class | Use | Tree | Deprecated | Index | Help
PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD

## org.apache.commons.digester3
Class SetNestedPropertiesRule

    java.lang.Object
      org.apache.commons.digester3.Rule
          org.apache.commons.digester3.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]

For each child element of [widget], a corresponding setter method is located on the object on the top of the digester stack, the body text of the child element is converted to the type specified for the (sole) parameter to the setter method, then the setter method is invoked.

This rule supports custom mapping of xml element names to property names. The default mapping for particular elements 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.

Note that this rule is designed to be used to set only "primitive" bean properties, eg String, int, boolean. If some of the child xml elements match ObjectCreateRule rules (ie cause objects to be created) then you must use one of the more complex constructors to this rule to explicitly skip processing of that xml element, and define a SetNextRule (or equivalent) to handle assigning the child object to the appropriate property instead.

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.

TODO: Optimise this class. Currently, each time begin is called, new AnyChildRules and AnyChildRule objects are created. It should be possible to cache these in normal use (though watch out for when a rule instance is invoked re-entrantly!).

Since:
  1.6

Constructor Summary
`SetNestedPropertiesRule()` Base constructor, which maps every child element into a bean property with the same name as the xml element.
`SetNestedPropertiesRule(Map<String,String> elementNames)` Constructor which allows element->property mapping to be overridden.
`SetNestedPropertiesRule(String[] elementNames, String[] propertyNames)` Constructor which allows element->property mapping to be overridden.
`SetNestedPropertiesRule(String elementName, String propertyName)` Convenience constructor which overrides the default mappings for just one property.

Method Summary
`void` | `addAlias(String elementName, String propertyName)` Add an additional custom xml-element -> property mapping.
`void` | `begin(String namespace, String name, Attributes attributes)` This method is called when the beginning of a matching XML element is encountered.
`void` | `body(String namespace, String name, String text)` This method is called when the body of a matching XML element is encountered.
`boolean` | `getAllowUnknownChildElements()` Return the flag to ignore any child element for which there is no corresponding object property
`boolean` | `getTrimData()` Return the flag to have leading and trailing whitespace removed.
`void` | `setAllowUnknownChildElements(boolean allowUnknownChildElements)` Determines whether an error is reported when a nested element is encountered for which there is no corresponding property-setter method.
`void` | `setDigester(Digester digester)` Set the `Digester` with which this `Rule` is associated.
`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()`

Methods inherited from class org.apache.commons.digester3.Rule
`end, finish, getDigester, getNamespaceURI, setNamespaceURI`

Methods inherited from class java.lang.Object
`clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait`

Constructor Detail

### SetNestedPropertiesRule

    public SetNestedPropertiesRule()

  Base constructor, which maps every child element into a bean property with the same name as the xml element.

  It is an error if a child xml element exists but the target java bean has no such property (unless `setAllowUnknownChildElements(boolean)` has been set to true).

### SetNestedPropertiesRule

    public SetNestedPropertiesRule(String elementName,
                                   String propertyName)

  Convenience constructor which overrides the default mappings for just one property.

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

  Parameters:
    `elementName` - is the child xml element to match
    `propertyName` - is the java bean property to be assigned the value of the specified xml element. This may be null, in which case the specified xml element will be ignored.

### SetNestedPropertiesRule

    public SetNestedPropertiesRule(String[] elementNames,
                                   String[] propertyNames)

  Constructor which allows element->property mapping to be overridden.

  Two arrays are passed in. One contains xml element names and the other java bean property names. The element name / property name pairs are matched by position; in order words, the first string in the element name array corresponds to the first string in the property name array and so on.

  If a property name is null or the xml element name has no matching property name due to the arrays being of different lengths then this indicates that the xml 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` xml element to the `className` property. The xml element `ignore-me` is not mapped, ie is ignored. 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

### SetNestedPropertiesRule

    public SetNestedPropertiesRule(Map<String,String> elementNames)

  Constructor which allows element->property mapping to be overridden.

  Parameters:
    `elementNames` - names of elements->properties to map
  Since:
    3.0

Method Detail

### setDigester

    public void setDigester(Digester digester)

  Set the `Digester` with which this `Rule` is associated.

  Overrides:
    `setDigester` in class `Rule`
  Parameters:
    `digester` - the `Digester` with which this `Rule` is associated

### 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.

  Parameters:
    `trimData` - flag to have leading and trailing whitespace removed

### getTrimData

    public boolean getTrimData()

  Return the flag to have leading and trailing whitespace removed.

  Returns:
    flag to have leading and trailing whitespace removed
  See Also:
    `setTrimData(boolean)`

### setAllowUnknownChildElements

    public void setAllowUnknownChildElements(boolean allowUnknownChildElements)

  Determines whether an error is reported when a nested element is encountered for which there is no corresponding property-setter method.

  When set to false, any child element for which there is no corresponding object property will cause an error to be reported.

  When set to true, any child element for which there is no corresponding object property will simply be ignored.

  The default value of this attribute is false (unknown child elements are not allowed).

  Parameters:
    `allowUnknownChildElements` - flag to ignore any child element for which there is no corresponding object property

### getAllowUnknownChildElements

    public boolean getAllowUnknownChildElements()

  Return the flag to ignore any child element for which there is no corresponding object property

  Returns:
    flag to ignore any child element for which there is no corresponding object property
  See Also:
    `setAllowUnknownChildElements(boolean).`

### begin

    public void begin(String namespace,
                      String name,
                      Attributes attributes)
               throws Exception

  This method is called when the beginning of a matching XML element is encountered.

  Overrides:
    `begin` in class `Rule`
  Parameters:
    `namespace` - the namespace URI of the matching element, or an empty string if the parser is not namespace aware or the element has no namespace
    `name` - the local name if the parser is namespace aware, or just the element name otherwise
    `attributes` - The attribute list of this element
  Throws:
    `Exception` - if any error occurs

### body

    public void body(String namespace,
                     String name,
                     String text)
              throws Exception

  This method is called when the body of a matching XML element is encountered. If the element has no body, this method is called with an empty string as the body text.

  Overrides:
    `body` in class `Rule`
  Parameters:
    `namespace` - the namespace URI of the matching element, or an empty string if the parser is not namespace aware or the element has no namespace
    `name` - the local name if the parser is namespace aware, or just the element name otherwise
    `text` - The text of the body of this element
  Throws:
    `Exception` - if any error occurs

### addAlias

    public void addAlias(String elementName,
                         String propertyName)

  Add an additional custom xml-element -> property mapping.

  This is primarily intended to be used from the xml rules module (as it is not possible there to pass the necessary parameters to the constructor for this class). However it is valid to use this method directly if desired.

  Parameters:
    `elementName` - the xml-element has to be mapped
    `propertyName` - the property name target

### toString

    public String toString()

  Overrides:
    `toString` in class `Object`

Overview | Package | Class | Use | Tree | Deprecated | Index | Help
PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD

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