EMMA Coverage Report (generated Tue May 18 22:13:27 CDT 2004)
[all classes][org.apache.velocity.runtime]

COVERAGE SUMMARY FOR SOURCE FILE [Runtime.java]

nameclass, %method, %block, %line, %
Runtime.java0%   (0/1)0%   (0/30)0%   (0/103)0%   (0/41)

COVERAGE BREAKDOWN BY CLASS AND METHOD

nameclass, %method, %block, %line, %
     
class Runtime0%   (0/1)0%   (0/30)0%   (0/103)0%   (0/41)
Runtime (): void 0%   (0/1)0%   (0/3)0%   (0/1)
addProperty (String, Object): void 0%   (0/1)0%   (0/4)0%   (0/2)
addVelocimacro (String, String, String [], String): boolean 0%   (0/1)0%   (0/6)0%   (0/1)
clearProperty (String): void 0%   (0/1)0%   (0/3)0%   (0/2)
debug (Object): void 0%   (0/1)0%   (0/3)0%   (0/2)
dumpVMNamespace (String): boolean 0%   (0/1)0%   (0/3)0%   (0/1)
error (Object): void 0%   (0/1)0%   (0/3)0%   (0/2)
getBoolean (String, boolean): boolean 0%   (0/1)0%   (0/4)0%   (0/1)
getConfiguration (): ExtendedProperties 0%   (0/1)0%   (0/2)0%   (0/1)
getContent (String): ContentResource 0%   (0/1)0%   (0/3)0%   (0/1)
getContent (String, String): ContentResource 0%   (0/1)0%   (0/4)0%   (0/1)
getInt (String): int 0%   (0/1)0%   (0/3)0%   (0/1)
getInt (String, int): int 0%   (0/1)0%   (0/4)0%   (0/1)
getLoaderNameForResource (String): String 0%   (0/1)0%   (0/3)0%   (0/1)
getProperty (String): Object 0%   (0/1)0%   (0/3)0%   (0/1)
getString (String): String 0%   (0/1)0%   (0/3)0%   (0/1)
getString (String, String): String 0%   (0/1)0%   (0/4)0%   (0/1)
getTemplate (String): Template 0%   (0/1)0%   (0/3)0%   (0/1)
getTemplate (String, String): Template 0%   (0/1)0%   (0/4)0%   (0/1)
getVelocimacro (String, String): Directive 0%   (0/1)0%   (0/4)0%   (0/1)
info (Object): void 0%   (0/1)0%   (0/3)0%   (0/2)
init (): void 0%   (0/1)0%   (0/2)0%   (0/2)
init (Properties): void 0%   (0/1)0%   (0/3)0%   (0/2)
init (String): void 0%   (0/1)0%   (0/3)0%   (0/2)
isVelocimacro (String, String): boolean 0%   (0/1)0%   (0/4)0%   (0/1)
parse (Reader, String): SimpleNode 0%   (0/1)0%   (0/4)0%   (0/1)
parse (Reader, String, boolean): SimpleNode 0%   (0/1)0%   (0/5)0%   (0/1)
setConfiguration (ExtendedProperties): void 0%   (0/1)0%   (0/3)0%   (0/2)
setProperty (String, Object): void 0%   (0/1)0%   (0/4)0%   (0/2)
warn (Object): void 0%   (0/1)0%   (0/3)0%   (0/2)

1package 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 
19import java.io.Reader;
20 
21import java.util.Properties;
22 
23import org.apache.velocity.Template;
24 
25 
26import org.apache.velocity.runtime.parser.ParseException;
27import org.apache.velocity.runtime.parser.node.SimpleNode;
28 
29import org.apache.velocity.runtime.directive.Directive;
30 
31import org.apache.velocity.runtime.resource.ContentResource;
32 
33import org.apache.velocity.exception.ResourceNotFoundException;
34import org.apache.velocity.exception.ParseErrorException;
35 
36import 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 */
90public 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}

[all classes][org.apache.velocity.runtime]
EMMA 2.0.4015 (stable) (C) Vladimir Roubtsov