Modified: velocity/site/production/engine/2.2/developer-guide.html URL: http://svn.apache.org/viewvc/velocity/site/production/engine/2.2/developer-guide.html?rev=1871674&r1=1871673&r2=1871674&view=diff ============================================================================== --- velocity/site/production/engine/2.2/developer-guide.html (original) +++ velocity/site/production/engine/2.2/developer-guide.html Mon Dec 16 18:44:00 2019 @@ -467,13 +467,15 @@ h2:hover > .headerlink, h3:hover > .head <p>Please note that like a Hashtable, the value must be derived from java.lang.Object, and must not be null. Fundamental types like int or float must be wrapped in the appropriate wrapper classes.</p> <p>That's really all there is to basic context operations. For more information, see the API documentation included in the distribution.</p> <h3 id="support-for-iterative-objects-for-foreach">Support for Iterative Objects for #foreach()<a class="headerlink" href="#support-for-iterative-objects-for-foreach" title="Permanent link">¶</a></h3> -<p>As a programmer, you have great freedom in the objects that you put into the context. But as with most freedoms, this one comes with a little bit of responsibility, so understand what Velocity supports, and any issues that may arise. Velocity supports serveral types of collection types suitable for use in the VTL <code>#foreach()</code> directive. -+ <code>Object []</code> Regular object array, not much needs to be said here. Velocity will internally wrap your array in a class that provides an Iterator interface, but that shouldn't concern you as the programmer, or the template author. Of more interest, is the fact that Velocity will now allow template authors to treat arrays as fixed-length lists. This means they may call methods like <code>size()</code>, <code>isEmpty()</code> and <code>get(int)</code> as well as the <code>empty</code> property on both arrays and standard java.util.List instances without concerning themselves about the difference. -+ <code>java.util.Collection</code> Velocity will use the <code>iterator()</code> method to get an Iterator to use in the loop, so if you are implementing a Collection interface on your object, please ensure that <code>iterator()</code> returns a working Iterator. -+ <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 <code>java.util.Iterable</code> interface.</p> +<p>As a programmer, you have great freedom in the objects that you put into the context. But as with most freedoms, this one comes with a little bit of responsibility, so understand what Velocity supports, and any issues that may arise. Velocity supports serveral types of collection types suitable for use in the VTL <code>#foreach()</code> directive:</p> +<ul> +<li><code>Object []</code> Regular object array, not much needs to be said here. Velocity will internally wrap your array in a class that provides an Iterator interface, but that shouldn't concern you as the programmer, or the template author. Of more interest, is the fact that Velocity will now allow template authors to treat arrays as fixed-length lists. This means they may call methods like <code>size()</code>, <code>isEmpty()</code> and <code>get(int)</code> as well as the <code>empty</code> property on both arrays and standard java.util.List instances without concerning themselves about the difference.</li> +<li><code>java.util.Collection</code> Velocity will use the <code>iterator()</code> method to get an Iterator to use in the loop, so if you are implementing a Collection interface on your object, please ensure that <code>iterator()</code> returns a working Iterator.</li> +<li><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.</li> +<li><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.</li> +<li><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.</li> +<li>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.</li> +</ul> <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><span class="n">Vector</span> <span class="n">v</span> <span class="o">=</span> <span class="k">new</span> <span class="n">Vector</span><span class="o">();</span> @@ -1045,7 +1047,7 @@ see the Javadoc API documentation.</p> </li> </ul> <p>The <a href="/tools/devel/">VelocityTools</a> project also defines a <a href="/tools/devel/apidocs/org/apache/velocity/tools/view/WebappResourceLoader.html">WebappResourceLoader</a>, active by default, which maps '/' to the root of the webapp.</p> -<p>Advanced users may also want to replace the Resource Manager or the Resource Cache: 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, it is possible to replace the default resource manager and resource cache with custom implementations. See the (related configuration options)[configuration.html#resource-management].</p> +<p>Advanced users may also want to replace the Resource Manager or the Resource Cache: 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, it is possible to replace the default resource manager and resource cache with custom implementations. See the <a href="configuration.html#resource-management">related configuration options</a>.</p> <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> @@ -1110,10 +1112,12 @@ see the Javadoc API documentation.</p> <p>When a reference has an alternate value provided, as in <code>${foo.bar|'foo'}</code>, whenever <code>$foo.bar</code> is invalid, the invalid reference handler will only be called if the alternate value is invalid.</p> -<p>There are three special cases where invalid reference events aren't triggered: -+ When the reference is a quiet reference (this behavior can be reverted to the 1.7 behavior using the backward compatibility flag <code>event_handler.invalid_references.quiet = true</code>). -+ when the reference is present in the context but has a null value, or the called method returned null (this behavior can be reverted to the 1.7 behavior using the backward compatibility flag <code>event_handler.invalid_references.null = true</code>). -+ when the reference is just tested for validity in an <code>#if()</code> statement (this behavior can be reverted to the 1.7 behavior using the backward compatibility flag <code>event_handler.invalid_references.tested = true</code>).</p> +<p>There are three special cases where invalid reference events aren't triggered:</p> +<ul> +<li>When the reference is a quiet reference (this behavior can be reverted to the 1.7 behavior using the backward compatibility flag <code>event_handler.invalid_references.quiet = true</code>).</li> +<li>when the reference is present in the context but has a null value, or the called method returned null (this behavior can be reverted to the 1.7 behavior using the backward compatibility flag <code>event_handler.invalid_references.null = true</code>).</li> +<li>when the reference is just tested for validity in an <code>#if()</code> statement (this behavior can be reverted to the 1.7 behavior using the backward compatibility flag <code>event_handler.invalid_references.tested = true</code>).</li> +</ul> <p>Available implementations include:</p> <ul> <li><code>org.apache.velocity.app.event.implement.ReportInvalidReferences</code><blockquote> @@ -1221,8 +1225,8 @@ see the Javadoc API documentation.</p> <h2 id="customizing-introspection">Customizing Introspection<a class="headerlink" href="#customizing-introspection" title="Permanent link">¶</a></h2> -<p>The [<code>runtime.introspector.uberspect</code> 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> +<p>The <a href="configuration.html#Pluggable-Introspection"><code>runtime.introspector.uberspect</code> configuration property</a> 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 <a href="apidocs/org/apache/velocity/util/introspection/package-summary.html"><code>org.apache.velocity.util.introspection</code></a> 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> @@ -1285,8 +1289,10 @@ see the Javadoc API documentation.</p> <th>Short</th> <th>Integer</th> <th>Long</th> + <th>BigInteger</th> <th>Float</th> <th>Double</th> + <th>BigDecimal</th> <th>Number</th> <th>String</th> <th>Object</th> @@ -1304,6 +1310,8 @@ see the Javadoc API documentation.</p> <td><span class="explicit">explicit</span></td> <td><span class="explicit">explicit</span></td> <td><span class="explicit">explicit</span></td> + <td><span class="explicit">explicit</span></td> + <td><span class="explicit">explicit</span></td> <td><span class="none">none</span></td> <td><span class="none">none</span></td> </tr> @@ -1321,17 +1329,21 @@ see the Javadoc API documentation.</p> <td><span class="none">none</span></td> <td><span class="none">none</span></td> <td><span class="none">none</span></td> + <td><span class="none">none</span></td> + <td><span class="none">none</span></td> </tr> <tr> <th>byte</th> <td><span class="explicit">explicit</span></td> <td><span class="none">none</span></td> - <td><span class="implicit">implicit</span></td> + <td><span class="strict">strict</span></td> + <td><span class="explicit">explicit</span></td> <td><span class="explicit">explicit</span></td> <td><span class="explicit">explicit</span></td> <td><span class="explicit">explicit</span></td> <td><span class="explicit">explicit</span></td> <td><span class="explicit">explicit</span></td> + <td><span class="none">none</span></td> <td><span class="explicit">explicit</span></td> <td><span class="explicit">explicit</span></td> <td><span class="none">none</span></td> @@ -1349,6 +1361,8 @@ see the Javadoc API documentation.</p> <td><span class="explicit">explicit</span></td> <td><span class="explicit">explicit</span></td> <td><span class="explicit">explicit</span></td> + <td><span class="explicit">explicit</span></td> + <td><span class="explicit">explicit</span></td> <td><span class="none">none</span></td> <td><span class="none">none</span></td> </tr> @@ -1364,6 +1378,8 @@ see the Javadoc API documentation.</p> <td><span class="explicit">explicit</span></td> <td><span class="explicit">explicit</span></td> <td><span class="explicit">explicit</span></td> + <td><span class="explicit">explicit</span></td> + <td><span class="explicit">explicit</span></td> <td><span class="none">none</span></td> <td><span class="none">none</span></td> </tr> @@ -1379,6 +1395,8 @@ see the Javadoc API documentation.</p> <td><span class="explicit">explicit</span></td> <td><span class="explicit">explicit</span></td> <td><span class="explicit">explicit</span></td> + <td><span class="explicit">explicit</span></td> + <td><span class="explicit">explicit</span></td> <td><span class="none">none</span></td> <td><span class="none">none</span></td> </tr> @@ -1390,10 +1408,12 @@ see the Javadoc API documentation.</p> <td><span class="implicit">implicit</span></td> <td><span class="implicit">implicit</span></td> <td><span class="implicit">implicit</span></td> + <td><span class="explicit">explicit</span></td> <td><span class="implicit">implicit</span></td> <td><span class="explicit">explicit</span></td> <td><span class="explicit">explicit</span></td> <td><span class="explicit">explicit</span></td> + <td><span class="explicit">explicit</span></td> <td><span class="none">none</span></td> <td><span class="none">none</span></td> </tr> @@ -1405,10 +1425,12 @@ see the Javadoc API documentation.</p> <td><span class="implicit">implicit</span></td> <td><span class="implicit">implicit</span></td> <td><span class="implicit">implicit</span></td> + <td><span class="explicit">explicit</span></td> <td><span class="implicit">implicit</span></td> <td><span class="implicit">implicit</span></td> <td><span class="explicit">explicit</span></td> <td><span class="explicit">explicit</span></td> + <td><span class="explicit">explicit</span></td> <td><span class="none">none</span></td> <td><span class="none">none</span></td> </tr> @@ -1424,6 +1446,8 @@ see the Javadoc API documentation.</p> <td><span class="explicit">explicit</span></td> <td><span class="explicit">explicit</span></td> <td><span class="explicit">explicit</span></td> + <td><span class="explicit">explicit</span></td> + <td><span class="explicit">explicit</span></td> <td><span class="none">none</span></td> <td><span class="strict">strict</span></td> </tr> @@ -1440,6 +1464,8 @@ see the Javadoc API documentation.</p> <td><span class="none">none</span></td> <td><span class="none">none</span></td> <td><span class="none">none</span></td> + <td><span class="none">none</span></td> + <td><span class="none">none</span></td> <td><span class="strict">strict</span></td> </tr> <tr> @@ -1454,6 +1480,8 @@ see the Javadoc API documentation.</p> <td><span class="explicit">explicit</span></td> <td><span class="explicit">explicit</span></td> <td><span class="explicit">explicit</span></td> + <td><span class="explicit">explicit</span></td> + <td><span class="explicit">explicit</span></td> <td><span class="none">none</span></td> <td><span class="strict">strict</span></td> </tr> @@ -1461,7 +1489,7 @@ see the Javadoc API documentation.</p> <th>Short</th> <td><span class="explicit">explicit</span></td> <td><span class="none">none</span></td> - <td><span class="none">none</span></td> + <td><span class="explicit">explicit</span></td> <td><span class="strict">strict</span></td> <td><span class="explicit">explicit</span></td> <td><span class="explicit">explicit</span></td> @@ -1469,6 +1497,8 @@ see the Javadoc API documentation.</p> <td><span class="explicit">explicit</span></td> <td><span class="explicit">explicit</span></td> <td><span class="explicit">explicit</span></td> + <td><span class="explicit">explicit</span></td> + <td><span class="explicit">explicit</span></td> <td><span class="none">none</span></td> <td><span class="strict">strict</span></td> </tr> @@ -1476,7 +1506,7 @@ see the Javadoc API documentation.</p> <th>Integer</th> <td><span class="explicit">explicit</span></td> <td><span class="none">none</span></td> - <td><span class="none">none</span></td> + <td><span class="explicit">explicit</span></td> <td><span class="explicit">explicit</span></td> <td><span class="strict">strict</span></td> <td><span class="explicit">explicit</span></td> @@ -1484,6 +1514,8 @@ see the Javadoc API documentation.</p> <td><span class="explicit">explicit</span></td> <td><span class="explicit">explicit</span></td> <td><span class="explicit">explicit</span></td> + <td><span class="explicit">explicit</span></td> + <td><span class="explicit">explicit</span></td> <td><span class="none">none</span></td> <td><span class="strict">strict</span></td> </tr> @@ -1491,7 +1523,7 @@ see the Javadoc API documentation.</p> <th>Long</th> <td><span class="explicit">explicit</span></td> <td><span class="none">none</span></td> - <td><span class="none">none</span></td> + <td><span class="explicit">explicit</span></td> <td><span class="explicit">explicit</span></td> <td><span class="explicit">explicit</span></td> <td><span class="strict">strict</span></td> @@ -1499,14 +1531,34 @@ see the Javadoc API documentation.</p> <td><span class="explicit">explicit</span></td> <td><span class="explicit">explicit</span></td> <td><span class="explicit">explicit</span></td> + <td><span class="explicit">explicit</span></td> + <td><span class="explicit">explicit</span></td> <td><span class="none">none</span></td> <td><span class="strict">strict</span></td> </tr> <tr> - <th>Float</th> + <th>BigInteger</th> + <td><span class="none">none</span></td> <td><span class="none">none</span></td> + <td><span class="explicit">explicit</span></td> + <td><span class="explicit">explicit</span></td> + <td><span class="explicit">explicit</span></td> + <td><span class="explicit">explicit</span></td> + <td><span class="strict">strict</span></td> + <td><span class="none">none</span></td> + <td><span class="none">none</span></td> + <td><span class="explicit">explicit</span></td> + <td><span class="none">none</span></td> + <td><span class="explicit">explicit</span></td> + <td><span class="none">none</span></td> + <td><span class="strict">strict</span></td> + </tr> + <tr> + <th>Float</th> <td><span class="none">none</span></td> <td><span class="none">none</span></td> + <td><span class="explicit">explicit</span></td> + <td><span class="explicit">explicit</span></td> <td><span class="explicit">explicit</span></td> <td><span class="explicit">explicit</span></td> <td><span class="explicit">explicit</span></td> @@ -1514,6 +1566,7 @@ see the Javadoc API documentation.</p> <td><span class="explicit">explicit</span></td> <td><span class="explicit">explicit</span></td> <td><span class="explicit">explicit</span></td> + <td><span class="explicit">explicit</span></td> <td><span class="none">none</span></td> <td><span class="strict">strict</span></td> </tr> @@ -1521,7 +1574,8 @@ see the Javadoc API documentation.</p> <th>Double</th> <td><span class="none">none</span></td> <td><span class="none">none</span></td> - <td><span class="none">none</span></td> + <td><span class="explicit">explicit</span></td> + <td><span class="explicit">explicit</span></td> <td><span class="explicit">explicit</span></td> <td><span class="explicit">explicit</span></td> <td><span class="explicit">explicit</span></td> @@ -1529,6 +1583,24 @@ see the Javadoc API documentation.</p> <td><span class="strict">strict</span></td> <td><span class="explicit">explicit</span></td> <td><span class="explicit">explicit</span></td> + <td><span class="explicit">explicit</span></td> + <td><span class="none">none</span></td> + <td><span class="strict">strict</span></td> + </tr> + <tr> + <th>BigDecimal</th> + <td><span class="none">none</span></td> + <td><span class="none">none</span></td> + <td><span class="explicit">explicit</span></td> + <td><span class="explicit">explicit</span></td> + <td><span class="explicit">explicit</span></td> + <td><span class="explicit">explicit</span></td> + <td><span class="explicit">explicit</span></td> + <td><span class="explicit">explicit</span></td> + <td><span class="explicit">explicit</span></td> + <td><span class="strict">strict</span></td> + <td><span class="none">none</span></td> + <td><span class="explicit">explicit</span></td> <td><span class="none">none</span></td> <td><span class="strict">strict</span></td> </tr> @@ -1543,6 +1615,8 @@ see the Javadoc API documentation.</p> <td><span class="strict">strict</span></td> <td><span class="strict">strict</span></td> <td><span class="strict">strict</span></td> + <td><span class="strict">strict</span></td> + <td><span class="strict">strict</span></td> <td><span class="none">none</span></td> <td><span class="none">none</span></td> <td><span class="strict">strict</span></td> @@ -1558,6 +1632,8 @@ see the Javadoc API documentation.</p> <td><span class="explicit">explicit</span></td> <td><span class="explicit">explicit</span></td> <td><span class="explicit">explicit</span></td> + <td><span class="explicit">explicit</span></td> + <td><span class="explicit">explicit</span></td> <td><span class="strict">strict</span></td> <td><span class="explicit">explicit</span></td> <td><span class="strict">strict</span></td> @@ -1576,6 +1652,8 @@ see the Javadoc API documentation.</p> <td><span class="strict">strict</span></td> <td><span class="strict">strict</span></td> <td><span class="strict">strict</span></td> + <td><span class="strict">strict</span></td> + <td><span class="strict">strict</span></td> </tr> </thead> <tbody> @@ -1725,7 +1803,7 @@ see the Javadoc API documentation.</p> <h2 id="customizing-the-vtl-parser">Customizing the VTL parser<a class="headerlink" href="#customizing-the-vtl-parser" title="Permanent link">¶</a></h2> -<p>Since 2.2, a Velocity Engine can use a custom parser. You need to generate your custom parser class, let's say <code>com.foo.MyCustomParser</code>, by copy pasting the content of the <a href="https://dist.apache.org/repos/dist/dev/velocity/velocity-engine/2.2/velocity-custom-parser-example-2.2.pom";>velocity-custom-parser-example</a> maven module pom file inside one of your own modules pom.xml, and then adapting its <code><properties></code> section. There's a minimal maven knowledge required to understand what you are doing, but basically it boils down to do merge the content of the <code><properties></code>, <code><dependencies></code> and <code><build></code> sections in your target pom file.</p> +<p>Since 2.2, Velocity Engine can use a custom parser. You need to generate your custom parser class, let's say <code>com.foo.MyCustomParser</code>, by copy pasting the content of the <a href="https://dist.apache.org/repos/dist/dev/velocity/velocity-engine/2.2/velocity-custom-parser-example-2.2.pom";>velocity-custom-parser-example</a> maven module pom file inside one of your own modules pom.xml, and then adapting its <code><properties></code> section. There's a minimal maven knowledge required to understand what you are doing, but basically it boils down to do merge the content of the <code><properties></code>, <code><dependencies></code> and <code><build></code> sections in your target pom file.</p> <p>This custom parser will let you configure the following VTL characters:</p> <ul> <li><code>*</code> (used in <code>#*</code> multiline comments syntax)</li>
Modified: velocity/site/production/engine/2.2/upgrading.html URL: http://svn.apache.org/viewvc/velocity/site/production/engine/2.2/upgrading.html?rev=1871674&r1=1871673&r2=1871674&view=diff ============================================================================== --- velocity/site/production/engine/2.2/upgrading.html (original) +++ velocity/site/production/engine/2.2/upgrading.html Mon Dec 16 18:44:00 2019 @@ -287,6 +287,7 @@ h2:hover > .headerlink, h3:hover > .head <li>The references with alternate values like <code>${foo|'foo'}</code> won't trigger any invalid reference event if their alternate value is valid.</li> <li>New <a href="configuration.html#logging"><code>runtime.log.track_location</code></a> debugging configuration flag (defaults to false). When true, logs VTL stacktrace on errors and populate slf4j template location MDC tags.</li> <li>New 1.7.x backward compatibility configuration flags for event handlers, see above section.</li> +<li>When active, the conversion handler will automatcally convert BigInteger and BigDecimal values towards/from expected method arguments types, see <a href="developer-guide.html#method-arguments-conversions">method arguments conversion</a>.</li> </ul> <h3 id="vtl-changes">VTL Changes<a class="headerlink" href="#vtl-changes" title="Permanent link">¶</a></h3> <ul> Modified: velocity/site/production/engine/devel/build.html URL: http://svn.apache.org/viewvc/velocity/site/production/engine/devel/build.html?rev=1871674&r1=1871673&r2=1871674&view=diff ============================================================================== --- velocity/site/production/engine/devel/build.html (original) +++ velocity/site/production/engine/devel/build.html Mon Dec 16 18:44:00 2019 @@ -224,7 +224,7 @@ 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="installation">Installation<a class="headerlink" href="#installation" title="Permanent link">¶</a></h2> -<p>Velocity runs on a variety of platforms that have installed the Java Virtual Machine. A Java Development Kit version 1.7+ is required to compile Velocity from its source code (as it is to run it).</p> +<p>Velocity runs on a variety of platforms that have installed the Java Virtual Machine. A Java Development Kit version 1.8+ is required to compile Velocity from its source code (as it is to run it).</p> <p>Everything required to build Velocity comes with the distribution, which can be obtained from <a href="http://svn.apache.org/repos/asf/velocity/engine/";>Subversion</a> or from the <a href="/download.cgi#engine">main distribution</a>. However, you will need to install <a href="http://maven.apache.org/";>Maven</a> to build the Velocity sources.</p> <p><a href="http://maven.apache.org/";>Maven</a> is also an Apache project. To build Apache Velocity, you need at least Version 3.0.5 of Apache Maven.</p> <h2 id="required-tools">Required Tools<a class="headerlink" href="#required-tools" title="Permanent link">¶</a></h2> @@ -238,9 +238,10 @@ mvn install <p>Executing this script will create a <strong>target</strong> directory within the velocity directory. Each subdirectory containing a module of Velocity will contain a "target" directory too, containing all built jars.</p> -<p>Refer to Maven documentation for all phases you can invoke.</p> +<p>After a successful build with the above command, your Velocity build will be available in your local Maven repository.</p> +<p>Refer to Maven documentation for alternate commands you can invoke.</p> <p>If you find a problem, do not hesitate to ask the Velocity community -via our <a href="/contact.html">mail lists</a>.</p></div></div> +via our <a href="/contact.html">email lists</a>.</p></div></div> <hr/> <div id="copyright"> Copyright © 2016 The Apache Software Foundation, Licensed under the <a href="http://www.apache.org/licenses/LICENSE-2.0";>Apache License, Version 2.0</a>.<br/>Apache and the Apache feather logo are trademarks of The Apache Software Foundation. Modified: velocity/site/production/engine/devel/changes.html URL: http://svn.apache.org/viewvc/velocity/site/production/engine/devel/changes.html?rev=1871674&r1=1871673&r2=1871674&view=diff ============================================================================== --- velocity/site/production/engine/devel/changes.html (original) +++ velocity/site/production/engine/devel/changes.html Mon Dec 16 18:44:00 2019 @@ -325,9 +325,16 @@ h2:hover > .headerlink, h3:hover > .head <tbody> <tr> <td> + <img src="images/add.png"/> + </td> + <td> Added BigInteger and BigDecimal implicit conversions . </td> + <td>cbrisson</td> + </tr> + <tr> + <td> <img src="images/fix.png"/> </td> - <td> Fix abnormal suppression of zero-width whitespaces . Fixes <a href="https://issues.apache.org/jira/browse/VELOCITY-919";>VELOCITY-919</a>. </td> + <td> Fixed abnormal suppression of zero-width whitespaces . Fixes <a href="https://issues.apache.org/jira/browse/VELOCITY-919";>VELOCITY-919</a>. </td> <td>cbrisson</td> </tr> <tr> Modified: velocity/site/production/engine/devel/configuration.html URL: http://svn.apache.org/viewvc/velocity/site/production/engine/devel/configuration.html?rev=1871674&r1=1871673&r2=1871674&view=diff ============================================================================== --- velocity/site/production/engine/devel/configuration.html (original) +++ velocity/site/production/engine/devel/configuration.html Mon Dec 16 18:44:00 2019 @@ -420,11 +420,11 @@ Defines the beginning and ending tags fo </blockquote> <p><strong><code>resource.manager.instance = null</code></strong></p> <blockquote> -<p>Living Java instance, that must implement the interface org.apache.velocity.runtime.resource.ResourceManager. This property can only be set programmatically, and takes precedence over the next property. It is otherwise used by Velocity to store its actual resource manager once instanciated.</p> +<p>Living Java instance, that must implement the <code>org.apache.velocity.runtime.resource.ResourceManager</code> interface. This property can only be set programmatically, and takes precedence over the next property. It is otherwise used by Velocity to store its actual resource manager once instanciated.</p> </blockquote> <p><strong><code>resource.manager.class = org.apache.velocity.runtime.resource.ResourceManagerImpl</code></strong></p> <blockquote> -<p>Replace the Velocity default Resource Manager class. A resource manager implementation must implement the (<code>org.apache.velocity.runtime.resource.ResourceManager</code>)[apidocs/org/apache/velocity/runtime/resource/ResourceManager.html] 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.</p> +<p>Replace the Velocity default Resource Manager class. A resource manager implementation must implement the <a href="apidocs/org/apache/velocity/runtime/resource/ResourceManager.html"><code>org.apache.velocity.runtime.resource.ResourceManager</code></a> 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.</p> </blockquote> <p>The following resource management configuration keys only apply to the default Resource Manager.</p> <p><strong><code>resource.manager.log_when_found = true</code></strong></p> @@ -433,7 +433,7 @@ Defines the beginning and ending tags fo </blockquote> <p><strong><code>resource.manager.cache.class = org.apache.velocity.runtime.resource.ResourceCacheImpl</code></strong></p> <blockquote> -<p>Replace the Velocity default Resource Cache class. A resource cache implementation must implement the (<code>org.apache.velocity.runtime.resource.ResourceCache</code>)[apidocs/org/apache/velocity/runtime/resource/ResourceCache.html] 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.</p> +<p>Replace the Velocity default Resource Cache class. A resource cache implementation must implement the <a href="apidocs/org/apache/velocity/runtime/resource/ResourceCache.html"><code>org.apache.velocity.runtime.resource.ResourceCache</code></a> 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.</p> </blockquote> <p><strong><code>resource.manager.cache.default_size = 89</code></strong></p> <blockquote> @@ -632,7 +632,7 @@ Defines the beginning and ending tags fo <h2 id="string-interning">String Interning<a class="headerlink" href="#string-interning" title="Permanent link">¶</a></h2> <p><strong><code>runtime.string_interning = true</code></strong></p> <blockquote> -<p>This property specifies whether to use Java (String interning)[https://en.wikipedia.org/wiki/String_interning] on identifiers. This may save some memory when set to true, and run a little bit faster when set to false.</p> +<p>This property specifies whether to use Java <a href="https://en.wikipedia.org/wiki/String_interning";>String interning</a> on identifiers. This may save some memory when set to true, and run a little bit faster when set to false.</p> </blockquote> <h2 id="space-gobbling">Space Gobbling<a class="headerlink" href="#space-gobbling" title="Permanent link">¶</a></h2> <p><strong><code>parser.space_gobbling = lines</code></strong></p> Modified: velocity/site/production/engine/devel/dependencies.html URL: http://svn.apache.org/viewvc/velocity/site/production/engine/devel/dependencies.html?rev=1871674&r1=1871673&r2=1871674&view=diff ============================================================================== --- velocity/site/production/engine/devel/dependencies.html (original) +++ velocity/site/production/engine/devel/dependencies.html Mon Dec 16 18:44:00 2019 @@ -241,7 +241,7 @@ h2:hover > .headerlink, h3:hover > .head <tbody> <tr> <td>slf4j-api</td> -<td>1.7.26</td> +<td>1.7.28</td> <td>Yes</td> <td>Yes</td> <td>Yes</td> @@ -265,7 +265,7 @@ h2:hover > .headerlink, h3:hover > .head </tr> <tr> <td>hsqldb</td> -<td>2.3.4</td> +<td>2.5.0</td> <td>No</td> <td>Yes</td> <td>No</td> @@ -281,7 +281,7 @@ h2:hover > .headerlink, h3:hover > .head </tr> <tr> <td>slf4j-simple</td> -<td>1.7.26</td> +<td>1.7.28</td> <td>No</td> <td>Yes</td> <td>No</td> Modified: velocity/site/production/engine/devel/developer-guide.html URL: http://svn.apache.org/viewvc/velocity/site/production/engine/devel/developer-guide.html?rev=1871674&r1=1871673&r2=1871674&view=diff ============================================================================== --- velocity/site/production/engine/devel/developer-guide.html (original) +++ velocity/site/production/engine/devel/developer-guide.html Mon Dec 16 18:44:00 2019 @@ -467,13 +467,15 @@ h2:hover > .headerlink, h3:hover > .head <p>Please note that like a Hashtable, the value must be derived from java.lang.Object, and must not be null. Fundamental types like int or float must be wrapped in the appropriate wrapper classes.</p> <p>That's really all there is to basic context operations. For more information, see the API documentation included in the distribution.</p> <h3 id="support-for-iterative-objects-for-foreach">Support for Iterative Objects for #foreach()<a class="headerlink" href="#support-for-iterative-objects-for-foreach" title="Permanent link">¶</a></h3> -<p>As a programmer, you have great freedom in the objects that you put into the context. But as with most freedoms, this one comes with a little bit of responsibility, so understand what Velocity supports, and any issues that may arise. Velocity supports serveral types of collection types suitable for use in the VTL <code>#foreach()</code> directive. -+ <code>Object []</code> Regular object array, not much needs to be said here. Velocity will internally wrap your array in a class that provides an Iterator interface, but that shouldn't concern you as the programmer, or the template author. Of more interest, is the fact that Velocity will now allow template authors to treat arrays as fixed-length lists. This means they may call methods like <code>size()</code>, <code>isEmpty()</code> and <code>get(int)</code> as well as the <code>empty</code> property on both arrays and standard java.util.List instances without concerning themselves about the difference. -+ <code>java.util.Collection</code> Velocity will use the <code>iterator()</code> method to get an Iterator to use in the loop, so if you are implementing a Collection interface on your object, please ensure that <code>iterator()</code> returns a working Iterator. -+ <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 <code>java.util.Iterable</code> interface.</p> +<p>As a programmer, you have great freedom in the objects that you put into the context. But as with most freedoms, this one comes with a little bit of responsibility, so understand what Velocity supports, and any issues that may arise. Velocity supports serveral types of collection types suitable for use in the VTL <code>#foreach()</code> directive:</p> +<ul> +<li><code>Object []</code> Regular object array, not much needs to be said here. Velocity will internally wrap your array in a class that provides an Iterator interface, but that shouldn't concern you as the programmer, or the template author. Of more interest, is the fact that Velocity will now allow template authors to treat arrays as fixed-length lists. This means they may call methods like <code>size()</code>, <code>isEmpty()</code> and <code>get(int)</code> as well as the <code>empty</code> property on both arrays and standard java.util.List instances without concerning themselves about the difference.</li> +<li><code>java.util.Collection</code> Velocity will use the <code>iterator()</code> method to get an Iterator to use in the loop, so if you are implementing a Collection interface on your object, please ensure that <code>iterator()</code> returns a working Iterator.</li> +<li><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.</li> +<li><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.</li> +<li><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.</li> +<li>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.</li> +</ul> <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><span class="n">Vector</span> <span class="n">v</span> <span class="o">=</span> <span class="k">new</span> <span class="n">Vector</span><span class="o">();</span> @@ -1045,7 +1047,7 @@ see the Javadoc API documentation.</p> </li> </ul> <p>The <a href="/tools/devel/">VelocityTools</a> project also defines a <a href="/tools/devel/apidocs/org/apache/velocity/tools/view/WebappResourceLoader.html">WebappResourceLoader</a>, active by default, which maps '/' to the root of the webapp.</p> -<p>Advanced users may also want to replace the Resource Manager or the Resource Cache: 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, it is possible to replace the default resource manager and resource cache with custom implementations. See the (related configuration options)[configuration.html#resource-management].</p> +<p>Advanced users may also want to replace the Resource Manager or the Resource Cache: 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, it is possible to replace the default resource manager and resource cache with custom implementations. See the <a href="configuration.html#resource-management">related configuration options</a>.</p> <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> @@ -1110,10 +1112,12 @@ see the Javadoc API documentation.</p> <p>When a reference has an alternate value provided, as in <code>${foo.bar|'foo'}</code>, whenever <code>$foo.bar</code> is invalid, the invalid reference handler will only be called if the alternate value is invalid.</p> -<p>There are three special cases where invalid reference events aren't triggered: -+ When the reference is a quiet reference (this behavior can be reverted to the 1.7 behavior using the backward compatibility flag <code>event_handler.invalid_references.quiet = true</code>). -+ when the reference is present in the context but has a null value, or the called method returned null (this behavior can be reverted to the 1.7 behavior using the backward compatibility flag <code>event_handler.invalid_references.null = true</code>). -+ when the reference is just tested for validity in an <code>#if()</code> statement (this behavior can be reverted to the 1.7 behavior using the backward compatibility flag <code>event_handler.invalid_references.tested = true</code>).</p> +<p>There are three special cases where invalid reference events aren't triggered:</p> +<ul> +<li>When the reference is a quiet reference (this behavior can be reverted to the 1.7 behavior using the backward compatibility flag <code>event_handler.invalid_references.quiet = true</code>).</li> +<li>when the reference is present in the context but has a null value, or the called method returned null (this behavior can be reverted to the 1.7 behavior using the backward compatibility flag <code>event_handler.invalid_references.null = true</code>).</li> +<li>when the reference is just tested for validity in an <code>#if()</code> statement (this behavior can be reverted to the 1.7 behavior using the backward compatibility flag <code>event_handler.invalid_references.tested = true</code>).</li> +</ul> <p>Available implementations include:</p> <ul> <li><code>org.apache.velocity.app.event.implement.ReportInvalidReferences</code><blockquote> @@ -1221,8 +1225,8 @@ see the Javadoc API documentation.</p> <h2 id="customizing-introspection">Customizing Introspection<a class="headerlink" href="#customizing-introspection" title="Permanent link">¶</a></h2> -<p>The [<code>runtime.introspector.uberspect</code> 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> +<p>The <a href="configuration.html#Pluggable-Introspection"><code>runtime.introspector.uberspect</code> configuration property</a> 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 <a href="apidocs/org/apache/velocity/util/introspection/package-summary.html"><code>org.apache.velocity.util.introspection</code></a> 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> @@ -1285,8 +1289,10 @@ see the Javadoc API documentation.</p> <th>Short</th> <th>Integer</th> <th>Long</th> + <th>BigInteger</th> <th>Float</th> <th>Double</th> + <th>BigDecimal</th> <th>Number</th> <th>String</th> <th>Object</th> @@ -1304,6 +1310,8 @@ see the Javadoc API documentation.</p> <td><span class="explicit">explicit</span></td> <td><span class="explicit">explicit</span></td> <td><span class="explicit">explicit</span></td> + <td><span class="explicit">explicit</span></td> + <td><span class="explicit">explicit</span></td> <td><span class="none">none</span></td> <td><span class="none">none</span></td> </tr> @@ -1321,17 +1329,21 @@ see the Javadoc API documentation.</p> <td><span class="none">none</span></td> <td><span class="none">none</span></td> <td><span class="none">none</span></td> + <td><span class="none">none</span></td> + <td><span class="none">none</span></td> </tr> <tr> <th>byte</th> <td><span class="explicit">explicit</span></td> <td><span class="none">none</span></td> - <td><span class="implicit">implicit</span></td> + <td><span class="strict">strict</span></td> + <td><span class="explicit">explicit</span></td> <td><span class="explicit">explicit</span></td> <td><span class="explicit">explicit</span></td> <td><span class="explicit">explicit</span></td> <td><span class="explicit">explicit</span></td> <td><span class="explicit">explicit</span></td> + <td><span class="none">none</span></td> <td><span class="explicit">explicit</span></td> <td><span class="explicit">explicit</span></td> <td><span class="none">none</span></td> @@ -1349,6 +1361,8 @@ see the Javadoc API documentation.</p> <td><span class="explicit">explicit</span></td> <td><span class="explicit">explicit</span></td> <td><span class="explicit">explicit</span></td> + <td><span class="explicit">explicit</span></td> + <td><span class="explicit">explicit</span></td> <td><span class="none">none</span></td> <td><span class="none">none</span></td> </tr> @@ -1364,6 +1378,8 @@ see the Javadoc API documentation.</p> <td><span class="explicit">explicit</span></td> <td><span class="explicit">explicit</span></td> <td><span class="explicit">explicit</span></td> + <td><span class="explicit">explicit</span></td> + <td><span class="explicit">explicit</span></td> <td><span class="none">none</span></td> <td><span class="none">none</span></td> </tr> @@ -1379,6 +1395,8 @@ see the Javadoc API documentation.</p> <td><span class="explicit">explicit</span></td> <td><span class="explicit">explicit</span></td> <td><span class="explicit">explicit</span></td> + <td><span class="explicit">explicit</span></td> + <td><span class="explicit">explicit</span></td> <td><span class="none">none</span></td> <td><span class="none">none</span></td> </tr> @@ -1390,10 +1408,12 @@ see the Javadoc API documentation.</p> <td><span class="implicit">implicit</span></td> <td><span class="implicit">implicit</span></td> <td><span class="implicit">implicit</span></td> + <td><span class="explicit">explicit</span></td> <td><span class="implicit">implicit</span></td> <td><span class="explicit">explicit</span></td> <td><span class="explicit">explicit</span></td> <td><span class="explicit">explicit</span></td> + <td><span class="explicit">explicit</span></td> <td><span class="none">none</span></td> <td><span class="none">none</span></td> </tr> @@ -1405,10 +1425,12 @@ see the Javadoc API documentation.</p> <td><span class="implicit">implicit</span></td> <td><span class="implicit">implicit</span></td> <td><span class="implicit">implicit</span></td> + <td><span class="explicit">explicit</span></td> <td><span class="implicit">implicit</span></td> <td><span class="implicit">implicit</span></td> <td><span class="explicit">explicit</span></td> <td><span class="explicit">explicit</span></td> + <td><span class="explicit">explicit</span></td> <td><span class="none">none</span></td> <td><span class="none">none</span></td> </tr> @@ -1424,6 +1446,8 @@ see the Javadoc API documentation.</p> <td><span class="explicit">explicit</span></td> <td><span class="explicit">explicit</span></td> <td><span class="explicit">explicit</span></td> + <td><span class="explicit">explicit</span></td> + <td><span class="explicit">explicit</span></td> <td><span class="none">none</span></td> <td><span class="strict">strict</span></td> </tr> @@ -1440,6 +1464,8 @@ see the Javadoc API documentation.</p> <td><span class="none">none</span></td> <td><span class="none">none</span></td> <td><span class="none">none</span></td> + <td><span class="none">none</span></td> + <td><span class="none">none</span></td> <td><span class="strict">strict</span></td> </tr> <tr> @@ -1454,6 +1480,8 @@ see the Javadoc API documentation.</p> <td><span class="explicit">explicit</span></td> <td><span class="explicit">explicit</span></td> <td><span class="explicit">explicit</span></td> + <td><span class="explicit">explicit</span></td> + <td><span class="explicit">explicit</span></td> <td><span class="none">none</span></td> <td><span class="strict">strict</span></td> </tr> @@ -1461,7 +1489,7 @@ see the Javadoc API documentation.</p> <th>Short</th> <td><span class="explicit">explicit</span></td> <td><span class="none">none</span></td> - <td><span class="none">none</span></td> + <td><span class="explicit">explicit</span></td> <td><span class="strict">strict</span></td> <td><span class="explicit">explicit</span></td> <td><span class="explicit">explicit</span></td> @@ -1469,6 +1497,8 @@ see the Javadoc API documentation.</p> <td><span class="explicit">explicit</span></td> <td><span class="explicit">explicit</span></td> <td><span class="explicit">explicit</span></td> + <td><span class="explicit">explicit</span></td> + <td><span class="explicit">explicit</span></td> <td><span class="none">none</span></td> <td><span class="strict">strict</span></td> </tr> @@ -1476,7 +1506,7 @@ see the Javadoc API documentation.</p> <th>Integer</th> <td><span class="explicit">explicit</span></td> <td><span class="none">none</span></td> - <td><span class="none">none</span></td> + <td><span class="explicit">explicit</span></td> <td><span class="explicit">explicit</span></td> <td><span class="strict">strict</span></td> <td><span class="explicit">explicit</span></td> @@ -1484,6 +1514,8 @@ see the Javadoc API documentation.</p> <td><span class="explicit">explicit</span></td> <td><span class="explicit">explicit</span></td> <td><span class="explicit">explicit</span></td> + <td><span class="explicit">explicit</span></td> + <td><span class="explicit">explicit</span></td> <td><span class="none">none</span></td> <td><span class="strict">strict</span></td> </tr> @@ -1491,7 +1523,7 @@ see the Javadoc API documentation.</p> <th>Long</th> <td><span class="explicit">explicit</span></td> <td><span class="none">none</span></td> - <td><span class="none">none</span></td> + <td><span class="explicit">explicit</span></td> <td><span class="explicit">explicit</span></td> <td><span class="explicit">explicit</span></td> <td><span class="strict">strict</span></td> @@ -1499,14 +1531,34 @@ see the Javadoc API documentation.</p> <td><span class="explicit">explicit</span></td> <td><span class="explicit">explicit</span></td> <td><span class="explicit">explicit</span></td> + <td><span class="explicit">explicit</span></td> + <td><span class="explicit">explicit</span></td> <td><span class="none">none</span></td> <td><span class="strict">strict</span></td> </tr> <tr> + <th>BigInteger</th> + <td><span class="none">none</span></td> + <td><span class="none">none</span></td> + <td><span class="explicit">explicit</span></td> + <td><span class="explicit">explicit</span></td> + <td><span class="explicit">explicit</span></td> + <td><span class="explicit">explicit</span></td> + <td><span class="strict">strict</span></td> + <td><span class="none">none</span></td> + <td><span class="none">none</span></td> + <td><span class="explicit">explicit</span></td> + <td><span class="none">none</span></td> + <td><span class="explicit">explicit</span></td> + <td><span class="none">none</span></td> + <td><span class="strict">strict</span></td> + </tr> + <tr> <th>Float</th> <td><span class="none">none</span></td> <td><span class="none">none</span></td> - <td><span class="none">none</span></td> + <td><span class="explicit">explicit</span></td> + <td><span class="explicit">explicit</span></td> <td><span class="explicit">explicit</span></td> <td><span class="explicit">explicit</span></td> <td><span class="explicit">explicit</span></td> @@ -1514,6 +1566,7 @@ see the Javadoc API documentation.</p> <td><span class="explicit">explicit</span></td> <td><span class="explicit">explicit</span></td> <td><span class="explicit">explicit</span></td> + <td><span class="explicit">explicit</span></td> <td><span class="none">none</span></td> <td><span class="strict">strict</span></td> </tr> @@ -1521,14 +1574,33 @@ see the Javadoc API documentation.</p> <th>Double</th> <td><span class="none">none</span></td> <td><span class="none">none</span></td> - <td><span class="none">none</span></td> <td><span class="explicit">explicit</span></td> <td><span class="explicit">explicit</span></td> <td><span class="explicit">explicit</span></td> <td><span class="explicit">explicit</span></td> + <td><span class="explicit">explicit</span></td> + <td><span class="explicit">explicit</span></td> + <td><span class="strict">strict</span></td> + <td><span class="explicit">explicit</span></td> + <td><span class="explicit">explicit</span></td> + <td><span class="explicit">explicit</span></td> + <td><span class="none">none</span></td> <td><span class="strict">strict</span></td> + </tr> + <tr> + <th>BigDecimal</th> + <td><span class="none">none</span></td> + <td><span class="none">none</span></td> + <td><span class="explicit">explicit</span></td> + <td><span class="explicit">explicit</span></td> <td><span class="explicit">explicit</span></td> <td><span class="explicit">explicit</span></td> + <td><span class="explicit">explicit</span></td> + <td><span class="explicit">explicit</span></td> + <td><span class="explicit">explicit</span></td> + <td><span class="strict">strict</span></td> + <td><span class="none">none</span></td> + <td><span class="explicit">explicit</span></td> <td><span class="none">none</span></td> <td><span class="strict">strict</span></td> </tr> @@ -1543,6 +1615,8 @@ see the Javadoc API documentation.</p> <td><span class="strict">strict</span></td> <td><span class="strict">strict</span></td> <td><span class="strict">strict</span></td> + <td><span class="strict">strict</span></td> + <td><span class="strict">strict</span></td> <td><span class="none">none</span></td> <td><span class="none">none</span></td> <td><span class="strict">strict</span></td> @@ -1558,6 +1632,8 @@ see the Javadoc API documentation.</p> <td><span class="explicit">explicit</span></td> <td><span class="explicit">explicit</span></td> <td><span class="explicit">explicit</span></td> + <td><span class="explicit">explicit</span></td> + <td><span class="explicit">explicit</span></td> <td><span class="strict">strict</span></td> <td><span class="explicit">explicit</span></td> <td><span class="strict">strict</span></td> @@ -1576,6 +1652,8 @@ see the Javadoc API documentation.</p> <td><span class="strict">strict</span></td> <td><span class="strict">strict</span></td> <td><span class="strict">strict</span></td> + <td><span class="strict">strict</span></td> + <td><span class="strict">strict</span></td> </tr> </thead> <tbody> @@ -1725,7 +1803,7 @@ see the Javadoc API documentation.</p> <h2 id="customizing-the-vtl-parser">Customizing the VTL parser<a class="headerlink" href="#customizing-the-vtl-parser" title="Permanent link">¶</a></h2> -<p>Since 2.2, a Velocity Engine can use a custom parser. You need to generate your custom parser class, let's say <code>com.foo.MyCustomParser</code>, by copy pasting the content of the <a href="https://repository.apache.org/content/repositories/snapshots/org/apache/velocity/velocity-custom-parser-example/2.2-SNAPSHOT/velocity-custom-parser-example-2.2-20190908.141659-1.pom";>velocity-custom-parser-example</a> maven module pom file inside one of your own modules pom.xml, and then adapting its <code><properties></code> section. There's a minimal maven knowledge required to understand what you are doing, but basically it boils down to do merge the content of the <code><properties></code>, <code><dependencies></code> and <code><build></code> sections in your target pom file.</p> +<p>Since 2.2, Velocity Engine can use a custom parser. You need to generate your custom parser class, let's say <code>com.foo.MyCustomParser</code>, by copy pasting the content of the <a href="https://repository.apache.org/content/repositories/snapshots/org/apache/velocity/velocity-custom-parser-example/2.2-SNAPSHOT/velocity-custom-parser-example-2.2-20190908.141659-1.pom";>velocity-custom-parser-example</a> maven module pom file inside one of your own modules pom.xml, and then adapting its <code><properties></code> section. There's a minimal maven knowledge required to understand what you are doing, but basically it boils down to do merge the content of the <code><properties></code>, <code><dependencies></code> and <code><build></code> sections in your target pom file.</p> <p>This custom parser will let you configure the following VTL characters:</p> <ul> <li><code>*</code> (used in <code>#*</code> multiline comments syntax)</li> Modified: velocity/site/production/engine/devel/upgrading.html URL: http://svn.apache.org/viewvc/velocity/site/production/engine/devel/upgrading.html?rev=1871674&r1=1871673&r2=1871674&view=diff ============================================================================== --- velocity/site/production/engine/devel/upgrading.html (original) +++ velocity/site/production/engine/devel/upgrading.html Mon Dec 16 18:44:00 2019 @@ -287,6 +287,7 @@ h2:hover > .headerlink, h3:hover > .head <li>The references with alternate values like <code>${foo|'foo'}</code> won't trigger any invalid reference event if their alternate value is valid.</li> <li>New <a href="configuration.html#logging"><code>runtime.log.track_location</code></a> debugging configuration flag (defaults to false). When true, logs VTL stacktrace on errors and populate slf4j template location MDC tags.</li> <li>New 1.7.x backward compatibility configuration flags for event handlers, see above section.</li> +<li>When active, the conversion handler will automatcally convert BigInteger and BigDecimal values towards/from expected method arguments types, see <a href="developer-guide.html#method-arguments-conversions">method arguments conversion</a>.</li> </ul> <h3 id="vtl-changes">VTL Changes<a class="headerlink" href="#vtl-changes" title="Permanent link">¶</a></h3> <ul> Modified: velocity/site/production/release-process.html URL: http://svn.apache.org/viewvc/velocity/site/production/release-process.html?rev=1871674&r1=1871673&r2=1871674&view=diff ============================================================================== --- velocity/site/production/release-process.html (original) +++ velocity/site/production/release-process.html Mon Dec 16 18:44:00 2019 @@ -294,17 +294,40 @@ h2:hover > .headerlink, h3:hover > .head <p>These steps must be performed <strong>for each</strong> release.</p> <ul> <li> -<p>Check dependencies and velocity-parent versions</p> +<p>Check updates of dependencies and maven plugins:</p> +<div class="codehilite"><pre>mvn versions:display-dependency-updates +mvn versions:display-plugin-updates +</pre></div> + + +</li> +<li> +<p>Check content of root README.md file (for new features documentation, important notices, and stated dependencies versions).</p> +</li> +<li> +<p>Also check updates for the parent velocity-master artifact version.</p> </li> <li> <p>Archive the previous release candidate</p> <p>If it's not the first release candidate you're trying to release, you should archive the previous release candidate. For instance:</p> -<div class="codehilite"><pre>svn mv ci -m <span class="s2">"[engine] archive engine 2.0 RC4"</span> https://[email protected]/repos/asf/velocity/engine/tags/2.0 https://[email protected]/repos/asf/velocity/engine/tags/2.0-RC4 +<div class="codehilite"><pre>svn mv -m <span class="s2">"[engine] archive engine 2.0 RC4"</span> https://[email protected]/repos/asf/velocity/engine/tags/2.0 https://[email protected]/repos/asf/velocity/engine/tags/2.0-RC4 </pre></div> <p>And don't forget to also drop the staged artifact.</p> -<p>Of course, you will also have to revert the automated commits from the previous <code>mvn release:*</code> commands.</p> +<p>Of course, you will also have to revert the automated commits from the previous <code>mvn release:*</code> commands. You can use the following shell one-liner to get their revision numbers:</p> +<div class="codehilite"><pre>$ svn log pom.xml <span class="p">|</span> grep -B2 maven-release-plugin <span class="p">|</span> egrep <span class="s2">"^r"</span> <span class="p">|</span> head -2 <span class="p">|</span> cut -d<span class="s1">' '</span> -f <span class="m">1</span> +r1866626 +r1866624 +</pre></div> + + +<p>Then, revert:</p> +<div class="codehilite"><pre>svn merge -r1866626:1866623 . +svn commit -m "[engine/tools] Revert poms for next 2.2 RC attempt" +</pre></div> + + </li> <li> <p>Complete and update the changelog source file <code>src/changes/changes.xml</code> (note: we may get rid of this changelog in the future since it is quite painful to maintain and seems highly redundant with the JIRA release notes).</p> @@ -317,7 +340,7 @@ you are preparing the release and type:< </pre></div> -<p>The plugin interactively will ask you the version to release, the Subversion tag to use and the next snapshot version. Rather than <code>velocity-engine-parent-X.X</code> (the default), we tend to use X.X for the tag name.</p> +<p>The plugin will interactively ask you the version to release, the subversion tag to use and the next snapshot version. Rather than the proposed default <code>velocity-engine-parent-X.X</code>, we tend to use X.X for the subversion tag.</p> </li> <li> <p>Perform the release</p> @@ -376,7 +399,7 @@ you are preparing the release and type:< </li> <li> <p>Prepare the site</p> -<p>Copy the <code>/devel/</code> section to its <code><version></code> section (but do not yet refence it from the menu)</p> +<p>Copy the <code>/devel/</code> section to its <code><version></code> section (but do not yet refence it from the menu), and fix any SNAPSHOT link within.</p> <p>Generate the corresponding javadoc with</p> <div class="codehilite"><pre>mvn javadoc:aggregate </pre></div> Modified: velocity/site/production/site-building.html URL: http://svn.apache.org/viewvc/velocity/site/production/site-building.html?rev=1871674&r1=1871673&r2=1871674&view=diff ============================================================================== --- velocity/site/production/site-building.html (original) +++ velocity/site/production/site-building.html Mon Dec 16 18:44:00 2019 @@ -231,7 +231,8 @@ h2:hover > .headerlink, h3:hover > .head <li><a href="#introduction">Introduction</a></li> <li><a href="#editing-the-site">Editing the Site</a></li> <li><a href="#building-the-site">Building the Site</a></li> -<li><a href="#additional-notes">Additional Notes</a><ul> +<li><a href="#additional-notes">Additional Notes</a></li> +<li><a href="#javadocs">Javadocs</a><ul> <li><a href="#table-of-content">Table of Content</a></li> <li><a href="#tables">Tables</a></li> <li><a href="#syntax-highlighting">Syntax highlighting</a></li> @@ -318,6 +319,14 @@ svn status <span class="nv">$VELOCITY</s <li>the python pygments lexer (used by markdown/codehilite for code syntax highlighting) knows about the Velocity syntax, but not about silent references like <code>$!foo</code> or <code>$!{bar}</code>. I patched it and sent the <a href="https://bitbucket.org/birkenfeld/pygments-main/pull-requests/771/add-velocity-silent-references-syntax/diff";>patch</a> upstream.</li> </ul> <h3 id="additional-notes">Additional Notes<a class="headerlink" href="#additional-notes" title="Permanent link">¶</a></h3> +<h3 id="javadocs">Javadocs<a class="headerlink" href="#javadocs" title="Permanent link">¶</a></h3> +<p>For the time being, here are the steps to build the javadocs (listed for the engine, adapt for the tools):</p> +<ol> +<li>issue an <code>mvn javadoc:aggregate -pl !velocity-custom-parser-example</code> command at the root of the source tree (the <code>-pl</code> option is here to ignore a specific module from the docs)</li> +<li>copy the content of the <code>target/site/apidocs</code> directory inside of the <code>apidocs</code> directory of the apropriate module inside the site sources</li> +<li>commit this result (which will produce a first big fat commit email...)</li> +<li>generate the site then commit the production result (second horrible commit email...)</li> +</ol> <h4 id="table-of-content">Table of Content<a class="headerlink" href="#table-of-content" title="Permanent link">¶</a></h4> <p>Per-page table of contents can be displayed with the following placeholder:</p> <div class="codehilite"><pre>[TOC]
