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 }