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(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.
CallMethodRule
public CallMethodRule(String methodName)
Construct a "call method" rule with the specified method name.
The method should accept no parameters.
methodName
- Method name of the parent method to call
CallMethodRule
public CallMethodRule(String methodName,
int paramCount)
Construct a "call method" rule with the specified method name. The
parameter types (if any) default to java.lang.String.
methodName
- Method name of the parent method to callparamCount
- The number of parameters to collect, or
zero for a single argument from the body of this element.
CallMethodRule
public CallMethodRule(String methodName,
int paramCount,
paramTypes[] )
Construct a "call method" rule with the specified method name and
parameter types. If paramCount
is set to zero the rule
will use the body of this element as the single argument of the
method, unless paramTypes
is null or empty, in this
case the rule will call the specified method with no arguments.
methodName
- Method name of the parent method to callparamCount
- The number of parameters to collect, or
zero for a single argument from the body of ths element
CallMethodRule
public CallMethodRule(String methodName,
int paramCount,
paramTypes[] )
Construct a "call method" rule with the specified method name and
parameter types. If paramCount
is set to zero the rule
will use the body of this element as the single argument of the
method, unless paramTypes
is null or empty, in this
case the rule will call the specified method with no arguments.
methodName
- Method name of the parent method to callparamCount
- The number of parameters to collect, or
zero for a single argument from the body of ths element
CallMethodRule
public CallMethodRule(int targetOffset,
String methodName)
Construct a "call method" rule with the specified method name.
The method should accept no parameters.
targetOffset
- location of the target object. Positive numbers are
relative to the top of the digester object stack. Negative numbers
are relative to the bottom of the stack. Zero implies the top
object on the stack.methodName
- Method name of the parent method to call
CallMethodRule
public CallMethodRule(int targetOffset,
String methodName,
int paramCount)
Construct a "call method" rule with the specified method name. The
parameter types (if any) default to java.lang.String.
targetOffset
- location of the target object. Positive numbers are
relative to the top of the digester object stack. Negative numbers
are relative to the bottom of the stack. Zero implies the top
object on the stack.methodName
- Method name of the parent method to callparamCount
- The number of parameters to collect, or
zero for a single argument from the body of this element.
CallMethodRule
public CallMethodRule(int targetOffset,
String methodName,
int paramCount,
paramTypes[] )
Construct a "call method" rule with the specified method name and
parameter types. If paramCount
is set to zero the rule
will use the body of this element as the single argument of the
method, unless paramTypes
is null or empty, in this
case the rule will call the specified method with no arguments.
targetOffset
- location of the target object. Positive numbers are
relative to the top of the digester object stack. Negative numbers
are relative to the bottom of the stack. Zero implies the top
object on the stack.methodName
- Method name of the parent method to callparamCount
- The number of parameters to collect, or
zero for a single argument from the body of ths element
CallMethodRule
public CallMethodRule(int targetOffset,
String methodName,
int paramCount,
paramTypes[] )
Construct a "call method" rule with the specified method name and
parameter types. If paramCount
is set to zero the rule
will use the body of this element as the single argument of the
method, unless paramTypes
is null or empty, in this
case the rule will call the specified method with no arguments.
targetOffset
- location of the target object. Positive numbers are
relative to the top of the digester object stack. Negative numbers
are relative to the bottom of the stack. Zero implies the top
object on the stack.methodName
- Method name of the parent method to callparamCount
- The number of parameters to collect, or
zero for a single argument from the body of ths element
CallMethodRule
public CallMethodRule(Digester digester,
String methodName,
int paramCount)
The digester instance is now set in the Digester.addRule(String,Rule)
method.
Use CallMethodRule(String methodName,int paramCount)
instead.
Construct a "call method" rule with the specified method name. The
parameter types (if any) default to java.lang.String.
digester
- The associated DigestermethodName
- Method name of the parent method to callparamCount
- The number of parameters to collect, or
zero for a single argument from the body of this element.
CallMethodRule
public CallMethodRule(Digester digester,
String methodName,
int paramCount,
paramTypes[] )
The digester instance is now set in the Digester.addRule(String,Rule)
method.
Use CallMethodRule(String methodName,int paramCount, String [] paramTypes)
instead.
Construct a "call method" rule with the specified method name.
digester
- The associated DigestermethodName
- Method name of the parent method to callparamCount
- The number of parameters to collect, or
zero for a single argument from the body of ths element
CallMethodRule
public CallMethodRule(Digester digester,
String methodName,
int paramCount,
paramTypes[] )
The digester instance is now set in the Digester.addRule(String,Rule)
method.
Use CallMethodRule(String methodName,int paramCount, Class [] paramTypes)
instead.
Construct a "call method" rule with the specified method name.
digester
- The associated DigestermethodName
- Method name of the parent method to callparamCount
- The number of parameters to collect, or
zero for a single argument from the body of ths element
begin
public void begin(Attributes attributes)
throws Exception
Process the start of this element.
- begin in interface Rule
attributes
- The attribute list for this element
body
public void body(String bodyText)
throws Exception
Process the body text of this element.
- body in interface Rule
bodyText
- The body text of this element
end
public void end()
throws Exception
Process the end of this element.
- end in interface Rule
finish
public void finish()
throws Exception
Clean up after parsing is complete.
- finish in interface Rule
getUseExactMatch
public boolean getUseExactMatch()
Should MethodUtils.invokeExactMethod
be used for the reflection.
processMethodCallResult
protected void processMethodCallResult(Object result)
Subclasses may override this method to perform additional processing of the
invoked method's result.
result
- the Object returned by the method invoked, possibly null
setDigester
public void setDigester(Digester digester)
Set the associated digester.
If needed, this class loads the parameter classes from their names.
- setDigester in interface Rule
setUseExactMatch
public void setUseExactMatch(boolean useExactMatch)
Set whether MethodUtils.invokeExactMethod
should be used for the reflection.
toString
public String toString()
Render a printable version of this Rule.