Modified: velocity/site/production/engine/devel/developer-guide.html URL: http://svn.apache.org/viewvc/velocity/site/production/engine/devel/developer-guide.html?rev=1753524&r1=1753523&r2=1753524&view=diff ============================================================================== --- velocity/site/production/engine/devel/developer-guide.html (original) +++ velocity/site/production/engine/devel/developer-guide.html Wed Jul 20 14:44:53 2016 @@ -170,6 +170,7 @@ h2:hover > .headerlink, h3:hover > .head <li><a href="user-guide.html">User Guide</a></li> <li><a href="developer-guide.html">Developer Guide</a></li> <li><a href="vtl-reference.html">VTL Reference</a></li> +<li><a href="configuration.html">Configuration</a></li> <li><a href="glossary.html">Glossary</a></li> <li><a href="apidocs/index.html">Javadoc</a></li> </ul> @@ -257,8 +258,10 @@ h2:hover > .headerlink, h3:hover > .head <li><a href="#miscellaneous-details">Miscellaneous Details</a></li> </ul> </li> +<li><a href="#logging">Logging</a></li> +<li><a href="#resource-loaders">Resource Loaders</a></li> <li><a href="#application-attributes">Application Attributes</a></li> -<li><a href="#configuring-event-handlers">Configuring Event Handlers</a><ul> +<li><a href="#event-handlers">Event Handlers</a><ul> <li><a href="#orgapachevelocityappeventincludeeventhandler">org.apache.velocity.app.event.IncludeEventHandler</a></li> <li><a href="#orgapachevelocityappeventinvalidreferenceeventhandler">org.apache.velocity.app.event.InvalidReferenceEventHandler</a></li> <li><a href="#orgapachevelocityappeventmethodexceptioneventhandler">org.apache.velocity.app.event.MethodExceptionEventHandler</a></li> @@ -267,30 +270,9 @@ h2:hover > .headerlink, h3:hover > .head <li><a href="#registering-event-handlers">Registering Event Handlers</a></li> </ul> </li> -<li><a href="#velocity-configuration-keys-and-values">Velocity Configuration Keys and Values</a><ul> -<li><a href="#runtime-log">Runtime Log</a></li> -<li><a href="#character-encoding">Character Encoding</a></li> -<li><a href="#define-directive">#define() Directive</a></li> -<li><a href="#evaluate-directive">#evaluate() Directive</a></li> -<li><a href="#foreach-directive">#foreach() Directive</a></li> -<li><a href="#if-directive">#if() Directive</a></li> -<li><a href="#set-directive">#set() Directive</a></li> -<li><a href="#include-and-parse-directives">#include() and #parse() Directives</a></li> -<li><a href="#resource-management">Resource Management</a></li> -<li><a href="#velocimacro">Velocimacro</a></li> -<li><a href="#strict-reference-setting">Strict Reference Setting</a></li> -<li><a href="#string-interpolation">String Interpolation</a></li> -<li><a href="#math">Math</a></li> -<li><a href="#parser-configuration">Parser Configuration</a></li> -<li><a href="#pluggable-introspection">Pluggable Introspection</a></li> -<li><a href="#context">Context</a></li> -</ul> -</li> -<li><a href="#configuring-logging">Configuring Logging</a></li> -<li><a href="#configuring-resource-loaders">Configuring Resource Loaders</a><ul> -<li><a href="#resource-loaders">Resource Loaders</a></li> -<li><a href="#configuration-examples">Configuration Examples</a></li> -<li><a href="#pluggable-resource-manager-and-resource-cache">Pluggable Resource Manager and Resource Cache</a></li> +<li><a href="#customizing-introspection">Customizing Introspection</a><ul> +<li><a href="#standard-uberspectors">Standard Uberspectors</a></li> +<li><a href="#uberspectors-providing-extra-features">Uberspectors providing extra features</a></li> </ul> </li> <li><a href="#template-encoding-for-internationalization">Template Encoding for Internationalization</a></li> @@ -313,11 +295,11 @@ h2:hover > .headerlink, h3:hover > .head <p>Instructions for building Velocity from source can be found in the <a href="build.html">Build</a> document.</p> <h3 id="dependencies">Dependencies<a class="headerlink" href="#dependencies" title="Permanent link">¶</a></h3> -<p>For compiling or at runtime, Velocity needs a Java runtime environment version of 1.5 or more recent.</p> -<p>Velocity also is dependent upon a few packages for general functionality:</p> +<p>For compiling or at runtime, Velocity needs a Java runtime environment version of 1.7 or more recent.</p> +<p>Velocity also depends upon a few packages for general functionality:</p> <ul> -<li><a href="https://commons.apache.org/proper/commons-collections/";><strong>Apache Commons Collections</strong></a> - required for compilation.</li> -<li><a href="http://commons.apache.org/proper/commons-lang/";><strong>Apache Commons Lang</strong></a> - required for compilation.</li> +<li><a href="https://commons.apache.org/proper/commons-collections/";><strong>Apache Commons Collections</strong></a> - required for compilation only.</li> +<li><a href="http://commons.apache.org/proper/commons-lang/";><strong>Apache Commons Lang</strong></a> - required for compilation only.</li> <li><a href="http://www.slf4j.org";><strong> SLF4J API</strong></a> - required for compilation and at runtime.</li> </ul> <p>At runtime, Velocity will require an SLF4J binding to be present in the path. Typically, one of:</p> @@ -486,7 +468,7 @@ public Object get(String key); + <code>java.util.Map</code> Here, Velocity depends upon the <code>values()</code> method of the interface to get a <code>Collection</code> interface, on which <code>iterator()</code> is called to retrieve an Iterator for the loop. + <code>java.util.Iterator</code> USE WITH CAUTION: This is currently supported only provisionally - the issue of concern is the 'non-resettablity' of the Iterator. If a 'naked' Iterator is placed into the context, and used in more than one #foreach(), subsequent #foreach() blocks after the first will fail, as the Iterator doesn't reset. + <code>java.util.Enumeration</code> USE WITH CAUTION: Like <code>java.util.Iterator</code>, this is currently supported only provisionally - the issue of concern is the 'non-resettablity' of the Enumeration. If a 'naked' Enumeration is placed into the context, and used in more than one #foreach(), subsequent #foreach() blocks after the first will fail, as the Enumeration doesn't reset. -+ Any public class with a <code>public Iterator iterator()</code> method that never returns <code>null</code>. As a last resort, Velocity will look for an <code>iterator()</code> method. This provides great flexibility and automatic support for Java 1.5's <code>java.util.Iterable</code> interface.</p> ++ Any public class with a <code>public Iterator iterator()</code> method that never returns <code>null</code>. As a last resort, Velocity will look for an <code>iterator()</code> method. This provides great flexibility and automatic support for <code>java.util.Iterable</code> interface.</p> <p>In the case of the <code>Iterator</code> and <code>Enumeration</code>, it is recommended that they are placed in the context only when it cannot be avoided, and you should let Velocity find the appropriate reusable iterative interface when that is sufficient and possible.</p> <p>There are good reasons to use the <code>java.util.Iterator</code> interface directly (large data sets via JDBC, for example), but if it can be avoided, it might be better to use something else. By 'directly' , we meant doing something like:</p> <div class="codehilite"><pre>Vector v = new Vector(); @@ -572,7 +554,7 @@ template.merge( context2, writer ); <li>Reuse the Template object for the duration of the loop iterations. Then you won't be forcing Velocity, if the cache is turned off, to reread and reparse the same template over and over, so the VelocityContext won't gather new introspection information each time.</li> </ul> <h2 id="using-velocity">Using Velocity<a class="headerlink" href="#using-velocity" title="Permanent link">¶</a></h2> -<p>If you are using <a href="/tools/devel/view-servlet.html">VelocityViewServlet</a> or other web frameworks, you may never call Velocity directly. However, if you use Velocity for non-web purposes, or create your own web framework you will need to directly call the Velocity Engine similar to <a href="#thefundamentalpattern">the fundamental pattern</a> shown earlier. One important additional thing to remember is to initialize the Velocity Engine before using it to merge templates.</p> +<p>If you are using <a href="/tools/devel/view-servlet.html">VelocityViewServlet</a> or other web frameworks, you may never call Velocity directly. However, if you use Velocity for non-web purposes, or create your own web framework you will need to directly call the Velocity Engine similar to <a href="#the-fundamental-pattern">the fundamental pattern</a> shown earlier. One important additional thing to remember is to initialize the Velocity Engine before using it to merge templates.</p> <h3 id="the-velocity-helper-class">The Velocity Helper Class<a class="headerlink" href="#the-velocity-helper-class" title="Permanent link">¶</a></h3> <p>Velocity contains an application utility class called Velocity ( <code>org.apache.velocity.app.Velocity</code> ). The purpose of this class is to provide the necessary methods required to initialize Velocity, as well as useful utility routines to make life easier in using Velocity. This class is documented in the project's javadoc, so please look there for definitive details. This documentation is intended to be of a tutorial nature; therefore for compete API information, the Javadoc is the definitive source.</p> <p>The Velocity runtime engine is a singleton instance that provides resource, logging and other services to all Velocity users running in the same JVM. Therefore, the runtime engine is initialized only once. You can attempt to initialize Velocity more than once, but only the first initialization will apply. The rest of the attempts will be ignored. The Velocity utility class currently provides five methods used in configuration of the runtime engine.</p> @@ -727,15 +709,15 @@ see the Javadoc API documentation.</p> <p>And, assuming you have a directory <code>/opt/templates</code> and the template <code>testtemplate.vm</code> is in there, then things would work just fine. If you try this and have a problem, be sure to look at the velocity.log for information - the error messages are pretty good for figuring out what is wrong.</p> -<p>If you need to place objects into the Velocity properties then you cannot use the Velocity.init(Properties p) method. Instead you should create a new instance of the <code>org.apache.commons.collections.ExtendedProperties</code> class, copy all properties from an existing Properties object into the ExtendedProperties and then add new properties with your objects to the ExtendedProperties object.</p> +<p>If you need to place objects into the Velocity properties then you cannot use the Velocity.init(Properties p) method. Instead you should create a new instance of the <code>org.apache.velocity.util.ExtProperties</code> class, copy all properties from an existing Properties object into the ExtProperties and then add new properties with your objects to the ExtProperties object.</p> <div class="codehilite"><pre> ... VelocityEngine velocityEngine = new VelocityEngine(); -ExtendedProperties eprops = null; +ExtProperties eprops = null; if (props==null) { - eprops = new ExtendedProperties(); + eprops = new ExtProperties(); } else { - eprops = ExtendedProperties.convertProperties(props); + eprops = ExtProperties.convertProperties(props); } // Now set the property with your object instance @@ -749,6 +731,47 @@ velocityEngine.init(); <p>You may want to also consider using the Application Attributes feature described in the following section.</p> +<h2 id="logging">Logging<a class="headerlink" href="#logging" title="Permanent link">¶</a></h2> +<p>Since version 2.0, Velocity has switched to the <a href="http://www.slf4j.org/";>SLF4J</a> logging facade.</p> +<p>All you have to do to enable logging is to make sure that your classpath contains the slf4j-api jar, and one and only one slf4j binding jar towards your favourite logsystem or facade. See the <a href="#dependencies">dependecies</a> section for a list of SLF4J bindings.</p> +<p>By default, Velocity will use a logger tagged for the org.apache.velocity.app.Velocity class. You can customize this logger in two ways:</p> +<ul> +<li>By programmatically giving Velocity a living instance of an orf.slf4j.Logger object, using the runtime.log.instance property key.</li> +<li>By configuring the name of the logger to be used by your velocity instance, using the runtime.log.name property key. It can be done from the velocity.properties file, if present.</li> +</ul> +<h2 id="resource-loaders">Resource Loaders<a class="headerlink" href="#resource-loaders" title="Permanent link">¶</a></h2> +<p>One of the fundamental and important parts about Velocity is the resource management system and the resource loaders. They are referred to as 'resources' here rather than 'templates' because the resource management system will also handle non-template reasources, specifically things that are loaded via the #include() directive.</p> +<p>The resource loader system if very flexible, allowing one or more resource loaders to be in operation at the same time. This allows tremendous flexibility in configuration and resource managment, and futher allows you to write your own resource loaders for your special needs.</p> +<p>There are currently four kinds of resource loaders that are included with Velocity, each described below. Note that in the example configuration properties given, a common name for the loader is shown (ex.'file' in <code>file.resource.loader.path</code>). This 'common name' may not work for your configuration, as resource loaders common names are defined by the <code>resource.loader</code> configuration entry. Also, each of these loaders is located in the package <code>org.apache.velocity.runtime.resource.loader</code>.</p> +<ul> +<li> +<p><strong>FileResourceLoader :</strong> This loader gets resources from the filesystem. Its configuration properties include:</p> +<ul> +<li><code>file.resource.loader.path</code> = <path to root of templates></li> +<li><code>file.resource.loader.cache</code> = true/false</li> +<li><code>file.resource.loader.modificationCheckInterval</code> = <seconds between checks></li> +</ul> +<p>This is the default loader, and is configured, by default to get templates from the 'current directory'. In the case of using Velocity with servlets, this can be a problem as you don't want to have to keep your templates in the directory from which you start your servlet engine. See the documentation for your servlet or web framework (for example <a href="/tools/devel/view-servlet.html">VelocityViewServlet</a>) for more info on how to configure the location of the Velocity templates.</p> +</li> +<li> +<p><strong>JarResourceLoader :</strong> This loader gets resource from specific jar files. It is very similar to the FileResourceLoader, except that you have the convenience of bundling your templates into jars. The properties are identical, except for <code>jar.resource.loader.path</code>, where you provide the full location of the jar(s) you wish to load resources from. To specify a jar for the loader.path you use the standard JAR URL syntax of <code>java.net.JarURLConnection</code>.</p> +</li> +<li> +<p><strong>ClasspathResourceLoader :</strong> This loader gets resources from the classloader. In general, this means that the ClasspathResourceLoader will load templates placed in the classpath (in jars, for example) While the classpath is a source of great pain and suffering in general, it is a very useful mechanism when working on a Servlet Spec 2.2 (or newer) compliant servlet runner. <a href="http://jakarta.apache.org/tomcat/"; class="externalLink">Tomcat</a> is an example of such. To use this loader effectively, all you must do is jar your templates, and put that jar into the WEB-INF/lib directory of your webapp. There are no configuration options to worry about, nor is the absolute vs. relative path an issue, as it is with Jar and File resource loaders. Again, please note that the ClasspathResourceLoader is not only for use with a servlet container, but can be used in any application context.</p> +</li> +<li> +<p><strong>URLResourceLoader :</strong> This loader gets resources from a URL connection. Its configuration properties include:</p> +<ul> +<li><code>url.resource.loader.root</code> = <root URL path of templates></li> +<li><code>url.resource.loader.cache</code> = true/false</li> +<li><code>url.resource.loader.modificationCheckInterval</code> = <seconds between checks></li> +</ul> +<p>This loader simply downloads resources from configured URLs. It works much like the FileResourceLoader, however, it can pull templates down from any valid URL to which the application can create a connection.</p> +</li> +<li> +<p><strong>DataSourceResourceLoader :</strong> This loader will load resources from a DataSource such as a database. This loader is only available under JDK 1.4 and later. For more information on this loader, please see the javadoc for the class <code>org.apache.velocity.runtime.resource.loader.DataSourceResourceLoader</code>.</p> +</li> +</ul> <h2 id="application-attributes">Application Attributes<a class="headerlink" href="#application-attributes" title="Permanent link">¶</a></h2> <p><em>Application Attributes</em> are name-value pairs that can be associated with a RuntimeInstance (either via the <code>VelocityEngine</code> or the <code>Velocity</code> singleton) and accessed from any part of the Velocity engine that has access to the RuntimeInstance.</p> <p>This feature was designed for applications that need to communicate between the application layer and custom parts of the Velocity engine, such as loggers, resource loaders, resource managers, etc.</p> @@ -764,7 +787,7 @@ velocityEngine.init(); <p>Note that internal components cannot set the value of the key, just get it. if the internal component must communicate information to the application layer, it must do so via the Object passed as the value.</p> -<h2 id="configuring-event-handlers">Configuring Event Handlers<a class="headerlink" href="#configuring-event-handlers" title="Permanent link">¶</a></h2> +<h2 id="event-handlers">Event Handlers<a class="headerlink" href="#event-handlers" title="Permanent link">¶</a></h2> <p>Velocity contains a fine-grained event handling system that allows you to customize the operation of the engine. For example, you may change the text of references that are inserted into a page, modify which templates are actually included with <code>#include</code> or <code>#parse</code>, or capture all invalid references.</p> <p>All event handler interfaces available in Velocity are in the package <code>org.apache.velocity.app.event</code>. You may create your own implementation or use one of the sample implementations in the package <code>org.apache.velocity.app.event.implement</code>. (See the javadocs for more details on the provided implementations).</p> <h3 id="orgapachevelocityappeventincludeeventhandler"><code>org.apache.velocity.app.event.IncludeEventHandler</code><a class="headerlink" href="#orgapachevelocityappeventincludeeventhandler" title="Permanent link">¶</a></h3> @@ -926,347 +949,44 @@ eventhandler.escape.sql.match = /sql.*/ </pre></div> -<h2 id="velocity-configuration-keys-and-values">Velocity Configuration Keys and Values<a class="headerlink" href="#velocity-configuration-keys-and-values" title="Permanent link">¶</a></h2> -<p>Velocity's runtime configuration is controlled by a set of configuration keys listed below. Generally, these keys will have values that consist of either a String, or a comma-separated list of Strings, referred to as a CSV for comma-separated values.</p> -<p>There is a set of default values contained in Velocity's jar, found in /src/java/org/apache/velocity/runtime/defaults/velocity.defaults, that Velocity uses as its configuration baseline. This ensures that Velocity will always have a 'correct' value for its configuration keys at startup, although it may not be what you want.</p> -<p>Any values specified before init() time will replace the default values. Therefore, you only have toconfigure velocity with the values for the keys that you need to change, and not worry about the rest. Further, as we add more features and configuration capability, you don't have to change your configuration files to suit - the Velocity engine will always have default values.</p> -<p>Please sees the section above <a href="#Using-Velocity"><strong>Using Velocity</strong></a> for discussion on the configuration API.</p> -<p>Below are listed the configuration keys that control Velocity's behavior. Organized by category, each key is listed with its current default value to the right of the '=' sign.</p> -<h3 id="runtime-log">Runtime Log<a class="headerlink" href="#runtime-log" title="Permanent link">¶</a></h3> -<p><code>runtime.log.instance = *Java Object instance*</code></p> -<blockquote> -<p>Living Java instance, that must implement the interface org.slf4j.Logger. This property can only be set programmatically.</p> -</blockquote> -<p><code>runtime.log.name = *name*</code></p> -<blockquote> -<p>This property has no default value, since the default logger will be instanciated as the logger for the class org.apache.velocity.app.Velocity. See <a href="#configuring-Logging">Configuring Logging</a>.</p> -</blockquote> -<p><code>runtime.log.invalid.references = true</code></p> -<blockquote> -<p>Property to turn off the log output when a reference isn't valid. Good thing to turn off in production, but very valuable for debugging.</p> -</blockquote> -<p><code>runtime.log.logsystem.avalon.logger = *name*</code></p> -<blockquote> -<p>Allows user to specify an existing logger <em>name</em> in the Avalon hierarchy without having to wrap with a LogChute interface. <strong>Note:</strong> You must also specify <code>runtime.log.logsystem.class = org.apache.velocity.runtime.log.AvalonLogChute</code> as the default logsystem may change. There is <strong>no</strong> guarantee that the Avalon log system will remain the default log system.</p> -</blockquote> -<h3 id="character-encoding">Character Encoding<a class="headerlink" href="#character-encoding" title="Permanent link">¶</a></h3> -<p><code>input.encoding = UTF-8</code></p> -<blockquote> -<p>Character encoding for input (templates). If not specified, Velocity relies on the 'file.encoding' system property.</p> -</blockquote> -<h3 id="define-directive">#define() Directive<a class="headerlink" href="#define-directive" title="Permanent link">¶</a></h3> -<p><code>define.provide.scope.control = false</code></p> -<blockquote> -<p>Used to turn on the automatic provision of the $define scope control during #define() calls. The default is false. Set it to true if you want a local, managed namespace you can put references in when within a #define block or if you want it for more advanced #break usage.</p> -</blockquote> -<h3 id="evaluate-directive">#evaluate() Directive<a class="headerlink" href="#evaluate-directive" title="Permanent link">¶</a></h3> -<p><code>evaluate.provide.scope.control = false</code></p> -<blockquote> -<p>Used to turn on the automatic provision of the $evaluate scope during #evaluate() or Velocity[Engine].evaluate(...) calls. The default is false. Set it to true if you want a local, managed namespace you can put references in during an evaluation or if you want it for more advanced #break usage.</p> -</blockquote> -<h3 id="foreach-directive">#foreach() Directive<a class="headerlink" href="#foreach-directive" title="Permanent link">¶</a></h3> -<p><code>foreach.provide.scope.control = true</code></p> -<blockquote> -<p>Used to control the automatic provision of the $foreach scope during #foreach calls. This gives access to the foreach status information (e.g. $foreach.index or $foreach.hasNext). The default is true. Set it to false if unused and you want a tiny performance boost.</p> -</blockquote> -<p><code>directive.foreach.maxloops = -1</code></p> -<blockquote> -<p>Maximum allowed number of loops for a #foreach() statement.</p> -</blockquote> -<p><code>directive.foreach.skip.invalid = true</code></p> -<blockquote> -<p>Tells #foreach to simply skip rendering when the object it is iterating over is not or cannot produce a valid Iterator.</p> -</blockquote> -<h3 id="if-directive">#if() Directive<a class="headerlink" href="#if-directive" title="Permanent link">¶</a></h3> -<p><code>directive.if.tostring.nullcheck = true</code></p> -<blockquote> -<p>Default behavior is to check return value of toString() and treat an object with toString() that returns null as null. If all objects have toString() methods that never return null, this check is unnecessary and can be disabled to gain performance. In Velocity 1.5, no such null check was performed.</p> -</blockquote> -<h3 id="set-directive">#set() Directive<a class="headerlink" href="#set-directive" title="Permanent link">¶</a></h3> -<p><code>directive.set.null.allowed = false</code></p> -<blockquote> -<p>If true, having a right hand side of a #set() statement with an invalid reference or null value will set the left hand side to null. If false, the left hand side will stay the same.</p> -</blockquote> -<h3 id="include-and-parse-directives">#include() and #parse() Directives<a class="headerlink" href="#include-and-parse-directives" title="Permanent link">¶</a></h3> -<p><code>directive.include.output.errormsg.start = <!-- include error :</code> -<code>directive.include.output.errormsg.end = see error log --></code></p> -<blockquote> -<p>Defines the beginning and ending tags for an in-stream error message in the case of a problem with the #include() directive. If both the .start and .end tags are defined, an error message will be output to the stream, of the form '.start msg .end' where .start and .end refer to the property values. Output to the render stream will only occur if both the .start and .end (next) tag are defined.</p> -</blockquote> -<p><code>directive.parse.max.depth = 10</code></p> -<blockquote> -<p>Defines the allowable parse depth for a template. A template may #parse() another template which itself may have a #parse() directive. This value prevents runaway #parse() recursion.</p> -</blockquote> -<p><code>template.provide.scope.control = false</code></p> -<blockquote> -<p>Used to turn on the automatic provision of the $template scope control during #parse calls and template.merge(...) calls. The default is false. Set it to true if you want a secure namespace for your template variables or more advanced #break control.</p> -</blockquote> -<h3 id="resource-management">Resource Management<a class="headerlink" href="#resource-management" title="Permanent link">¶</a></h3> -<p><code>resource.manager.logwhenfound = true</code></p> -<blockquote> -<p>Switch to control logging of 'found' messages from resource manager. When a resource is found for the first time, the resource name and classname of the loader that found it will be noted in the runtime log.</p> -</blockquote> -<p><code>resource.manager.cache.class</code></p> -<blockquote> -<p>Declares the class to be used for resource caching. The current default is <code>org.apache.velocity.runtime.resource.ResourceCacheImpl</code>. When <code>resource.manager.defaultcache.size</code> is set to 0, then the default implementation is the standard Java <code>ConcurrentHashMap</code>. Otherwise, a non-zero cache size uses an LRU Map. The default cache size is 89. Note that the ConcurrentHashMap may be better at thread concurrency.</p> -</blockquote> -<p><code>resource.manager.defaultcache.size</code></p> -<blockquote> -<p>Sets the size of the default implementation of the resource manager cache size. The default is 89.</p> -</blockquote> -<p><code>resource.loader = <name> (default = file)</code></p> -<blockquote> -<p><em>Multi-valued key. Will accept CSV for value.</em> Public name of a resource loader to be used. This public name will then be used in the specification of the specific properties for that resource loader. Note that as a multi-valued key, it's possible to pass a value like "file, class" (sans quotes), indicating that following will be configuration values for two loaders.</p> -</blockquote> -<p><code><name>.loader.description = Velocity File Resource Loader</code></p> -<blockquote> -<p>Description string for the given loader.</p> -</blockquote> -<p><code><name>.resource.loader.class = org.apache.velocity.runtime.resource.loader.FileResourceLoader</code></p> -<blockquote> -<p>Name of implementation class for the loader. The default loader is the file loader.</p> -</blockquote> -<p><code><name>.resource.loader.path = .</code></p> -<blockquote> -<p><em>Multi-valued key. Will accept CSV for value.</em> Root(s) from which the loader loads templates. Templates may live in subdirectories of this root. ex. homesite/index.vm This configuration key applies currently to the FileResourceLoader and JarResourceLoader.</p> -</blockquote> -<p><code><name>.resource.loader.cache = false</code></p> -<blockquote> -<p>Controls caching of the templates in the loader. Default is false, to make life easy for development and debugging. This should be set to true for production deployment. When 'true', the <code>modificationCheckInterval</code> property applies. This allows for the efficiency of caching, with the convenience of controlled reloads - useful in a hosted or ISP environment where templates can be modifed frequently and bouncing the application or servlet engine is not desired or permitted.</p> -</blockquote> -<p><code><name>.resource.loader.modificationCheckInterval = 2</code></p> -<blockquote> -<p>This is the number of seconds between modification checks when caching is turned on. When this is an integer > 0, this represents the number of seconds between checks to see if the template was modified. If the template has been modified since last check, then it is reloaded and reparsed. Otherwise nothing is done. When <= 0, no modification checks will take place, and assuming that the property <code>cache</code> (above) is true, once a template is loaded and parsed the first time it is used, it will not be checked or reloaded after that until the application or servlet engine is restarted.</p> -<p>To illustrate, here is an example taken right from the default Velocity properties, showing how setting up the FileResourceLoader is managed</p> -</blockquote> -<div class="codehilite"><pre>resource.loader = file - -file.resource.loader.description = Velocity File Resource Loader -file.resource.loader.class = org.apache.velocity.runtime.resource.loader.FileResourceLoader -file.resource.loader.path = . -file.resource.loader.cache = false -file.resource.loader.modificationCheckInterval = 2 -</pre></div> - - -<h3 id="velocimacro">Velocimacro<a class="headerlink" href="#velocimacro" title="Permanent link">¶</a></h3> -<p><code>velocimacro.library = VM_global_library.vm</code></p> -<blockquote> -<p><em>Multi-valued key. Will accept CSV for value.</em> Filename(s) of Velocimacro library to be loaded when the Velocity Runtime engine starts. These Velocimacros are accessable to all templates. The file is assumed to be relative to the root of the file loader resource path.</p> -</blockquote> -<p><code>velocimacro.permissions.allow.inline = true</code></p> -<blockquote> -<p>Determines of the definition of new Velocimacros via the #macro() directive in templates is allowed. The default value is true, meaning any template can define and use new Velocimacros. Note that depending on other properties, those #macro() statements can replace global definitions.</p> -</blockquote> -<p><code>velocimacro.permissions.allow.inline.to.replace.global = false</code></p> -<blockquote> -<p>Controls if a Velocimacro defind 'inline' in a template can replace a Velocimacro defined in a library loaded at startup.</p> -</blockquote> -<p><code>velocimacro.permissions.allow.inline.local.scope = false</code></p> -<blockquote> -<p>Controls 'private' templates namespaces for Velocimacros. When true, a #macro() directive in a template creates a Velocimacro that is accessable only from the defining template. This means that Velocimacros cannot be shared unless they are in the global or local library loaded at startup. (See above.) It also means that templates cannot interfere with each other. This property also allows a technique where there is a 'default' Velocimacro definition in the global or local library, and a template can 'override' the implementation for use within that template. This occurrs because when this property is true, the template's namespace is searched for a Velocimacro before the global namespace, therefore allowing the override mechanism.</p> -</blockquote> -<p><code>velocimacro.context.localscope = false</code></p> -<blockquote> -<p>Controls whether reference access (set/get) within a Velocimacro will change the context, or be of local scope in that Velocimacro. This feature is deprecated and has been removed in Velocity 2.0. Instead, please use the $macro namespace for storage of references local to your Velocimacro. (e.g. #set( $macro.foo = 'bar') and $macro.foo)</p> -</blockquote> -<p><code>velocimacro.library.autoreload = false</code></p> -<blockquote> -<p>Controls Velocimacro library autoloading. When set to <code>true</code> the source Velocimacro library for an invoked Velocimacro will be checked for changes, and reloaded if necessary. This allows you to change and test Velocimacro libraries without having to restart your application or servlet container, just like you can with regular templates. This mode only works when caching is <em>off</em> in the resource loaders (e.g. <code>file.resource.loader.cache = false</code> ). This feature is intended for development, not for production.</p> -</blockquote> -<p><code>velocimacro.arguments.strict = false</code></p> -<blockquote> -<p>When set to true, will throw a <code>ParseErrorException</code> when parsing a template containing a macro with an invalid number of arguments. Is set to false by default to maintain backwards compatibility with templates written before this feature became available.</p> -</blockquote> -<p><code>velocimacro.body.reference = false</code></p> -<blockquote> -<p>Defines name of the reference that can be used to get the body content (an AST block) given for a block macro call (e.g. #@myMacro() has a body #end). The default reference name is "bodyContent" (e.g. $bodyContent). This block macro feature was introduced in Velocity 1.7.</p> -</blockquote> -<p><code>macro.provide.scope.control = false</code></p> -<blockquote> -<p>Used to turn on the automatic provision of the $macro scope control during #macro calls. The default is false. Set it to true if you need a local namespace in macros or more advanced #break controls.</p> -</blockquote> -<p><code><somebodymacro>.provide.scope.control = false</code></p> -<blockquote> -<p>Used to turn on the automatic provision of the $<nameofthemacro> scope control during a call to a macro with a body (e.g. #@foo #set($foo.a=$b) ... $foo.a #end). The default is false. Set it to true if you happen to need a namespace just for your macro's body content or more advanced #break controls. -</p></p> -</blockquote> -<h3 id="strict-reference-setting">Strict Reference Setting<a class="headerlink" href="#strict-reference-setting" title="Permanent link">¶</a></h3> -<p><code>runtime.references.strict = false</code></p> -<blockquote> -<p>New in Velocity 1.6, when set to true Velocity will throw a <code>MethodInvocationException</code> for references that are not defined in the context, or have not been defined with a #set directive. This setting will also throw an exception if an attempt is made to call a non-existing property on an object or if the object is null. When this property is true then property 'directive.set.null.allowed' is also set to true. Also, 'directive.foreach.skip.invalid' defaults to true when this property is true, but explicitly setting 'directive.foreach.skip.invalid' will override this default. For a complete discussion see <a href="user-guide.html#strict-reference-mode">Strict References Setting</a>.</p> -<p><code>runtime.references.strict.escape = false</code> Changes escape behavior such that putting a forward slash before a reference or macro always escapes the reference or macro and absorbs the forward slash regardless if the reference or macro is defined. For example "\$foo" always renders as "$foo", or "#foo()" is always rendered as "#foo()". This escape behavior is of use in strict mode since unintended strings of characters that look like references or macros will throw an exception. This provides an easy way to escape these references. However, even in non-strict mode the developer may find this a more consistent and reliable method for escaping.</p> -</blockquote> -<h3 id="string-interpolation">String Interpolation<a class="headerlink" href="#string-interpolation" title="Permanent link">¶</a></h3> -<p><code>runtime.interpolate.string.literals = true</code></p> -<blockquote> -<p>Controls interpolation mechanism of VTL String Literals. Note that a VTL StringLiteral is specifically a string using double quotes that is used in a #set() statement, a method call of a reference, a parameter to a VM, or as an argument to a VTL directive in general. See the VTL reference for further information.</p> -</blockquote> -<h3 id="math">Math<a class="headerlink" href="#math" title="Permanent link">¶</a></h3> -<p><code>runtime.strict.math = false</code></p> -<blockquote> -<p>Affects all math operations in VTL. If changed to true, this will cause Velocity to throw a MathException whenever one side of a math operation has a null value (e.g. <code>#set( $foo = $null * 5 )</code>) or when trying to divide by zero. If this value is left <code>false</code>, then rendering will continue and that math operation will be ignored.</p> -</blockquote> -<h3 id="parser-configuration">Parser Configuration<a class="headerlink" href="#parser-configuration" title="Permanent link">¶</a></h3> -<p><code>parser.pool.class = org.apache.velocity.runtime.ParserPoolImpl</code></p> -<blockquote> -<p>This property selects the implementation for the parser pool. This class must implement ParserPool. Generally there is no reason to change this though if you are building a high volume web application you might consider including an alternate implementation that automatically adjusts the size of the pool.</p> +<h2 id="customizing-introspection">Customizing Introspection<a class="headerlink" href="#customizing-introspection" title="Permanent link">¶</a></h2> +<p>The [runtime.introspector.uberspect configuration property](configuration.html#Pluggable-Introspection] property takes a list of Uberspector class names that constitute the Velocity introspection chain. By means it, you can change the way context objects are introspected at runtime to map VTL properties and methods to Java calls.</p> +<p>Here is the list of provided uberspectors (which are found in the (org.apache.velocity.util.introspection)[apidocs/org/apache/velocity/util/introspection/package-summary.html] package).</p> +<h3 id="standard-uberspectors">Standard Uberspectors<a class="headerlink" href="#standard-uberspectors" title="Permanent link">¶</a></h3> +<ul> +<li><a href="apidocs/org/apache/velocity/util/introspection/UberspectImpl.html">UberspectImpl</a><blockquote> +<p>this is the default uberspector. It successively tries to resolve <code>$foo.bar</code> into <code>foo.getBar()</code>, <code>foo.get('bar')</code> or <code>foo.isBar()</code> (plus some case variants), and tries to match methods using arguments count and type.</p> </blockquote> -<p><code>parser.pool.size = 20</code></p> -<blockquote> -<p>This property is used by the default pooling implementation to set the number of parser instances that Velocity will create at startup and keep in a pool. The default of 20 parsers should be more than enough for most uses. In the event that Velocity does run out of parsers, it will indicate so in the log, and dynamically create overflow instances as needed. Note that these extra parsers will not be added to the pool, and will be discarded after use. This will result in very slow operation compared to the normal usage of pooled parsers, but this is considered an exceptional condition. A web application using Velocity as its view engine might exhibit this behavior under extremely high concurrency (such as when getting Slashdotted). If you see a corresponding message referencing the <code>parser.pool.size</code> property in your log files, please increment this property immediately to avoid performance degradation.</p> +</li> +<li><a href="apidocs/org/apache/velocity/util/introspection/ChainableUberspector.html">ChainableUberspector</a> (interface) and <a href="apidocs/org/apache/velocity/util/introspection/AbstractChainableUberspector.html">AbstractChainableUberspector</a> (meant to be inherited)<blockquote> +<p>A Chainable uberspector is an uberspector that wraps the previous uberspector in the introspection chain.</p> </blockquote> -<h3 id="pluggable-introspection">Pluggable Introspection<a class="headerlink" href="#pluggable-introspection" title="Permanent link">¶</a></h3> -<p><code>runtime.introspector.uberspect = org.apache.velocity.util.introspection.UberspectImpl</code></p> -<blockquote> -<p>This property sets the 'Uberspector', the introspection package that handles all introspection strategies for Velocity. You can specify a comma-separated list of Uberspector classes, in which case all Uberspectors are chained. The default chaining behaviour is to return the first non-null value for each introspection call among all provided uberspectors. You can modify this behaviour (for instance to restrict access to some methods) by subclassing org.apache.velocity.util.introspection.AbstractChainableUberspector (or implementing directly org.apache.velocity.util.introspection.ChainableUberspector). This allows you to create more interesting rules or patterns for Uberspection, rather than just returning the first non-null value.</p> -<p>Some alternate Uberspectors are provided. You would for instance use <code>runtime.introspector.uberspect = org.apache.velocity.util.introspection.SecureUberspector</code> to avoid template authors to instanciate new classes or to use reflection, or use <code>runtime.introspector.uberspect = org.apache.velocity.util.introspection.UberspectImpl, org.apache.velocity.util.introspection.UberspectPublicFields</code> to expose Java public fields in your templates.</p> +</li> +<li><a href="apidocs/org/apache/velocity/util/introspection/LinkingUberspector.html">LinkingUberspector</a><blockquote> +<p>The Linking uberspector is meant for internal use only. It provides introspection chaining when the left uberspector of two following uberspectors of the introspection chain is not a ChainableUberspector. It first tries to delegate introspection to the left uberspector, and only calls the right one in case of failure.</p> </blockquote> -<h3 id="context">Context<a class="headerlink" href="#context" title="Permanent link">¶</a></h3> -<p><code>context.autoreference.key = *name*</code></p> -<blockquote> -<p>This property has no default value. If present, the Context object will become accessible from the templates under the provided name. For instance, with the configuration <code>context.autoreference.key = self</code>, <code>$self</code> will contain the context itself. This feature is meant to be used for debugging purposes.</p> +</li> +<li><a href="apidocs/org/apache/velocity/util/introspection/UberspectLoggable.html">UberspectLoggable</a> interface<blockquote> +<p>When an uberspector implements the UberspectLoggable interface, it is provided a logger during initialization via the <code>setLog(Logger)</code> method.</p> </blockquote> -<h2 id="configuring-logging">Configuring Logging<a class="headerlink" href="#configuring-logging" title="Permanent link">¶</a></h2> -<p>Since version 2.0, Velocity has switched to the <a href="http://www.slf4j.org/";>SLF4J</a> logging facade.</p> -<p>All you have to do to enable logging is to make sure that your classpath contains the slf4j-api jar, and one and only one slf4j binding jar towards your favourite logsystem or facade. See the <a href="#dependencies">dependecies</a> section for a list of SLF4J bindings.</p> -<p>By default, Velocity will use a logger tagged for the org.apache.velocity.app.Velocity class. You can customize this logger in two ways:</p> -<ul> -<li>By programmatically giving Velocity a living instance of an orf.slf4j.Logger object, using the runtime.log.instance property key.</li> -<li>By configuring the name of the logger to be used by your velocity instance, using the runtime.log.name property key. It can be done from the velocity.properties file, if present.</li> +</li> </ul> -<h2 id="configuring-resource-loaders">Configuring Resource Loaders<a class="headerlink" href="#configuring-resource-loaders" title="Permanent link">¶</a></h2> -<h3 id="resource-loaders">Resource Loaders<a class="headerlink" href="#resource-loaders" title="Permanent link">¶</a></h3> -<p>One of the fundamental and important parts about Velocity is the resource management system and the resource loaders. They are referred to as 'resources' here rather than 'templates' because the resource management system will also handle non-template reasources, specifically things that are loaded via the #include() directive.</p> -<p>The resource loader system if very flexible, allowing one or more resource loaders to be in operation at the same time. This allows tremendous flexibility in configuration and resource managment, and futher allows you to write your own resource loaders for your special needs.</p> -<p>There are currently four kinds of resource loaders that are included with Velocity, each described below. Note that in the example configuration properties given, a common name for the loader is shown (ex.'file' in <code>file.resource.loader.path</code>). This 'common name' may not work for your configuration. Please read the section on <a href="#Velocity_Configuration_Keys_and_Values">resource configuration properties</a> to understand how this system works. Also, each of these loaders is located in the package <code>org.apache.velocity.runtime.resource.loader</code>.</p> -<ul> -<li> -<p><strong>FileResourceLoader :</strong> This loader gets resources from the filesystem. Its configuration properties include:</p> +<p>If an Uberspector implements the <a href="apidocs/org/apache/velocity/util/RuntimeServicesAware.html">RuntimeServicesAware</a> interface, it will be provided a Velocity <a href="apidocs/org/apache/velocity/runtime/RuntimeServices.html">RuntimeServices</a> instance during initialization, via the <code>setRuntimeServices(RuntimeServices)</code> method.</p> +<h3 id="uberspectors-providing-extra-features">Uberspectors providing extra features<a class="headerlink" href="#uberspectors-providing-extra-features" title="Permanent link">¶</a></h3> <ul> -<li><code>file.resource.loader.path</code> = <path to root of templates></li> -<li><code>file.resource.loader.cache</code> = true/false</li> -<li><code>file.resource.loader.modificationCheckInterval</code> = <seconds between checks></li> -</ul> -<p>This is the default loader, and is configured, by default to get templates from the 'current directory'. In the case of using Velocity with servlets, this can be a problem as you don't want to have to keep your templates in the directory from which you start your servlet engine. See the documentation for your servlet or web framework (for example <a href="/tools/devel/view-servlet.html">VelocityViewServlet</a>) for more info on how to configure the location of the Velocity templates.</p> -</li> -<li> -<p><strong>JarResourceLoader :</strong> This loader gets resource from specific jar files. It is very similar to the FileResourceLoader, except that you have the convenience of bundling your templates into jars. The properties are identical, except for <code>jar.resource.loader.path</code>, where you provide the full location of the jar(s) you wish to load resources from. To specify a jar for the loader.path you use the standard JAR URL syntax of <code>java.net.JarURLConnection</code>.</p> -</li> -<li> -<p><strong>ClasspathResourceLoader :</strong> This loader gets resources from the classloader. In general, this means that the ClasspathResourceLoader will load templates placed in the classpath (in jars, for example) While the classpath is a source of great pain and suffering in general, it is a very useful mechanism when working on a Servlet Spec 2.2 (or newer) compliant servlet runner. <a href="http://jakarta.apache.org/tomcat/"; class="externalLink">Tomcat</a> is an example of such. To use this loader effectively, all you must do is jar your templates, and put that jar into the WEB-INF/lib directory of your webapp. There are no configuration options to worry about, nor is the absolute vs. relative path an issue, as it is with Jar and File resource loaders. Again, please note that the ClasspathResourceLoader is not only for use with a servlet container, but can be used in any application context.</p> +<li><a href="apidocs/org/apache/velocity/util/introspection/DeprecatedCheckUberspector.html">DeprecatedCheckUberspector</a><blockquote> +<p>This uberspector will emit warnings in the log whenever a VTL fragment uses a deprecated Java method. It is a Chainable uberspector that must be declared <em>after</em> its wrapped uberspector.</p> +</blockquote> </li> -<li> -<p><strong>URLResourceLoader :</strong> This loader gets resources from a URL connection. Its configuration properties include:</p> -<ul> -<li><code>url.resource.loader.root</code> = <root URL path of templates></li> -<li><code>url.resource.loader.cache</code> = true/false</li> -<li><code>url.resource.loader.modificationCheckInterval</code> = <seconds between checks></li> -</ul> -<p>This loader simply downloads resources from configured URLs. It works much like the FileResourceLoader, however, it can pull templates down from any valid URL to which the application can create a connection.</p> +<li><a href="apidocs/org/apache/velocity/util/introspection/SecureUberspector.html">SecureUberspector</a><blockquote> +<p>This uberspector prevents classloader related method calls. Use this introspector for situations in which template writers are numerous or untrusted. Specifically, this introspector prevents creation of arbitrary objects or reflection on objects. It is a standalone uberspector.</p> +</blockquote> </li> -<li> -<p><strong>DataSourceResourceLoader :</strong> This loader will load resources from a DataSource such as a database. This loader is only available under JDK 1.4 and later. For more information on this loader, please see the javadoc for the class <code>org.apache.velocity.runtime.resource.loader.DataSourceResourceLoader</code>.</p> +<li><a href="apidocs/org/apache/velocity/util/introspection/UberspectPublicFields">UberspectPublicFields</a><blockquote> +<p>This uberspector exposes the public fields of objects. It can be prepended or suffixed to other uberspectors, depending on whether you want to priorize or not public fields versus potentially matching methods.</p> +</blockquote> </li> </ul> -<h3 id="configuration-examples">Configuration Examples<a class="headerlink" href="#configuration-examples" title="Permanent link">¶</a></h3> -<p>Configuring the resource loaders for Velocity is straightforward. The properties that control the are listed in the <a href="#Configuring_Resource_Loaders">resource configuration</a> section, for further reference.</p> -<p>The first step in configuring one or more resource loaders is do 'declare' them by name to Velocity. Use the property <code>resource.loader</code> and list one or more loader names. You can use anything you want - these names are used to associate configuration properties with a given loader.</p> -<div class="codehilite"><pre>resource.loader = file -</pre></div> - - -<p>That entry declares that we will have a resource loader known as 'file'. The next thing to do is to set the important properties. The most critical is to declare the class to use as the loader:</p> -<div class="codehilite"><pre>file.resource.loader.class = org.apache.velocity.runtime.resource.loader.FileResourceLoader -</pre></div> - - -<p>In this case, we are telling velocity that we are setting up -a resource loadercalled 'file', and are using the class <code>org.apache.velocity.runtime.resource.loader.FileResourceLoader</code> to be the class to use. The next thing we do is set the properties important to this loader.</p> -<div class="codehilite"><pre>file.resource.loader.path = /opt/templates -file.resource.loader.cache = true -file.resource.loader.modificationCheckInterval = 2 -</pre></div> - - -<p>Here, we set a few things. First, we set the path to find the templates to be <code>/opt/templates</code>. Second, we turned caching on, so that after a template or static file is read in, it is cached in memory. And finally, we set the modification check interval to 2 seconds, allowing Velocity to check for new templates.</p> -<p>Those are the basics. What follows are a few examples of different configuraitons.</p> -<p><strong>Do-nothing Default Configuration: </strong> As the name says, there is nothing you have to do or configure to get the default configuration. This configuration uses the FileResourceLoader with the current directory as the default resource path, and caching is off. As a properties set, this is expressed as:</p> -<div class="codehilite"><pre>resource.loader = file - -file.resource.loader.description = Velocity File Resource Loader -file.resource.loader.class = org.apache.velocity.runtime.resource.loader.FileResourceLoader -file.resource.loader.path = . -file.resource.loader.cache = false -file.resource.loader.modificationCheckInterval = 0 -</pre></div> - - -<p><strong>Multiple Template Path Configuration: </strong> This configuration uses the FileResourceLoader with several directories as 'nodes' on the template search path. We also want to use caching, and have the templates checked for changes in 10 second intervals. As a properties set, this is expressed as:</p> -<div class="codehilite"><pre>resource.loader = file - -file.resource.loader.description = Velocity File Resource Loader -file.resource.loader.class = org.apache.velocity.runtime.resource.loader.FileResourceLoader -file.resource.loader.path = /opt/directory1, /opt/directory2 -file.resource.loader.cache = true -file.resource.loader.modificationCheckInterval = 10 -</pre></div> - - -<p><strong>Multiple Loader Configuration :</strong> This configuration sets up three loaders at the same time, the FileResourceLoader, the ClasspathResourceLoader, and the JarResourceLoader. The loaders are set-up such that the FileResourceLoader is consulted first, then the ClasspathResourceLoader, and finally the JarResourceLoader. This would allow you to qickly drop a template into the file template area to replace on of the templates found in the classpath (usually via a jar) without having to rebuild the jar.</p> -<div class="codehilite"><pre># -# specify three resource loaders to use -# -resource.loader = file, class, jar - -# -# for the loader we call 'file', set the FileResourceLoader as the -# class to use, turn off caching, and use 3 directories for templates -# -file.resource.loader.description = Velocity File Resource Loader -file.resource.loader.class = org.apache.velocity.runtime.resource.loader.FileResourceLoader -file.resource.loader.path = templatedirectory1, anotherdirectory, foo/bar -file.resource.loader.cache = false -file.resource.loader.modificationCheckInterval = 0 - -# -# for the loader we call 'class', use the ClasspathResourceLoader -# -class.resource.loader.description = Velocity Classpath Resource Loader -class.resource.loader.class = org.apache.velocity.runtime.resource.loader.ClasspathResourceLoader - -# -# and finally, for the loader we call 'jar', use the JarResourceLoader -# and specify two jars to load from -# -jar.resource.loader.description = Velocity Jar Resource Loader -jar.resource.loader.class = org.apache.velocity.runtime.resource.loader.JarResourceLoader -jar.resource.loader.path = jar:file:/myjarplace/myjar.jar, jar:file:/myjarplace/myjar2.jar -</pre></div> - - -<p>Node that the three names 'file', 'class', and 'jar' are merely for your convenience and sanity. They can be anything you want - they are just used to associate a set of properties together. However, it is recommended that you use names that give some hint of the function.</p> -<p>Note that while all three require very little configuration information for proper operation, the ClasspathResourceLoader is the simplest.</p> -<h3 id="pluggable-resource-manager-and-resource-cache">Pluggable Resource Manager and Resource Cache<a class="headerlink" href="#pluggable-resource-manager-and-resource-cache" title="Permanent link">¶</a></h3> -<p>The Resource Manager is the main part of the resource (template and static content) management system, and is responsible for taking application requests for templates, finding them in the available resource loaders, and then optionally caching the parsed template. The Resource Cache is the mechanism that the Resource Manager uses to cache templates for quick reuse. While the default versions of these two facilities are suitable for most applications, for advanced users it now is possible to replace the default resource manager and resource cache with custom implementations.</p> -<p>A resource manager implementation must implement the <code>org.apache.velocity.runtime.resource.ResourceManager</code> interface. A description of the requirements of a resource manager is out of scope for this document. Implementors are encouraged to review the default implementation. To configure Velocity to load the replacement implementation, use the configuration key:</p> -<div class="codehilite"><pre>resource.manager.class -</pre></div> - - -<p>This key is also defined as a contstant <code>RuntimeConstants.RESOURCE_MANAGER_CLASS</code></p> -<p>A resource cache implementation must implement the <code>org.apache.velocity.runtime.resource.ResourceCache</code> interface As with the resource manager, a description of the requirements of a resource manager is out of scope for this document. Implementors are encouraged to review the default implementation. To configure Velocity to load the replacement implementation, use the configuration key:</p> -<div class="codehilite"><pre>resource.manager.cache.class -</pre></div> - - -<p>This key is also defined as a contstant <code>RuntimeConstants.RESOURCE_MANAGER_CACHE_CLASS</code></p> -<p>A resource cache implementation may want to limit the cache size (rather than providing an unbounded cache which could consume all available memory). To configure Velocity to set the size for your cache, use the configuration key:</p> -<div class="codehilite"><pre>resource.manager.cache.size -</pre></div> - - -<p>This key is also defined as a contstant <code>RuntimeConstants.RESOURCE_MANAGER_CACHE_SIZE</code></p> <h2 id="template-encoding-for-internationalization">Template Encoding for Internationalization<a class="headerlink" href="#template-encoding-for-internationalization" title="Permanent link">¶</a></h2> <p>Velocity allows you to specify the character encoding of your template resources on a template by template basis. The normal resource API's have been extended to take the encoding as an argument:</p> <p><code>org.apache.velocity.app.Velocity</code></p>
Modified: velocity/site/production/engine/devel/getting-started.html URL: http://svn.apache.org/viewvc/velocity/site/production/engine/devel/getting-started.html?rev=1753524&r1=1753523&r2=1753524&view=diff ============================================================================== --- velocity/site/production/engine/devel/getting-started.html (original) +++ velocity/site/production/engine/devel/getting-started.html Wed Jul 20 14:44:53 2016 @@ -170,6 +170,7 @@ h2:hover > .headerlink, h3:hover > .head <li><a href="user-guide.html">User Guide</a></li> <li><a href="developer-guide.html">Developer Guide</a></li> <li><a href="vtl-reference.html">VTL Reference</a></li> +<li><a href="configuration.html">Configuration</a></li> <li><a href="glossary.html">Glossary</a></li> <li><a href="apidocs/index.html">Javadoc</a></li> </ul> Modified: velocity/site/production/engine/devel/glossary.html URL: http://svn.apache.org/viewvc/velocity/site/production/engine/devel/glossary.html?rev=1753524&r1=1753523&r2=1753524&view=diff ============================================================================== --- velocity/site/production/engine/devel/glossary.html (original) +++ velocity/site/production/engine/devel/glossary.html Wed Jul 20 14:44:53 2016 @@ -170,6 +170,7 @@ h2:hover > .headerlink, h3:hover > .head <li><a href="user-guide.html">User Guide</a></li> <li><a href="developer-guide.html">Developer Guide</a></li> <li><a href="vtl-reference.html">VTL Reference</a></li> +<li><a href="configuration.html">Configuration</a></li> <li><a href="glossary.html">Glossary</a></li> <li><a href="apidocs/index.html">Javadoc</a></li> </ul> Modified: velocity/site/production/engine/devel/index.html URL: http://svn.apache.org/viewvc/velocity/site/production/engine/devel/index.html?rev=1753524&r1=1753523&r2=1753524&view=diff ============================================================================== --- velocity/site/production/engine/devel/index.html (original) +++ velocity/site/production/engine/devel/index.html Wed Jul 20 14:44:53 2016 @@ -170,6 +170,7 @@ h2:hover > .headerlink, h3:hover > .head <li><a href="user-guide.html">User Guide</a></li> <li><a href="developer-guide.html">Developer Guide</a></li> <li><a href="vtl-reference.html">VTL Reference</a></li> +<li><a href="configuration.html">Configuration</a></li> <li><a href="glossary.html">Glossary</a></li> <li><a href="apidocs/index.html">Javadoc</a></li> </ul> Modified: velocity/site/production/engine/devel/left.nav URL: http://svn.apache.org/viewvc/velocity/site/production/engine/devel/left.nav?rev=1753524&r1=1753523&r2=1753524&view=diff ============================================================================== --- velocity/site/production/engine/devel/left.nav (original) +++ velocity/site/production/engine/devel/left.nav Wed Jul 20 14:44:53 2016 @@ -9,6 +9,7 @@ * [User Guide](user-guide.html) * [Developer Guide](developer-guide.html) * [VTL Reference](vtl-reference.html) +* [Configuration](configuration.html) * [Glossary](glossary.html) * [Javadoc](apidocs/index.html) ## Developers Modified: velocity/site/production/engine/devel/license.html URL: http://svn.apache.org/viewvc/velocity/site/production/engine/devel/license.html?rev=1753524&r1=1753523&r2=1753524&view=diff ============================================================================== --- velocity/site/production/engine/devel/license.html (original) +++ velocity/site/production/engine/devel/license.html Wed Jul 20 14:44:53 2016 @@ -170,6 +170,7 @@ h2:hover > .headerlink, h3:hover > .head <li><a href="user-guide.html">User Guide</a></li> <li><a href="developer-guide.html">Developer Guide</a></li> <li><a href="vtl-reference.html">VTL Reference</a></li> +<li><a href="configuration.html">Configuration</a></li> <li><a href="glossary.html">Glossary</a></li> <li><a href="apidocs/index.html">Javadoc</a></li> </ul> Modified: velocity/site/production/engine/devel/overview.html URL: http://svn.apache.org/viewvc/velocity/site/production/engine/devel/overview.html?rev=1753524&r1=1753523&r2=1753524&view=diff ============================================================================== --- velocity/site/production/engine/devel/overview.html (original) +++ velocity/site/production/engine/devel/overview.html Wed Jul 20 14:44:53 2016 @@ -170,6 +170,7 @@ h2:hover > .headerlink, h3:hover > .head <li><a href="user-guide.html">User Guide</a></li> <li><a href="developer-guide.html">Developer Guide</a></li> <li><a href="vtl-reference.html">VTL Reference</a></li> +<li><a href="configuration.html">Configuration</a></li> <li><a href="glossary.html">Glossary</a></li> <li><a href="apidocs/index.html">Javadoc</a></li> </ul> Modified: velocity/site/production/engine/devel/source-repository.html URL: http://svn.apache.org/viewvc/velocity/site/production/engine/devel/source-repository.html?rev=1753524&r1=1753523&r2=1753524&view=diff ============================================================================== --- velocity/site/production/engine/devel/source-repository.html (original) +++ velocity/site/production/engine/devel/source-repository.html Wed Jul 20 14:44:53 2016 @@ -170,6 +170,7 @@ h2:hover > .headerlink, h3:hover > .head <li><a href="user-guide.html">User Guide</a></li> <li><a href="developer-guide.html">Developer Guide</a></li> <li><a href="vtl-reference.html">VTL Reference</a></li> +<li><a href="configuration.html">Configuration</a></li> <li><a href="glossary.html">Glossary</a></li> <li><a href="apidocs/index.html">Javadoc</a></li> </ul> Modified: velocity/site/production/engine/devel/upgrading.html URL: http://svn.apache.org/viewvc/velocity/site/production/engine/devel/upgrading.html?rev=1753524&r1=1753523&r2=1753524&view=diff ============================================================================== --- velocity/site/production/engine/devel/upgrading.html (original) +++ velocity/site/production/engine/devel/upgrading.html Wed Jul 20 14:44:53 2016 @@ -170,6 +170,7 @@ h2:hover > .headerlink, h3:hover > .head <li><a href="user-guide.html">User Guide</a></li> <li><a href="developer-guide.html">Developer Guide</a></li> <li><a href="vtl-reference.html">VTL Reference</a></li> +<li><a href="configuration.html">Configuration</a></li> <li><a href="glossary.html">Glossary</a></li> <li><a href="apidocs/index.html">Javadoc</a></li> </ul> @@ -224,9 +225,10 @@ h2:hover > .headerlink, h3:hover > .head h2:hover > .headerlink, h3:hover > .headerlink, h1:hover > .headerlink, h6:hover > .headerlink, h4:hover > .headerlink, h5:hover > .headerlink, dt:hover > .elementid-permalink { visibility: visible }</style> <h2 id="upgrading-from-earlier-versions">Upgrading from earlier versions<a class="headerlink" href="#upgrading-from-earlier-versions" title="Permanent link">¶</a></h2> <p>Release with the same major number (1.x) are intended to be drop-in replacements. However, in most cases the versions of dependency jars must be adjusted because newer versions of Velocity might require updates.</p> -<h3 id="upgrading-from-velocity-17">Upgrading from Velocity 1.7<a class="headerlink" href="#upgrading-from-velocity-17" title="Permanent link">¶</a></h3> +<h3 id="upgrading-from-velocity-17x-to-velocity-20x">Upgrading from Velocity 1.7.x to Velocity 2.0.x<a class="headerlink" href="#upgrading-from-velocity-17x-to-velocity-20x" title="Permanent link">¶</a></h3> <p>Behavior / API changes:</p> <ul> +<li>velocity is now using the SLF4J logging facade. Hence, all methods accepting or returning a logger now use the org.slf4j.Logger object.</li> <li>the internal Context API now enforces String keys everywhere, this may break custom Context implementations at compile-time.</li> <li> <p>invalid reference events are now more sparsely sent; they're not sent if <em>any</em> of the following conditions is met:</p> @@ -240,9 +242,9 @@ h2:hover > .headerlink, h3:hover > .head <li> <p>The <code>ResourceLoader</code> class has been deprecated in favor of a <code>ResourceLoader2</code> class, in which the <code>InputStream ResourceLoader.getResourceStream(String name)</code> has been replaced by a <code>Reader ResourceLoader.getResourceReader(String name, String encoding)</code>. Since <code>ResourceLoader</code> inherits from <code>ResourceLoader2</code>, the change remains backward compatible, but custom resource loaders should be upgraded to avoid deprecattion warnings.</p> </li> -<li>The default encoding ('ISO-8859-1' in 1.x) is now read from the standard <code>file.encoding</code> Java system property.</li> -<li>The <code>output.encoding</code> configuration property has been removed.</li> +<li>the default encoding ('ISO-8859-1' in 1.x) is now read from the standard <code>file.encoding</code> Java system property.</li> <li>the MethodException event handler now receives an additional argument providing template name and location infos.</li> +<li>all occurences of the class org.apache.commons.collections.ExtendedProperties in the initialization API have been replaced by org.apache.velocity.util.ExtProperties.</li> </ul> <p>VTL Syntax changes:</p> <ul> @@ -251,11 +253,12 @@ h2:hover > .headerlink, h3:hover > .head </ul> <p>Dependencies changes:</p> <ul> +<li>Velocity now requires a JDK version of 1.7 or higher.</li> <li>commons-lang, commons-collections and commons-logging aren't needed any more at runtime.</li> <li>there's a new runtime dependency, slf4j-api 1.7.12</li> <li>you'll need an <a href="dependencies.html">SLF4J binding</a></li> </ul> -<h3 id="upgrading-from-velocity-16">Upgrading from Velocity 1.6<a class="headerlink" href="#upgrading-from-velocity-16" title="Permanent link">¶</a></h3> +<h3 id="upgrading-from-velocity-16x-to-velocity-17x">Upgrading from Velocity 1.6.x to Velocity 1.7.x<a class="headerlink" href="#upgrading-from-velocity-16x-to-velocity-17x" title="Permanent link">¶</a></h3> <p>There are no changes in the dependencies since Velocity 1.6</p> <ul> <li>Deprecated $velocityCount; please use $foreach.count or $foreach.index</li> @@ -267,7 +270,7 @@ h2:hover > .headerlink, h3:hover > .head <li>Removed obsolete Veltag (use VelocityViewTag in VelocityTools project)</li> <li>Removed obsolete WebMacro conversion code.</li> </ul> -<h3 id="upgrading-from-velocity-15">Upgrading from Velocity 1.5<a class="headerlink" href="#upgrading-from-velocity-15" title="Permanent link">¶</a></h3> +<h3 id="upgrading-from-velocity-15x-to-velocity-16x">Upgrading from Velocity 1.5.x to Velocity 1.6.x<a class="headerlink" href="#upgrading-from-velocity-15x-to-velocity-16x" title="Permanent link">¶</a></h3> <ul> <li><a href="http://commons.apache.org/collections/";>Commons Collections</a> has been upgraded to version 3.2.1.</li> <li><a href="http://commons.apache.org/lang/";>Commons Lang</a> has been upgraded to version 2.4.</li> Modified: velocity/site/production/engine/devel/user-guide.html URL: http://svn.apache.org/viewvc/velocity/site/production/engine/devel/user-guide.html?rev=1753524&r1=1753523&r2=1753524&view=diff ============================================================================== --- velocity/site/production/engine/devel/user-guide.html (original) +++ velocity/site/production/engine/devel/user-guide.html Wed Jul 20 14:44:53 2016 @@ -170,6 +170,7 @@ h2:hover > .headerlink, h3:hover > .head <li><a href="user-guide.html">User Guide</a></li> <li><a href="developer-guide.html">Developer Guide</a></li> <li><a href="vtl-reference.html">VTL Reference</a></li> +<li><a href="configuration.html">Configuration</a></li> <li><a href="glossary.html">Glossary</a></li> <li><a href="apidocs/index.html">Javadoc</a></li> </ul> @@ -473,7 +474,7 @@ visible. *# This text is outside the com </pre></div> -<p>Also new in Velocity 1.6 is support for vararg methods. A method like <code>azpublic void setPlanets(String... planets)</code> or even just <code>public void setPlanets(String[] planets)</code> (if you are using a pre-Java 5 JDK), can now accept any number of arguments when called in a template.</p> +<p>Also new in Velocity 1.6 is support for vararg methods. A method like <code>azpublic void setPlanets(String... planets)</code> or even just <code>public void setPlanets(String[] planets)</code> can now accept any number of arguments when called in a template.</p> <div class="codehilite"><pre><span class="p">$</span><span class="nv">sun</span><span class="p">.</span><span class="nv">setPlanets</span><span class="p">(</span><span class="s1">'Earth'</span><span class="p">,</span> <span class="s1">'Mars'</span><span class="p">,</span> <span class="s1">'Neptune'</span><span class="p">)</span><span class="x"></span> <span class="p">$</span><span class="nv">sun</span><span class="p">.</span><span class="nv">setPlanets</span><span class="p">(</span><span class="s1">'Mercury'</span><span class="p">)</span><span class="x"></span> Modified: velocity/site/production/engine/devel/vtl-reference.html URL: http://svn.apache.org/viewvc/velocity/site/production/engine/devel/vtl-reference.html?rev=1753524&r1=1753523&r2=1753524&view=diff ============================================================================== --- velocity/site/production/engine/devel/vtl-reference.html (original) +++ velocity/site/production/engine/devel/vtl-reference.html Wed Jul 20 14:44:53 2016 @@ -170,6 +170,7 @@ h2:hover > .headerlink, h3:hover > .head <li><a href="user-guide.html">User Guide</a></li> <li><a href="developer-guide.html">Developer Guide</a></li> <li><a href="vtl-reference.html">VTL Reference</a></li> +<li><a href="configuration.html">Configuration</a></li> <li><a href="glossary.html">Glossary</a></li> <li><a href="apidocs/index.html">Javadoc</a></li> </ul> Modified: velocity/site/production/engine/devel/webapps.html URL: http://svn.apache.org/viewvc/velocity/site/production/engine/devel/webapps.html?rev=1753524&r1=1753523&r2=1753524&view=diff ============================================================================== --- velocity/site/production/engine/devel/webapps.html (original) +++ velocity/site/production/engine/devel/webapps.html Wed Jul 20 14:44:53 2016 @@ -170,6 +170,7 @@ h2:hover > .headerlink, h3:hover > .head <li><a href="user-guide.html">User Guide</a></li> <li><a href="developer-guide.html">Developer Guide</a></li> <li><a href="vtl-reference.html">VTL Reference</a></li> +<li><a href="configuration.html">Configuration</a></li> <li><a href="glossary.html">Glossary</a></li> <li><a href="apidocs/index.html">Javadoc</a></li> </ul>
