Class CallMethodRule

java.lang.Object
org.apache.commons.digester3.Rule
org.apache.commons.digester3.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 when MethodUtils.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 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 behavior 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 behavior; see the BeanUtils 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 String
    The body text collected from this element.
    protected String
    The method name to call on the parent object.
    private String[]
    The names of the classes of the parameters to be collected.
    protected int
    The number of parameters to collect from MethodParam rules.
    protected Class<?>[]
    The parameter types of the parameters to be collected.
    protected int
    location of the target object for the call, relative to the top of the digester object stack.
    private boolean
    Should MethodUtils.invokeExactMethod be used for reflection.
  • Constructor Summary

    Constructors
    Constructor
    Description
    CallMethodRule(int targetOffset, String methodName)
    Construct a "call method" rule with the specified method name.
    CallMethodRule(int targetOffset, String methodName, int paramCount)
    Construct a "call method" rule with the specified method name.
    CallMethodRule(int targetOffset, String methodName, int paramCount, Class<?>[] paramTypes)
    Construct a "call method" rule with the specified method name and parameter types.
    CallMethodRule(int targetOffset, String methodName, int paramCount, String[] paramTypes)
    Construct a "call method" rule with the specified method name and parameter types.
    CallMethodRule(String methodName)
    Construct a "call method" rule with the specified method name.
    CallMethodRule(String methodName, int paramCount)
    Construct a "call method" rule with the specified method name.
    CallMethodRule(String methodName, int paramCount, Class<?>[] paramTypes)
    Construct a "call method" rule with the specified method name and parameter types.
    CallMethodRule(String methodName, int paramCount, String[] paramTypes)
    Construct a "call method" rule with the specified method name and parameter types.
  • Method Summary

    Modifier and Type
    Method
    Description
    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.
    void
    end(String namespace, String name)
    This method is called when the end of a matching XML element is encountered.
    void
    This method is called after all parsing methods have been called, to allow Rules to remove temporary data.
    boolean
    Should MethodUtils.invokeExactMethod be used for the reflection.
    protected void
    Subclasses may override this method to perform additional processing of the invoked method's result.
    void
    Set the Digester with which this Rule is associated.
    void
    setUseExactMatch(boolean useExactMatch)
    Set whether MethodUtils.invokeExactMethod should be used for the reflection.

    Methods inherited from class org.apache.commons.digester3.Rule

    getDigester, getNamespaceURI, setNamespaceURI

    Methods inherited from class java.lang.Object

    clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait
  • Field Details

    • bodyText

      protected String bodyText
      The body text collected from this element.
    • targetOffset

      protected 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 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 Class<?>[] paramTypes
      The parameter types of the parameters to be collected.
    • paramClassNames

      private 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

      private boolean useExactMatch
      Should MethodUtils.invokeExactMethod be used for reflection.
  • Constructor Details

    • 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.
      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, 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(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, 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(String methodName, int paramCount, 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, String methodName, int paramCount, 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 the element
      paramTypes - The Java class names of the arguments (if you wish to use a primitive type, specify the corresponding Java wrapper class instead, such as java.lang.Boolean for a boolean parameter)
    • CallMethodRule

      public CallMethodRule(String methodName, int paramCount, 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 the element
      paramTypes - The Java classes that represent the parameter types of the method arguments (if you wish to use a primitive type, specify the corresponding Java wrapper class instead, such as java.lang.Boolean.TYPE for a boolean parameter)
    • CallMethodRule

      public CallMethodRule(int targetOffset, String methodName, int paramCount, 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 the element
      paramTypes - The Java classes that represent the parameter types of the method arguments (if you wish to use a primitive type, specify the corresponding Java wrapper class instead, such as java.lang.Boolean.TYPE for a boolean parameter)
  • Method Details

    • getUseExactMatch

      public boolean getUseExactMatch()
      Should MethodUtils.invokeExactMethod be used for the reflection.
      Returns:
      true, if MethodUtils.invokeExactMethod Should be used for the reflection, false otherwise
    • setUseExactMatch

      public void setUseExactMatch(boolean useExactMatch)
      Set whether MethodUtils.invokeExactMethod should be used for the reflection.
      Parameters:
      useExactMatch - The MethodUtils.invokeExactMethod flag
    • 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
    • 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
    • end

      public void end(String namespace, String name) throws Exception
      This method is called when the end of a matching XML element is encountered.
      Overrides:
      end 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
      Throws:
      Exception - if any error occurs
    • finish

      public void finish() throws Exception
      This method is called after all parsing methods have been called, to allow Rules to remove temporary data.
      Overrides:
      finish in class Rule
      Throws:
      Exception - if any error occurs
    • processMethodCallResult

      protected void processMethodCallResult(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 String toString()
      Overrides:
      toString in class Object