1package org.apache.velocity.runtime;
23/*4 * Licensed to the Apache Software Foundation (ASF) under one5 * or more contributor license agreements. See the NOTICE file6 * distributed with this work for additional information7 * regarding copyright ownership. The ASF licenses this file8 * to you under the Apache License, Version 2.0 (the9 * "License"); you may not use this file except in compliance10 * with the License. You may obtain a copy of the License at11 *12 * http://www.apache.org/licenses/LICENSE-2.013 *14 * Unless required by applicable law or agreed to in writing,15 * software distributed under the License is distributed on an16 * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY17 * KIND, either express or implied. See the License for the18 * specific language governing permissions and limitations19 * under the License. 20 */2122import java.io.File;
23import java.io.IOException;
24import java.io.InputStream;
25import java.io.Reader;
26import java.io.StringReader;
27import java.io.Writer;
28import java.util.Enumeration;
29import java.util.HashMap;
30import java.util.Hashtable;
31import java.util.Map;
32import java.util.Properties;
3334import org.apache.commons.collections.ExtendedProperties;
35import org.apache.commons.lang.text.StrBuilder;
36import org.apache.velocity.Template;
37import org.apache.velocity.app.event.EventCartridge;
38import org.apache.velocity.app.event.EventHandler;
39import org.apache.velocity.app.event.IncludeEventHandler;
40import org.apache.velocity.app.event.InvalidReferenceEventHandler;
41import org.apache.velocity.app.event.MethodExceptionEventHandler;
42import org.apache.velocity.app.event.NullSetEventHandler;
43import org.apache.velocity.app.event.ReferenceInsertionEventHandler;
44import org.apache.velocity.context.Context;
45import org.apache.velocity.context.InternalContextAdapterImpl;
46import org.apache.velocity.exception.MethodInvocationException;
47import org.apache.velocity.exception.ParseErrorException;
48import org.apache.velocity.exception.ResourceNotFoundException;
49import org.apache.velocity.exception.TemplateInitException;
50import org.apache.velocity.exception.VelocityException;
51import org.apache.velocity.runtime.directive.Directive;
52import org.apache.velocity.runtime.log.Log;
53import org.apache.velocity.runtime.log.LogManager;
54import org.apache.velocity.runtime.parser.ParseException;
55import org.apache.velocity.runtime.parser.Parser;
56import org.apache.velocity.runtime.parser.node.Node;
57import org.apache.velocity.runtime.parser.node.SimpleNode;
58import org.apache.velocity.runtime.resource.ContentResource;
59import org.apache.velocity.runtime.resource.ResourceManager;
60import org.apache.velocity.util.ClassUtils;
61import org.apache.velocity.util.RuntimeServicesAware;
62import org.apache.velocity.util.StringUtils;
63import org.apache.velocity.util.introspection.Introspector;
64import org.apache.velocity.util.introspection.Uberspect;
65import org.apache.velocity.util.introspection.UberspectLoggable;
66import org.apache.velocity.util.introspection.ChainableUberspector;
67import org.apache.velocity.util.introspection.LinkingUberspector;
6869/**70 * This is the Runtime system for Velocity. It is the71 * single access point for all functionality in Velocity.72 * It adheres to the mediator pattern and is the only73 * structure that developers need to be familiar with74 * in order to get Velocity to perform.75 *76 * The Runtime will also cooperate with external77 * systems like Turbine. Runtime properties can78 * set and then the Runtime is initialized.79 *80 * Turbine, for example, knows where the templates81 * are to be loaded from, and where the Velocity82 * log file should be placed.83 *84 * So in the case of Velocity cooperating with Turbine85 * the code might look something like the following:86 *87 * <blockquote><code><pre>88 * ri.setProperty(Runtime.FILE_RESOURCE_LOADER_PATH, templatePath);89 * ri.setProperty(Runtime.RUNTIME_LOG, pathToVelocityLog);90 * ri.init();91 * </pre></code></blockquote>92 *93 * <pre>94 * -----------------------------------------------------------------------95 * 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 N96 * -----------------------------------------------------------------------97 * init()98 *99 * If init() is called by itself the RuntimeInstance will initialize100 * with a set of default values.101 * -----------------------------------------------------------------------102 * init(String/Properties)103 *104 * In this case the default velocity properties are layed down105 * first to provide a solid base, then any properties provided106 * in the given properties object will override the corresponding107 * default property.108 * -----------------------------------------------------------------------109 * </pre>110 *111 * @author <a href="mailto:jvanzyl@apache.org">Jason van Zyl</a>112 * @author <a href="mailto:jlb@houseofdistraction.com">Jeff Bowden</a>113 * @author <a href="mailto:geirm@optonline.net">Geir Magusson Jr.</a>114 * @version $Id: RuntimeInstance.java 703049 2008-10-09 03:18:58Z nbubna $115 */116publicclassRuntimeInstance implements RuntimeConstants, RuntimeServices117 {
118/**119 * VelocimacroFactory object to manage VMs120 */121private VelocimacroFactory vmFactory = null;
122123/**124 * The Runtime logger. We start with an instance of125 * a 'primordial logger', which just collects log messages126 * then, when the log system is initialized, all the127 * messages get dumpted out of the primordial one into the real one.128 */129privateLog log = newLog();
130131/**132 * The Runtime parser pool133 */134private ParserPool parserPool;
135136/**137 * Indicate whether the Runtime is in the midst of initialization.138 */139privateboolean initializing = false;
140141/**142 * Indicate whether the Runtime has been fully initialized.143 */144privateboolean initialized = false;
145146/**147 * These are the properties that are laid down over top148 * of the default properties when requested.149 */150private ExtendedProperties overridingProperties = null;
151152/**153 * This is a hashtable of initialized directives.154 * The directives that populate this hashtable are155 * taken from the RUNTIME_DEFAULT_DIRECTIVES156 * property file. This hashtable is passed157 * to each parser that is created.158 */159private Hashtable runtimeDirectives;
160161/**162 * Object that houses the configuration options for163 * the velocity runtime. The ExtendedProperties object allows164 * the convenient retrieval of a subset of properties.165 * For example all the properties for a resource loader166 * can be retrieved from the main ExtendedProperties object167 * using something like the following:168 *169 * ExtendedProperties loaderConfiguration =170 * configuration.subset(loaderID);171 *172 * And a configuration is a lot more convenient to deal173 * with then conventional properties objects, or Maps.174 */175private ExtendedProperties configuration = new ExtendedProperties();
176177privateResourceManager resourceManager = null;
178179/**180 * This stores the engine-wide set of event handlers. Event handlers for181 * each specific merge are stored in the context.182 */183privateEventCartridge eventCartridge = null;
184185/*186 * Each runtime instance has it's own introspector187 * to ensure that each instance is completely separate.188 */189privateIntrospector introspector = null;
190191192/*193 * Opaque reference to something specificed by the194 * application for use in application supplied/specified195 * pluggable components196 */197private Map applicationAttributes = null;
198privateUberspect uberSpect;
199private String encoding;
200201/**202 * Creates a new RuntimeInstance object.203 */204publicRuntimeInstance()
205 {
206/*207 * create a VM factory, introspector, and application attributes208 */209 vmFactory = newVelocimacroFactory( this );
210211/*212 * make a new introspector and initialize it213 */214 introspector = newIntrospector(getLog());
215216/*217 * and a store for the application attributes218 */219 applicationAttributes = new HashMap();
220 }
221222/**223 * This is the primary initialization method in the Velocity224 * Runtime. The systems that are setup/initialized here are225 * as follows:226 *227 * <ul>228 * <li>Logging System</li>229 * <li>ResourceManager</li>230 * <li>EventHandler</li>231 * <li>Parser Pool</li>232 * <li>Global Cache</li>233 * <li>Static Content Include System</li>234 * <li>Velocimacro System</li>235 * </ul>236 * @throws Exception When an error occured during initialization.237 */238publicsynchronizedvoid init()
239throws Exception
240 {
241if (!initialized && !initializing)
242 {
243 initializing = true;
244245 log.trace("*******************************************************************");
246 log.debug("Starting Apache Velocity v@build.version@ (compiled: @build.time@)");
247 log.trace("RuntimeInstance initializing.");
248249 initializeProperties();
250 initializeLog();
251 initializeResourceManager();
252 initializeDirectives();
253 initializeEventHandlers();
254 initializeParserPool();
255256 initializeIntrospection();
257/*258 * initialize the VM Factory. It will use the properties259 * accessable from Runtime, so keep this here at the end.260 */261 vmFactory.initVelocimacro();
262263 log.trace("RuntimeInstance successfully initialized.");
264265 initialized = true;
266 initializing = false;
267 }
268 }
269270/**271 * Returns true if the RuntimeInstance has been successfully initialized.272 * @return True if the RuntimeInstance has been successfully initialized.273 * @since 1.5274 */275publicboolean isInitialized()
276 {
277return initialized;
278 }
279280/**281 * Init or die! (with some log help, of course)282 */283privatevoid requireInitialization()
284 {
285if (!initialized && !initializing)
286 {
287 log.debug("Velocity was not initialized! Calling init()...");
288try289 {
290 init();
291 }
292catch (Exception e)
293 {
294 getLog().error("Could not auto-initialize Velocity", e);
295thrownew RuntimeException("Velocity could not be initialized!", e);
296 }
297 }
298 }
299300/**301 * Gets the classname for the Uberspect introspection package and302 * instantiates an instance.303 */304privatevoid initializeIntrospection()
305throws Exception
306 {
307 String[] uberspectors = configuration.getStringArray(RuntimeConstants.UBERSPECT_CLASSNAME);
308for (int i=0; i <uberspectors.length;i++)
309 {
310 String rm = uberspectors[i];
311 Object o = null;
312313try314 {
315 o = ClassUtils.getNewInstance( rm );
316 }
317catch (ClassNotFoundException cnfe)
318 {
319 String err = "The specified class for Uberspect (" + rm
320 + ") does not exist or is not accessible to the current classloader.";
321 log.error(err);
322thrownew Exception(err);
323 }
324325if (!(o instanceof Uberspect))
326 {
327 String err = "The specified class for Uberspect ("328 + rm + ") does not implement " + Uberspect.class.getName()
329 + "; Velocity is not initialized correctly.";
330331 log.error(err);
332thrownew Exception(err);
333 }
334335Uberspect u = (Uberspect)o;
336337if (u instanceof UberspectLoggable)
338 {
339 ((UberspectLoggable)u).setLog(getLog());
340 }
341342if (u instanceof RuntimeServicesAware)
343 {
344 ((RuntimeServicesAware)u).setRuntimeServices(this);
345 }
346347if (uberSpect == null)
348 {
349 uberSpect = u;
350 }
351else352 {
353if (u instanceof ChainableUberspector)
354 {
355 ((ChainableUberspector)u).wrap(uberSpect);
356 uberSpect = u;
357 }
358else359 {
360 uberSpect = newLinkingUberspector(uberSpect,u);
361 }
362 }
363 }
364365if(uberSpect != null)
366 {
367 uberSpect.init();
368 }
369else370 {
371/*372 * someone screwed up. Lets not fool around...373 */374375 String err = "It appears that no class was specified as the"376 + " Uberspect. Please ensure that all configuration"377 + " information is correct.";
378379 log.error(err);
380thrownew Exception(err);
381 }
382 }
383384/**385 * Initializes the Velocity Runtime with properties file.386 * The properties file may be in the file system proper,387 * or the properties file may be in the classpath.388 */389privatevoid setDefaultProperties()
390 {
391 InputStream inputStream = null;
392try393 {
394 inputStream = getClass()
395 .getResourceAsStream('/' + DEFAULT_RUNTIME_PROPERTIES);
396397 configuration.load( inputStream );
398399if (log.isDebugEnabled())
400 {
401 log.debug("Default Properties File: " +
402new File(DEFAULT_RUNTIME_PROPERTIES).getPath());
403 }
404405406 }
407catch (IOException ioe)
408 {
409 String msg = "Cannot get Velocity Runtime default properties!";
410 log.error(msg, ioe);
411thrownew RuntimeException(msg, ioe);
412 }
413finally414 {
415try416 {
417if (inputStream != null)
418 {
419 inputStream.close();
420 }
421 }
422catch (IOException ioe)
423 {
424 String msg = "Cannot close Velocity Runtime default properties!";
425 log.error(msg, ioe);
426thrownew RuntimeException(msg, ioe);
427 }
428 }
429 }
430431/**432 * Allows an external system to set a property in433 * the Velocity Runtime.434 *435 * @param key property key436 * @param value property value437 */438publicvoid setProperty(String key, Object value)
439 {
440if (overridingProperties == null)
441 {
442 overridingProperties = new ExtendedProperties();
443 }
444445 overridingProperties.setProperty(key, value);
446 }
447448/**449 * Allow an external system to set an ExtendedProperties450 * object to use. This is useful where the external451 * system also uses the ExtendedProperties class and452 * the velocity configuration is a subset of453 * parent application's configuration. This is454 * the case with Turbine.455 *456 * @param configuration457 */458publicvoid setConfiguration( ExtendedProperties configuration)
459 {
460if (overridingProperties == null)
461 {
462 overridingProperties = configuration;
463 }
464else465 {
466// Avoid possible ConcurrentModificationException467if (overridingProperties != configuration)
468 {
469 overridingProperties.combine(configuration);
470 }
471 }
472 }
473474/**475 * Add a property to the configuration. If it already476 * exists then the value stated here will be added477 * to the configuration entry. For example, if478 *479 * resource.loader = file480 *481 * is already present in the configuration and you482 *483 * addProperty("resource.loader", "classpath")484 *485 * Then you will end up with a Vector like the486 * following:487 *488 * ["file", "classpath"]489 *490 * @param key491 * @param value492 */493publicvoid addProperty(String key, Object value)
494 {
495if (overridingProperties == null)
496 {
497 overridingProperties = new ExtendedProperties();
498 }
499500 overridingProperties.addProperty(key, value);
501 }
502503/**504 * Clear the values pertaining to a particular505 * property.506 *507 * @param key of property to clear508 */509publicvoid clearProperty(String key)
510 {
511if (overridingProperties != null)
512 {
513 overridingProperties.clearProperty(key);
514 }
515 }
516517/**518 * Allows an external caller to get a property. The calling519 * routine is required to know the type, as this routine520 * will return an Object, as that is what properties can be.521 *522 * @param key property to return523 * @return Value of the property or null if it does not exist.524 */525public Object getProperty(String key)
526 {
527 Object o = null;
528529/**530 * Before initialization, check the user-entered properties first.531 */532if (!initialized && !initializing && overridingProperties != null)
533 {
534 o = overridingProperties.get(key);
535 }
536537/**538 * After initialization, configuration will hold all properties.539 */540if (o == null)
541 {
542 o = configuration.getProperty(key);
543 }
544if (o instanceof String)
545 {
546return StringUtils.nullTrim((String) o);
547 }
548else549 {
550return o;
551 }
552 }
553554/**555 * Initialize Velocity properties, if the default556 * properties have not been laid down first then557 * do so. Then proceed to process any overriding558 * properties. Laying down the default properties559 * gives a much greater chance of having a560 * working system.561 */562privatevoid initializeProperties()
563 {
564/*565 * Always lay down the default properties first as566 * to provide a solid base.567 */568if (configuration.isInitialized() == false)
569 {
570 setDefaultProperties();
571 }
572573if( overridingProperties != null)
574 {
575 configuration.combine(overridingProperties);
576 }
577 }
578579/**580 * Initialize the Velocity Runtime with a Properties581 * object.582 *583 * @param p584 * @throws Exception When an error occurs during initialization.585 */586publicvoid init(Properties p) throws Exception
587 {
588 setProperties(ExtendedProperties.convertProperties(p));
589 init();
590 }
591592privatevoid setProperties(ExtendedProperties p)
593 {
594if (overridingProperties == null)
595 {
596 overridingProperties = p;
597 }
598else599 {
600 overridingProperties.combine(p);
601 }
602 }
603604/**605 * Initialize the Velocity Runtime with the name of606 * ExtendedProperties object.607 *608 * @param configurationFile609 * @throws Exception When an error occurs during initialization.610 */611publicvoid init(String configurationFile)
612throws Exception
613 {
614 setProperties(new ExtendedProperties(configurationFile));
615 init();
616 }
617618privatevoid initializeResourceManager()
619throws Exception
620 {
621/*622 * Which resource manager?623 */624625 String rm = getString(RuntimeConstants.RESOURCE_MANAGER_CLASS);
626627if (rm != null && rm.length() > 0)
628 {
629/*630 * if something was specified, then make one.631 * if that isn't a ResourceManager, consider632 * this a huge error and throw633 */634635 Object o = null;
636637try638 {
639 o = ClassUtils.getNewInstance( rm );
640 }
641catch (ClassNotFoundException cnfe )
642 {
643 String err = "The specified class for ResourceManager (" + rm
644 + ") does not exist or is not accessible to the current classloader.";
645 log.error(err);
646thrownew Exception(err);
647 }
648649if (!(o instanceof ResourceManager))
650 {
651 String err = "The specified class for ResourceManager (" + rm
652 + ") does not implement " + ResourceManager.class.getName()
653 + "; Velocity is not initialized correctly.";
654655 log.error(err);
656thrownew Exception(err);
657 }
658659 resourceManager = (ResourceManager) o;
660661 resourceManager.initialize(this);
662 }
663else664 {
665/*666 * someone screwed up. Lets not fool around...667 */668669 String err = "It appears that no class was specified as the"670 + " ResourceManager. Please ensure that all configuration"671 + " information is correct.";
672673 log.error(err);
674thrownew Exception( err );
675 }
676 }
677678privatevoid initializeEventHandlers()
679throws Exception
680 {
681682 eventCartridge = newEventCartridge();
683684/**685 * For each type of event handler, get the class name, instantiate it, and store it.686 */687688 String[] referenceinsertion = configuration.getStringArray(RuntimeConstants.EVENTHANDLER_REFERENCEINSERTION);
689if ( referenceinsertion != null )
690 {
691for ( int i=0; i < referenceinsertion.length; i++ )
692 {
693EventHandler ev = initializeSpecificEventHandler(referenceinsertion[i],RuntimeConstants.EVENTHANDLER_REFERENCEINSERTION,ReferenceInsertionEventHandler.class);
694if (ev != null)
695 eventCartridge.addReferenceInsertionEventHandler((ReferenceInsertionEventHandler) ev);
696 }
697 }
698699 String[] nullset = configuration.getStringArray(RuntimeConstants.EVENTHANDLER_NULLSET);
700if ( nullset != null )
701 {
702for ( int i=0; i < nullset.length; i++ )
703 {
704EventHandler ev = initializeSpecificEventHandler(nullset[i],RuntimeConstants.EVENTHANDLER_NULLSET,NullSetEventHandler.class);
705if (ev != null)
706 eventCartridge.addNullSetEventHandler((NullSetEventHandler) ev);
707 }
708 }
709710 String[] methodexception = configuration.getStringArray(RuntimeConstants.EVENTHANDLER_METHODEXCEPTION);
711if ( methodexception != null )
712 {
713for ( int i=0; i < methodexception.length; i++ )
714 {
715EventHandler ev = initializeSpecificEventHandler(methodexception[i],RuntimeConstants.EVENTHANDLER_METHODEXCEPTION,MethodExceptionEventHandler.class);
716if (ev != null)
717 eventCartridge.addMethodExceptionHandler((MethodExceptionEventHandler) ev);
718 }
719 }
720721 String[] includeHandler = configuration.getStringArray(RuntimeConstants.EVENTHANDLER_INCLUDE);
722if ( includeHandler != null )
723 {
724for ( int i=0; i < includeHandler.length; i++ )
725 {
726EventHandler ev = initializeSpecificEventHandler(includeHandler[i],RuntimeConstants.EVENTHANDLER_INCLUDE,IncludeEventHandler.class);
727if (ev != null)
728 eventCartridge.addIncludeEventHandler((IncludeEventHandler) ev);
729 }
730 }
731732 String[] invalidReferenceSet = configuration.getStringArray(RuntimeConstants.EVENTHANDLER_INVALIDREFERENCES);
733if ( invalidReferenceSet != null )
734 {
735for ( int i=0; i < invalidReferenceSet.length; i++ )
736 {
737EventHandler ev = initializeSpecificEventHandler(invalidReferenceSet[i],RuntimeConstants.EVENTHANDLER_INVALIDREFERENCES,InvalidReferenceEventHandler.class);
738if (ev != null)
739 {
740 eventCartridge.addInvalidReferenceEventHandler((InvalidReferenceEventHandler) ev);
741 }
742 }
743 }
744745746 }
747748privateEventHandler initializeSpecificEventHandler(String classname, String paramName, Class EventHandlerInterface)
749throws Exception
750 {
751if ( classname != null && classname.length() > 0)
752 {
753 Object o = null;
754try {
755 o = ClassUtils.getNewInstance(classname);
756 }
757catch (ClassNotFoundException cnfe )
758 {
759 String err = "The specified class for "760 + paramName + " (" + classname
761 + ") does not exist or is not accessible to the current classloader.";
762 log.error(err);
763thrownew Exception(err);
764 }
765766if (!EventHandlerInterface.isAssignableFrom(EventHandlerInterface))
767 {
768 String err = "The specified class for " + paramName + " ("769 + classname + ") does not implement "770 + EventHandlerInterface.getName()
771 + "; Velocity is not initialized correctly.";
772773 log.error(err);
774thrownew Exception(err);
775 }
776777EventHandler ev = (EventHandler) o;
778if ( ev instanceof RuntimeServicesAware )
779 ((RuntimeServicesAware) ev).setRuntimeServices(this);
780return ev;
781782 } else783returnnull;
784 }
785786/**787 * Initialize the Velocity logging system.788 *789 * @throws Exception790 */791privatevoid initializeLog() throws Exception
792 {
793// since the Log we started with was just placeholding,794// let's update it with the real LogChute settings.795 LogManager.updateLog(this.log, this);
796 }
797798799/**800 * This methods initializes all the directives801 * that are used by the Velocity Runtime. The802 * directives to be initialized are listed in803 * the RUNTIME_DEFAULT_DIRECTIVES properties804 * file.805 *806 * @throws Exception807 */808privatevoid initializeDirectives()
809throws Exception
810 {
811/*812 * Initialize the runtime directive table.813 * This will be used for creating parsers.814 */815 runtimeDirectives = new Hashtable();
816817 Properties directiveProperties = new Properties();
818819/*820 * Grab the properties file with the list of directives821 * that we should initialize.822 */823824 InputStream inputStream = null;
825826try827 {
828 inputStream = getClass().getResourceAsStream('/' + DEFAULT_RUNTIME_DIRECTIVES);
829830if (inputStream == null)
831 {
832thrownew Exception("Error loading directive.properties! " +
833"Something is very wrong if these properties " +
834"aren't being located. Either your Velocity " +
835"distribution is incomplete or your Velocity " +
836"jar file is corrupted!");
837 }
838839 directiveProperties.load(inputStream);
840841 }
842catch (IOException ioe)
843 {
844 String msg = "Error while loading directive properties!";
845 log.error(msg, ioe);
846thrownew RuntimeException(msg, ioe);
847 }
848finally849 {
850try851 {
852if (inputStream != null)
853 {
854 inputStream.close();
855 }
856 }
857catch (IOException ioe)
858 {
859 String msg = "Cannot close directive properties!";
860 log.error(msg, ioe);
861thrownew RuntimeException(msg, ioe);
862 }
863 }
864865866/*867 * Grab all the values of the properties. These868 * are all class names for example:869 *870 * org.apache.velocity.runtime.directive.Foreach871 */872 Enumeration directiveClasses = directiveProperties.elements();
873874while (directiveClasses.hasMoreElements())
875 {
876 String directiveClass = (String) directiveClasses.nextElement();
877 loadDirective(directiveClass);
878 log.debug("Loaded System Directive: " + directiveClass);
879 }
880881/*882 * now the user's directives883 */884885 String[] userdirective = configuration.getStringArray("userdirective");
886887for( int i = 0; i < userdirective.length; i++)
888 {
889 loadDirective(userdirective[i]);
890if (log.isDebugEnabled())
891 {
892 log.debug("Loaded User Directive: " + userdirective[i]);
893 }
894 }
895896 }
897898/**899 * Programatically add a directive.900 * @param directive901 */902publicvoid addDirective(Directive directive)
903 {
904 runtimeDirectives.put(directive.getName(), directive);
905 }
906907/**908 * Retrieve a previously instantiated directive.909 * @param name name of the directive910 * @return the {@link Directive} for that name911 */912publicDirective getDirective(String name)
913 {
914return (Directive) runtimeDirectives.get(name);
915 }
916917/**918 * Remove a directive.919 * @param name name of the directive.920 */921publicvoid removeDirective(String name)
922 {
923 runtimeDirectives.remove(name);
924 }
925926/**927 * instantiates and loads the directive with some basic checks928 *929 * @param directiveClass classname of directive to load930 */931privatevoid loadDirective(String directiveClass)
932 {
933try934 {
935 Object o = ClassUtils.getNewInstance( directiveClass );
936937if (o instanceof Directive)
938 {
939Directive directive = (Directive) o;
940 addDirective(directive);
941 }
942else943 {
944 String msg = directiveClass + " does not implement "945 + Directive.class.getName() + "; it cannot be loaded.";
946 log.error(msg);
947thrownewVelocityException(msg);
948 }
949 }
950// The ugly threesome: ClassNotFoundException,951// IllegalAccessException, InstantiationException.952// Ignore Findbugs complaint for now.953catch (Exception e)
954 {
955 String msg = "Failed to load Directive: " + directiveClass;
956 log.error(msg, e);
957thrownewVelocityException(msg, e);
958 }
959 }
960961962/**963 * Initializes the Velocity parser pool.964 */965privatevoid initializeParserPool() throws Exception
966 {
967/*968 * Which parser pool?969 */970 String pp = getString(RuntimeConstants.PARSER_POOL_CLASS);
971972if (pp != null && pp.length() > 0)
973 {
974/*975 * if something was specified, then make one.976 * if that isn't a ParserPool, consider977 * this a huge error and throw978 */979980 Object o = null;
981982try983 {
984 o = ClassUtils.getNewInstance( pp );
985 }
986catch (ClassNotFoundException cnfe )
987 {
988 String err = "The specified class for ParserPool ("989 + pp
990 + ") does not exist (or is not accessible to the current classloader.";
991 log.error(err);
992thrownew Exception(err);
993 }
994995if (!(o instanceof ParserPool))
996 {
997 String err = "The specified class for ParserPool ("998 + pp + ") does not implement " + ParserPool.class999 + " Velocity not initialized correctly.";
10001001 log.error(err);
1002thrownew Exception(err);
1003 }
10041005 parserPool = (ParserPool) o;
10061007 parserPool.initialize(this);
1008 }
1009else1010 {
1011/*1012 * someone screwed up. Lets not fool around...1013 */10141015 String err = "It appears that no class was specified as the"1016 + " ParserPool. Please ensure that all configuration"1017 + " information is correct.";
10181019 log.error(err);
1020thrownew Exception( err );
1021 }
10221023 }
10241025/**1026 * Returns a JavaCC generated Parser.1027 *1028 * @return Parser javacc generated parser1029 */1030publicParser createNewParser()
1031 {
1032 requireInitialization();
10331034Parser parser = newParser(this);
1035 parser.setDirectives(runtimeDirectives);
1036return parser;
1037 }
10381039/**1040 * Parse the input and return the root of1041 * AST node structure.1042 * <br><br>1043 * In the event that it runs out of parsers in the1044 * pool, it will create and let them be GC'd1045 * dynamically, logging that it has to do that. This1046 * is considered an exceptional condition. It is1047 * expected that the user will set the1048 * PARSER_POOL_SIZE property appropriately for their1049 * application. We will revisit this.1050 *1051 * @param string String to be parsed1052 * @param templateName name of the template being parsed1053 * @return A root node representing the template as an AST tree.1054 * @throws ParseException When the string could not be parsed as a template.1055 * @since 1.61056 */1057publicSimpleNode parse(String string, String templateName)
1058throwsParseException1059 {
1060return parse(new StringReader(string), templateName);
1061 }
10621063/**1064 * Parse the input and return the root of1065 * AST node structure.1066 * <br><br>1067 * In the event that it runs out of parsers in the1068 * pool, it will create and let them be GC'd1069 * dynamically, logging that it has to do that. This1070 * is considered an exceptional condition. It is1071 * expected that the user will set the1072 * PARSER_POOL_SIZE property appropriately for their1073 * application. We will revisit this.1074 *1075 * @param reader Reader retrieved by a resource loader1076 * @param templateName name of the template being parsed1077 * @return A root node representing the template as an AST tree.1078 * @throws ParseException When the template could not be parsed.1079 */1080publicSimpleNode parse(Reader reader, String templateName)
1081throwsParseException1082 {
1083/*1084 * do it and dump the VM namespace for this template1085 */1086return parse(reader, templateName, true);
1087 }
10881089/**1090 * Parse the input and return the root of the AST node structure.1091 *1092 * @param reader Reader retrieved by a resource loader1093 * @param templateName name of the template being parsed1094 * @param dumpNamespace flag to dump the Velocimacro namespace for this template1095 * @return A root node representing the template as an AST tree.1096 * @throws ParseException When the template could not be parsed.1097 */1098publicSimpleNode parse(Reader reader, String templateName, boolean dumpNamespace)
1099throwsParseException1100 {
1101 requireInitialization();
11021103Parser parser = (Parser) parserPool.get();
1104boolean keepParser = true;
1105if (parser == null)
1106 {
1107/*1108 * if we couldn't get a parser from the pool make one and log it.1109 */1110if (log.isInfoEnabled())
1111 {
1112 log.info("Runtime : ran out of parsers. Creating a new one. "1113 + " Please increment the parser.pool.size property."1114 + " The current value is too small.");
1115 }
1116 parser = createNewParser();
1117 keepParser = false;
1118 }
11191120try1121 {
1122/*1123 * dump namespace if we are told to. Generally, you want to1124 * do this - you don't in special circumstances, such as1125 * when a VM is getting init()-ed & parsed1126 */1127if (dumpNamespace)
1128 {
1129 dumpVMNamespace(templateName);
1130 }
1131return parser.parse(reader, templateName);
1132 }
1133finally1134 {
1135if (keepParser)
1136 {
1137 parserPool.put(parser);
1138 }
11391140 }
1141 }
11421143/**1144 * Renders the input string using the context into the output writer.1145 * To be used when a template is dynamically constructed, or want to use1146 * Velocity as a token replacer.1147 *1148 * @param context context to use in rendering input string1149 * @param out Writer in which to render the output1150 * @param logTag string to be used as the template name for log1151 * messages in case of error1152 * @param instring input string containing the VTL to be rendered1153 *1154 * @return true if successful, false otherwise. If false, see1155 * Velocity runtime log1156 * @throws ParseErrorException The template could not be parsed.1157 * @throws MethodInvocationException A method on a context object could not be invoked.1158 * @throws ResourceNotFoundException A referenced resource could not be loaded.1159 * @throws IOException While rendering to the writer, an I/O problem occured.1160 * @since Velocity 1.61161 */1162publicboolean evaluate(Context context, Writer out,
1163 String logTag, String instring) throws IOException
1164 {
1165return evaluate(context, out, logTag, new StringReader(instring));
1166 }
11671168/**1169 * Renders the input reader using the context into the output writer.1170 * To be used when a template is dynamically constructed, or want to1171 * use Velocity as a token replacer.1172 *1173 * @param context context to use in rendering input string1174 * @param writer Writer in which to render the output1175 * @param logTag string to be used as the template name for log messages1176 * in case of error1177 * @param reader Reader containing the VTL to be rendered1178 *1179 * @return true if successful, false otherwise. If false, see1180 * Velocity runtime log1181 * @throws ParseErrorException The template could not be parsed.1182 * @throws MethodInvocationException A method on a context object could not be invoked.1183 * @throws ResourceNotFoundException A referenced resource could not be loaded.1184 * @throws IOException While reading from the reader or rendering to the writer,1185 * an I/O problem occured.1186 * @since Velocity 1.61187 */1188publicboolean evaluate(Context context, Writer writer,
1189 String logTag, Reader reader) throws IOException
1190 {
1191if (logTag == null)
1192 {
1193thrownew NullPointerException("logTag (i.e. template name) cannot be null, you must provide an identifier for the content being evaluated");
1194 }
11951196SimpleNode nodeTree = null;
1197try1198 {
1199 nodeTree = parse(reader, logTag);
1200 }
1201catch (ParseException pex)
1202 {
1203thrownewParseErrorException(pex);
1204 }
1205catch (TemplateInitException pex)
1206 {
1207thrownewParseErrorException(pex);
1208 }
12091210if (nodeTree == null)
1211 {
1212return false;
1213 }
1214else1215 {
1216return render(context, writer, logTag, nodeTree);
1217 }
1218 }
121912201221/**1222 * Initializes and renders the AST {@link SimpleNode} using the context1223 * into the output writer.1224 *1225 * @param context context to use in rendering input string1226 * @param writer Writer in which to render the output1227 * @param logTag string to be used as the template name for log messages1228 * in case of error1229 * @param nodeTree SimpleNode which is the root of the AST to be rendered1230 *1231 * @return true if successful, false otherwise. If false, see1232 * Velocity runtime log for errors1233 * @throws ParseErrorException The template could not be parsed.1234 * @throws MethodInvocationException A method on a context object could not be invoked.1235 * @throws ResourceNotFoundException A referenced resource could not be loaded.1236 * @throws IOException While rendering to the writer, an I/O problem occured.1237 * @since Velocity 1.61238 */1239publicboolean render(Context context, Writer writer,
1240 String logTag, SimpleNode nodeTree) throws IOException
1241 {
1242/*1243 * we want to init then render1244 */1245InternalContextAdapterImpl ica =
1246newInternalContextAdapterImpl(context);
12471248 ica.pushCurrentTemplateName(logTag);
12491250try1251 {
1252try1253 {
1254 nodeTree.init(ica, this);
1255 }
1256catch (TemplateInitException pex)
1257 {
1258thrownewParseErrorException(pex);
1259 }
1260/**1261 * pass through application level runtime exceptions1262 */1263catch(RuntimeException e)
1264 {
1265throw e;
1266 }
1267catch(Exception e)
1268 {
1269 String msg = "RuntimeInstance.render(): init exception for tag = "+logTag;
1270 getLog().error(msg, e);
1271thrownewVelocityException(msg, e);
1272 }
12731274/*1275 * now render, and let any exceptions fly1276 */1277 nodeTree.render(ica, writer);
1278 }
1279finally1280 {
1281 ica.popCurrentTemplateName();
1282 }
12831284returntrue;
1285 }
12861287/**1288 * Invokes a currently registered Velocimacro with the params provided1289 * and places the rendered stream into the writer.1290 * <br>1291 * Note : currently only accepts args to the VM if they are in the context.1292 *1293 * @param vmName name of Velocimacro to call1294 * @param logTag string to be used for template name in case of error. if null,1295 * the vmName will be used1296 * @param params keys for args used to invoke Velocimacro, in java format1297 * rather than VTL (eg "foo" or "bar" rather than "$foo" or "$bar")1298 * @param context Context object containing data/objects used for rendering.1299 * @param writer Writer for output stream1300 * @return true if Velocimacro exists and successfully invoked, false otherwise.1301 * @throws IOException While rendering to the writer, an I/O problem occured.1302 * @since 1.61303 */1304publicboolean invokeVelocimacro(final String vmName, String logTag,
1305 String[] params, finalContext context,
1306final Writer writer)
1307throws IOException
1308 {
1309/* check necessary parameters */1310if (vmName == null || context == null || writer == null)
1311 {
1312 String msg = "RuntimeInstance.invokeVelocimacro() : invalid call : vmName, context, and writer must not be null";
1313 getLog().error(msg);
1314thrownew NullPointerException(msg);
1315 }
13161317/* handle easily corrected parameters */1318if (logTag == null)
1319 {
1320 logTag = vmName;
1321 }
1322if (params == null)
1323 {
1324 params = new String[0];
1325 }
13261327/* does the VM exist? */1328if (!isVelocimacro(vmName, logTag))
1329 {
1330 String msg = "RuntimeInstance.invokeVelocimacro() : VM '" + vmName
1331 + "' is not registered.";
1332 getLog().error(msg);
1333thrownewVelocityException(msg);
1334 }
13351336/* now just create the VM call, and use evaluate */1337 StrBuilder template = new StrBuilder("#");
1338 template.append(vmName);
1339 template.append("(");
1340for( int i = 0; i < params.length; i++)
1341 {
1342 template.append(" $");
1343 template.append(params[i]);
1344 }
1345 template.append(" )");
13461347return evaluate(context, writer, logTag, template.toString());
1348 }
13491350/**1351 * Retrieves and caches the configured default encoding1352 * for better performance. (VELOCITY-606)1353 */1354private String getDefaultEncoding()
1355 {
1356if (encoding == null)
1357 {
1358 encoding = getString(INPUT_ENCODING, ENCODING_DEFAULT);
1359 }
1360return encoding;
1361 }
13621363/**1364 * Returns a <code>Template</code> from the resource manager.1365 * This method assumes that the character encoding of the1366 * template is set by the <code>input.encoding</code>1367 * property. The default is "ISO-8859-1"1368 *1369 * @param name The file name of the desired template.1370 * @return The template.1371 * @throws ResourceNotFoundException if template not found1372 * from any available source.1373 * @throws ParseErrorException if template cannot be parsed due1374 * to syntax (or other) error.1375 * @throws Exception if an error occurs in template initialization1376 */1377publicTemplate getTemplate(String name)
1378throws ResourceNotFoundException, ParseErrorException, Exception
1379 {
1380return getTemplate(name, getDefaultEncoding());
1381 }
13821383/**1384 * Returns a <code>Template</code> from the resource manager1385 *1386 * @param name The name of the desired template.1387 * @param encoding Character encoding of the template1388 * @return The template.1389 * @throws ResourceNotFoundException if template not found1390 * from any available source.1391 * @throws ParseErrorException if template cannot be parsed due1392 * to syntax (or other) error.1393 * @throws Exception if an error occurs in template initialization1394 */1395publicTemplate getTemplate(String name, String encoding)
1396throws ResourceNotFoundException, ParseErrorException, Exception
1397 {
1398 requireInitialization();
13991400return (Template)
1401 resourceManager.getResource(name,
1402 ResourceManager.RESOURCE_TEMPLATE, encoding);
1403 }
14041405/**1406 * Returns a static content resource from the1407 * resource manager. Uses the current value1408 * if INPUT_ENCODING as the character encoding.1409 *1410 * @param name Name of content resource to get1411 * @return parsed ContentResource object ready for use1412 * @throws ResourceNotFoundException if template not found1413 * from any available source.1414 * @throws ParseErrorException When the template could not be parsed.1415 * @throws Exception Any other error.1416 */1417publicContentResource getContent(String name)
1418throws ResourceNotFoundException, ParseErrorException, Exception
1419 {
1420/*1421 * the encoding is irrelvant as we don't do any converstion1422 * the bytestream should be dumped to the output stream1423 */14241425return getContent(name, getDefaultEncoding());
1426 }
14271428/**1429 * Returns a static content resource from the1430 * resource manager.1431 *1432 * @param name Name of content resource to get1433 * @param encoding Character encoding to use1434 * @return parsed ContentResource object ready for use1435 * @throws ResourceNotFoundException if template not found1436 * from any available source.1437 * @throws ParseErrorException When the template could not be parsed.1438 * @throws Exception Any other error.1439 */1440publicContentResource getContent(String name, String encoding)
1441throws ResourceNotFoundException, ParseErrorException, Exception
1442 {
1443 requireInitialization();
14441445return (ContentResource)
1446 resourceManager.getResource(name,
1447 ResourceManager.RESOURCE_CONTENT, encoding);
1448 }
144914501451/**1452 * Determines if a template exists and returns name of the loader that1453 * provides it. This is a slightly less hokey way to support1454 * the Velocity.resourceExists() utility method, which was broken1455 * when per-template encoding was introduced. We can revisit this.1456 *1457 * @param resourceName Name of template or content resource1458 * @return class name of loader than can provide it1459 */1460public String getLoaderNameForResource(String resourceName)
1461 {
1462 requireInitialization();
14631464return resourceManager.getLoaderNameForResource(resourceName);
1465 }
14661467/**1468 * Returns a convenient Log instance that wraps the current LogChute.1469 * Use this to log error messages. It has the usual methods.1470 *1471 * @return A convenience Log instance that wraps the current LogChute.1472 * @since 1.51473 */1474publicLog getLog()
1475 {
1476return log;
1477 }
14781479/**1480 * @deprecated Use getLog() and call warn() on it.1481 * @see Log#warn(Object)1482 * @param message The message to log.1483 */1484publicvoid warn(Object message)
1485 {
1486 getLog().warn(message);
1487 }
14881489/**1490 * @deprecated Use getLog() and call info() on it.1491 * @see Log#info(Object)1492 * @param message The message to log.1493 */1494publicvoid info(Object message)
1495 {
1496 getLog().info(message);
1497 }
14981499/**1500 * @deprecated Use getLog() and call error() on it.1501 * @see Log#error(Object)1502 * @param message The message to log.1503 */1504publicvoid error(Object message)
1505 {
1506 getLog().error(message);
1507 }
15081509/**1510 * @deprecated Use getLog() and call debug() on it.1511 * @see Log#debug(Object)1512 * @param message The message to log.1513 */1514publicvoid debug(Object message)
1515 {
1516 getLog().debug(message);
1517 }
15181519/**1520 * String property accessor method with default to hide the1521 * configuration implementation.1522 *1523 * @param key property key1524 * @param defaultValue default value to return if key not1525 * found in resource manager.1526 * @return value of key or default1527 */1528public String getString( String key, String defaultValue)
1529 {
1530return configuration.getString(key, defaultValue);
1531 }
15321533/**1534 * Returns the appropriate VelocimacroProxy object if vmName1535 * is a valid current Velocimacro.1536 *1537 * @param vmName Name of velocimacro requested1538 * @param templateName Name of the template that contains the velocimacro.1539 * @return The requested VelocimacroProxy.1540 * @since 1.61541 */1542publicDirective getVelocimacro(String vmName, String templateName)
1543 {
1544return vmFactory.getVelocimacro( vmName, templateName );
1545 }
15461547/**1548 * Returns the appropriate VelocimacroProxy object if vmName1549 * is a valid current Velocimacro.1550 *1551 * @param vmName Name of velocimacro requested1552 * @param templateName Name of the namespace.1553 * @param renderingTemplate Name of the template we are currently rendering. This1554 * information is needed when VM_PERM_ALLOW_INLINE_REPLACE_GLOBAL setting is true1555 * and template contains a macro with the same name as the global macro library.1556 * 1557 * @since Velocity 1.61558 * 1559 * @return VelocimacroProxy1560 */1561publicDirective getVelocimacro(String vmName, String templateName, String renderingTemplate)
1562 {
1563return vmFactory.getVelocimacro( vmName, templateName, renderingTemplate );
1564 }
156515661567/**1568 * Adds a new Velocimacro. Usually called by Macro only while parsing.1569 *1570 * @param name Name of velocimacro1571 * @param macro String form of macro body1572 * @param argArray Array of strings, containing the1573 * #macro() arguments. the 0th is the name.1574 * @param sourceTemplate Name of the template that contains the velocimacro.1575 * 1576 * @deprecated Use addVelocimacro(String, Node, String[], String) instead1577 * 1578 * @return True if added, false if rejected for some1579 * reason (either parameters or permission settings)1580 */1581publicboolean addVelocimacro( String name,
1582 String macro,
1583 String argArray[],
1584 String sourceTemplate )
1585 {
1586return vmFactory.addVelocimacro(name, macro, argArray, sourceTemplate);
1587 }
15881589/**1590 * Adds a new Velocimacro. Usually called by Macro only while parsing.1591 * 1592 * Called by org.apache.velocity.runtime.directive.processAndRegister1593 *1594 * @param name Name of velocimacro1595 * @param macro root AST node of the parsed macro1596 * @param argArray Array of strings, containing the1597 * #macro() arguments. the 0th is the name.1598 * @param sourceTemplate1599 * 1600 * @since Velocity 1.61601 * 1602 * @return boolean True if added, false if rejected for some1603 * reason (either parameters or permission settings)1604 */1605publicboolean addVelocimacro( String name,
1606Node macro,
1607 String argArray[],
1608 String sourceTemplate )
1609 {
1610return vmFactory.addVelocimacro(name, macro, argArray, sourceTemplate);
1611 }
161216131614/**1615 * Checks to see if a VM exists1616 *1617 * @param vmName Name of the Velocimacro.1618 * @param templateName Template on which to look for the Macro.1619 * @return True if VM by that name exists, false if not1620 */1621publicboolean isVelocimacro( String vmName, String templateName )
1622 {
1623return vmFactory.isVelocimacro(vmName, templateName);
1624 }
16251626/**1627 * tells the vmFactory to dump the specified namespace. This is to support1628 * clearing the VM list when in inline-VM-local-scope mode1629 * @param namespace Namespace to dump.1630 * @return True if namespace was dumped successfully.1631 */1632publicboolean dumpVMNamespace(String namespace)
1633 {
1634return vmFactory.dumpVMNamespace( namespace );
1635 }
16361637/* --------------------------------------------------------------------1638 * R U N T I M E A C C E S S O R M E T H O D S1639 * --------------------------------------------------------------------1640 * These are the getXXX() methods that are a simple wrapper1641 * around the configuration object. This is an attempt1642 * to make a the Velocity Runtime the single access point1643 * for all things Velocity, and allow the Runtime to1644 * adhere as closely as possible the the Mediator pattern1645 * which is the ultimate goal.1646 * --------------------------------------------------------------------1647 */16481649/**1650 * String property accessor method to hide the configuration implementation1651 * @param key property key1652 * @return value of key or null1653 */1654public String getString(String key)
1655 {
1656return StringUtils.nullTrim(configuration.getString(key));
1657 }
16581659/**1660 * Int property accessor method to hide the configuration implementation.1661 *1662 * @param key Property key1663 * @return value1664 */1665publicint getInt(String key)
1666 {
1667return configuration.getInt(key);
1668 }
16691670/**1671 * Int property accessor method to hide the configuration implementation.1672 *1673 * @param key property key1674 * @param defaultValue The default value.1675 * @return value1676 */1677publicint getInt(String key, int defaultValue)
1678 {
1679return configuration.getInt(key, defaultValue);
1680 }
16811682/**1683 * Boolean property accessor method to hide the configuration implementation.1684 *1685 * @param key property key1686 * @param def The default value if property not found.1687 * @return value of key or default value1688 */1689publicboolean getBoolean(String key, boolean def)
1690 {
1691return configuration.getBoolean(key, def);
1692 }
16931694/**1695 * Return the velocity runtime configuration object.1696 *1697 * @return Configuration object which houses the Velocity runtime1698 * properties.1699 */1700public ExtendedProperties getConfiguration()
1701 {
1702return configuration;
1703 }
17041705/**1706 * Return the Introspector for this instance1707 * @return The Introspector for this instance1708 */1709publicIntrospector getIntrospector()
1710 {
1711return introspector;
1712 }
17131714/**1715 * Returns the event handlers for the application.1716 * @return The event handlers for the application.1717 * @since 1.51718 */1719publicEventCartridge getApplicationEventCartridge()
1720 {
1721return eventCartridge;
1722 }
172317241725/**1726 * Gets the application attribute for the given key1727 *1728 * @param key1729 * @return The application attribute for the given key.1730 */1731public Object getApplicationAttribute(Object key)
1732 {
1733return applicationAttributes.get(key);
1734 }
17351736/**1737 * Sets the application attribute for the given key1738 *1739 * @param key1740 * @param o The new application attribute.1741 * @return The old value of this attribute or null if it hasn't been set before.1742 */1743public Object setApplicationAttribute(Object key, Object o)
1744 {
1745return applicationAttributes.put(key, o);
1746 }
17471748/**1749 * Returns the Uberspect object for this Instance.1750 *1751 * @return The Uberspect object for this Instance.1752 */1753publicUberspect getUberspect()
1754 {
1755return uberSpect;
1756 }
17571758 }
1package org.apache.velocity.runtime;
23/*4 * Licensed to the Apache Software Foundation (ASF) under one5 * or more contributor license agreements. See the NOTICE file6 * distributed with this work for additional information7 * regarding copyright ownership. The ASF licenses this file8 * to you under the Apache License, Version 2.0 (the9 * "License"); you may not use this file except in compliance10 * with the License. You may obtain a copy of the License at11 *12 * http://www.apache.org/licenses/LICENSE-2.013 *14 * Unless required by applicable law or agreed to in writing,15 * software distributed under the License is distributed on an16 * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY17 * KIND, either express or implied. See the License for the18 * specific language governing permissions and limitations19 * under the License. 20 */2122import java.io.File;
23import java.io.IOException;
24import java.io.InputStream;
25import java.io.Reader;
26import java.io.StringReader;
27import java.io.Writer;
28import java.util.Enumeration;
29import java.util.HashMap;
30import java.util.Hashtable;
31import java.util.Map;
32import java.util.Properties;
3334import org.apache.commons.collections.ExtendedProperties;
35import org.apache.commons.lang.text.StrBuilder;
36import org.apache.velocity.Template;
37import org.apache.velocity.app.event.EventCartridge;
38import org.apache.velocity.app.event.EventHandler;
39import org.apache.velocity.app.event.IncludeEventHandler;
40import org.apache.velocity.app.event.InvalidReferenceEventHandler;
41import org.apache.velocity.app.event.MethodExceptionEventHandler;
42import org.apache.velocity.app.event.NullSetEventHandler;
43import org.apache.velocity.app.event.ReferenceInsertionEventHandler;
44import org.apache.velocity.context.Context;
45import org.apache.velocity.context.InternalContextAdapterImpl;
46import org.apache.velocity.exception.MethodInvocationException;
47import org.apache.velocity.exception.ParseErrorException;
48import org.apache.velocity.exception.ResourceNotFoundException;
49import org.apache.velocity.exception.TemplateInitException;
50import org.apache.velocity.exception.VelocityException;
51import org.apache.velocity.runtime.directive.Directive;
52import org.apache.velocity.runtime.log.Log;
53import org.apache.velocity.runtime.log.LogManager;
54import org.apache.velocity.runtime.parser.ParseException;
55import org.apache.velocity.runtime.parser.Parser;
56import org.apache.velocity.runtime.parser.node.Node;
57import org.apache.velocity.runtime.parser.node.SimpleNode;
58import org.apache.velocity.runtime.resource.ContentResource;
59import org.apache.velocity.runtime.resource.ResourceManager;
60import org.apache.velocity.util.ClassUtils;
61import org.apache.velocity.util.RuntimeServicesAware;
62import org.apache.velocity.util.StringUtils;
63import org.apache.velocity.util.introspection.Introspector;
64import org.apache.velocity.util.introspection.Uberspect;
65import org.apache.velocity.util.introspection.UberspectLoggable;
66import org.apache.velocity.util.introspection.ChainableUberspector;
67import org.apache.velocity.util.introspection.LinkingUberspector;
6869/**70 * This is the Runtime system for Velocity. It is the71 * single access point for all functionality in Velocity.72 * It adheres to the mediator pattern and is the only73 * structure that developers need to be familiar with74 * in order to get Velocity to perform.75 *76 * The Runtime will also cooperate with external77 * systems like Turbine. Runtime properties can78 * set and then the Runtime is initialized.79 *80 * Turbine, for example, knows where the templates81 * are to be loaded from, and where the Velocity82 * log file should be placed.83 *84 * So in the case of Velocity cooperating with Turbine85 * the code might look something like the following:86 *87 * <blockquote><code><pre>88 * ri.setProperty(Runtime.FILE_RESOURCE_LOADER_PATH, templatePath);89 * ri.setProperty(Runtime.RUNTIME_LOG, pathToVelocityLog);90 * ri.init();91 * </pre></code></blockquote>92 *93 * <pre>94 * -----------------------------------------------------------------------95 * 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 N96 * -----------------------------------------------------------------------97 * init()98 *99 * If init() is called by itself the RuntimeInstance will initialize100 * with a set of default values.101 * -----------------------------------------------------------------------102 * init(String/Properties)103 *104 * In this case the default velocity properties are layed down105 * first to provide a solid base, then any properties provided106 * in the given properties object will override the corresponding107 * default property.108 * -----------------------------------------------------------------------109 * </pre>110 *111 * @author <a href="mailto:jvanzyl@apache.org">Jason van Zyl</a>112 * @author <a href="mailto:jlb@houseofdistraction.com">Jeff Bowden</a>113 * @author <a href="mailto:geirm@optonline.net">Geir Magusson Jr.</a>114 * @version $Id: RuntimeInstance.java 703049 2008-10-09 03:18:58Z nbubna $115 */116publicclassRuntimeInstance implements RuntimeConstants, RuntimeServices117 {
118/**119 * VelocimacroFactory object to manage VMs120 */121private VelocimacroFactory vmFactory = null;
122123/**124 * The Runtime logger. We start with an instance of125 * a 'primordial logger', which just collects log messages126 * then, when the log system is initialized, all the127 * messages get dumpted out of the primordial one into the real one.128 */129privateLog log = newLog();
130131/**132 * The Runtime parser pool133 */134private ParserPool parserPool;
135136/**137 * Indicate whether the Runtime is in the midst of initialization.138 */139privateboolean initializing = false;
140141/**142 * Indicate whether the Runtime has been fully initialized.143 */144privateboolean initialized = false;
145146/**147 * These are the properties that are laid down over top148 * of the default properties when requested.149 */150private ExtendedProperties overridingProperties = null;
151152/**153 * This is a hashtable of initialized directives.154 * The directives that populate this hashtable are155 * taken from the RUNTIME_DEFAULT_DIRECTIVES156 * property file. This hashtable is passed157 * to each parser that is created.158 */159private Hashtable runtimeDirectives;
160161/**162 * Object that houses the configuration options for163 * the velocity runtime. The ExtendedProperties object allows164 * the convenient retrieval of a subset of properties.165 * For example all the properties for a resource loader166 * can be retrieved from the main ExtendedProperties object167 * using something like the following:168 *169 * ExtendedProperties loaderConfiguration =170 * configuration.subset(loaderID);171 *172 * And a configuration is a lot more convenient to deal173 * with then conventional properties objects, or Maps.174 */175private ExtendedProperties configuration = new ExtendedProperties();
176177privateResourceManager resourceManager = null;
178179/**180 * This stores the engine-wide set of event handlers. Event handlers for181 * each specific merge are stored in the context.182 */183privateEventCartridge eventCartridge = null;
184185/*186 * Each runtime instance has it's own introspector187 * to ensure that each instance is completely separate.188 */189privateIntrospector introspector = null;
190191192/*193 * Opaque reference to something specificed by the194 * application for use in application supplied/specified195 * pluggable components196 */197private Map applicationAttributes = null;
198privateUberspect uberSpect;
199private String encoding;
200201/**202 * Creates a new RuntimeInstance object.203 */204publicRuntimeInstance()
205 {
206/*207 * create a VM factory, introspector, and application attributes208 */209 vmFactory = newVelocimacroFactory( this );
210211/*212 * make a new introspector and initialize it213 */214 introspector = newIntrospector(getLog());
215216/*217 * and a store for the application attributes218 */219 applicationAttributes = new HashMap();
220 }
221222/**223 * This is the primary initialization method in the Velocity224 * Runtime. The systems that are setup/initialized here are225 * as follows:226 *227 * <ul>228 * <li>Logging System</li>229 * <li>ResourceManager</li>230 * <li>EventHandler</li>231 * <li>Parser Pool</li>232 * <li>Global Cache</li>233 * <li>Static Content Include System</li>234 * <li>Velocimacro System</li>235 * </ul>236 * @throws Exception When an error occured during initialization.237 */238publicsynchronizedvoid init()
239throws Exception
240 {
241if (!initialized && !initializing)
242 {
243 initializing = true;
244245 log.trace("*******************************************************************");
246 log.debug("Starting Apache Velocity v@build.version@ (compiled: @build.time@)");
247 log.trace("RuntimeInstance initializing.");
248249 initializeProperties();
250 initializeLog();
251 initializeResourceManager();
252 initializeDirectives();
253 initializeEventHandlers();
254 initializeParserPool();
255256 initializeIntrospection();
257/*258 * initialize the VM Factory. It will use the properties259 * accessable from Runtime, so keep this here at the end.260 */261 vmFactory.initVelocimacro();
262263 log.trace("RuntimeInstance successfully initialized.");
264265 initialized = true;
266 initializing = false;
267 }
268 }
269270/**271 * Returns true if the RuntimeInstance has been successfully initialized.272 * @return True if the RuntimeInstance has been successfully initialized.273 * @since 1.5274 */275publicboolean isInitialized()
276 {
277return initialized;
278 }
279280/**281 * Init or die! (with some log help, of course)282 */283privatevoid requireInitialization()
284 {
285if (!initialized && !initializing)
286 {
287 log.debug("Velocity was not initialized! Calling init()...");
288try289 {
290 init();
291 }
292catch (Exception e)
293 {
294 getLog().error("Could not auto-initialize Velocity", e);
295thrownew RuntimeException("Velocity could not be initialized!", e);
296 }
297 }
298 }
299300/**301 * Gets the classname for the Uberspect introspection package and302 * instantiates an instance.303 */304privatevoid initializeIntrospection()
305throws Exception
306 {
307 String[] uberspectors = configuration.getStringArray(RuntimeConstants.UBERSPECT_CLASSNAME);
308for (int i=0; i <uberspectors.length;i++)
309 {
310 String rm = uberspectors[i];
311 Object o = null;
312313try314 {
315 o = ClassUtils.getNewInstance( rm );
316 }
317catch (ClassNotFoundException cnfe)
318 {
319 String err = "The specified class for Uberspect (" + rm
320 + ") does not exist or is not accessible to the current classloader.";
321 log.error(err);
322thrownew Exception(err);
323 }
324325if (!(o instanceof Uberspect))
326 {
327 String err = "The specified class for Uberspect ("328 + rm + ") does not implement " + Uberspect.class.getName()
329 + "; Velocity is not initialized correctly.";
330331 log.error(err);
332thrownew Exception(err);
333 }
334335Uberspect u = (Uberspect)o;
336337if (u instanceof UberspectLoggable)
338 {
339 ((UberspectLoggable)u).setLog(getLog());
340 }
341342if (u instanceof RuntimeServicesAware)
343 {
344 ((RuntimeServicesAware)u).setRuntimeServices(this);
345 }
346347if (uberSpect == null)
348 {
349 uberSpect = u;
350 }
351else352 {
353if (u instanceof ChainableUberspector)
354 {
355 ((ChainableUberspector)u).wrap(uberSpect);
356 uberSpect = u;
357 }
358else359 {
360 uberSpect = newLinkingUberspector(uberSpect,u);
361 }
362 }
363 }
364365if(uberSpect != null)
366 {
367 uberSpect.init();
368 }
369else370 {
371/*372 * someone screwed up. Lets not fool around...373 */374375 String err = "It appears that no class was specified as the"376 + " Uberspect. Please ensure that all configuration"377 + " information is correct.";
378379 log.error(err);
380thrownew Exception(err);
381 }
382 }
383384/**385 * Initializes the Velocity Runtime with properties file.386 * The properties file may be in the file system proper,387 * or the properties file may be in the classpath.388 */389privatevoid setDefaultProperties()
390 {
391 InputStream inputStream = null;
392try393 {
394 inputStream = getClass()
395 .getResourceAsStream('/' + DEFAULT_RUNTIME_PROPERTIES);
396397 configuration.load( inputStream );
398399if (log.isDebugEnabled())
400 {
401 log.debug("Default Properties File: " +
402new File(DEFAULT_RUNTIME_PROPERTIES).getPath());
403 }
404405406 }
407catch (IOException ioe)
408 {
409 String msg = "Cannot get Velocity Runtime default properties!";
410 log.error(msg, ioe);
411thrownew RuntimeException(msg, ioe);
412 }
413finally414 {
415try416 {
417if (inputStream != null)
418 {
419 inputStream.close();
420 }
421 }
422catch (IOException ioe)
423 {
424 String msg = "Cannot close Velocity Runtime default properties!";
425 log.error(msg, ioe);
426thrownew RuntimeException(msg, ioe);
427 }
428 }
429 }
430431/**432 * Allows an external system to set a property in433 * the Velocity Runtime.434 *435 * @param key property key436 * @param value property value437 */438publicvoid setProperty(String key, Object value)
439 {
440if (overridingProperties == null)
441 {
442 overridingProperties = new ExtendedProperties();
443 }
444445 overridingProperties.setProperty(key, value);
446 }
447448/**449 * Allow an external system to set an ExtendedProperties450 * object to use. This is useful where the external451 * system also uses the ExtendedProperties class and452 * the velocity configuration is a subset of453 * parent application's configuration. This is454 * the case with Turbine.455 *456 * @param configuration457 */458publicvoid setConfiguration( ExtendedProperties configuration)
459 {
460if (overridingProperties == null)
461 {
462 overridingProperties = configuration;
463 }
464else465 {
466// Avoid possible ConcurrentModificationException467if (overridingProperties != configuration)
468 {
469 overridingProperties.combine(configuration);
470 }
471 }
472 }
473474/**475 * Add a property to the configuration. If it already476 * exists then the value stated here will be added477 * to the configuration entry. For example, if478 *479 * resource.loader = file480 *481 * is already present in the configuration and you482 *483 * addProperty("resource.loader", "classpath")484 *485 * Then you will end up with a Vector like the486 * following:487 *488 * ["file", "classpath"]489 *490 * @param key491 * @param value492 */493publicvoid addProperty(String key, Object value)
494 {
495if (overridingProperties == null)
496 {
497 overridingProperties = new ExtendedProperties();
498 }
499500 overridingProperties.addProperty(key, value);
501 }
502503/**504 * Clear the values pertaining to a particular505 * property.506 *507 * @param key of property to clear508 */509publicvoid clearProperty(String key)
510 {
511if (overridingProperties != null)
512 {
513 overridingProperties.clearProperty(key);
514 }
515 }
516517/**518 * Allows an external caller to get a property. The calling519 * routine is required to know the type, as this routine520 * will return an Object, as that is what properties can be.521 *522 * @param key property to return523 * @return Value of the property or null if it does not exist.524 */525public Object getProperty(String key)
526 {
527 Object o = null;
528529/**530 * Before initialization, check the user-entered properties first.531 */532if (!initialized && !initializing && overridingProperties != null)
533 {
534 o = overridingProperties.get(key);
535 }
536537/**538 * After initialization, configuration will hold all properties.539 */540if (o == null)
541 {
542 o = configuration.getProperty(key);
543 }
544if (o instanceof String)
545 {
546return StringUtils.nullTrim((String) o);
547 }
548else549 {
550return o;
551 }
552 }
553554/**555 * Initialize Velocity properties, if the default556 * properties have not been laid down first then557 * do so. Then proceed to process any overriding558 * properties. Laying down the default properties559 * gives a much greater chance of having a560 * working system.561 */562privatevoid initializeProperties()
563 {
564/*565 * Always lay down the default properties first as566 * to provide a solid base.567 */568if (configuration.isInitialized() == false)
569 {
570 setDefaultProperties();
571 }
572573if( overridingProperties != null)
574 {
575 configuration.combine(overridingProperties);
576 }
577 }
578579/**580 * Initialize the Velocity Runtime with a Properties581 * object.582 *583 * @param p584 * @throws Exception When an error occurs during initialization.585 */586publicvoid init(Properties p) throws Exception
587 {
588 setProperties(ExtendedProperties.convertProperties(p));
589 init();
590 }
591592privatevoid setProperties(ExtendedProperties p)
593 {
594if (overridingProperties == null)
595 {
596 overridingProperties = p;
597 }
598else599 {
600 overridingProperties.combine(p);
601 }
602 }
603604/**605 * Initialize the Velocity Runtime with the name of606 * ExtendedProperties object.607 *608 * @param configurationFile609 * @throws Exception When an error occurs during initialization.610 */611publicvoid init(String configurationFile)
612throws Exception
613 {
614 setProperties(new ExtendedProperties(configurationFile));
615 init();
616 }
617618privatevoid initializeResourceManager()
619throws Exception
620 {
621/*622 * Which resource manager?623 */624625 String rm = getString(RuntimeConstants.RESOURCE_MANAGER_CLASS);
626627if (rm != null && rm.length() > 0)
628 {
629/*630 * if something was specified, then make one.631 * if that isn't a ResourceManager, consider632 * this a huge error and throw633 */634635 Object o = null;
636637try638 {
639 o = ClassUtils.getNewInstance( rm );
640 }
641catch (ClassNotFoundException cnfe )
642 {
643 String err = "The specified class for ResourceManager (" + rm
644 + ") does not exist or is not accessible to the current classloader.";
645 log.error(err);
646thrownew Exception(err);
647 }
648649if (!(o instanceof ResourceManager))
650 {
651 String err = "The specified class for ResourceManager (" + rm
652 + ") does not implement " + ResourceManager.class.getName()
653 + "; Velocity is not initialized correctly.";
654655 log.error(err);
656thrownew Exception(err);
657 }
658659 resourceManager = (ResourceManager) o;
660661 resourceManager.initialize(this);
662 }
663else664 {
665/*666 * someone screwed up. Lets not fool around...667 */668669 String err = "It appears that no class was specified as the"670 + " ResourceManager. Please ensure that all configuration"671 + " information is correct.";
672673 log.error(err);
674thrownew Exception( err );
675 }
676 }
677678privatevoid initializeEventHandlers()
679throws Exception
680 {
681682 eventCartridge = newEventCartridge();
683684/**685 * For each type of event handler, get the class name, instantiate it, and store it.686 */687688 String[] referenceinsertion = configuration.getStringArray(RuntimeConstants.EVENTHANDLER_REFERENCEINSERTION);
689if ( referenceinsertion != null )
690 {
691for ( int i=0; i < referenceinsertion.length; i++ )
692 {
693EventHandler ev = initializeSpecificEventHandler(referenceinsertion[i],RuntimeConstants.EVENTHANDLER_REFERENCEINSERTION,ReferenceInsertionEventHandler.class);
694if (ev != null)
695 eventCartridge.addReferenceInsertionEventHandler((ReferenceInsertionEventHandler) ev);
696 }
697 }
698699 String[] nullset = configuration.getStringArray(RuntimeConstants.EVENTHANDLER_NULLSET);
700if ( nullset != null )
701 {
702for ( int i=0; i < nullset.length; i++ )
703 {
704EventHandler ev = initializeSpecificEventHandler(nullset[i],RuntimeConstants.EVENTHANDLER_NULLSET,NullSetEventHandler.class);
705if (ev != null)
706 eventCartridge.addNullSetEventHandler((NullSetEventHandler) ev);
707 }
708 }
709710 String[] methodexception = configuration.getStringArray(RuntimeConstants.EVENTHANDLER_METHODEXCEPTION);
711if ( methodexception != null )
712 {
713for ( int i=0; i < methodexception.length; i++ )
714 {
715EventHandler ev = initializeSpecificEventHandler(methodexception[i],RuntimeConstants.EVENTHANDLER_METHODEXCEPTION,MethodExceptionEventHandler.class);
716if (ev != null)
717 eventCartridge.addMethodExceptionHandler((MethodExceptionEventHandler) ev);
718 }
719 }
720721 String[] includeHandler = configuration.getStringArray(RuntimeConstants.EVENTHANDLER_INCLUDE);
722if ( includeHandler != null )
723 {
724for ( int i=0; i < includeHandler.length; i++ )
725 {
726EventHandler ev = initializeSpecificEventHandler(includeHandler[i],RuntimeConstants.EVENTHANDLER_INCLUDE,IncludeEventHandler.class);
727if (ev != null)
728 eventCartridge.addIncludeEventHandler((IncludeEventHandler) ev);
729 }
730 }
731732 String[] invalidReferenceSet = configuration.getStringArray(RuntimeConstants.EVENTHANDLER_INVALIDREFERENCES);
733if ( invalidReferenceSet != null )
734 {
735for ( int i=0; i < invalidReferenceSet.length; i++ )
736 {
737EventHandler ev = initializeSpecificEventHandler(invalidReferenceSet[i],RuntimeConstants.EVENTHANDLER_INVALIDREFERENCES,InvalidReferenceEventHandler.class);
738if (ev != null)
739 {
740 eventCartridge.addInvalidReferenceEventHandler((InvalidReferenceEventHandler) ev);
741 }
742 }
743 }
744745746 }
747748privateEventHandler initializeSpecificEventHandler(String classname, String paramName, Class EventHandlerInterface)
749throws Exception
750 {
751if ( classname != null && classname.length() > 0)
752 {
753 Object o = null;
754try {
755 o = ClassUtils.getNewInstance(classname);
756 }
757catch (ClassNotFoundException cnfe )
758 {
759 String err = "The specified class for "760 + paramName + " (" + classname
761 + ") does not exist or is not accessible to the current classloader.";
762 log.error(err);
763thrownew Exception(err);
764 }
765766if (!EventHandlerInterface.isAssignableFrom(EventHandlerInterface))
767 {
768 String err = "The specified class for " + paramName + " ("769 + classname + ") does not implement "770 + EventHandlerInterface.getName()
771 + "; Velocity is not initialized correctly.";
772773 log.error(err);
774thrownew Exception(err);
775 }
776777EventHandler ev = (EventHandler) o;
778if ( ev instanceof RuntimeServicesAware )
779 ((RuntimeServicesAware) ev).setRuntimeServices(this);
780return ev;
781782 } else783returnnull;
784 }
785786/**787 * Initialize the Velocity logging system.788 *789 * @throws Exception790 */791privatevoid initializeLog() throws Exception
792 {
793// since the Log we started with was just placeholding,794// let's update it with the real LogChute settings.795 LogManager.updateLog(this.log, this);
796 }
797798799/**800 * This methods initializes all the directives801 * that are used by the Velocity Runtime. The802 * directives to be initialized are listed in803 * the RUNTIME_DEFAULT_DIRECTIVES properties804 * file.805 *806 * @throws Exception807 */808privatevoid initializeDirectives()
809throws Exception
810 {
811/*812 * Initialize the runtime directive table.813 * This will be used for creating parsers.814 */815 runtimeDirectives = new Hashtable();
816817 Properties directiveProperties = new Properties();
818819/*820 * Grab the properties file with the list of directives821 * that we should initialize.822 */823824 InputStream inputStream = null;
825826try827 {
828 inputStream = getClass().getResourceAsStream('/' + DEFAULT_RUNTIME_DIRECTIVES);
829830if (inputStream == null)
831 {
832thrownew Exception("Error loading directive.properties! " +
833"Something is very wrong if these properties " +
834"aren't being located. Either your Velocity " +
835"distribution is incomplete or your Velocity " +
836"jar file is corrupted!");
837 }
838839 directiveProperties.load(inputStream);
840841 }
842catch (IOException ioe)
843 {
844 String msg = "Error while loading directive properties!";
845 log.error(msg, ioe);
846thrownew RuntimeException(msg, ioe);
847 }
848finally849 {
850try851 {
852if (inputStream != null)
853 {
854 inputStream.close();
855 }
856 }
857catch (IOException ioe)
858 {
859 String msg = "Cannot close directive properties!";
860 log.error(msg, ioe);
861thrownew RuntimeException(msg, ioe);
862 }
863 }
864865866/*867 * Grab all the values of the properties. These868 * are all class names for example:869 *870 * org.apache.velocity.runtime.directive.Foreach871 */872 Enumeration directiveClasses = directiveProperties.elements();
873874while (directiveClasses.hasMoreElements())
875 {
876 String directiveClass = (String) directiveClasses.nextElement();
877 loadDirective(directiveClass);
878 log.debug("Loaded System Directive: " + directiveClass);
879 }
880881/*882 * now the user's directives883 */884885 String[] userdirective = configuration.getStringArray("userdirective");
886887for( int i = 0; i < userdirective.length; i++)
888 {
889 loadDirective(userdirective[i]);
890if (log.isDebugEnabled())
891 {
892 log.debug("Loaded User Directive: " + userdirective[i]);
893 }
894 }
895896 }
897898/**899 * Programatically add a directive.900 * @param directive901 */902publicvoid addDirective(Directive directive)
903 {
904 runtimeDirectives.put(directive.getName(), directive);
905 }
906907/**908 * Retrieve a previously instantiated directive.909 * @param name name of the directive910 * @return the {@link Directive} for that name911 */912publicDirective getDirective(String name)
913 {
914return (Directive) runtimeDirectives.get(name);
915 }
916917/**918 * Remove a directive.919 * @param name name of the directive.920 */921publicvoid removeDirective(String name)
922 {
923 runtimeDirectives.remove(name);
924 }
925926/**927 * instantiates and loads the directive with some basic checks928 *929 * @param directiveClass classname of directive to load930 */931privatevoid loadDirective(String directiveClass)
932 {
933try934 {
935 Object o = ClassUtils.getNewInstance( directiveClass );
936937if (o instanceof Directive)
938 {
939Directive directive = (Directive) o;
940 addDirective(directive);
941 }
942else943 {
944 String msg = directiveClass + " does not implement "945 + Directive.class.getName() + "; it cannot be loaded.";
946 log.error(msg);
947thrownewVelocityException(msg);
948 }
949 }
950// The ugly threesome: ClassNotFoundException,951// IllegalAccessException, InstantiationException.952// Ignore Findbugs complaint for now.953catch (Exception e)
954 {
955 String msg = "Failed to load Directive: " + directiveClass;
956 log.error(msg, e);
957thrownewVelocityException(msg, e);
958 }
959 }
960961962/**963 * Initializes the Velocity parser pool.964 */965privatevoid initializeParserPool() throws Exception
966 {
967/*968 * Which parser pool?969 */970 String pp = getString(RuntimeConstants.PARSER_POOL_CLASS);
971972if (pp != null && pp.length() > 0)
973 {
974/*975 * if something was specified, then make one.976 * if that isn't a ParserPool, consider977 * this a huge error and throw978 */979980 Object o = null;
981982try983 {
984 o = ClassUtils.getNewInstance( pp );
985 }
986catch (ClassNotFoundException cnfe )
987 {
988 String err = "The specified class for ParserPool ("989 + pp
990 + ") does not exist (or is not accessible to the current classloader.";
991 log.error(err);
992thrownew Exception(err);
993 }
994995if (!(o instanceof ParserPool))
996 {
997 String err = "The specified class for ParserPool ("998 + pp + ") does not implement " + ParserPool.class999 + " Velocity not initialized correctly.";
10001001 log.error(err);
1002thrownew Exception(err);
1003 }
10041005 parserPool = (ParserPool) o;
10061007 parserPool.initialize(this);
1008 }
1009else1010 {
1011/*1012 * someone screwed up. Lets not fool around...1013 */10141015 String err = "It appears that no class was specified as the"1016 + " ParserPool. Please ensure that all configuration"1017 + " information is correct.";
10181019 log.error(err);
1020thrownew Exception( err );
1021 }
10221023 }
10241025/**1026 * Returns a JavaCC generated Parser.1027 *1028 * @return Parser javacc generated parser1029 */1030publicParser createNewParser()
1031 {
1032 requireInitialization();
10331034Parser parser = newParser(this);
1035 parser.setDirectives(runtimeDirectives);
1036return parser;
1037 }
10381039/**1040 * Parse the input and return the root of1041 * AST node structure.1042 * <br><br>1043 * In the event that it runs out of parsers in the1044 * pool, it will create and let them be GC'd1045 * dynamically, logging that it has to do that. This1046 * is considered an exceptional condition. It is1047 * expected that the user will set the1048 * PARSER_POOL_SIZE property appropriately for their1049 * application. We will revisit this.1050 *1051 * @param string String to be parsed1052 * @param templateName name of the template being parsed1053 * @return A root node representing the template as an AST tree.1054 * @throws ParseException When the string could not be parsed as a template.1055 * @since 1.61056 */1057publicSimpleNode parse(String string, String templateName)
1058throwsParseException1059 {
1060return parse(new StringReader(string), templateName);
1061 }
10621063/**1064 * Parse the input and return the root of1065 * AST node structure.1066 * <br><br>1067 * In the event that it runs out of parsers in the1068 * pool, it will create and let them be GC'd1069 * dynamically, logging that it has to do that. This1070 * is considered an exceptional condition. It is1071 * expected that the user will set the1072 * PARSER_POOL_SIZE property appropriately for their1073 * application. We will revisit this.1074 *1075 * @param reader Reader retrieved by a resource loader1076 * @param templateName name of the template being parsed1077 * @return A root node representing the template as an AST tree.1078 * @throws ParseException When the template could not be parsed.1079 */1080publicSimpleNode parse(Reader reader, String templateName)
1081throwsParseException1082 {
1083/*1084 * do it and dump the VM namespace for this template1085 */1086return parse(reader, templateName, true);
1087 }
10881089/**1090 * Parse the input and return the root of the AST node structure.1091 *1092 * @param reader Reader retrieved by a resource loader1093 * @param templateName name of the template being parsed1094 * @param dumpNamespace flag to dump the Velocimacro namespace for this template1095 * @return A root node representing the template as an AST tree.1096 * @throws ParseException When the template could not be parsed.1097 */1098publicSimpleNode parse(Reader reader, String templateName, boolean dumpNamespace)
1099throwsParseException1100 {
1101 requireInitialization();
11021103Parser parser = (Parser) parserPool.get();
1104boolean keepParser = true;
1105if (parser == null)
1106 {
1107/*1108 * if we couldn't get a parser from the pool make one and log it.1109 */1110if (log.isInfoEnabled())
1111 {
1112 log.info("Runtime : ran out of parsers. Creating a new one. "1113 + " Please increment the parser.pool.size property."1114 + " The current value is too small.");
1115 }
1116 parser = createNewParser();
1117 keepParser = false;
1118 }
11191120try1121 {
1122/*1123 * dump namespace if we are told to. Generally, you want to1124 * do this - you don't in special circumstances, such as1125 * when a VM is getting init()-ed & parsed1126 */1127if (dumpNamespace)
1128 {
1129 dumpVMNamespace(templateName);
1130 }
1131return parser.parse(reader, templateName);
1132 }
1133finally1134 {
1135if (keepParser)
1136 {
1137 parserPool.put(parser);
1138 }
11391140 }
1141 }
11421143/**1144 * Renders the input string using the context into the output writer.1145 * To be used when a template is dynamically constructed, or want to use1146 * Velocity as a token replacer.1147 *1148 * @param context context to use in rendering input string1149 * @param out Writer in which to render the output1150 * @param logTag string to be used as the template name for log1151 * messages in case of error1152 * @param instring input string containing the VTL to be rendered1153 *1154 * @return true if successful, false otherwise. If false, see1155 * Velocity runtime log1156 * @throws ParseErrorException The template could not be parsed.1157 * @throws MethodInvocationException A method on a context object could not be invoked.1158 * @throws ResourceNotFoundException A referenced resource could not be loaded.1159 * @throws IOException While rendering to the writer, an I/O problem occured.1160 * @since Velocity 1.61161 */1162publicboolean evaluate(Context context, Writer out,
1163 String logTag, String instring) throws IOException
1164 {
1165return evaluate(context, out, logTag, new StringReader(instring));
1166 }
11671168/**1169 * Renders the input reader using the context into the output writer.1170 * To be used when a template is dynamically constructed, or want to1171 * use Velocity as a token replacer.1172 *1173 * @param context context to use in rendering input string1174 * @param writer Writer in which to render the output1175 * @param logTag string to be used as the template name for log messages1176 * in case of error1177 * @param reader Reader containing the VTL to be rendered1178 *1179 * @return true if successful, false otherwise. If false, see1180 * Velocity runtime log1181 * @throws ParseErrorException The template could not be parsed.1182 * @throws MethodInvocationException A method on a context object could not be invoked.1183 * @throws ResourceNotFoundException A referenced resource could not be loaded.1184 * @throws IOException While reading from the reader or rendering to the writer,1185 * an I/O problem occured.1186 * @since Velocity 1.61187 */1188publicboolean evaluate(Context context, Writer writer,
1189 String logTag, Reader reader) throws IOException
1190 {
1191if (logTag == null)
1192 {
1193thrownew NullPointerException("logTag (i.e. template name) cannot be null, you must provide an identifier for the content being evaluated");
1194 }
11951196SimpleNode nodeTree = null;
1197try1198 {
1199 nodeTree = parse(reader, logTag);
1200 }
1201catch (ParseException pex)
1202 {
1203thrownewParseErrorException(pex);
1204 }
1205catch (TemplateInitException pex)
1206 {
1207thrownewParseErrorException(pex);
1208 }
12091210if (nodeTree == null)
1211 {
1212return false;
1213 }
1214else1215 {
1216return render(context, writer, logTag, nodeTree);
1217 }
1218 }
121912201221/**1222 * Initializes and renders the AST {@link SimpleNode} using the context1223 * into the output writer.1224 *1225 * @param context context to use in rendering input string1226 * @param writer Writer in which to render the output1227 * @param logTag string to be used as the template name for log messages1228 * in case of error1229 * @param nodeTree SimpleNode which is the root of the AST to be rendered1230 *1231 * @return true if successful, false otherwise. If false, see1232 * Velocity runtime log for errors1233 * @throws ParseErrorException The template could not be parsed.1234 * @throws MethodInvocationException A method on a context object could not be invoked.1235 * @throws ResourceNotFoundException A referenced resource could not be loaded.1236 * @throws IOException While rendering to the writer, an I/O problem occured.1237 * @since Velocity 1.61238 */1239publicboolean render(Context context, Writer writer,
1240 String logTag, SimpleNode nodeTree) throws IOException
1241 {
1242/*1243 * we want to init then render1244 */1245InternalContextAdapterImpl ica =
1246newInternalContextAdapterImpl(context);
12471248 ica.pushCurrentTemplateName(logTag);
12491250try1251 {
1252try1253 {
1254 nodeTree.init(ica, this);
1255 }
1256catch (TemplateInitException pex)
1257 {
1258thrownewParseErrorException(pex);
1259 }
1260/**1261 * pass through application level runtime exceptions1262 */1263catch(RuntimeException e)
1264 {
1265throw e;
1266 }
1267catch(Exception e)
1268 {
1269 String msg = "RuntimeInstance.render(): init exception for tag = "+logTag;
1270 getLog().error(msg, e);
1271thrownewVelocityException(msg, e);
1272 }
12731274/*1275 * now render, and let any exceptions fly1276 */1277 nodeTree.render(ica, writer);
1278 }
1279finally1280 {
1281 ica.popCurrentTemplateName();
1282 }
12831284returntrue;
1285 }
12861287/**1288 * Invokes a currently registered Velocimacro with the params provided1289 * and places the rendered stream into the writer.1290 * <br>1291 * Note : currently only accepts args to the VM if they are in the context.1292 *1293 * @param vmName name of Velocimacro to call1294 * @param logTag string to be used for template name in case of error. if null,1295 * the vmName will be used1296 * @param params keys for args used to invoke Velocimacro, in java format1297 * rather than VTL (eg "foo" or "bar" rather than "$foo" or "$bar")1298 * @param context Context object containing data/objects used for rendering.1299 * @param writer Writer for output stream1300 * @return true if Velocimacro exists and successfully invoked, false otherwise.1301 * @throws IOException While rendering to the writer, an I/O problem occured.1302 * @since 1.61303 */1304publicboolean invokeVelocimacro(final String vmName, String logTag,
1305 String[] params, finalContext context,
1306final Writer writer)
1307throws IOException
1308 {
1309/* check necessary parameters */1310if (vmName == null || context == null || writer == null)
1311 {
1312 String msg = "RuntimeInstance.invokeVelocimacro() : invalid call : vmName, context, and writer must not be null";
1313 getLog().error(msg);
1314thrownew NullPointerException(msg);
1315 }
13161317/* handle easily corrected parameters */1318if (logTag == null)
1319 {
1320 logTag = vmName;
1321 }
1322if (params == null)
1323 {
1324 params = new String[0];
1325 }
13261327/* does the VM exist? */1328if (!isVelocimacro(vmName, logTag))
1329 {
1330 String msg = "RuntimeInstance.invokeVelocimacro() : VM '" + vmName
1331 + "' is not registered.";
1332 getLog().error(msg);
1333thrownewVelocityException(msg);
1334 }
13351336/* now just create the VM call, and use evaluate */1337 StrBuilder template = new StrBuilder("#");
1338 template.append(vmName);
1339 template.append("(");
1340for( int i = 0; i < params.length; i++)
1341 {
1342 template.append(" $");
1343 template.append(params[i]);
1344 }
1345 template.append(" )");
13461347return evaluate(context, writer, logTag, template.toString());
1348 }
13491350/**1351 * Retrieves and caches the configured default encoding1352 * for better performance. (VELOCITY-606)1353 */1354private String getDefaultEncoding()
1355 {
1356if (encoding == null)
1357 {
1358 encoding = getString(INPUT_ENCODING, ENCODING_DEFAULT);
1359 }
1360return encoding;
1361 }
13621363/**1364 * Returns a <code>Template</code> from the resource manager.1365 * This method assumes that the character encoding of the1366 * template is set by the <code>input.encoding</code>1367 * property. The default is "ISO-8859-1"1368 *1369 * @param name The file name of the desired template.1370 * @return The template.1371 * @throws ResourceNotFoundException if template not found1372 * from any available source.1373 * @throws ParseErrorException if template cannot be parsed due1374 * to syntax (or other) error.1375 * @throws Exception if an error occurs in template initialization1376 */1377publicTemplate getTemplate(String name)
1378throws ResourceNotFoundException, ParseErrorException, Exception
1379 {
1380return getTemplate(name, getDefaultEncoding());
1381 }
13821383/**1384 * Returns a <code>Template</code> from the resource manager1385 *1386 * @param name The name of the desired template.1387 * @param encoding Character encoding of the template1388 * @return The template.1389 * @throws ResourceNotFoundException if template not found1390 * from any available source.1391 * @throws ParseErrorException if template cannot be parsed due1392 * to syntax (or other) error.1393 * @throws Exception if an error occurs in template initialization1394 */1395publicTemplate getTemplate(String name, String encoding)
1396throws ResourceNotFoundException, ParseErrorException, Exception
1397 {
1398 requireInitialization();
13991400return (Template)
1401 resourceManager.getResource(name,
1402 ResourceManager.RESOURCE_TEMPLATE, encoding);
1403 }
14041405/**1406 * Returns a static content resource from the1407 * resource manager. Uses the current value1408 * if INPUT_ENCODING as the character encoding.1409 *1410 * @param name Name of content resource to get1411 * @return parsed ContentResource object ready for use1412 * @throws ResourceNotFoundException if template not found1413 * from any available source.1414 * @throws ParseErrorException When the template could not be parsed.1415 * @throws Exception Any other error.1416 */1417publicContentResource getContent(String name)
1418throws ResourceNotFoundException, ParseErrorException, Exception
1419 {
1420/*1421 * the encoding is irrelvant as we don't do any converstion1422 * the bytestream should be dumped to the output stream1423 */14241425return getContent(name, getDefaultEncoding());
1426 }
14271428/**1429 * Returns a static content resource from the1430 * resource manager.1431 *1432 * @param name Name of content resource to get1433 * @param encoding Character encoding to use1434 * @return parsed ContentResource object ready for use1435 * @throws ResourceNotFoundException if template not found1436 * from any available source.1437 * @throws ParseErrorException When the template could not be parsed.1438 * @throws Exception Any other error.1439 */1440publicContentResource getContent(String name, String encoding)
1441throws ResourceNotFoundException, ParseErrorException, Exception
1442 {
1443 requireInitialization();
14441445return (ContentResource)
1446 resourceManager.getResource(name,
1447 ResourceManager.RESOURCE_CONTENT, encoding);
1448 }
144914501451/**1452 * Determines if a template exists and returns name of the loader that1453 * provides it. This is a slightly less hokey way to support1454 * the Velocity.resourceExists() utility method, which was broken1455 * when per-template encoding was introduced. We can revisit this.1456 *1457 * @param resourceName Name of template or content resource1458 * @return class name of loader than can provide it1459 */1460public String getLoaderNameForResource(String resourceName)
1461 {
1462 requireInitialization();
14631464return resourceManager.getLoaderNameForResource(resourceName);
1465 }
14661467/**1468 * Returns a convenient Log instance that wraps the current LogChute.1469 * Use this to log error messages. It has the usual methods.1470 *1471 * @return A convenience Log instance that wraps the current LogChute.1472 * @since 1.51473 */1474publicLog getLog()
1475 {
1476return log;
1477 }
14781479/**1480 * @deprecated Use getLog() and call warn() on it.1481 * @see Log#warn(Object)1482 * @param message The message to log.1483 */1484publicvoid warn(Object message)
1485 {
1486 getLog().warn(message);
1487 }
14881489/**1490 * @deprecated Use getLog() and call info() on it.1491 * @see Log#info(Object)1492 * @param message The message to log.1493 */1494publicvoid info(Object message)
1495 {
1496 getLog().info(message);
1497 }
14981499/**1500 * @deprecated Use getLog() and call error() on it.1501 * @see Log#error(Object)1502 * @param message The message to log.1503 */1504publicvoid error(Object message)
1505 {
1506 getLog().error(message);
1507 }
15081509/**1510 * @deprecated Use getLog() and call debug() on it.1511 * @see Log#debug(Object)1512 * @param message The message to log.1513 */1514publicvoid debug(Object message)
1515 {
1516 getLog().debug(message);
1517 }
15181519/**1520 * String property accessor method with default to hide the1521 * configuration implementation.1522 *1523 * @param key property key1524 * @param defaultValue default value to return if key not1525 * found in resource manager.1526 * @return value of key or default1527 */1528public String getString( String key, String defaultValue)
1529 {
1530return configuration.getString(key, defaultValue);
1531 }
15321533/**1534 * Returns the appropriate VelocimacroProxy object if vmName1535 * is a valid current Velocimacro.1536 *1537 * @param vmName Name of velocimacro requested1538 * @param templateName Name of the template that contains the velocimacro.1539 * @return The requested VelocimacroProxy.1540 * @since 1.61541 */1542publicDirective getVelocimacro(String vmName, String templateName)
1543 {
1544return vmFactory.getVelocimacro( vmName, templateName );
1545 }
15461547/**1548 * Returns the appropriate VelocimacroProxy object if vmName1549 * is a valid current Velocimacro.1550 *1551 * @param vmName Name of velocimacro requested1552 * @param templateName Name of the namespace.1553 * @param renderingTemplate Name of the template we are currently rendering. This1554 * information is needed when VM_PERM_ALLOW_INLINE_REPLACE_GLOBAL setting is true1555 * and template contains a macro with the same name as the global macro library.1556 * 1557 * @since Velocity 1.61558 * 1559 * @return VelocimacroProxy1560 */1561publicDirective getVelocimacro(String vmName, String templateName, String renderingTemplate)
1562 {
1563return vmFactory.getVelocimacro( vmName, templateName, renderingTemplate );
1564 }
156515661567/**1568 * Adds a new Velocimacro. Usually called by Macro only while parsing.1569 *1570 * @param name Name of velocimacro1571 * @param macro String form of macro body1572 * @param argArray Array of strings, containing the1573 * #macro() arguments. the 0th is the name.1574 * @param sourceTemplate Name of the template that contains the velocimacro.1575 * 1576 * @deprecated Use addVelocimacro(String, Node, String[], String) instead1577 * 1578 * @return True if added, false if rejected for some1579 * reason (either parameters or permission settings)1580 */1581publicboolean addVelocimacro( String name,
1582 String macro,
1583 String argArray[],
1584 String sourceTemplate )
1585 {
1586return vmFactory.addVelocimacro(name, macro, argArray, sourceTemplate);
1587 }
15881589/**1590 * Adds a new Velocimacro. Usually called by Macro only while parsing.1591 * 1592 * Called by org.apache.velocity.runtime.directive.processAndRegister1593 *1594 * @param name Name of velocimacro1595 * @param macro root AST node of the parsed macro1596 * @param argArray Array of strings, containing the1597 * #macro() arguments. the 0th is the name.1598 * @param sourceTemplate1599 * 1600 * @since Velocity 1.61601 * 1602 * @return boolean True if added, false if rejected for some1603 * reason (either parameters or permission settings)1604 */1605publicboolean addVelocimacro( String name,
1606Node macro,
1607 String argArray[],
1608 String sourceTemplate )
1609 {
1610return vmFactory.addVelocimacro(name, macro, argArray, sourceTemplate);
1611 }
161216131614/**1615 * Checks to see if a VM exists1616 *1617 * @param vmName Name of the Velocimacro.1618 * @param templateName Template on which to look for the Macro.1619 * @return True if VM by that name exists, false if not1620 */1621publicboolean isVelocimacro( String vmName, String templateName )
1622 {
1623return vmFactory.isVelocimacro(vmName, templateName);
1624 }
16251626/**1627 * tells the vmFactory to dump the specified namespace. This is to support1628 * clearing the VM list when in inline-VM-local-scope mode1629 * @param namespace Namespace to dump.1630 * @return True if namespace was dumped successfully.1631 */1632publicboolean dumpVMNamespace(String namespace)
1633 {
1634return vmFactory.dumpVMNamespace( namespace );
1635 }
16361637/* --------------------------------------------------------------------1638 * R U N T I M E A C C E S S O R M E T H O D S1639 * --------------------------------------------------------------------1640 * These are the getXXX() methods that are a simple wrapper1641 * around the configuration object. This is an attempt1642 * to make a the Velocity Runtime the single access point1643 * for all things Velocity, and allow the Runtime to1644 * adhere as closely as possible the the Mediator pattern1645 * which is the ultimate goal.1646 * --------------------------------------------------------------------1647 */16481649/**1650 * String property accessor method to hide the configuration implementation1651 * @param key property key1652 * @return value of key or null1653 */1654public String getString(String key)
1655 {
1656return StringUtils.nullTrim(configuration.getString(key));
1657 }
16581659/**1660 * Int property accessor method to hide the configuration implementation.1661 *1662 * @param key Property key1663 * @return value1664 */1665publicint getInt(String key)
1666 {
1667return configuration.getInt(key);
1668 }
16691670/**1671 * Int property accessor method to hide the configuration implementation.1672 *1673 * @param key property key1674 * @param defaultValue The default value.1675 * @return value1676 */1677publicint getInt(String key, int defaultValue)
1678 {
1679return configuration.getInt(key, defaultValue);
1680 }
16811682/**1683 * Boolean property accessor method to hide the configuration implementation.1684 *1685 * @param key property key1686 * @param def The default value if property not found.1687 * @return value of key or default value1688 */1689publicboolean getBoolean(String key, boolean def)
1690 {
1691return configuration.getBoolean(key, def);
1692 }
16931694/**1695 * Return the velocity runtime configuration object.1696 *1697 * @return Configuration object which houses the Velocity runtime1698 * properties.1699 */1700public ExtendedProperties getConfiguration()
1701 {
1702return configuration;
1703 }
17041705/**1706 * Return the Introspector for this instance1707 * @return The Introspector for this instance1708 */1709publicIntrospector getIntrospector()
1710 {
1711return introspector;
1712 }
17131714/**1715 * Returns the event handlers for the application.1716 * @return The event handlers for the application.1717 * @since 1.51718 */1719publicEventCartridge getApplicationEventCartridge()
1720 {
1721return eventCartridge;
1722 }
172317241725/**1726 * Gets the application attribute for the given key1727 *1728 * @param key1729 * @return The application attribute for the given key.1730 */1731public Object getApplicationAttribute(Object key)
1732 {
1733return applicationAttributes.get(key);
1734 }
17351736/**1737 * Sets the application attribute for the given key1738 *1739 * @param key1740 * @param o The new application attribute.1741 * @return The old value of this attribute or null if it hasn't been set before.1742 */1743public Object setApplicationAttribute(Object key, Object o)
1744 {
1745return applicationAttributes.put(key, o);
1746 }
17471748/**1749 * Returns the Uberspect object for this Instance.1750 *1751 * @return The Uberspect object for this Instance.1752 */1753publicUberspect getUberspect()
1754 {
1755return uberSpect;
1756 }
17571758 }