Class CallMethodRule
- java.lang.Object
-
- org.apache.commons.digester.Rule
-
- org.apache.commons.digester.CallMethodRule
-
public class CallMethodRule extends Rule
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(java.lang.Object, java.lang.String, java.lang.Object)
by default. This increases the kinds of methods successfully and allows primitives to be matched by passing in wrapper classes. There are rare cases whenMethodUtils.invokeExactMethod(java.lang.Object, java.lang.String, java.lang.Object)
(the old default) is required. This method is much stricter in it's reflection. Setting theUseExactMatch
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.
-
-
Field Summary
Fields Modifier and Type Field Description protected java.lang.String
bodyText
The body text collected from this element.protected java.lang.String
methodName
The method name to call on the parent object.private java.lang.String[]
paramClassNames
The names of the classes of the parameters to be collected.protected int
paramCount
The number of parameters to collect fromMethodParam
rules.protected java.lang.Class[]
paramTypes
The parameter types of the parameters to be collected.private int
targetOffset
location of the target object for the call, relative to the top of the digester object stack.protected boolean
useExactMatch
ShouldMethodUtils.invokeExactMethod
be used for reflection.-
Fields inherited from class org.apache.commons.digester.Rule
digester, namespaceURI
-
-
Constructor Summary
Constructors Constructor Description CallMethodRule(int targetOffset, java.lang.String methodName)
Construct a "call method" rule with the specified method name.CallMethodRule(int targetOffset, java.lang.String methodName, int paramCount)
Construct a "call method" rule with the specified method name.CallMethodRule(int targetOffset, java.lang.String methodName, int paramCount, java.lang.Class[] paramTypes)
Construct a "call method" rule with the specified method name and parameter types.CallMethodRule(int targetOffset, java.lang.String methodName, int paramCount, java.lang.String[] paramTypes)
Construct a "call method" rule with the specified method name and parameter types.CallMethodRule(java.lang.String methodName)
Construct a "call method" rule with the specified method name.CallMethodRule(java.lang.String methodName, int paramCount)
Construct a "call method" rule with the specified method name.CallMethodRule(java.lang.String methodName, int paramCount, java.lang.Class[] paramTypes)
Construct a "call method" rule with the specified method name and parameter types.CallMethodRule(java.lang.String methodName, int paramCount, java.lang.String[] paramTypes)
Construct a "call method" rule with the specified method name and parameter types.CallMethodRule(Digester digester, java.lang.String methodName, int paramCount)
Deprecated.The digester instance is now set in theDigester.addRule(java.lang.String, org.apache.commons.digester.Rule)
method.CallMethodRule(Digester digester, java.lang.String methodName, int paramCount, java.lang.Class[] paramTypes)
Deprecated.The digester instance is now set in theDigester.addRule(java.lang.String, org.apache.commons.digester.Rule)
method.CallMethodRule(Digester digester, java.lang.String methodName, int paramCount, java.lang.String[] paramTypes)
Deprecated.The digester instance is now set in theDigester.addRule(java.lang.String, org.apache.commons.digester.Rule)
method.
-
Method Summary
All Methods Instance Methods Concrete Methods Modifier and Type Method Description void
begin(org.xml.sax.Attributes attributes)
Process the start of this element.void
body(java.lang.String bodyText)
Process the body text of this element.void
end()
Process the end of this element.void
finish()
Clean up after parsing is complete.boolean
getUseExactMatch()
ShouldMethodUtils.invokeExactMethod
be used for the reflection.protected void
processMethodCallResult(java.lang.Object result)
Subclasses may override this method to perform additional processing of the invoked method's result.void
setDigester(Digester digester)
Set the associated digester.void
setUseExactMatch(boolean useExactMatch)
Set whetherMethodUtils.invokeExactMethod
should be used for the reflection.java.lang.String
toString()
Render a printable version of this Rule.-
Methods inherited from class org.apache.commons.digester.Rule
begin, body, end, getDigester, getNamespaceURI, setNamespaceURI
-
-
-
-
Field Detail
-
bodyText
protected java.lang.String bodyText
The body text collected from this element.
-
targetOffset
private int targetOffset
location of the target object for the call, relative to the top of the digester object stack. The default value of zero means the target object is the one on top of the stack.
-
methodName
protected java.lang.String methodName
The method name to call on the parent object.
-
paramCount
protected int paramCount
The number of parameters to collect fromMethodParam
rules. If this value is zero, a single parameter will be collected from the body of this element.
-
paramTypes
protected java.lang.Class[] paramTypes
The parameter types of the parameters to be collected.
-
paramClassNames
private java.lang.String[] paramClassNames
The names of the classes of the parameters to be collected. This attribute allows creation of the classes to be postponed until the digester is set.
-
useExactMatch
protected boolean useExactMatch
ShouldMethodUtils.invokeExactMethod
be used for reflection.
-
-
Constructor Detail
-
CallMethodRule
public CallMethodRule(Digester digester, java.lang.String methodName, int paramCount)
Deprecated.The digester instance is now set in theDigester.addRule(java.lang.String, org.apache.commons.digester.Rule)
method. UseCallMethodRule(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.- Parameters:
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, java.lang.String methodName, int paramCount, java.lang.String[] paramTypes)
Deprecated.The digester instance is now set in theDigester.addRule(java.lang.String, org.apache.commons.digester.Rule)
method. UseCallMethodRule(String methodName,int paramCount, String [] paramTypes)
instead.Construct a "call method" rule with the specified method name.- Parameters:
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 elementparamTypes
- The Java class names of the arguments (if you wish to use a primitive type, specify the corresonding Java wrapper class instead, such asjava.lang.Boolean
for aboolean
parameter)
-
CallMethodRule
public CallMethodRule(Digester digester, java.lang.String methodName, int paramCount, java.lang.Class[] paramTypes)
Deprecated.The digester instance is now set in theDigester.addRule(java.lang.String, org.apache.commons.digester.Rule)
method. UseCallMethodRule(String methodName,int paramCount, Class [] paramTypes)
instead.Construct a "call method" rule with the specified method name.- Parameters:
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 elementparamTypes
- The Java classes that represent the parameter types of the method arguments (if you wish to use a primitive type, specify the corresonding Java wrapper class instead, such asjava.lang.Boolean.TYPE
for aboolean
parameter)
-
CallMethodRule
public CallMethodRule(java.lang.String methodName, int paramCount)
Construct a "call method" rule with the specified method name. The parameter types (if any) default to java.lang.String.- Parameters:
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, java.lang.String methodName, int paramCount)
Construct a "call method" rule with the specified method name. The parameter types (if any) default to java.lang.String.- 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 callparamCount
- The number of parameters to collect, or zero for a single argument from the body of this element.
-
CallMethodRule
public CallMethodRule(java.lang.String methodName)
Construct a "call method" rule with the specified method name. The method should accept no parameters.- Parameters:
methodName
- Method name of the parent method to call
-
CallMethodRule
public CallMethodRule(int targetOffset, java.lang.String methodName)
Construct a "call method" rule with the specified method name. The method should accept no parameters.- 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(java.lang.String methodName, int paramCount, java.lang.String[] paramTypes)
Construct a "call method" rule with the specified method name and parameter types. IfparamCount
is set to zero the rule will use the body of this element as the single argument of the method, unlessparamTypes
is null or empty, in this case the rule will call the specified method with no arguments.- Parameters:
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 elementparamTypes
- The Java class names of the arguments (if you wish to use a primitive type, specify the corresonding Java wrapper class instead, such asjava.lang.Boolean
for aboolean
parameter)
-
CallMethodRule
public CallMethodRule(int targetOffset, java.lang.String methodName, int paramCount, java.lang.String[] paramTypes)
Construct a "call method" rule with the specified method name and parameter types. IfparamCount
is set to zero the rule will use the body of this element as the single argument of the method, unlessparamTypes
is null or empty, in this case the rule will call the specified method with no arguments.- 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 callparamCount
- The number of parameters to collect, or zero for a single argument from the body of ths elementparamTypes
- The Java class names of the arguments (if you wish to use a primitive type, specify the corresonding Java wrapper class instead, such asjava.lang.Boolean
for aboolean
parameter)
-
CallMethodRule
public CallMethodRule(java.lang.String methodName, int paramCount, java.lang.Class[] paramTypes)
Construct a "call method" rule with the specified method name and parameter types. IfparamCount
is set to zero the rule will use the body of this element as the single argument of the method, unlessparamTypes
is null or empty, in this case the rule will call the specified method with no arguments.- Parameters:
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 elementparamTypes
- The Java classes that represent the parameter types of the method arguments (if you wish to use a primitive type, specify the corresonding Java wrapper class instead, such asjava.lang.Boolean.TYPE
for aboolean
parameter)
-
CallMethodRule
public CallMethodRule(int targetOffset, java.lang.String methodName, int paramCount, java.lang.Class[] paramTypes)
Construct a "call method" rule with the specified method name and parameter types. IfparamCount
is set to zero the rule will use the body of this element as the single argument of the method, unlessparamTypes
is null or empty, in this case the rule will call the specified method with no arguments.- 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 callparamCount
- The number of parameters to collect, or zero for a single argument from the body of ths elementparamTypes
- The Java classes that represent the parameter types of the method arguments (if you wish to use a primitive type, specify the corresonding Java wrapper class instead, such asjava.lang.Boolean.TYPE
for aboolean
parameter)
-
-
Method Detail
-
getUseExactMatch
public boolean getUseExactMatch()
ShouldMethodUtils.invokeExactMethod
be used for the reflection.
-
setUseExactMatch
public void setUseExactMatch(boolean useExactMatch)
Set whetherMethodUtils.invokeExactMethod
should be used for the reflection.
-
setDigester
public void setDigester(Digester digester)
Set the associated digester. If needed, this class loads the parameter classes from their names.- Overrides:
setDigester
in classRule
-
begin
public void begin(org.xml.sax.Attributes attributes) throws java.lang.Exception
Process the start of this element.
-
body
public void body(java.lang.String bodyText) throws java.lang.Exception
Process the body text of this element.
-
end
public void end() throws java.lang.Exception
Process the end of this element.
-
finish
public void finish() throws java.lang.Exception
Clean up after parsing is complete.
-
processMethodCallResult
protected void processMethodCallResult(java.lang.Object result)
Subclasses may override this method to perform additional processing of the invoked method's result.- Parameters:
result
- the Object returned by the method invoked, possibly null
-
toString
public java.lang.String toString()
Render a printable version of this Rule.- Overrides:
toString
in classjava.lang.Object
-
-