Java Doc for CallMethodRule.java in  » Library » Apache-commons-digester-1.8-src » org » apache » commons » digester » Java Source Code / Java DocumentationJava Source Code and Java Documentation

Rule implementation that calls a method on an object on the stack (normally the top/parent object), passing arguments collected from subsequent CallParamRule rules or from the body of this element.

By using CallMethodRule.CallMethodRule(String methodName) a method call can be made to a method which accepts no arguments.

Incompatible method parameter types are converted using org.apache.commons.beanutils.ConvertUtils.

This rule now uses MethodUtils.invokeMethod by default. This increases the kinds of methods successfully and allows primitives to be matched by passing in wrapper classes. There are rare cases when MethodUtils.invokeExactMethod (the old default) is required. This method is much stricter in it's reflection. Setting the UseExactMatch to true reverts to the use of this method.

Note that the target method is invoked when the end of the tag the CallMethodRule fired on is encountered, not when the last parameter becomes available. This implies that rules which fire on tags nested within the one associated with the CallMethodRule will fire before the CallMethodRule invokes the target method. This behaviour is not configurable.

Note also that if a CallMethodRule is expecting exactly one parameter and that parameter is not available (eg CallParamRule is used with an attribute name but the attribute does not exist) then the method will not be invoked. If a CallMethodRule is expecting more than one parameter, then it is always invoked, regardless of whether the parameters were available or not; missing parameters are converted to the appropriate target type by calling ConvertUtils.convert. Note that the default ConvertUtils converters for the String type returns a null when passed a null, meaning that CallMethodRule will passed null for all String parameters for which there is no parameter info available from the XML. However parameters of type Float and Integer will be passed a real object containing a zero value as that is the output of the default ConvertUtils converters for those types when passed a null. You can register custom converters to change this behaviour; see the beautils library documentation for more info.

Note that when a constructor is used with paramCount=0, indicating that the body of the element is to be passed to the target method, an empty element will cause an empty string to be passed to the target method, not null. And if automatic type conversion is being applied (ie if the target function takes something other than a string as a parameter) then the conversion will fail if the converter class does not accept an empty string as valid input.

CallMethodRule has a design flaw which can cause it to fail under certain rule configurations. All CallMethodRule instances share a single parameter stack, and all CallParamRule instances simply store their data into the parameter-info structure that is on the top of the stack. This means that two CallMethodRule instances cannot be associated with the same pattern without getting scrambled parameter data. This same issue also applies when a CallMethodRule matches some element X, a different CallMethodRule matches a child element Y and some of the CallParamRules associated with the first CallMethodRule match element Y or one of its child elements. This issue has been present since the very first release of Digester. Note, however, that this configuration of CallMethodRule instances is not commonly required.