001: package org.apache.velocity.runtime;
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 java.io.Reader;
023:
024: import java.util.Properties;
025:
026: import org.apache.velocity.Template;
027:
028: import org.apache.velocity.runtime.parser.ParseException;
029: import org.apache.velocity.runtime.parser.node.SimpleNode;
030:
031: import org.apache.velocity.runtime.directive.Directive;
032:
033: import org.apache.velocity.runtime.resource.ContentResource;
034:
035: import org.apache.velocity.exception.ResourceNotFoundException;
036: import org.apache.velocity.exception.ParseErrorException;
037:
038: import org.apache.commons.collections.ExtendedProperties;
039:
040: /**
041: * This is the Runtime system for Velocity. It is the
042: * single access point for all functionality in Velocity.
043: * It adheres to the mediator pattern and is the only
044: * structure that developers need to be familiar with
045: * in order to get Velocity to perform.
046: *
047: * The Runtime will also cooperate with external
048: * systems like Turbine. Runtime properties can
049: * set and then the Runtime is initialized.
050: *
051: * Turbine for example knows where the templates
052: * are to be loaded from, and where the velocity
053: * log file should be placed.
054: *
055: * So in the case of Velocity cooperating with Turbine
056: * the code might look something like the following:
057: *
058: * <pre>
059: * Runtime.setProperty(Runtime.FILE_RESOURCE_LOADER_PATH, templatePath);
060: * Runtime.setProperty(Runtime.RUNTIME_LOG, pathToVelocityLog);
061: * Runtime.init();
062: * </pre>
063: *
064: * <pre>
065: * -----------------------------------------------------------------------
066: * N O T E S O N R U N T I M E I N I T I A L I Z A T I O N
067: * -----------------------------------------------------------------------
068: * Runtime.init()
069: *
070: * If Runtime.init() is called by itself the Runtime will
071: * initialize with a set of default values.
072: * -----------------------------------------------------------------------
073: * Runtime.init(String/Properties)
074: *
075: * In this case the default velocity properties are layed down
076: * first to provide a solid base, then any properties provided
077: * in the given properties object will override the corresponding
078: * default property.
079: * -----------------------------------------------------------------------
080: * </pre>
081: *
082: * @author <a href="mailto:jvanzyl@apache.org">Jason van Zyl</a>
083: * @author <a href="mailto:jlb@houseofdistraction.com">Jeff Bowden</a>
084: * @author <a href="mailto:geirm@optonline.net">Geir Magusson Jr.</a>
085: *
086: * @see org.apache.velocity.runtime.RuntimeInstance
087: * @see org.apache.velocity.runtime.RuntimeSingleton
088: * @deprecated Use RuntimeInstance or RuntimeSingleton instead.
089: *
090: * @version $Id: Runtime.java 463298 2006-10-12 16:10:32Z henning $
091: */
092: public class Runtime implements RuntimeConstants {
093:
094: /**
095: * This is the primary initialization method in the Velocity
096: * Runtime. The systems that are setup/initialized here are
097: * as follows:
098: *
099: * <ul>
100: * <li>Logging System</li>
101: * <li>ResourceManager</li>
102: * <li>Parser Pool</li>
103: * <li>Global Cache</li>
104: * <li>Static Content Include System</li>
105: * <li>Velocimacro System</li>
106: * </ul>
107: *
108: * @throws Exception When init fails for any reason.
109: */
110: public synchronized static void init() throws Exception {
111: RuntimeSingleton.init();
112: }
113:
114: /**
115: * Allows an external system to set a property in
116: * the Velocity Runtime.
117: *
118: * @param key The property key.
119: * @param value The property value.
120: */
121: public static void setProperty(String key, Object value) {
122: RuntimeSingleton.setProperty(key, value);
123: }
124:
125: /**
126: * Allow an external system to set an ExtendedProperties
127: * object to use. This is useful where the external
128: * system also uses the ExtendedProperties class and
129: * the velocity configuration is a subset of
130: * parent application's configuration. This is
131: * the case with Turbine.
132: *
133: * @param configuration A configuration object.
134: */
135: public static void setConfiguration(ExtendedProperties configuration) {
136: RuntimeSingleton.setConfiguration(configuration);
137: }
138:
139: /**
140: * Add a property to the configuration. If it already
141: * exists then the value stated here will be added
142: * to the configuration entry. For example, if
143: *
144: * resource.loader = file
145: *
146: * is already present in the configuration and you
147: *
148: * addProperty("resource.loader", "classpath")
149: *
150: * Then you will end up with a Vector like the
151: * following:
152: *
153: * ["file", "classpath"]
154: *
155: * @param key A property key.
156: * @param value The property value.
157: */
158: public static void addProperty(String key, Object value) {
159: RuntimeSingleton.addProperty(key, value);
160: }
161:
162: /**
163: * Clear the values pertaining to a particular
164: * property.
165: *
166: * @param key Name of the property to clear.
167: */
168: public static void clearProperty(String key) {
169: RuntimeSingleton.clearProperty(key);
170: }
171:
172: /**
173: * Allows an external caller to get a property. The calling
174: * routine is required to know the type, as this routine
175: * will return an Object, as that is what properties can be.
176: *
177: * @param key property to return
178: * @return The property value or null.
179: */
180: public static Object getProperty(String key) {
181: return RuntimeSingleton.getProperty(key);
182: }
183:
184: /**
185: * Initialize the Velocity Runtime with a Properties
186: * object.
187: *
188: * @param p The properties used for initializiation.
189: * @throws Exception When a problem occurs during init.
190: */
191: public static void init(Properties p) throws Exception {
192: RuntimeSingleton.init(p);
193: }
194:
195: /**
196: * Initialize the Velocity Runtime with the name of
197: * ExtendedProperties object.
198: * *
199: * @param configurationFile The name of a properties file.
200: * @throws Exception When a problem occurs during init.
201: */
202: public static void init(String configurationFile) throws Exception {
203: RuntimeSingleton.init(configurationFile);
204: }
205:
206: /**
207: * Parse the input and return the root of
208: * AST node structure.
209: * <br><br>
210: * In the event that it runs out of parsers in the
211: * pool, it will create and let them be GC'd
212: * dynamically, logging that it has to do that. This
213: * is considered an exceptional condition. It is
214: * expected that the user will set the
215: * PARSER_POOL_SIZE property appropriately for their
216: * application. We will revisit this.
217: *
218: * @param reader A reader returning the template input stream.
219: * @param templateName name of the template being parsed
220: * @return The root node of an AST structure for the template input stream.
221: * @throws ParseException When the input stream is not parsable.
222: */
223: public static SimpleNode parse(Reader reader, String templateName)
224: throws ParseException {
225: return RuntimeSingleton.parse(reader, templateName);
226: }
227:
228: /**
229: * Parse the input and return the root of the AST node structure.
230: *
231: * @see #parse(Reader, String)
232: *
233: * @param reader A reader returning the template input stream.
234: * @param templateName name of the template being parsed
235: * @param dumpNamespace flag to dump the Velocimacro namespace for this template.
236: * @return The root node of an AST structure for the template input stream.
237: * @throws ParseException When the input stream is not parsable.
238: */
239: public static SimpleNode parse(Reader reader, String templateName,
240: boolean dumpNamespace) throws ParseException {
241: return RuntimeSingleton.parse(reader, templateName,
242: dumpNamespace);
243: }
244:
245: /**
246: * Returns a <code>Template</code> from the resource manager.
247: * This method assumes that the character encoding of the
248: * template is set by the <code>input.encoding</code>
249: * property. The default is "ISO-8859-1"
250: *
251: * @param name The file name of the desired template.
252: * @return The template.
253: * @throws ResourceNotFoundException if template not found
254: * from any available source.
255: * @throws ParseErrorException if template cannot be parsed due
256: * to syntax (or other) error.
257: * @throws Exception if an error occurs in template initialization.
258: */
259: public static Template getTemplate(String name)
260: throws ResourceNotFoundException, ParseErrorException,
261: Exception {
262: return RuntimeSingleton.getTemplate(name);
263: }
264:
265: /**
266: * Returns a <code>Template</code> from the resource manager
267: *
268: * @param name The name of the desired template.
269: * @param encoding Character encoding of the template
270: * @return The template.
271: * @throws ResourceNotFoundException if template not found
272: * from any available source.
273: * @throws ParseErrorException if template cannot be parsed due
274: * to syntax (or other) error.
275: * @throws Exception if an error occurs in template initialization
276: */
277: public static Template getTemplate(String name, String encoding)
278: throws ResourceNotFoundException, ParseErrorException,
279: Exception {
280: return RuntimeSingleton.getTemplate(name, encoding);
281: }
282:
283: /**
284: * Returns a static content resource from the
285: * resource manager. Uses the current value
286: * if INPUT_ENCODING as the character encoding.
287: *
288: * @param name Name of content resource to get
289: * @return parsed ContentResource object ready for use
290: * @throws ResourceNotFoundException if template not found
291: * from any available source.
292: * @throws ParseErrorException if template cannot be parsed due
293: * to syntax (or other) error.
294: * @throws Exception if an error occurs in template initialization
295: */
296: public static ContentResource getContent(String name)
297: throws ResourceNotFoundException, ParseErrorException,
298: Exception {
299: return RuntimeSingleton.getContent(name);
300: }
301:
302: /**
303: * Returns a static content resource from the
304: * resource manager.
305: *
306: * @param name Name of content resource to get
307: * @param encoding Character encoding to use
308: * @return parsed ContentResource object ready for use
309: * @throws ResourceNotFoundException if template not found
310: * from any available source.
311: * @throws ParseErrorException if template cannot be parsed due
312: * to syntax (or other) error.
313: * @throws Exception if an error occurs in template initialization
314: */
315: public static ContentResource getContent(String name,
316: String encoding) throws ResourceNotFoundException,
317: ParseErrorException, Exception {
318: return RuntimeSingleton.getContent(name, encoding);
319: }
320:
321: /**
322: * Determines is a template exists, and returns name of the loader that
323: * provides it. This is a slightly less hokey way to support
324: * the Velocity.templateExists() utility method, which was broken
325: * when per-template encoding was introduced. We can revisit this.
326: *
327: * @param resourceName Name of template or content resource
328: * @return class name of loader than can provide it
329: */
330: public static String getLoaderNameForResource(String resourceName) {
331: return RuntimeSingleton.getLoaderNameForResource(resourceName);
332: }
333:
334: /**
335: * Log a warning message.
336: *
337: * @param message message to log
338: */
339: public static void warn(Object message) {
340: RuntimeSingleton.warn(message);
341: }
342:
343: /**
344: * Log an info message.
345: *
346: * @param message message to log
347: */
348: public static void info(Object message) {
349: RuntimeSingleton.info(message);
350: }
351:
352: /**
353: * Log an error message.
354: *
355: * @param message message to log
356: */
357: public static void error(Object message) {
358: RuntimeSingleton.error(message);
359: }
360:
361: /**
362: * Log a debug message.
363: *
364: * @param message message to log
365: */
366: public static void debug(Object message) {
367: RuntimeSingleton.debug(message);
368: }
369:
370: /**
371: * String property accessor method with default to hide the
372: * configuration implementation.
373: *
374: * @param key A property key.
375: * @param defaultValue default value to return if key not
376: * found in resource manager.
377: * @return The property value of of key or default.
378: */
379: public static String getString(String key, String defaultValue) {
380: return RuntimeSingleton.getString(key, defaultValue);
381: }
382:
383: /**
384: * Returns the appropriate VelocimacroProxy object if strVMname
385: * is a valid current Velocimacro.
386: *
387: * @param vmName Name of velocimacro requested
388: * @param templateName The template from which the macro is requested.
389: * @return A VelocimacroProxy object for the macro.
390: */
391: public static Directive getVelocimacro(String vmName,
392: String templateName) {
393: return RuntimeSingleton.getVelocimacro(vmName, templateName);
394: }
395:
396: /**
397: * Adds a new Velocimacro. Usually called by Macro only while parsing.
398: *
399: * @param name Name of a new velocimacro.
400: * @param macro String form of the macro body.
401: * @param argArray Array of strings, containing the
402: * #macro() arguments. the 0th argument is the name.
403: * @param sourceTemplate The template from which the macro is requested.
404: * @return boolean True if added, false if rejected for some
405: * reason (either parameters or permission settings)
406: */
407: public static boolean addVelocimacro(String name, String macro,
408: String argArray[], String sourceTemplate) {
409: return RuntimeSingleton.addVelocimacro(name, macro, argArray,
410: sourceTemplate);
411: }
412:
413: /**
414: * Checks to see if a VM exists
415: *
416: * @param vmName The name of velocimacro.
417: * @param templateName The template from which the macro is requested.
418: * @return boolean True if VM by that name exists, false if not
419: */
420: public static boolean isVelocimacro(String vmName,
421: String templateName) {
422: return RuntimeSingleton.isVelocimacro(vmName, templateName);
423: }
424:
425: /**
426: * tells the vmFactory to dump the specified namespace. This is to support
427: * clearing the VM list when in inline-VM-local-scope mode
428: *
429: * @param namespace The namespace to dump.
430: * @return True if the namespace has been dumped.
431: */
432: public static boolean dumpVMNamespace(String namespace) {
433: return RuntimeSingleton.dumpVMNamespace(namespace);
434: }
435:
436: /* --------------------------------------------------------------------
437: * R U N T I M E A C C E S S O R M E T H O D S
438: * --------------------------------------------------------------------
439: * These are the getXXX() methods that are a simple wrapper
440: * around the configuration object. This is an attempt
441: * to make a the Velocity Runtime the single access point
442: * for all things Velocity, and allow the Runtime to
443: * adhere as closely as possible the the Mediator pattern
444: * which is the ultimate goal.
445: * --------------------------------------------------------------------
446: */
447:
448: /**
449: * String property accessor method to hide the configuration implementation
450: * @param key property key
451: * @return value of key or null
452: */
453: public static String getString(String key) {
454: return RuntimeSingleton.getString(key);
455: }
456:
457: /**
458: * Int property accessor method to hide the configuration implementation.
459: *
460: * @param key A property key.
461: * @return Integer value for this key.
462: */
463: public static int getInt(String key) {
464: return RuntimeSingleton.getInt(key);
465: }
466:
467: /**
468: * Int property accessor method to hide the configuration implementation.
469: *
470: * @param key property key
471: * @param defaultValue default value
472: * @return The integer value.
473: */
474: public static int getInt(String key, int defaultValue) {
475: return RuntimeSingleton.getInt(key, defaultValue);
476: }
477:
478: /**
479: * Boolean property accessor method to hide the configuration implementation.
480: *
481: * @param key property key
482: * @param def default default value if property not found
483: * @return boolean value of key or default value
484: */
485: public static boolean getBoolean(String key, boolean def) {
486: return RuntimeSingleton.getBoolean(key, def);
487: }
488:
489: /**
490: * Return the velocity runtime configuration object.
491: *
492: * @return ExtendedProperties configuration object which houses
493: * the velocity runtime properties.
494: */
495: public static ExtendedProperties getConfiguration() {
496: return RuntimeSingleton.getConfiguration();
497: }
498: }
|