View Javadoc

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