You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@velocity.apache.org by cb...@apache.org on 2019/06/06 00:29:08 UTC
svn commit: r1860693 - in /velocity/site/cms/trunk/content/engine/devel:
configuration.mdtext developer-guide.mdtext upgrading.mdtext
Author: cbrisson
Date: Thu Jun 6 00:29:08 2019
New Revision: 1860693
URL: http://svn.apache.org/viewvc?rev=1860693&view=rev
Log:
[engine][site] Document last changes
Modified:
velocity/site/cms/trunk/content/engine/devel/configuration.mdtext
velocity/site/cms/trunk/content/engine/devel/developer-guide.mdtext
velocity/site/cms/trunk/content/engine/devel/upgrading.mdtext
Modified: velocity/site/cms/trunk/content/engine/devel/configuration.mdtext
URL: http://svn.apache.org/viewvc/velocity/site/cms/trunk/content/engine/devel/configuration.mdtext?rev=1860693&r1=1860692&r2=1860693&view=diff
==============================================================================
--- velocity/site/cms/trunk/content/engine/devel/configuration.mdtext (original)
+++ velocity/site/cms/trunk/content/engine/devel/configuration.mdtext Thu Jun 6 00:29:08 2019
@@ -36,7 +36,10 @@ The following tree gathers all non depre
+-- parse.max_depth = 10
event_handler. +-- include.class = *classname*, *classname* ...
- +-- invalid_reference.class = *classname*, *classname* ...
+ +-- invalid_reference. +-- class = *classname*, *classname* ...
+ +-- null = false
+ +-- quiet = false
+ +-- tested = false
+-- method_exception.class = *classname*, *classname* ...
+-- reference_insertion.class = *classname*, *classname* ...
@@ -306,6 +309,15 @@ See the [Event Handlers](developer-guide
**`event_handler.invalid_reference.class`** = *classname*, *classname* ...
> register an [invalid reference event handler](apidocs/org/apache/velocity/app/event/InvalidReferenceEventHandler.html).
+**`event_handler.invalid_reference.null`** = `false`
+> make registered event handlers receive events whenever the reference value is present in the context but has a null value, or if a method call returned null.
+
+**`event_handler.invalid_reference.quiet`** = `false`
+> make registered event handlers receive events whenever the invalid reference is a quiet reference.
+
+**`event_handler.invalid_reference.tested`** = `false`
+> make registered event handlers receive events whenever the invalid reference is just tested for validity in an `#if()` statement.
+
**`event_handler.method_exception.class`** = *classname*, *classname* ...
> register a [method exception event handler](apidocs/org/apache/velocity/app/event/MethodExceptionEventHandler.html).
Modified: velocity/site/cms/trunk/content/engine/devel/developer-guide.mdtext
URL: http://svn.apache.org/viewvc/velocity/site/cms/trunk/content/engine/devel/developer-guide.mdtext?rev=1860693&r1=1860692&r2=1860693&view=diff
==============================================================================
--- velocity/site/cms/trunk/content/engine/devel/developer-guide.mdtext (original)
+++ velocity/site/cms/trunk/content/engine/devel/developer-guide.mdtext Thu Jun 6 00:29:08 2019
@@ -917,11 +917,17 @@ All event handler interfaces available i
> Info info);
> }
>
-> When a reference has an alternate value provided, as in `${foo.bar|'foo'}`, whenever `$foo.bar` is invalid, the invalid reference handler is called **before** the alternate value (and the alternate value will be used only if the value returned by the handler evaluates to null, false, empty or zero).
+> When a reference has an alternate value provided, as in `${foo.bar|'foo'}`, whenever `$foo.bar` is invalid, the invalid reference handler will only be called if the alternate value is invalid.
+>
+> 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 `event_handler.invalid_references.quiet = true`).
+> + 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 `event_handler.invalid_references.null = true`).
+> + when the reference is just tested for validity in an `#if()` statement (this behavior can be reverted to the 1.7 behavior using the backward compatibility flag `event_handler.invalid_references.tested = true`).
>
> Available implementations include:
>
> + `org.apache.velocity.app.event.implement.ReportInvalidReferences`
+> > This event handler defines the `event_handler.invalid_references.exception` configuration flag (defaults to false). When true, the first encountered invalid reference will throw an exception.
### `org.apache.velocity.app.event.MethodExceptionEventHandler`
Modified: velocity/site/cms/trunk/content/engine/devel/upgrading.mdtext
URL: http://svn.apache.org/viewvc/velocity/site/cms/trunk/content/engine/devel/upgrading.mdtext?rev=1860693&r1=1860692&r2=1860693&view=diff
==============================================================================
--- velocity/site/cms/trunk/content/engine/devel/upgrading.mdtext (original)
+++ velocity/site/cms/trunk/content/engine/devel/upgrading.mdtext Thu Jun 6 00:29:08 2019
@@ -8,6 +8,49 @@ Title: Apache Velocity Engine - Upgradin
Release with the same major number (1.x, 2.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.
+## Upgrading from Velocity 2.1 to Velocity 2.2
+
+For busy people: To maximize backward compatibility of Velocity 2.2 with Velocity 1.x, be sure to include the following lines in your Velocity configuration:
+
+ :::properties
+ # No automatic conversion of methods arguments
+ introspector.conversion_handler.class = none
+
+ # Use backward compatible space gobbling
+ parser.space_gobbling = bc
+
+ # Have #if($foo) only returns false if $foo is false or null
+ directive.if.empty_check = false
+
+ # Allow '-' in identifiers (since 2.1)
+ parser.allow_hyphen_in_identifiers = true
+
+ # When displaying null arguments literals, use provided arguments literals (since 2.1)
+ velocimacro.arguments.preserve_literals = true
+
+ # When using an invalid reference handler, also include quiet references (since 2.2)
+ event_handler.invalid_references.quiet = true
+
+ # When using an invalid reference handler, also include null references (since 2.2)
+ event_handler.invalid_references.null = true
+
+ # When using an invalid reference handler, also include tested references (since 2.2)
+ event_handler.invalid_references.tested = true
+
+Also, please note that since version 2.1, Velocity requires Java JDK 1.8+ for bulding and Java JRE 1.8+ at runtime.
+
+### Behavior / API Changes
+
++ The references with alternate values like `${foo|'foo'}` won't trigger any invalid reference event if their alternate value os valid.
+
+### VTL Changes
+
+(none)
+
+### Dependency Changes
+
+TODO
+
## Upgrading from Velocity 2.0 to Velocity 2.1
For busy people: To maximize backward compatibility of Velocity 2.1 with Velocity 1.x, be sure to include the following lines in your Velocity configuration:
@@ -28,7 +71,7 @@ For busy people: To maximize backward co
# When displaying null arguments literals, use provided arguments literals (since 2.1)
velocimacro.arguments.preserve_literals = true
-Also, please note that Velocity 2.1 now requires Java JDK 1.8 for bulding and Java JRE 1.8 at runtime.
+Also, please note that Velocity 2.1 now requires Java JDK 1.8+ for bulding and Java JRE 1.8+ at runtime.
### Behavior / API Changes