001: package org.apache.velocity.app.event;
002:
003: /*
004: * Licensed to the Apache Software Foundation (ASF) under one
005: * or more contributor license agreements. See the NOTICE file
006: * distributed with this work for additional information
007: * regarding copyright ownership. The ASF licenses this file
008: * to you under the Apache License, Version 2.0 (the
009: * "License"); you may not use this file except in compliance
010: * with the License. You may obtain a copy of the License at
011: *
012: * http://www.apache.org/licenses/LICENSE-2.0
013: *
014: * Unless required by applicable law or agreed to in writing,
015: * software distributed under the License is distributed on an
016: * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
017: * KIND, either express or implied. See the License for the
018: * specific language governing permissions and limitations
019: * under the License.
020: */
021:
022: import org.apache.velocity.context.Context;
023: import org.apache.velocity.util.introspection.Info;
024:
025: /**
026: * Event handler called when an invalid reference is encountered. Allows
027: * the application to report errors or substitute return values. May be chained
028: * in sequence; the behavior will differ per method.
029: *
030: * <p>This feature should be regarded as experimental.
031: *
032: * @author <a href="mailto:wglass@forio.com">Will Glass-Husain</a>
033: * @version $Id: InvalidReferenceEventHandler.java 470256 2006-11-02 07:20:36Z wglass $
034: */
035: public interface InvalidReferenceEventHandler extends EventHandler {
036:
037: /**
038: * Called when object is null or there is no getter for the given
039: * property. Also called for invalid references without properties.
040: * invalidGetMethod() will be called in sequence for
041: * each link in the chain until the first non-null value is
042: * returned.
043: *
044: * @param context the context when the reference was found invalid
045: * @param reference string with complete invalid reference
046: * @param object the object referred to, or null if not found
047: * @param property the property name from the reference
048: * @param info contains template, line, column details
049: * @return substitute return value for missing reference, or null if no substitute
050: */
051: public Object invalidGetMethod(Context context, String reference,
052: Object object, String property, Info info);
053:
054: /**
055: * Called when object is null or there is no setter for the given
056: * property. invalidSetMethod() will be called in sequence for
057: * each link in the chain until a true value is returned. It's
058: * recommended that false be returned as a default to allow
059: * for easy chaining.
060: *
061: * @param context the context when the reference was found invalid
062: * @param leftreference left reference being assigned to
063: * @param rightreference invalid reference on the right
064: * @param info contains info on template, line, col
065: *
066: * @return if true then stop calling invalidSetMethod along the
067: * chain.
068: */
069: public boolean invalidSetMethod(Context context,
070: String leftreference, String rightreference, Info info);
071:
072: /**
073: * Called when object is null or the given method does not exist.
074: * invalidMethod() will be called in sequence for each link in
075: * the chain until the first non-null value is returned.
076: *
077: * @param context the context when the reference was found invalid
078: * @param reference string with complete invalid reference
079: * @param object the object referred to, or null if not found
080: * @param method the name of the (non-existent) method
081: * @param info contains template, line, column details
082: * @return substitute return value for missing reference, or null if no substitute
083: */
084: public Object invalidMethod(Context context, String reference,
085: Object object, String method, Info info);
086:
087: /**
088: * Defines the execution strategy for invalidGetMethod
089: */
090: static class InvalidGetMethodExecutor implements
091: EventHandlerMethodExecutor {
092: private Context context;
093: private String reference;
094: private Object object;
095: private String property;
096: private Info info;
097:
098: private Object result;
099:
100: InvalidGetMethodExecutor(Context context, String reference,
101: Object object, String property, Info info) {
102: this .context = context;
103: this .reference = reference;
104: this .object = object;
105: this .property = property;
106: this .info = info;
107: }
108:
109: /**
110: * Call the method invalidGetMethod()
111: *
112: * @param handler call the appropriate method on this handler
113: */
114: public void execute(EventHandler handler) {
115: result = ((InvalidReferenceEventHandler) handler)
116: .invalidGetMethod(context, reference, object,
117: property, info);
118: }
119:
120: public Object getReturnValue() {
121: return result;
122: }
123:
124: public boolean isDone() {
125: return (result != null);
126: }
127: }
128:
129: /**
130: * Defines the execution strategy for invalidGetMethod
131: */
132: static class InvalidSetMethodExecutor implements
133: EventHandlerMethodExecutor {
134: private Context context;
135: private String leftreference;
136: private String rightreference;
137: private Info info;
138:
139: private boolean result;
140:
141: InvalidSetMethodExecutor(Context context, String leftreference,
142: String rightreference, Info info) {
143: this .context = context;
144: this .leftreference = leftreference;
145: this .rightreference = rightreference;
146: this .info = info;
147: }
148:
149: /**
150: * Call the method invalidSetMethod()
151: *
152: * @param handler call the appropriate method on this handler
153: */
154: public void execute(EventHandler handler) {
155: result = ((InvalidReferenceEventHandler) handler)
156: .invalidSetMethod(context, leftreference,
157: rightreference, info);
158: }
159:
160: public Object getReturnValue() {
161: return null;
162: }
163:
164: public boolean isDone() {
165: return result;
166: }
167:
168: }
169:
170: /**
171: * Defines the execution strategy for invalidGetMethod
172: */
173: static class InvalidMethodExecutor implements
174: EventHandlerMethodExecutor {
175: private Context context;
176: private String reference;
177: private Object object;
178: private String method;
179: private Info info;
180:
181: private Object result;
182: private boolean executed = false;
183:
184: InvalidMethodExecutor(Context context, String reference,
185: Object object, String method, Info info) {
186: this .context = context;
187: this .reference = reference;
188: this .object = object;
189: this .method = method;
190: this .info = info;
191: }
192:
193: /**
194: * Call the method invalidMethod()
195: *
196: * @param handler call the appropriate method on this handler
197: */
198: public void execute(EventHandler handler) {
199: executed = true;
200: result = ((InvalidReferenceEventHandler) handler)
201: .invalidMethod(context, reference, object, method,
202: info);
203: }
204:
205: public Object getReturnValue() {
206: return result;
207: }
208:
209: public boolean isDone() {
210: return executed && (result != null);
211: }
212:
213: }
214:
215: }
|