MethodParameter


1   /*
2    * Copyright 2004 The Apache Software Foundation.
3    *
4    * Licensed under the Apache License, Version 2.0 (the "License");
5    * you may not use this file except in compliance with the License.
6    * You may obtain a copy of the License at
7    * 
8    *     http://www.apache.org/licenses/LICENSE-2.0
9    * 
10   * Unless required by applicable law or agreed to in writing, software
11   * distributed under the License is distributed on an "AS IS" BASIS,
12   * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
13   * See the License for the specific language governing permissions and
14   * limitations under the License.
15   *
16   * $Header:$
17   */
18  package org.apache.beehive.netui.tags.databinding.invoke;
19  
20  import javax.servlet.jsp.JspException  ;
21  import javax.servlet.jsp.tagext.Tag  ;
22  
23  import org.apache.beehive.netui.tags.AbstractClassicTag;
24  import org.apache.beehive.netui.util.Bundle;
25  
26  /**
27   * <p>
28   * A tag that is used to add an argument to a method that will be called
29   * on some object. This tag can be nested within tags that extend the AbstractCallMethod
30   * class. Those tags are:
31   * <ul>
32   * <li>{@link CallMethod}</li>
33   * <li>{@link CallPageFlow}</li>
34   * </ul>
35   * </p>
36   * <p>
37   * The {@link MethodParameter} tags are used to parameterize the method that the {@link AbstractCallMethod} class
38   * will call; each <code>methodParameter</code> tag represents a single parameter. These tags are evaluated
39   * in order and the parameters they describe are passed in order.
40   * </p>
41   * <p>
42   * Overloaded methods on an object can be invoked by setting the <code>type</code> attribute on each
43   * <code>methodParameter</code> tag that is embedded in a method invocation tag.  The type name must
44   * exactly match the primitive type name or the fully qualified class name of the argument.  The
45   * <code>methodParameter</code> tags must also be in the order that they will be passed to this method.
46   * The value of the type attribute must be an exact match of the type if it were printed after having been
47   * accessed through Java reflection.
48   * </p>
49   * <p>
50   * In order to pass <code>null</code> as an argument to a method, the null attribute must be set on this tag.
51   * Either the null attribute or the value attribute must be set on this tag.
52   * </p>
53   * <p>
54   * This example shows how to pass parameters to the method call <code>foo(int integer, String string)</code>.
55   * <pre>
56   *    &lt;netui-data:methodParamter value="42"/&gt;
57   *    &lt;netui-data:methodParamter null="true"/&gt;
58   * </pre>
59   * This will correspond to the method call:<br/>
60   * <pre>
61   *     foo(42, null);
62   * </pre>
63   * The following sample shows how to pass parameters to the method call <code>foo(int integer, String string)</code>
64   * where the class has both of the methods <code>foo(int integer, String string)</code> and
65   * <code>foo(Integer integer, String string)</code>.
66   * <pre>
67   *     &lt;netui-data:methodParamter type="int" value="42"/&gt;
68   *     &lt;netui-data:methodParamter type="java.lang.String" null="true"/&gt;
69   * </pre>
70   * This will correspond to the method call:<br/>
71   * <pre>
72   *     foo(42, null);
73   * </pre>
74   * </p>
75   *
76   * @jsptagref.tagdescription
77   * <p>
78   * A tag that is used to add an argument to a method that will be called
79   * on some object. This tag can be nested within tags that extend the AbstractCallMethod
80   * class. Those tags are:
81   * <ul>
82   * <li>{@link CallMethod}</li>
83   * <li>{@link CallPageFlow}</li>
84   * </ul>
85   * </p>
86   * <p>
87   * The {@link MethodParameter} tags are used to parameterize the method that the {@link AbstractCallMethod} class
88   * will call; each <code>methodParameter</code> tag represents a single parameter. These tags are evaluated
89   * in order and the parameters they describe are passed in order.
90   * </p>
91   * <p>
92   * Overloaded methods on an object can be invoked by setting the <code>type</code> attribute on each
93   * <code>methodParameter</code> tag that is embedded in a method invocation tag.  The type name must
94   * exactly match the primitive type name or the fully qualified class name of the argument.  The
95   * <code>methodParameter</code> tags must also be in the order that they will be passed to this method.
96   * The value of the type attribute must be an exact match of the type if it were printed after having been
97   * accessed through Java reflection.
98   * </p>
99   * <p>
100  * In order to pass <code>null</code> as an argument to a method, the null attribute must be set on this tag.
101  * Either the null attribute or the value attribute must be set on this tag.
102  * </p>
103  *
104  * @example
105  * <p>
106  * This example shows how to pass parameters to the method call <code>foo(int integer, String string)</code>.
107  * <pre>
108  *    &lt;netui-data:methodParamter value="42"/&gt;
109  *    &lt;netui-data:methodParamter null="true"/&gt;
110  * </pre>
111  * This will correspond to the method call:<br/>
112  * <pre>
113  *     foo(42, null);
114  * </pre>
115  * The following sample shows how to pass parameters to the method call <code>foo(int integer, String string)</code>
116  * where the class has both of the methods <code>foo(int integer, String string)</code> and
117  * <code>foo(Integer integer, String string)</code>.
118  * <pre>
119  *     &lt;netui-data:methodParamter type="int" value="42"/&gt;
120  *     &lt;netui-data:methodParamter type="java.lang.String" null="true"/&gt;
121  * </pre>
122  * This will correspond to the method call:<br/>
123  * <pre>
124  *     foo(42, null);
125  * </pre>
126  * </p>
127  *
128  * @netui:tag name="methodParameter"
129  *            description="Use this tag to add an argument to a method that will be called on some object."
130  */
131 public class MethodParameter
132         extends AbstractClassicTag {
133 
134     /**
135      * An identifier denoting that the value of this method parameter
136      * should be treated as 'null'.
137      */
138     public static final Integer   NULL_ARG = new Integer  (-1);
139 
140     private boolean _isNull = false;
141     private Object   _value = null;
142     private String   _type = null;
143 
144     /**
145      * Reset all of the fields of this tag.
146      */
147     protected void localRelease() {
148         super.localRelease();
149         _isNull = false;
150         _value = null;
151         _type = null;
152     }
153 
154     /**
155      * Get the name of this tag.  This is used to identify the type of this tag
156      * for reporting tag errors.
157      *
158      * @return a constant String representing the name of this tag.
159      */
160     public String   getTagName() {
161         return "MethodParamter";
162     }
163 
164     /**
165      * <p/>
166      * Set a String matching the type of this parameter on the method to invoke.
167      * </p>
168      * <p/>
169      * This name should match the primitive type name or fully qualified class
170      * name of the parameters on the signature of the method to which this
171      * parameter will be passed.
172      * </p>
173      * <p/>
174      * For example:
175      * <table>
176      * <tr><td>Method Signature</td><td>Argument Name</td><td>Type value</td></tr>
177      * <tr><td>addToPrice(int price)</td><td>price</td><td><code>int</code></td></tr>
178      * <tr><td>addToPrice(Integer price)</td><td>price</td><td><code>java.lang.Integer</code></td></tr>
179      * </table>
180      *
181      * @param type the type name
182      * @jsptagref.attributedescription <p>
183      * Set a String matching the type of this parameter on the method to invoke.
184      * </p>
185      * <p/>
186      * This name should match the primitive type name or fully qualified class
187      * name of the parameters on the signature of the method to which this
188      * parameter will be passed.
189      * </p>
190      * <p/>
191      * For example:
192      * <table border='1'>
193      * <tr><td><b>Method Signature</b></td><td><b>Argument Name</b></td><td><b>Type value</b></td></tr>
194      * <tr><td>addToPrice(int price)</td><td>price</td><td><code>int</code></td></tr>
195      * <tr><td>addToPrice(Integer price)</td><td>price</td><td><code>java.lang.Integer</code></td></tr>
196      * </table>
197      * @jsptagref.attributesyntaxvalue <i>string_type</i>
198      * @netui:attribute required="false"
199      */
200     public void setType(String   type) {
201         _type = type;
202     }
203 
204     /**
205      * Sets the value of the method parameter that will be passed
206      * to the method call.  This String can be an expression.
207      * If the value is not an expression that references
208      * an Ojbect, the {@link AbstractCallMethod#doEndTag()} will attempt to convert
209      * the String to type that matches the position of the MethodParameter
210      * tag in the list of MethodParameter tags nested inside of an {@link AbstractCallMethod}
211      * tag.
212      *
213      * @param value a String value which may be an expression
214      * @jsptagref.attributedescription The value of the method parameter that will be passed to the method call.
215      * @jsptagref.attributesyntaxvalue <i>expression_value</i>
216      * @netui:attribute required="false" rtexprvalue="true"
217      */
218     public void setValue(Object   value) {
219         _value = value;
220     }
221 
222     /**
223      * Sets a boolean that describes that the parameter that should be passed
224      * to the method is null.
225      *
226      * @param isNull a value that describes whether or not this tag should pass null; if
227      *               <code>true</code> null will be passed; otherwise the value from the value attribute
228      *               will be passed.
229      * @jsptagref.attributedescription Boolean. Determines if the parameter passed to the method is null.
230      * @jsptagref.attributesyntaxvalue <i>boolean_passNullValue</i>
231      * @netui:attribute required="false" rtexprvalue="true"
232      */
233     public void setNull(boolean isNull) {
234         _isNull = isNull;
235     }
236 
237     /**
238      * Start this tag's lifecycle.  Verify that this tag is nested within
239      * a {@link AbstractCallMethod} tag and that one of the "null" and "value"
240      * attributes are set.
241      *
242      * @return {@link #SKIP_BODY}
243      * @throws JspException if an error occurs getting the parameter
244      */
245     public int doStartTag()
246             throws JspException   {
247         Tag   parent = getParent();
248         if(parent == null || !(parent instanceof AbstractCallMethod)) {
249             String   msg = Bundle.getErrorString("Tags_MethodParameter_invalidParent");
250             registerTagError(msg, null);
251             reportErrors();
252             return SKIP_BODY;
253         }
254 
255         if(_isNull == false && _value == null) {
256             String   msg = Bundle.getErrorString("Tags_MethodParameter_undefinedValue");
257             registerTagError(msg, null);
258             reportErrors();
259             return SKIP_BODY;
260         }
261 
262         return SKIP_BODY;
263     }
264 
265     /**
266      * Prepare the value to pass up to the {@link AbstractCallMethod} type
267      * parent.
268      *
269      * @return {@link #EVAL_PAGE} to continue evaluating the page
270      */
271     public int doEndTag()
272             throws JspException   {
273         if(!hasErrors()) {
274             AbstractCallMethod cm = (AbstractCallMethod)getParent();
275             if(_isNull || _value == null)
276                 cm.addParameter(_type, null);
277             else
278                 cm.addParameter(_type, _value);
279         }
280 
281         if(hasErrors())
282             reportErrors();
283 
284         localRelease();
285         return EVAL_PAGE;
286     }
287 }
288
A to Z: JavaDoc & Examples Daily Java News & Articles Open Source Projects Open Source Codes Free Computer Books Remove Frame
Popular Tags