Package org.apache.tomcat.util.digester

Class 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

      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.
      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 int targetOffset
      location of the target object for the call, relative to the top of the digester object stack.
      protected boolean useExactMatch
      Should MethodUtils.invokeExactMethod be used for reflection.

    • Constructor Summary

      Constructors 
      Constructor Description
      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​(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.

    • Method Summary

      All Methods Instance Methods Concrete Methods 
      Modifier and Type Method Description
      void begin​(java.lang.String namespace, java.lang.String name, org.xml.sax.Attributes attributes)
      Process the start of this element.
      void body​(java.lang.String namespace, java.lang.String name, java.lang.String bodyText)
      Process the body text of this element.
      void end​(java.lang.String namespace, java.lang.String name)
      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 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 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.

      • targetOffset

        protected final 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 final java.lang.String methodName
        The method name to call on the parent object.

      • paramCount

        protected final 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​(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,
                      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 this 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 Detail

      • getUseExactMatch

        public boolean getUseExactMatch()
        Should MethodUtils.invokeExactMethod be used for the reflection.
        Returns:
        true if invokeExactMethod is used

      • setUseExactMatch

        public void setUseExactMatch​(boolean useExactMatch)
        Set whether MethodUtils.invokeExactMethod should be used for the reflection.
        Parameters:
        useExactMatch - The flag value

      • begin

        public void begin​(java.lang.String namespace,
                  java.lang.String name,
                  org.xml.sax.Attributes attributes)
           throws java.lang.Exception
        Process the start of this element.
        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 for this element
        Throws:
        java.lang.Exception - if an error occurs while processing the event

      • body

        public void body​(java.lang.String namespace,
                 java.lang.String name,
                 java.lang.String bodyText)
          throws java.lang.Exception
        Process the body text of this element.
        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
        bodyText - The body text of this element
        Throws:
        java.lang.Exception - if an error occurs while processing the event

      • end

        public void end​(java.lang.String namespace,
                java.lang.String name)
         throws java.lang.Exception
        Process the end of this element.
        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:
        java.lang.Exception - if an error occurs while processing the event

      • finish

        public void finish()
            throws java.lang.Exception
        Clean up after parsing is complete.
        Overrides:
        finish in class Rule
        Throws:
        java.lang.Exception - if an error occurs while processing the event

      • 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 class java.lang.Object