From commits-return-3812-archive-asf-public=cust-asf.ponee.io@velocity.apache.org Thu Jun 6 00:29:11 2019 Return-Path: X-Original-To: archive-asf-public@cust-asf.ponee.io Delivered-To: archive-asf-public@cust-asf.ponee.io Received: from mail.apache.org (hermes.apache.org [207.244.88.153]) by mx-eu-01.ponee.io (Postfix) with SMTP id E59C318065D for ; Thu, 6 Jun 2019 02:29:10 +0200 (CEST) Received: (qmail 33103 invoked by uid 500); 6 Jun 2019 00:29:10 -0000 Mailing-List: contact commits-help@velocity.apache.org; run by ezmlm Precedence: bulk List-Help: List-Unsubscribe: List-Post: List-Id: Reply-To: dev@velocity.apache.org Delivered-To: mailing list commits@velocity.apache.org Received: (qmail 33094 invoked by uid 99); 6 Jun 2019 00:29:10 -0000 Received: from Unknown (HELO svn01-us-west.apache.org) (209.188.14.144) by apache.org (qpsmtpd/0.29) with ESMTP; Thu, 06 Jun 2019 00:29:10 +0000 Received: from svn01-us-west.apache.org (localhost [127.0.0.1]) by svn01-us-west.apache.org (ASF Mail Server at svn01-us-west.apache.org) with ESMTP id 05C853A0826 for ; Thu, 6 Jun 2019 00:29:08 +0000 (UTC) Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit 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 -0000 To: commits@velocity.apache.org From: cbrisson@apache.org X-Mailer: svnmailer-1.0.9 Message-Id: <20190606002909.05C853A0826@svn01-us-west.apache.org> 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