1 package org.apache.velocity.runtime;
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 java.io.Reader;
23 import java.util.Properties;
24 import org.apache.commons.collections.ExtendedProperties;
25 import org.apache.velocity.Template;
26 import org.apache.velocity.app.event.EventCartridge;
27 import org.apache.velocity.exception.ParseErrorException;
28 import org.apache.velocity.exception.ResourceNotFoundException;
29 import org.apache.velocity.runtime.directive.Directive;
30 import org.apache.velocity.runtime.log.Log;
31 import org.apache.velocity.runtime.parser.ParseException;
32 import org.apache.velocity.runtime.parser.Parser;
33 import org.apache.velocity.runtime.parser.node.SimpleNode;
34 import org.apache.velocity.runtime.resource.ContentResource;
35 import org.apache.velocity.util.introspection.Introspector;
36 import org.apache.velocity.util.introspection.Uberspect;
37
38
39 /**
40 * Interface for internal runtime services that are needed by the
41 * various components w/in Velocity. This was taken from the old
42 * Runtime singleton, and anything not necessary was removed.
43 *
44 * Currently implemented by RuntimeInstance.
45 *
46 * @author <a href="mailto:geirm@optonline.net">Geir Magusson Jr.</a>
47 * @version $Id: RuntimeServices.java 463298 2006-10-12 16:10:32Z henning $
48 */
49 public interface RuntimeServices extends RuntimeLogger
50 {
51
52 /**
53 * This is the primary initialization method in the Velocity
54 * Runtime. The systems that are setup/initialized here are
55 * as follows:
56 *
57 * <ul>
58 * <li>Logging System</li>
59 * <li>ResourceManager</li>
60 * <li>Parser Pool</li>
61 * <li>Global Cache</li>
62 * <li>Static Content Include System</li>
63 * <li>Velocimacro System</li>
64 * </ul>
65 * @throws Exception
66 */
67 public void init() throws Exception;
68
69 /**
70 * Allows an external system to set a property in
71 * the Velocity Runtime.
72 *
73 * @param key property key
74 * @param value property value
75 */
76 public void setProperty(String key, Object value);
77
78 /**
79 * Allow an external system to set an ExtendedProperties
80 * object to use. This is useful where the external
81 * system also uses the ExtendedProperties class and
82 * the velocity configuration is a subset of
83 * parent application's configuration. This is
84 * the case with Turbine.
85 *
86 * @param configuration
87 */
88 public void setConfiguration( ExtendedProperties configuration);
89
90 /**
91 * Add a property to the configuration. If it already
92 * exists then the value stated here will be added
93 * to the configuration entry. For example, if
94 *
95 * resource.loader = file
96 *
97 * is already present in the configuration and you
98 *
99 * addProperty("resource.loader", "classpath")
100 *
101 * Then you will end up with a Vector like the
102 * following:
103 *
104 * ["file", "classpath"]
105 *
106 * @param key
107 * @param value
108 */
109 public void addProperty(String key, Object value);
110
111 /**
112 * Clear the values pertaining to a particular
113 * property.
114 *
115 * @param key of property to clear
116 */
117 public void clearProperty(String key);
118
119 /**
120 * Allows an external caller to get a property. The calling
121 * routine is required to know the type, as this routine
122 * will return an Object, as that is what properties can be.
123 *
124 * @param key property to return
125 * @return The value.
126 */
127 public Object getProperty( String key );
128
129 /**
130 * Initialize the Velocity Runtime with a Properties
131 * object.
132 *
133 * @param p
134 * @throws Exception
135 */
136 public void init(Properties p) throws Exception;
137
138 /**
139 * Initialize the Velocity Runtime with the name of
140 * ExtendedProperties object.
141 *
142 * @param configurationFile
143 * @throws Exception
144 */
145 public void init(String configurationFile) throws Exception;
146
147 /**
148 * Parse the input and return the root of
149 * AST node structure.
150 * <br><br>
151 * In the event that it runs out of parsers in the
152 * pool, it will create and let them be GC'd
153 * dynamically, logging that it has to do that. This
154 * is considered an exceptional condition. It is
155 * expected that the user will set the
156 * PARSER_POOL_SIZE property appropriately for their
157 * application. We will revisit this.
158 *
159 * @param reader inputstream retrieved by a resource loader
160 * @param templateName name of the template being parsed
161 * @return The AST representing the template.
162 * @throws ParseException
163 */
164 public SimpleNode parse( Reader reader, String templateName )
165 throws ParseException;
166
167 /**
168 * Parse the input and return the root of the AST node structure.
169 *
170 * @param reader inputstream retrieved by a resource loader
171 * @param templateName name of the template being parsed
172 * @param dumpNamespace flag to dump the Velocimacro namespace for this template
173 * @return The AST representing the template.
174 * @throws ParseException
175 */
176 public SimpleNode parse( Reader reader, String templateName, boolean dumpNamespace )
177 throws ParseException;
178
179 /**
180 * Returns a <code>Template</code> from the resource manager.
181 * This method assumes that the character encoding of the
182 * template is set by the <code>input.encoding</code>
183 * property. The default is "ISO-8859-1"
184 *
185 * @param name The file name of the desired template.
186 * @return The template.
187 * @throws ResourceNotFoundException if template not found
188 * from any available source.
189 * @throws ParseErrorException if template cannot be parsed due
190 * to syntax (or other) error.
191 * @throws Exception if an error occurs in template initialization
192 */
193 public Template getTemplate(String name)
194 throws ResourceNotFoundException, ParseErrorException, Exception;
195
196 /**
197 * Returns a <code>Template</code> from the resource manager
198 *
199 * @param name The name of the desired template.
200 * @param encoding Character encoding of the template
201 * @return The template.
202 * @throws ResourceNotFoundException if template not found
203 * from any available source.
204 * @throws ParseErrorException if template cannot be parsed due
205 * to syntax (or other) error.
206 * @throws Exception if an error occurs in template initialization
207 */
208 public Template getTemplate(String name, String encoding)
209 throws ResourceNotFoundException, ParseErrorException, Exception;
210
211 /**
212 * Returns a static content resource from the
213 * resource manager. Uses the current value
214 * if INPUT_ENCODING as the character encoding.
215 *
216 * @param name Name of content resource to get
217 * @return parsed ContentResource object ready for use
218 * @throws ResourceNotFoundException if template not found
219 * from any available source.
220 * @throws ParseErrorException
221 * @throws Exception
222 */
223 public ContentResource getContent(String name)
224 throws ResourceNotFoundException, ParseErrorException, Exception;
225
226 /**
227 * Returns a static content resource from the
228 * resource manager.
229 *
230 * @param name Name of content resource to get
231 * @param encoding Character encoding to use
232 * @return parsed ContentResource object ready for use
233 * @throws ResourceNotFoundException if template not found
234 * from any available source.
235 * @throws ParseErrorException
236 * @throws Exception
237 */
238 public ContentResource getContent( String name, String encoding )
239 throws ResourceNotFoundException, ParseErrorException, Exception;
240
241 /**
242 * Determines is a template exists, and returns name of the loader that
243 * provides it. This is a slightly less hokey way to support
244 * the Velocity.templateExists() utility method, which was broken
245 * when per-template encoding was introduced. We can revisit this.
246 *
247 * @param resourceName Name of template or content resource
248 * @return class name of loader than can provide it
249 */
250 public String getLoaderNameForResource( String resourceName );
251
252 /**
253 * String property accessor method with default to hide the
254 * configuration implementation.
255 *
256 * @param key property key
257 * @param defaultValue default value to return if key not
258 * found in resource manager.
259 * @return String value of key or default
260 */
261 public String getString( String key, String defaultValue);
262
263 /**
264 * Returns the appropriate VelocimacroProxy object if strVMname
265 * is a valid current Velocimacro.
266 *
267 * @param vmName Name of velocimacro requested
268 * @param templateName Name of the namespace.
269 * @return VelocimacroProxy
270 */
271 public Directive getVelocimacro( String vmName, String templateName );
272
273 /**
274 * Adds a new Velocimacro. Usually called by Macro only while parsing.
275 *
276 * @param name Name of velocimacro
277 * @param macro String form of macro body
278 * @param argArray Array of strings, containing the
279 * #macro() arguments. the 0th is the name.
280 * @param sourceTemplate
281 * @return boolean True if added, false if rejected for some
282 * reason (either parameters or permission settings)
283 */
284 public boolean addVelocimacro( String name,
285 String macro,
286 String argArray[],
287 String sourceTemplate );
288
289 /**
290 * Checks to see if a VM exists
291 *
292 * @param vmName Name of velocimacro
293 * @param templateName
294 * @return boolean True if VM by that name exists, false if not
295 */
296 public boolean isVelocimacro( String vmName, String templateName );
297
298 /**
299 * tells the vmFactory to dump the specified namespace. This is to support
300 * clearing the VM list when in inline-VM-local-scope mode
301 * @param namespace
302 * @return True if the Namespace was dumped.
303 */
304 public boolean dumpVMNamespace( String namespace );
305
306 /**
307 * String property accessor method to hide the configuration implementation
308 * @param key property key
309 * @return value of key or null
310 */
311 public String getString(String key);
312
313 /**
314 * Int property accessor method to hide the configuration implementation.
315 *
316 * @param key property key
317 * @return int value
318 */
319 public int getInt( String key );
320
321 /**
322 * Int property accessor method to hide the configuration implementation.
323 *
324 * @param key property key
325 * @param defaultValue default value
326 * @return int value
327 */
328 public int getInt( String key, int defaultValue );
329
330 /**
331 * Boolean property accessor method to hide the configuration implementation.
332 *
333 * @param key property key
334 * @param def default default value if property not found
335 * @return boolean value of key or default value
336 */
337 public boolean getBoolean( String key, boolean def );
338
339 /**
340 * Return the velocity runtime configuration object.
341 *
342 * @return ExtendedProperties configuration object which houses
343 * the velocity runtime properties.
344 */
345 public ExtendedProperties getConfiguration();
346
347 /**
348 * Return the specified application attribute.
349 *
350 * @param key The name of the attribute to retrieve.
351 * @return The value of the attribute.
352 */
353 public Object getApplicationAttribute( Object key );
354
355 /**
356 * Set the specified application attribute.
357 *
358 * @param key The name of the attribute to set.
359 * @param value The attribute value to set.
360 * @return the displaced attribute value
361 */
362 public Object setApplicationAttribute( Object key, Object value );
363
364 /**
365 * Returns the configured class introspection/reflection
366 * implemenation.
367 * @return The current Uberspect object.
368 */
369 public Uberspect getUberspect();
370
371 /**
372 * Returns a convenient Log instance that wraps the current LogChute.
373 * @return A log object.
374 */
375 public Log getLog();
376
377 /**
378 * Returns the event handlers for the application.
379 * @return The event handlers for the application.
380 */
381 public EventCartridge getApplicationEventCartridge();
382
383
384 /**
385 * Returns the configured method introspection/reflection
386 * implementation.
387 * @return The configured method introspection/reflection
388 * implementation.
389 */
390 public Introspector getIntrospector();
391
392 /**
393 * Returns true if the RuntimeInstance has been successfully initialized.
394 * @return True if the RuntimeInstance has been successfully initialized.
395 */
396 public boolean isInitialized();
397
398 /**
399 * Create a new parser instance.
400 * @return A new parser instance.
401 */
402 public Parser createNewParser();
403 }