Runtime


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