RuntimeSingleton


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