velocity-commits mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From cbris...@apache.org
Subject svn commit: r1860693 - in /velocity/site/cms/trunk/content/engine/devel: configuration.mdtext developer-guide.mdtext upgrading.mdtext
Date Thu, 06 Jun 2019 00:29:08 GMT
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
 



Mime
View raw message