CallParamRule


1   /* $Id: CallParamRule.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.xml.sax.Attributes  ;
23  
24  import org.apache.commons.collections.ArrayStack;
25  
26  
27  /**
28   * <p>Rule implementation that saves a parameter for use by a surrounding 
29   * <code>CallMethodRule<code>.</p>
30   *
31   * <p>This parameter may be:
32   * <ul>
33   * <li>from an attribute of the current element
34   * See {@link #CallParamRule(int paramIndex, String attributeName)}
35   * <li>from current the element body
36   * See {@link #CallParamRule(int paramIndex)}
37   * <li>from the top object on the stack. 
38   * See {@link #CallParamRule(int paramIndex, boolean fromStack)}
39   * <li>the current path being processed (separate <code>Rule</code>). 
40   * See {@link PathCallParamRule}
41   * </ul>
42   * </p>
43   */
44  
45  public class CallParamRule extends Rule {
46  
47      // ----------------------------------------------------------- Constructors
48  
49  
50      /**
51       * Construct a "call parameter" rule that will save the body text of this
52       * element as the parameter value.
53       *
54       * <p>Note that if the element is empty the an <i>empty string</i> is 
55       * passed to the target method, not null. And if automatic type conversion
56       * is being applied (ie if the target function takes something other than 
57       * a string as a parameter) then the conversion will fail if the converter
58       * class does not accept an empty string as valid input.</p>
59       *
60       * @param digester The associated Digester
61       * @param paramIndex The zero-relative parameter number
62       *
63       * @deprecated The digester instance is now set in the {@link Digester#addRule} method. 
64       * Use {@link #CallParamRule(int paramIndex)} instead.
65       */
66      public CallParamRule(Digester digester, int paramIndex) {
67  
68          this(paramIndex);
69  
70      }
71  
72  
73      /**
74       * Construct a "call parameter" rule that will save the value of the
75       * specified attribute as the parameter value.
76       *
77       * @param digester The associated Digester
78       * @param paramIndex The zero-relative parameter number
79       * @param attributeName The name of the attribute to save
80       *
81       * @deprecated The digester instance is now set in the {@link Digester#addRule} method. 
82       * Use {@link #CallParamRule(int paramIndex, String attributeName)} instead.
83       */
84      public CallParamRule(Digester digester, int paramIndex,
85                           String   attributeName) {
86  
87          this(paramIndex, attributeName);
88  
89      }
90  
91      /**
92       * Construct a "call parameter" rule that will save the body text of this
93       * element as the parameter value.
94       *
95       * <p>Note that if the element is empty the an <i>empty string</i> is 
96       * passed to the target method, not null. And if automatic type conversion
97       * is being applied (ie if the target function takes something other than 
98       * a string as a parameter) then the conversion will fail if the converter
99       * class does not accept an empty string as valid input.</p>
100      *
101      * @param paramIndex The zero-relative parameter number
102      */
103     public CallParamRule(int paramIndex) {
104 
105         this(paramIndex, null);
106 
107     }
108 
109 
110     /**
111      * Construct a "call parameter" rule that will save the value of the
112      * specified attribute as the parameter value.
113      *
114      * @param paramIndex The zero-relative parameter number
115      * @param attributeName The name of the attribute to save
116      */
117     public CallParamRule(int paramIndex,
118                          String   attributeName) {
119 
120         this.paramIndex = paramIndex;
121         this.attributeName = attributeName;
122 
123     }
124 
125 
126     /**
127      * Construct a "call parameter" rule.
128      *
129      * @param paramIndex The zero-relative parameter number
130      * @param fromStack should this parameter be taken from the top of the stack?
131      */    
132     public CallParamRule(int paramIndex, boolean fromStack) {
133     
134         this.paramIndex = paramIndex;  
135         this.fromStack = fromStack;
136 
137     }
138     
139     /**
140      * Constructs a "call parameter" rule which sets a parameter from the stack.
141      * If the stack contains too few objects, then the parameter will be set to null.
142      *
143      * @param paramIndex The zero-relative parameter number
144      * @param stackIndex the index of the object which will be passed as a parameter. 
145      * The zeroth object is the top of the stack, 1 is the next object down and so on.
146      */    
147     public CallParamRule(int paramIndex, int stackIndex) {
148     
149         this.paramIndex = paramIndex;  
150         this.fromStack = true;
151         this.stackIndex = stackIndex;
152     }
153  
154     // ----------------------------------------------------- Instance Variables
155 
156 
157     /**
158      * The attribute from which to save the parameter value
159      */
160     protected String   attributeName = null;
161 
162 
163     /**
164      * The zero-relative index of the parameter we are saving.
165      */
166     protected int paramIndex = 0;
167 
168 
169     /**
170      * Is the parameter to be set from the stack?
171      */
172     protected boolean fromStack = false;
173     
174     /**
175      * The position of the object from the top of the stack
176      */
177     protected int stackIndex = 0;
178 
179     /** 
180      * Stack is used to allow nested body text to be processed.
181      * Lazy creation.
182      */
183     protected ArrayStack bodyTextStack;
184 
185     // --------------------------------------------------------- Public Methods
186 
187 
188     /**
189      * Process the start of this element.
190      *
191      * @param attributes The attribute list for this element
192      */
193     public void begin(Attributes   attributes) throws Exception   {
194 
195         Object   param = null;
196         
197         if (attributeName != null) {
198         
199             param = attributes.getValue(attributeName);
200             
201         } else if(fromStack) {
202         
203             param = digester.peek(stackIndex);
204             
205             if (digester.log.isDebugEnabled()) {
206             
207                 StringBuffer   sb = new StringBuffer  ("[CallParamRule]{");
208                 sb.append(digester.match);
209                 sb.append("} Save from stack; from stack?").append(fromStack);
210                 sb.append("; object=").append(param);
211                 digester.log.debug(sb.toString());
212             }   
213         }
214         
215         // Have to save the param object to the param stack frame here.
216         // Can't wait until end(). Otherwise, the object will be lost.
217         // We can't save the object as instance variables, as 
218         // the instance variables will be overwritten
219         // if this CallParamRule is reused in subsequent nesting.
220         
221         if(param != null) {
222             Object   parameters[] = (Object  []) digester.peekParams();
223             parameters[paramIndex] = param;
224         }
225     }
226 
227 
228     /**
229      * Process the body text of this element.
230      *
231      * @param bodyText The body text of this element
232      */
233     public void body(String   bodyText) throws Exception   {
234 
235         if (attributeName == null && !fromStack) {
236             // We must wait to set the parameter until end
237             // so that we can make sure that the right set of parameters
238             // is at the top of the stack
239             if (bodyTextStack == null) {
240                 bodyTextStack = new ArrayStack();
241             }
242             bodyTextStack.push(bodyText.trim());
243         }
244 
245     }
246     
247     /**
248      * Process any body texts now.
249      */
250     public void end(String   namespace, String   name) {
251         if (bodyTextStack != null && !bodyTextStack.empty()) {
252             // what we do now is push one parameter onto the top set of parameters
253             Object   parameters[] = (Object  []) digester.peekParams();
254             parameters[paramIndex] = bodyTextStack.pop();
255         }
256     }
257 
258     /**
259      * Render a printable version of this Rule.
260      */
261     public String   toString() {
262 
263         StringBuffer   sb = new StringBuffer  ("CallParamRule[");
264         sb.append("paramIndex=");
265         sb.append(paramIndex);
266         sb.append(", attributeName=");
267         sb.append(attributeName);
268         sb.append(", from stack=");
269         sb.append(fromStack);
270         sb.append("]");
271         return (sb.toString());
272 
273     }
274 
275 
276 }
277
A to Z: JavaDoc & Examples Daily Java News & Articles Open Source Projects Open Source Codes Free Computer Books Remove Frame
Popular Tags