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
