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 685685 2008-08-13 21:43:27Z nbubna $
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
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
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 }