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 832324 2009-11-03 07:33:03Z wglass $
34   * @since 1.5
35   */
36  public interface InvalidReferenceEventHandler extends EventHandler
37  {
38      
39      /**
40       * Called when object is null or there is no getter for the given 
41       * property.  Also called for invalid references without properties.  
42       * invalidGetMethod() will be called in sequence for
43       * each link in the chain until the first non-null value is
44       * returned.
45       * 
46       * @param context the context when the reference was found invalid
47       * @param reference string with complete invalid reference. If silent reference, will start with $!
48       * @param object the object referred to, or null if not found
49       * @param property the property name from the reference
50       * @param info contains template, line, column details
51       * @return substitute return value for missing reference, or null if no substitute
52       */
53      public Object invalidGetMethod(Context context, String reference, 
54              Object object, String property, Info info);
55  
56      /**
57       * Called when object is null or there is no setter for the given 
58       * property.  invalidSetMethod() will be called in sequence for
59       * each link in the chain until a true value is returned.  It's
60       * recommended that false be returned as a default to allow
61       * for easy chaining.
62       * 
63       * @param context the context when the reference was found invalid
64       * @param leftreference left reference being assigned to
65       * @param rightreference invalid reference on the right
66       * @param info contains info on template, line, col
67       * 
68       * @return if true then stop calling invalidSetMethod along the 
69       * chain.
70       */
71      public boolean invalidSetMethod(Context context, String leftreference, 
72              String rightreference, Info info);
73  
74      /**
75       * Called when object is null or the given method does not exist.
76       * invalidMethod() will be called in sequence for each link in 
77       * the chain until the first non-null value is returned. 
78       * 
79       * @param context the context when the reference was found invalid
80       * @param reference string with complete invalid reference.  If silent reference, will start with $!
81       * @param object the object referred to, or null if not found
82       * @param method the name of the (non-existent) method
83       * @param info contains template, line, column details
84       * @return substitute return value for missing reference, or null if no substitute
85       */
86      public Object invalidMethod(Context context, String reference,  
87              Object object, String method, Info info);
88      
89      
90      /**
91       * Defines the execution strategy for invalidGetMethod
92       */
93      static class InvalidGetMethodExecutor implements EventHandlerMethodExecutor 
94      {
95          private Context context;
96          private String reference;
97          private Object object;
98          private String property;
99          private Info info;
100         
101         private Object result;
102         
103         InvalidGetMethodExecutor(
104                 Context context, 
105                 String reference, 
106                 Object object, 
107                 String property, 
108                 Info info)
109         {
110             this.context = context;
111             this.reference = reference;
112             this.object = object;
113             this.property = property;
114             this.info = info;
115         }
116 
117         /**
118          * Call the method invalidGetMethod()
119          *  
120          * @param handler call the appropriate method on this handler
121          */
122         public void execute(EventHandler handler)
123         {
124             result = ((InvalidReferenceEventHandler) handler).invalidGetMethod(
125                     context, reference, object, property, info);
126         }
127 
128         public Object getReturnValue()
129         {
130             return result;
131         }
132 
133         public boolean isDone()
134         {
135             return (result != null);
136         }                
137     }
138 
139     /**
140      * Defines the execution strategy for invalidGetMethod
141      */
142     static class InvalidSetMethodExecutor implements EventHandlerMethodExecutor 
143     {
144         private Context context;
145         private String leftreference;
146         private String rightreference;
147         private Info info;
148         
149         private boolean result;
150         
151         InvalidSetMethodExecutor(
152                 Context context, 
153                 String leftreference, 
154                 String rightreference, 
155                 Info info)
156         {
157             this.context = context;
158             this.leftreference = leftreference;
159             this.rightreference = rightreference;
160             this.info = info;
161         }
162 
163         /**
164          * Call the method invalidSetMethod()
165          *  
166          * @param handler call the appropriate method on this handler
167          */
168         public void execute(EventHandler handler)
169         {
170             result = ((InvalidReferenceEventHandler) handler).invalidSetMethod(
171                     context, leftreference, rightreference, info);            
172         }        
173     
174         public Object getReturnValue()
175         {
176             return null;
177         }
178 
179         public boolean isDone()
180         {
181             return result;
182         }        
183 
184     }
185 
186     /**
187      * Defines the execution strategy for invalidGetMethod
188      */
189     static class InvalidMethodExecutor implements EventHandlerMethodExecutor
190     {
191         private Context context;
192         private String reference;
193         private Object object;
194         private String method;
195         private Info info;
196 
197         private Object result;
198         private boolean executed = false;
199         
200         InvalidMethodExecutor(
201                 Context context, 
202                 String reference, 
203                 Object object,
204                 String method,
205                 Info info)
206         {
207             this.context = context;
208             this.reference = reference;
209             this.object = object;
210             this.method = method;
211             this.info = info;
212         }
213 
214         /**
215          * Call the method invalidMethod()
216          *  
217          * @param handler call the appropriate method on this handler
218          */
219         public void execute(EventHandler handler)
220         {
221             executed = true;
222             result = ((InvalidReferenceEventHandler) handler).invalidMethod(
223                     context, reference, object, method, info);
224         }
225         
226         public Object getReturnValue()
227         {
228             return result;
229         }
230 
231         public boolean isDone()
232         {
233             return executed && (result != null);
234         }        
235 
236     }
237 
238 }