SetNextRule


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