View Javadoc

1   package org.apache.velocity.app.event;
2   
3   /*
4    * Licensed to the Apache Software Foundation (ASF) under one
5    * or more contributor license agreements.  See the NOTICE file
6    * distributed with this work for additional information
7    * regarding copyright ownership.  The ASF licenses this file
8    * to you under the Apache License, Version 2.0 (the
9    * "License"); you may not use this file except in compliance
10   * with the License.  You may obtain a copy of the License at
11   *
12   *   http://www.apache.org/licenses/LICENSE-2.0
13   *
14   * Unless required by applicable law or agreed to in writing,
15   * software distributed under the License is distributed on an
16   * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
17   * KIND, either express or implied.  See the License for the
18   * specific language governing permissions and limitations
19   * under the License.    
20   */
21  
22  import org.apache.velocity.context.Context;
23  import org.apache.velocity.util.introspection.Info;
24  
25  /**
26   * Event handler called when an invalid reference is encountered.  Allows 
27   * the application to report errors or substitute return values. May be chained
28   * in sequence; the behavior will differ per method.
29   * 
30   * <p>This feature should be regarded as experimental.
31   *
32   * @author <a href="mailto:wglass@forio.com">Will Glass-Husain</a>
33   * @version $Id: InvalidReferenceEventHandler.java 470256 2006-11-02 07:20:36Z wglass $
34   */
35  public interface InvalidReferenceEventHandler extends EventHandler
36  {
37      
38      /**
39       * Called when object is null or there is no getter for the given 
40       * property.  Also called for invalid references without properties.  
41       * invalidGetMethod() will be called in sequence for
42       * each link in the chain until the first non-null value is
43       * returned.
44       * 
45       * @param context the context when the reference was found invalid
46       * @param reference string with complete invalid reference
47       * @param object the object referred to, or null if not found
48       * @param property the property name from the reference
49       * @param info contains template, line, column details
50       * @return substitute return value for missing reference, or null if no substitute
51       */
52      public Object invalidGetMethod(Context context, String reference, 
53              Object object, String property, Info info);
54  
55      /**
56       * Called when object is null or there is no setter for the given 
57       * property.  invalidSetMethod() will be called in sequence for
58       * each link in the chain until a true value is returned.  It's
59       * recommended that false be returned as a default to allow
60       * for easy chaining.
61       * 
62       * @param context the context when the reference was found invalid
63       * @param leftreference left reference being assigned to
64       * @param rightreference invalid reference on the right
65       * @param info contains info on template, line, col
66       * 
67       * @return if true then stop calling invalidSetMethod along the 
68       * chain.
69       */
70      public boolean invalidSetMethod(Context context, String leftreference, 
71              String rightreference, Info info);
72  
73      /**
74       * Called when object is null or the given method does not exist.
75       * invalidMethod() will be called in sequence for each link in 
76       * the chain until the first non-null value is returned. 
77       * 
78       * @param context the context when the reference was found invalid
79       * @param reference string with complete invalid reference
80       * @param object the object referred to, or null if not found
81       * @param method the name of the (non-existent) method
82       * @param info contains template, line, column details
83       * @return substitute return value for missing reference, or null if no substitute
84       */
85      public Object invalidMethod(Context context, String reference,  
86              Object object, String method, Info info);
87      
88      
89      /**
90       * Defines the execution strategy for invalidGetMethod
91       */
92      static class InvalidGetMethodExecutor implements EventHandlerMethodExecutor 
93      {
94          private Context context;
95          private String reference;
96          private Object object;
97          private String property;
98          private Info info;
99          
100         private Object result;
101         
102         InvalidGetMethodExecutor(
103                 Context context, 
104                 String reference, 
105                 Object object, 
106                 String property, 
107                 Info info)
108         {
109             this.context = context;
110             this.reference = reference;
111             this.object = object;
112             this.property = property;
113             this.info = info;
114         }
115 
116         /**
117          * Call the method invalidGetMethod()
118          *  
119          * @param handler call the appropriate method on this handler
120          */
121         public void execute(EventHandler handler)
122         {
123             result = ((InvalidReferenceEventHandler) handler).invalidGetMethod(
124                     context, reference, object, property, info);
125         }
126 
127         public Object getReturnValue()
128         {
129             return result;
130         }
131 
132         public boolean isDone()
133         {
134             return (result != null);
135         }                
136     }
137 
138     /**
139      * Defines the execution strategy for invalidGetMethod
140      */
141     static class InvalidSetMethodExecutor implements EventHandlerMethodExecutor 
142     {
143         private Context context;
144         private String leftreference;
145         private String rightreference;
146         private Info info;
147         
148         private boolean result;
149         
150         InvalidSetMethodExecutor(
151                 Context context, 
152                 String leftreference, 
153                 String rightreference, 
154                 Info info)
155         {
156             this.context = context;
157             this.leftreference = leftreference;
158             this.rightreference = rightreference;
159             this.info = info;
160         }
161 
162         /**
163          * Call the method invalidSetMethod()
164          *  
165          * @param handler call the appropriate method on this handler
166          */
167         public void execute(EventHandler handler)
168         {
169             result = ((InvalidReferenceEventHandler) handler).invalidSetMethod(
170                     context, leftreference, rightreference, info);            
171         }        
172     
173         public Object getReturnValue()
174         {
175             return null;
176         }
177 
178         public boolean isDone()
179         {
180             return result;
181         }        
182 
183     }
184 
185     /**
186      * Defines the execution strategy for invalidGetMethod
187      */
188     static class InvalidMethodExecutor implements EventHandlerMethodExecutor
189     {
190         private Context context;
191         private String reference;
192         private Object object;
193         private String method;
194         private Info info;
195 
196         private Object result;
197         private boolean executed = false;
198         
199         InvalidMethodExecutor(
200                 Context context, 
201                 String reference, 
202                 Object object,
203                 String method,
204                 Info info)
205         {
206             this.context = context;
207             this.reference = reference;
208             this.object = object;
209             this.method = method;
210             this.info = info;
211         }
212 
213         /**
214          * Call the method invalidMethod()
215          *  
216          * @param handler call the appropriate method on this handler
217          */
218         public void execute(EventHandler handler)
219         {
220             executed = true;
221             result = ((InvalidReferenceEventHandler) handler).invalidMethod(
222                     context, reference, object, method, info);
223         }
224         
225         public Object getReturnValue()
226         {
227             return result;
228         }
229 
230         public boolean isDone()
231         {
232             return executed && (result != null);
233         }        
234 
235     }
236 
237 }