org.apache.tomcat.util.digester
Class CallMethodRule

java.lang.Object
  org.apache.tomcat.util.digester.Rule
      org.apache.tomcat.util.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 org.apache.commons.beanutils.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 org.apache.commons.beanutils.MethodUtils#invokeExactMethod (the old default) is required. This method is much stricter in its 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 passed as null values).

Field Summary

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.
protected int	paramCount The number of parameters to collect from MethodParam rules.
protected java.lang.Class[]	paramTypes The parameter types of the parameters to be collected.
protected boolean	useExactMatch Should MethodUtils.invokeExactMethod be used for reflection.

Fields inherited from class org.apache.tomcat.util.digester.Rule

digester, namespaceURI

Constructor Summary

CallMethodRule(Digester digester, java.lang.String methodName, int paramCount)
Deprecated. The digester instance is now set in the Digester.addRule(java.lang.String, org.apache.tomcat.util.digester.Rule) method. Use CallMethodRule(String methodName,int paramCount) instead.

CallMethodRule(Digester digester, java.lang.String methodName, int paramCount, java.lang.Class[] paramTypes)
Deprecated. The digester instance is now set in the Digester.addRule(java.lang.String, org.apache.tomcat.util.digester.Rule) method. Use CallMethodRule(String methodName,int paramCount, Class [] paramTypes) instead.

CallMethodRule(Digester digester, java.lang.String methodName, int paramCount, java.lang.String[] paramTypes)
Deprecated. The digester instance is now set in the Digester.addRule(java.lang.String, org.apache.tomcat.util.digester.Rule) method. Use CallMethodRule(String methodName,int paramCount, String [] paramTypes) instead.

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.

Method Summary

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() Should MethodUtils.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 whether MethodUtils.invokeExactMethod should be used for the reflection.
java.lang.String	toString() Render a printable version of this Rule.

Methods inherited from class org.apache.tomcat.util.digester.Rule

begin, body, end, getDigester, getNamespaceURI, setNamespaceURI

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait

Field Detail

bodyText

protected java.lang.String bodyText

The body text collected from this element.

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 from MethodParam 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.

useExactMatch

protected boolean useExactMatch

Should MethodUtils.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 the Digester.addRule(java.lang.String, org.apache.tomcat.util.digester.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.

Parameters:

digester - The associated Digester

methodName - Method name of the parent method to call

paramCount - 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 the Digester.addRule(java.lang.String, org.apache.tomcat.util.digester.Rule) method. Use CallMethodRule(String methodName,int paramCount, String [] paramTypes) instead.

Construct a "call method" rule with the specified method name.

Parameters:

digester - The associated Digester

methodName - Method name of the parent method to call

paramCount - The number of parameters to collect, or zero for a single argument from the body of ths element

paramTypes - The Java class names of the arguments (if you wish to use a primitive type, specify the corresonding Java wrapper class instead, such as java.lang.Boolean for a boolean parameter)

CallMethodRule

public CallMethodRule(Digester digester,
                      java.lang.String methodName,
                      int paramCount,
                      java.lang.Class[] paramTypes)

Deprecated. The digester instance is now set in the Digester.addRule(java.lang.String, org.apache.tomcat.util.digester.Rule) method. Use CallMethodRule(String methodName,int paramCount, Class [] paramTypes) instead.

Construct a "call method" rule with the specified method name.

Parameters:

digester - The associated Digester

methodName - Method name of the parent method to call

paramCount - The number of parameters to collect, or zero for a single argument from the body of ths element

paramTypes - 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 as java.lang.Boolean.TYPE for a boolean 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 call

paramCount - 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 call

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

Parameters:

methodName - Method name of the parent method to call

paramCount - The number of parameters to collect, or zero for a single argument from the body of ths element

paramTypes - The Java class names of the arguments (if you wish to use a primitive type, specify the corresonding Java wrapper class instead, such as java.lang.Boolean for a boolean 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. 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.

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

paramCount - The number of parameters to collect, or zero for a single argument from the body of ths element

paramTypes - The Java class names of the arguments (if you wish to use a primitive type, specify the corresonding Java wrapper class instead, such as java.lang.Boolean for a boolean 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. 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.

Parameters:

methodName - Method name of the parent method to call

paramCount - The number of parameters to collect, or zero for a single argument from the body of ths element

paramTypes - 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 as java.lang.Boolean.TYPE for a boolean 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. 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.

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

paramCount - The number of parameters to collect, or zero for a single argument from the body of ths element

paramTypes - 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 as java.lang.Boolean.TYPE for a boolean parameter)

Method Detail

getUseExactMatch

public boolean getUseExactMatch()

Should MethodUtils.invokeExactMethod be used for the reflection.

setUseExactMatch

public void setUseExactMatch(boolean useExactMatch)

Set whether MethodUtils.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 class Rule

begin

public void begin(org.xml.sax.Attributes attributes)
           throws java.lang.Exception

Process the start of this element.

Overrides:

begin in class Rule

Parameters:

attributes - The attribute list for this element

Throws:

java.lang.Exception

body

public void body(java.lang.String bodyText)
          throws java.lang.Exception

Process the body text of this element.

Overrides:

body in class Rule

Parameters:

bodyText - The body text of this element

Throws:

java.lang.Exception

end

public void end()
         throws java.lang.Exception

Process the end of this element.

Overrides:

end in class Rule

Throws:

java.lang.Exception

finish

public void finish()
            throws java.lang.Exception

Clean up after parsing is complete.

Overrides:

finish in class Rule

Throws:

java.lang.Exception

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.