001/* $Id: CallMethodRule.java 992060 2010-09-02 19:09:47Z simonetripodi $
002 *
003 * Licensed to the Apache Software Foundation (ASF) under one or more
004 * contributor license agreements.  See the NOTICE file distributed with
005 * this work for additional information regarding copyright ownership.
006 * The ASF licenses this file to You under the Apache License, Version 2.0
007 * (the "License"); you may not use this file except in compliance with
008 * the License.  You may obtain a copy of the License at
009 *
010 *      http://www.apache.org/licenses/LICENSE-2.0
011 *
012 * Unless required by applicable law or agreed to in writing, software
013 * distributed under the License is distributed on an "AS IS" BASIS,
014 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
015 * See the License for the specific language governing permissions and
016 * limitations under the License.
017 */
018
019
020package org.apache.commons.digester;
021
022
023import org.apache.commons.beanutils.ConvertUtils;
024import org.apache.commons.beanutils.MethodUtils;
025import org.xml.sax.Attributes;
026
027
028/**
029 * <p>Rule implementation that calls a method on an object on the stack
030 * (normally the top/parent object), passing arguments collected from 
031 * subsequent <code>CallParamRule</code> rules or from the body of this
032 * element. </p>
033 *
034 * <p>By using {@link #CallMethodRule(String methodName)} 
035 * a method call can be made to a method which accepts no
036 * arguments.</p>
037 *
038 * <p>Incompatible method parameter types are converted 
039 * using <code>org.apache.commons.beanutils.ConvertUtils</code>.
040 * </p>
041 *
042 * <p>This rule now uses {@link MethodUtils#invokeMethod} by default.
043 * This increases the kinds of methods successfully and allows primitives
044 * to be matched by passing in wrapper classes.
045 * There are rare cases when {@link MethodUtils#invokeExactMethod} 
046 * (the old default) is required.
047 * This method is much stricter in it's reflection.
048 * Setting the <code>UseExactMatch</code> to true reverts to the use of this 
049 * method.</p>
050 *
051 * <p>Note that the target method is invoked when the  <i>end</i> of
052 * the tag the CallMethodRule fired on is encountered, <i>not</i> when the
053 * last parameter becomes available. This implies that rules which fire on
054 * tags nested within the one associated with the CallMethodRule will 
055 * fire before the CallMethodRule invokes the target method. This behaviour is
056 * not configurable. </p>
057 *
058 * <p>Note also that if a CallMethodRule is expecting exactly one parameter
059 * and that parameter is not available (eg CallParamRule is used with an
060 * attribute name but the attribute does not exist) then the method will
061 * not be invoked. If a CallMethodRule is expecting more than one parameter,
062 * then it is always invoked, regardless of whether the parameters were
063 * available or not; missing parameters are converted to the appropriate target
064 * type by calling ConvertUtils.convert. Note that the default ConvertUtils
065 * converters for the String type returns a null when passed a null, meaning
066 * that CallMethodRule will passed null for all String parameters for which
067 * there is no parameter info available from the XML. However parameters of
068 * type Float and Integer will be passed a real object containing a zero value
069 * as that is the output of the default ConvertUtils converters for those
070 * types when passed a null. You can register custom converters to change
071 * this behaviour; see the beautils library documentation for more info.</p>
072 *
073 * <p>Note that when a constructor is used with paramCount=0, indicating that
074 * the body of the element is to be passed to the target method, an empty 
075 * element will cause an <i>empty string</i> to be passed to the target method,
076 * not null. And if automatic type conversion is being applied (ie if the 
077 * target function takes something other than a string as a parameter) then 
078 * the conversion will fail if the converter class does not accept an empty 
079 * string as valid input.</p>
080 * 
081 * <p>CallMethodRule has a design flaw which can cause it to fail under
082 * certain rule configurations. All CallMethodRule instances share a single
083 * parameter stack, and all CallParamRule instances simply store their data
084 * into the parameter-info structure that is on the top of the stack. This
085 * means that two CallMethodRule instances cannot be associated with the
086 * same pattern without getting scrambled parameter data. This same issue
087 * also applies when a CallMethodRule matches some element X, a different 
088 * CallMethodRule matches a child element Y and some of the CallParamRules 
089 * associated with the first CallMethodRule match element Y or one of its 
090 * child elements. This issue has been present since the very first release
091 * of Digester. Note, however, that this configuration of CallMethodRule
092 * instances is not commonly required.</p>
093 */
094
095public class CallMethodRule extends Rule {
096
097    // ----------------------------------------------------------- Constructors
098
099    /**
100     * Construct a "call method" rule with the specified method name.  The
101     * parameter types (if any) default to java.lang.String.
102     *
103     * @param digester The associated Digester
104     * @param methodName Method name of the parent method to call
105     * @param paramCount The number of parameters to collect, or
106     *  zero for a single argument from the body of this element.
107     *
108     *
109     * @deprecated The digester instance is now set in the {@link Digester#addRule} method. 
110     * Use {@link #CallMethodRule(String methodName,int paramCount)} instead.
111     */
112    @Deprecated
113    public CallMethodRule(Digester digester, String methodName,
114                          int paramCount) {
115
116        this(methodName, paramCount);
117
118    }
119
120
121    /**
122     * Construct a "call method" rule with the specified method name.
123     *
124     * @param digester The associated Digester
125     * @param methodName Method name of the parent method to call
126     * @param paramCount The number of parameters to collect, or
127     *  zero for a single argument from the body of ths element
128     * @param paramTypes The Java class names of the arguments
129     *  (if you wish to use a primitive type, specify the corresonding
130     *  Java wrapper class instead, such as <code>java.lang.Boolean</code>
131     *  for a <code>boolean</code> parameter)
132     *
133     * @deprecated The digester instance is now set in the {@link Digester#addRule} method. 
134     * Use {@link #CallMethodRule(String methodName,int paramCount, String [] paramTypes)} instead.
135     */
136    @Deprecated
137    public CallMethodRule(Digester digester, String methodName,
138                          int paramCount, String paramTypes[]) {
139
140        this(methodName, paramCount, paramTypes);
141
142    }
143
144
145    /**
146     * Construct a "call method" rule with the specified method name.
147     *
148     * @param digester The associated Digester
149     * @param methodName Method name of the parent method to call
150     * @param paramCount The number of parameters to collect, or
151     *  zero for a single argument from the body of ths element
152     * @param paramTypes The Java classes that represent the
153     *  parameter types of the method arguments
154     *  (if you wish to use a primitive type, specify the corresonding
155     *  Java wrapper class instead, such as <code>java.lang.Boolean.TYPE</code>
156     *  for a <code>boolean</code> parameter)
157     *
158     * @deprecated The digester instance is now set in the {@link Digester#addRule} method. 
159     * Use {@link #CallMethodRule(String methodName,int paramCount, Class [] paramTypes)} instead.
160     */
161    @Deprecated
162    public CallMethodRule(Digester digester, String methodName,
163                          int paramCount, Class<?> paramTypes[]) {
164
165        this(methodName, paramCount, paramTypes);
166    }
167
168
169    /**
170     * Construct a "call method" rule with the specified method name.  The
171     * parameter types (if any) default to java.lang.String.
172     *
173     * @param methodName Method name of the parent method to call
174     * @param paramCount The number of parameters to collect, or
175     *  zero for a single argument from the body of this element.
176     */
177    public CallMethodRule(String methodName,
178                          int paramCount) {
179        this(0, methodName, paramCount);
180    }
181
182    /**
183     * Construct a "call method" rule with the specified method name.  The
184     * parameter types (if any) default to java.lang.String.
185     *
186     * @param targetOffset location of the target object. Positive numbers are
187     * relative to the top of the digester object stack. Negative numbers 
188     * are relative to the bottom of the stack. Zero implies the top
189     * object on the stack.
190     * @param methodName Method name of the parent method to call
191     * @param paramCount The number of parameters to collect, or
192     *  zero for a single argument from the body of this element.
193     */
194    public CallMethodRule(int targetOffset,
195                          String methodName,
196                          int paramCount) {
197
198        this.targetOffset = targetOffset;
199        this.methodName = methodName;
200        this.paramCount = paramCount;        
201        if (paramCount == 0) {
202            this.paramTypes = new Class[] { String.class };
203        } else {
204            this.paramTypes = new Class[paramCount];
205            for (int i = 0; i < this.paramTypes.length; i++) {
206                this.paramTypes[i] = String.class;
207            }
208        }
209
210    }
211
212    /**
213     * Construct a "call method" rule with the specified method name.  
214     * The method should accept no parameters.
215     *
216     * @param methodName Method name of the parent method to call
217     */
218    public CallMethodRule(String methodName) {
219    
220        this(0, methodName, 0, (Class[]) null);
221    
222    }
223    
224
225    /**
226     * Construct a "call method" rule with the specified method name.  
227     * The method should accept no parameters.
228     *
229     * @param targetOffset location of the target object. Positive numbers are
230     * relative to the top of the digester object stack. Negative numbers 
231     * are relative to the bottom of the stack. Zero implies the top
232     * object on the stack.
233     * @param methodName Method name of the parent method to call
234     */
235    public CallMethodRule(int targetOffset, String methodName) {
236    
237        this(targetOffset, methodName, 0, (Class[]) null);
238    
239    }
240    
241
242    /**
243     * Construct a "call method" rule with the specified method name and
244     * parameter types. If <code>paramCount</code> is set to zero the rule
245     * will use the body of this element as the single argument of the
246     * method, unless <code>paramTypes</code> is null or empty, in this
247     * case the rule will call the specified method with no arguments.
248     *
249     * @param methodName Method name of the parent method to call
250     * @param paramCount The number of parameters to collect, or
251     *  zero for a single argument from the body of ths element
252     * @param paramTypes The Java class names of the arguments
253     *  (if you wish to use a primitive type, specify the corresonding
254     *  Java wrapper class instead, such as <code>java.lang.Boolean</code>
255     *  for a <code>boolean</code> parameter)
256     */
257    public CallMethodRule(
258                            String methodName,
259                            int paramCount, 
260                            String paramTypes[]) {
261        this(0, methodName, paramCount, paramTypes);
262    }
263
264    /**
265     * Construct a "call method" rule with the specified method name and
266     * parameter types. If <code>paramCount</code> is set to zero the rule
267     * will use the body of this element as the single argument of the
268     * method, unless <code>paramTypes</code> is null or empty, in this
269     * case the rule will call the specified method with no arguments.
270     *
271     * @param targetOffset location of the target object. Positive numbers are
272     * relative to the top of the digester object stack. Negative numbers 
273     * are relative to the bottom of the stack. Zero implies the top
274     * object on the stack.
275     * @param methodName Method name of the parent method to call
276     * @param paramCount The number of parameters to collect, or
277     *  zero for a single argument from the body of ths element
278     * @param paramTypes The Java class names of the arguments
279     *  (if you wish to use a primitive type, specify the corresonding
280     *  Java wrapper class instead, such as <code>java.lang.Boolean</code>
281     *  for a <code>boolean</code> parameter)
282     */
283    public CallMethodRule(  int targetOffset,
284                            String methodName,
285                            int paramCount, 
286                            String paramTypes[]) {
287
288        this.targetOffset = targetOffset;
289        this.methodName = methodName;
290        this.paramCount = paramCount;
291        if (paramTypes == null) {
292            this.paramTypes = new Class[paramCount];
293            for (int i = 0; i < this.paramTypes.length; i++) {
294                this.paramTypes[i] = String.class;
295            }
296        } else {
297            // copy the parameter class names into an array
298            // the classes will be loaded when the digester is set 
299            this.paramClassNames = new String[paramTypes.length];
300            for (int i = 0; i < this.paramClassNames.length; i++) {
301                this.paramClassNames[i] = paramTypes[i];
302            }
303        }
304
305    }
306
307
308    /**
309     * Construct a "call method" rule with the specified method name and
310     * parameter types. If <code>paramCount</code> is set to zero the rule
311     * will use the body of this element as the single argument of the
312     * method, unless <code>paramTypes</code> is null or empty, in this
313     * case the rule will call the specified method with no arguments.
314     *
315     * @param methodName Method name of the parent method to call
316     * @param paramCount The number of parameters to collect, or
317     *  zero for a single argument from the body of ths element
318     * @param paramTypes The Java classes that represent the
319     *  parameter types of the method arguments
320     *  (if you wish to use a primitive type, specify the corresonding
321     *  Java wrapper class instead, such as <code>java.lang.Boolean.TYPE</code>
322     *  for a <code>boolean</code> parameter)
323     */
324    public CallMethodRule(
325                            String methodName,
326                            int paramCount, 
327                            Class<?> paramTypes[]) {
328        this(0, methodName, paramCount, paramTypes);
329    }
330
331    /**
332     * Construct a "call method" rule with the specified method name and
333     * parameter types. If <code>paramCount</code> is set to zero the rule
334     * will use the body of this element as the single argument of the
335     * method, unless <code>paramTypes</code> is null or empty, in this
336     * case the rule will call the specified method with no arguments.
337     *
338     * @param targetOffset location of the target object. Positive numbers are
339     * relative to the top of the digester object stack. Negative numbers 
340     * are relative to the bottom of the stack. Zero implies the top
341     * object on the stack.
342     * @param methodName Method name of the parent method to call
343     * @param paramCount The number of parameters to collect, or
344     *  zero for a single argument from the body of ths element
345     * @param paramTypes The Java classes that represent the
346     *  parameter types of the method arguments
347     *  (if you wish to use a primitive type, specify the corresonding
348     *  Java wrapper class instead, such as <code>java.lang.Boolean.TYPE</code>
349     *  for a <code>boolean</code> parameter)
350     */
351    public CallMethodRule(  int targetOffset,
352                            String methodName,
353                            int paramCount, 
354                            Class<?> paramTypes[]) {
355
356        this.targetOffset = targetOffset;
357        this.methodName = methodName;
358        this.paramCount = paramCount;
359        if (paramTypes == null) {
360            this.paramTypes = new Class[paramCount];
361            for (int i = 0; i < this.paramTypes.length; i++) {
362                this.paramTypes[i] = String.class;
363            }
364        } else {
365            this.paramTypes = new Class[paramTypes.length];
366            for (int i = 0; i < this.paramTypes.length; i++) {
367                this.paramTypes[i] = paramTypes[i];
368            }
369        }
370
371    }
372
373
374    // ----------------------------------------------------- Instance Variables
375
376
377    /**
378     * The body text collected from this element.
379     */
380    protected String bodyText = null;
381
382
383    /** 
384     * location of the target object for the call, relative to the
385     * top of the digester object stack. The default value of zero
386     * means the target object is the one on top of the stack.
387     */
388    protected int targetOffset = 0;
389
390    /**
391     * The method name to call on the parent object.
392     */
393    protected String methodName = null;
394
395
396    /**
397     * The number of parameters to collect from <code>MethodParam</code> rules.
398     * If this value is zero, a single parameter will be collected from the
399     * body of this element.
400     */
401    protected int paramCount = 0;
402
403
404    /**
405     * The parameter types of the parameters to be collected.
406     */
407    protected Class<?> paramTypes[] = null;
408
409    /**
410     * The names of the classes of the parameters to be collected.
411     * This attribute allows creation of the classes to be postponed until the digester is set.
412     */
413    private String paramClassNames[] = null;
414    
415    /**
416     * Should <code>MethodUtils.invokeExactMethod</code> be used for reflection.
417     */
418    protected boolean useExactMatch = false;
419    
420    // --------------------------------------------------------- Public Methods
421    
422    /**
423     * Should <code>MethodUtils.invokeExactMethod</code>
424     * be used for the reflection.
425     */
426    public boolean getUseExactMatch() {
427        return useExactMatch;
428    }
429    
430    /**
431     * Set whether <code>MethodUtils.invokeExactMethod</code>
432     * should be used for the reflection.
433     */    
434    public void setUseExactMatch(boolean useExactMatch)
435    { 
436        this.useExactMatch = useExactMatch;
437    }
438
439    /**
440     * Set the associated digester.
441     * If needed, this class loads the parameter classes from their names.
442     */
443    @Override
444    public void setDigester(Digester digester)
445    {
446        // call superclass
447        super.setDigester(digester);
448        // if necessary, load parameter classes
449        if (this.paramClassNames != null) {
450            this.paramTypes = new Class[paramClassNames.length];
451            for (int i = 0; i < this.paramClassNames.length; i++) {
452                try {
453                    this.paramTypes[i] =
454                            digester.getClassLoader().loadClass(this.paramClassNames[i]);
455                } catch (ClassNotFoundException e) {
456                    // use the digester log
457                    digester.getLogger().error("(CallMethodRule) Cannot load class " + this.paramClassNames[i], e);
458                    this.paramTypes[i] = null; // Will cause NPE later
459                }
460            }
461        }
462    }
463
464    /**
465     * Process the start of this element.
466     *
467     * @param attributes The attribute list for this element
468     */
469    @Override
470    public void begin(Attributes attributes) throws Exception {
471
472        // Push an array to capture the parameter values if necessary
473        if (paramCount > 0) {
474            Object parameters[] = new Object[paramCount];
475            for (int i = 0; i < parameters.length; i++) {
476                parameters[i] = null;
477            }
478            digester.pushParams(parameters);
479        }
480
481    }
482
483
484    /**
485     * Process the body text of this element.
486     *
487     * @param bodyText The body text of this element
488     */
489    @Override
490    public void body(String bodyText) throws Exception {
491
492        if (paramCount == 0) {
493            this.bodyText = bodyText.trim();
494        }
495
496    }
497
498
499    /**
500     * Process the end of this element.
501     */
502    @Override
503    public void end() throws Exception {
504
505        // Retrieve or construct the parameter values array
506        Object parameters[] = null;
507        if (paramCount > 0) {
508
509            parameters = (Object[]) digester.popParams();
510            
511            if (digester.log.isTraceEnabled()) {
512                for (int i=0,size=parameters.length;i<size;i++) {
513                    digester.log.trace("[CallMethodRule](" + i + ")" + parameters[i]) ;
514                }
515            }
516            
517            // In the case where the target method takes a single parameter
518            // and that parameter does not exist (the CallParamRule never
519            // executed or the CallParamRule was intended to set the parameter
520            // from an attribute but the attribute wasn't present etc) then
521            // skip the method call.
522            //
523            // This is useful when a class has a "default" value that should
524            // only be overridden if data is present in the XML. I don't
525            // know why this should only apply to methods taking *one*
526            // parameter, but it always has been so we can't change it now.
527            if (paramCount == 1 && parameters[0] == null) {
528                return;
529            }
530
531        } else if (paramTypes != null && paramTypes.length != 0) {
532            // Having paramCount == 0 and paramTypes.length == 1 indicates
533            // that we have the special case where the target method has one
534            // parameter being the body text of the current element.
535
536            // There is no body text included in the source XML file,
537            // so skip the method call
538            if (bodyText == null) {
539                return;
540            }
541
542            parameters = new Object[1];
543            parameters[0] = bodyText;
544            if (paramTypes.length == 0) {
545                paramTypes = new Class[1];
546                paramTypes[0] = String.class;
547            }
548
549        } else {
550            // When paramCount is zero and paramTypes.length is zero it
551            // means that we truly are calling a method with no parameters.
552            // Nothing special needs to be done here.
553        }
554
555        // Construct the parameter values array we will need
556        // We only do the conversion if the param value is a String and
557        // the specified paramType is not String. 
558        Object paramValues[] = new Object[paramTypes.length];
559        for (int i = 0; i < paramTypes.length; i++) {
560            // convert nulls and convert stringy parameters 
561            // for non-stringy param types
562            if(
563                parameters[i] == null ||
564                 (parameters[i] instanceof String && 
565                   !String.class.isAssignableFrom(paramTypes[i]))) {
566                
567                paramValues[i] =
568                        ConvertUtils.convert((String) parameters[i], paramTypes[i]);
569            } else {
570                paramValues[i] = parameters[i];
571            }
572        }
573
574        // Determine the target object for the method call
575        Object target;
576        if (targetOffset >= 0) {
577            target = digester.peek(targetOffset);
578        } else {
579            target = digester.peek( digester.getCount() + targetOffset );
580        }
581        
582        if (target == null) {
583            StringBuffer sb = new StringBuffer();
584            sb.append("[CallMethodRule]{");
585            sb.append(digester.match);
586            sb.append("} Call target is null (");
587            sb.append("targetOffset=");
588            sb.append(targetOffset);
589            sb.append(",stackdepth=");
590            sb.append(digester.getCount());
591            sb.append(")");
592            throw new org.xml.sax.SAXException(sb.toString());
593        }
594        
595        // Invoke the required method on the top object
596        if (digester.log.isDebugEnabled()) {
597            StringBuffer sb = new StringBuffer("[CallMethodRule]{");
598            sb.append(digester.match);
599            sb.append("} Call ");
600            sb.append(target.getClass().getName());
601            sb.append(".");
602            sb.append(methodName);
603            sb.append("(");
604            for (int i = 0; i < paramValues.length; i++) {
605                if (i > 0) {
606                    sb.append(",");
607                }
608                if (paramValues[i] == null) {
609                    sb.append("null");
610                } else {
611                    sb.append(paramValues[i].toString());
612                }
613                sb.append("/");
614                if (paramTypes[i] == null) {
615                    sb.append("null");
616                } else {
617                    sb.append(paramTypes[i].getName());
618                }
619            }
620            sb.append(")");
621            digester.log.debug(sb.toString());
622        }
623        
624        Object result = null;
625        if (useExactMatch) {
626            // invoke using exact match
627            result = MethodUtils.invokeExactMethod(target, methodName,
628                paramValues, paramTypes);
629                
630        } else {
631            // invoke using fuzzier match
632            result = MethodUtils.invokeMethod(target, methodName,
633                paramValues, paramTypes);            
634        }
635        
636        processMethodCallResult(result);
637    }
638
639
640    /**
641     * Clean up after parsing is complete.
642     */
643    @Override
644    public void finish() throws Exception {
645
646        bodyText = null;
647
648    }
649
650    /**
651     * Subclasses may override this method to perform additional processing of the 
652     * invoked method's result.
653     *
654     * @param result the Object returned by the method invoked, possibly null
655     */
656    protected void processMethodCallResult(Object result) {
657        // do nothing
658    }
659
660    /**
661     * Render a printable version of this Rule.
662     */
663    @Override
664    public String toString() {
665
666        StringBuffer sb = new StringBuffer("CallMethodRule[");
667        sb.append("methodName=");
668        sb.append(methodName);
669        sb.append(", paramCount=");
670        sb.append(paramCount);
671        sb.append(", paramTypes={");
672        if (paramTypes != null) {
673            for (int i = 0; i < paramTypes.length; i++) {
674                if (i > 0) {
675                    sb.append(", ");
676                }
677                sb.append(paramTypes[i].getName());
678            }
679        }
680        sb.append("}");
681        sb.append("]");
682        return (sb.toString());
683
684    }
685
686
687}