SetTopRule


1   /* $Id: SetTopRule.java 155412 2005-02-26 12:58:36Z dirkv $
2    *
3    * Copyright 2001-2004 The Apache Software Foundation.
4    * 
5    * Licensed under the Apache License, Version 2.0 (the "License");
6    * you may not use this file except in compliance with the License.
7    * You may obtain a copy of the License at
8    * 
9    *      http://www.apache.org/licenses/LICENSE-2.0
10   * 
11   * Unless required by applicable law or agreed to in writing, software
12   * distributed under the License is distributed on an "AS IS" BASIS,
13   * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
14   * See the License for the specific language governing permissions and
15   * limitations under the License.
16   */ 
17  
18  
19  package org.apache.commons.digester;
20  
21  
22  import org.apache.commons.beanutils.MethodUtils;
23  
24  
25  /**
26   * <p>Rule implementation that calls a "set parent" method on the top (child)
27   * object, passing the (top-1) (parent) object as an argument.</p>
28   *
29   * <p>This rule now supports more flexible method matching by default.
30   * It is possible that this may break (some) code 
31   * written against release 1.1.1 or earlier.
32   * See {@link #isExactMatch()} for more details.</p>
33   */
34  
35  public class SetTopRule extends Rule {
36  
37  
38      // ----------------------------------------------------------- Constructors
39  
40  
41      /**
42       * Construct a "set parent" rule with the specified method name.  The
43       * "set parent" method's argument type is assumed to be the class of the
44       * parent object.
45       *
46       * @param digester The associated Digester
47       * @param methodName Method name of the "set parent" method to call
48       *
49       * @deprecated The digester instance is now set in the {@link Digester#addRule} method. 
50       * Use {@link #SetTopRule(String methodName)} instead.
51       */
52      public SetTopRule(Digester digester, String   methodName) {
53  
54          this(methodName);
55  
56      }
57  
58  
59      /**
60       * Construct a "set parent" rule with the specified method name.
61       *
62       * @param digester The associated Digester
63       * @param methodName Method name of the "set parent" method to call
64       * @param paramType Java class of the "set parent" method's argument
65       *  (if you wish to use a primitive type, specify the corresonding
66       *  Java wrapper class instead, such as <code>java.lang.Boolean</code>
67       *  for a <code>boolean</code> parameter)
68       *
69       * @deprecated The digester instance is now set in the {@link Digester#addRule} method. 
70       * Use {@link #SetTopRule(String methodName, String paramType)} instead.
71       */
72      public SetTopRule(Digester digester, String   methodName,
73                        String   paramType) {
74  
75          this(methodName, paramType);
76  
77      }
78  
79      /**
80       * Construct a "set parent" rule with the specified method name.  The
81       * "set parent" method's argument type is assumed to be the class of the
82       * parent object.
83       *
84       * @param methodName Method name of the "set parent" method to call
85       */
86      public SetTopRule(String   methodName) {
87  
88          this(methodName, null);
89  
90      }
91  
92  
93      /**
94       * Construct a "set parent" rule with the specified method name.
95       *
96       * @param methodName Method name of the "set parent" method to call
97       * @param paramType Java class of the "set parent" method's argument
98       *  (if you wish to use a primitive type, specify the corresonding
99       *  Java wrapper class instead, such as <code>java.lang.Boolean</code>
100      *  for a <code>boolean</code> parameter)
101      */
102     public SetTopRule(String   methodName,
103                       String   paramType) {
104 
105         this.methodName = methodName;
106         this.paramType = paramType;
107 
108     }
109 
110 
111     // ----------------------------------------------------- Instance Variables
112 
113 
114     /**
115      * The method name to call on the child object.
116      */
117     protected String   methodName = null;
118 
119 
120     /**
121      * The Java class name of the parameter type expected by the method.
122      */
123     protected String   paramType = null;
124     
125     /**
126      * Should we use exact matching. Default is no.
127      */
128     protected boolean useExactMatch = false;
129 
130 
131     // --------------------------------------------------------- Public Methods
132 
133     /**
134      * <p>Is exact matching being used.</p>
135      *
136      * <p>This rule uses <code>org.apache.commons.beanutils.MethodUtils</code> 
137      * to introspect the relevent objects so that the right method can be called.
138      * Originally, <code>MethodUtils.invokeExactMethod</code> was used.
139      * This matches methods very strictly 
140      * and so may not find a matching method when one exists.
141      * This is still the behaviour when exact matching is enabled.</p>
142      *
143      * <p>When exact matching is disabled, <code>MethodUtils.invokeMethod</code> is used.
144      * This method finds more methods but is less precise when there are several methods 
145      * with correct signatures.
146      * So, if you want to choose an exact signature you might need to enable this property.</p>
147      *
148      * <p>The default setting is to disable exact matches.</p>
149      *
150      * @return true iff exact matching is enabled
151      * @since Digester Release 1.1.1
152      */
153     public boolean isExactMatch() {
154     
155         return useExactMatch;
156     }
157     
158     /**
159      * <p>Set whether exact matching is enabled.</p>
160      *
161      * <p>See {@link #isExactMatch()}.</p>
162      *
163      * @param useExactMatch should this rule use exact method matching
164      * @since Digester Release 1.1.1
165      */
166     public void setExactMatch(boolean useExactMatch) {
167 
168         this.useExactMatch = useExactMatch;
169     }
170     
171     /**
172      * Process the end of this element.
173      */
174     public void end() throws Exception   {
175 
176         // Identify the objects to be used
177         Object   child = digester.peek(0);
178         Object   parent = digester.peek(1);
179         
180         if (digester.log.isDebugEnabled()) {
181             if (child == null) {
182                 digester.log.debug("[SetTopRule]{" + digester.match +
183                         "} Call [NULL CHILD]." +
184                         methodName + "(" + parent + ")");
185             } else {
186                 digester.log.debug("[SetTopRule]{" + digester.match +
187                         "} Call " + child.getClass().getName() + "." +
188                         methodName + "(" + parent + ")");
189             }
190         }
191 
192         // Call the specified method
193         Class   paramTypes[] = new Class  [1];
194         if (paramType != null) {
195             paramTypes[0] =
196                     digester.getClassLoader().loadClass(paramType);
197         } else {
198             paramTypes[0] = parent.getClass();
199         }
200 
201         if (useExactMatch) {
202         
203             MethodUtils.invokeExactMethod(child, methodName,
204                 new Object  []{ parent }, paramTypes);
205                 
206         } else {
207         
208             MethodUtils.invokeMethod(child, methodName,
209                 new Object  []{ parent }, paramTypes);
210         
211         }
212     }
213 
214 
215     /**
216      * Render a printable version of this Rule.
217      */
218     public String   toString() {
219 
220         StringBuffer   sb = new StringBuffer  ("SetTopRule[");
221         sb.append("methodName=");
222         sb.append(methodName);
223         sb.append(", paramType=");
224         sb.append(paramType);
225         sb.append("]");
226         return (sb.toString());
227 
228     }
229 
230 
231 }
232
A to Z: JavaDoc & Examples Daily Java News & Articles Open Source Projects Open Source Codes Free Computer Books Remove Frame
Popular Tags