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/03/03 14:30:12 UTC
svn commit: r1854721 - in /velocity/site/cms/trunk/content/engine:
2.1/configuration.mdtext 2.1/developer-guide.mdtext 2.1/upgrading.mdtext
devel/configuration.mdtext devel/developer-guide.mdtext
devel/upgrading.mdtext
Author: cbrisson
Date: Sun Mar 3 14:30:12 2019
New Revision: 1854721
URL: http://svn.apache.org/viewvc?rev=1854721&view=rev
Log:
[site] Document deprecation of ConversionHandler in favor of TypeConversionHandler
Modified:
velocity/site/cms/trunk/content/engine/2.1/configuration.mdtext
velocity/site/cms/trunk/content/engine/2.1/developer-guide.mdtext
velocity/site/cms/trunk/content/engine/2.1/upgrading.mdtext
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/2.1/configuration.mdtext
URL: http://svn.apache.org/viewvc/velocity/site/cms/trunk/content/engine/2.1/configuration.mdtext?rev=1854721&r1=1854720&r2=1854721&view=diff
==============================================================================
--- velocity/site/cms/trunk/content/engine/2.1/configuration.mdtext (original)
+++ velocity/site/cms/trunk/content/engine/2.1/configuration.mdtext Sun Mar 3 14:30:12 2019
@@ -275,13 +275,16 @@ Introspection is the process of mapping
>
> Some alternate Uberspectors are provided within the Velocity package. Please refer to the [Customizing Introspection](developer-guide.html#customizing-introspection) section for a detailed list. You would for instance use `runtime.introspector.uberspect = org.apache.velocity.util.introspection.SecureUberspector` to avoid template authors to instanciate new classes or to use reflection, or use `runtime.introspector.uberspect = org.apache.velocity.util.introspection.UberspectImpl, org.apache.velocity.util.introspection.UberspectPublicFields` to expose Java public fields in your templates.
-**`runtime.conversion.handler.class = org.apache.velocity.util.introspection.ConversionHandlerImpl`**
+**`runtime.conversion.handler.class = org.apache.velocity.util.introspection.TypeConversionHandlerImpl`**
> This configuration option is only taken into account by the default uberspector (UberspectImpl) and its subclasses (like SecureUberspector). It can be set to:
>
>- `none`: the only accepted conversions for method arguments will be the ones accepted by Java, typically widening number conversions. This reflects the behavior of Velocity 1.x.
->- *classname*: the name of a class implementing the interface [org.apache.velocity.util.introspection.ConversionHandler](apidocs/org/apache/velocity/util/introspection/ConversionHandler.html).
+>- *classname*: the name of a class implementing the interface [org.apache.velocity.util.introspection.TypeConversionHandler](apidocs/org/apache/velocity/util/introspection/TypeConversionHandler.html) or the deprecated (since 2.1) interface [org.apache.velocity.util.introspection.ConversionHandler](apidocs/org/apache/velocity/util/introspection/ConversionHandler.html).
>
-> The default conversion handler will try to convert values between all number, boolean and string types. Failed conversions will throw a MethodInvocationException (or call the registered MethodExceptionEventHandler, if any). Watch out for conversions towards boolean: non-zero numbers and the "true" String are true, everything else is false. This differs slighly from the `#if($reference)` truthness rules, where all non-null numbers and all non-null and non-empty strings are true.
+> The default conversion handler will try to convert values between all number, boolean and string types (along with a Locale to string conversion since 2.1). Failed conversions will throw a MethodInvocationException (or call the registered MethodExceptionEventHandler, if any). Watch out for conversions towards boolean: non-zero numbers and the "true" String are true, everything else is false. This differs slighly from the `#if($reference)` truthness rules, where all non-null numbers and all non-null and non-empty strings are true.
+
+**`runtime.conversion.handler.instance`** = *Java Object instance*
+> This configuration option is only taken into account by the default uberspector (UberspectImpl) and its subclasses (like SecureUberspector). It can be set to a living Java instance of an object implementing the interface [org.apache.velocity.util.introspection.TypeConversionHandler](apidocs/org/apache/velocity/util/introspection/TypeConversionHandler.html) or the deprecated (since 2.1) interface [org.apache.velocity.util.introspection.ConversionHandler](apidocs/org/apache/velocity/util/introspection/ConversionHandler.html).
## Context
Modified: velocity/site/cms/trunk/content/engine/2.1/developer-guide.mdtext
URL: http://svn.apache.org/viewvc/velocity/site/cms/trunk/content/engine/2.1/developer-guide.mdtext?rev=1854721&r1=1854720&r2=1854721&view=diff
==============================================================================
--- velocity/site/cms/trunk/content/engine/2.1/developer-guide.mdtext (original)
+++ velocity/site/cms/trunk/content/engine/2.1/developer-guide.mdtext Sun Mar 3 14:30:12 2019
@@ -1402,7 +1402,9 @@ You can also provide custom [`Converter<
}
}
-You'll then need to register your uberspector with `runtime.introspection.uberspect = mypackage.MyUberspector`. Another approach would be to inherit from ConversionHandlerImpl, add converters within its constructor and register your conversion handler using the `runtime.conversion.handler` configuration property.
+You'll then need to register your uberspector with `runtime.introspection.uberspect = mypackage.MyUberspector`. Another approach would be to inherit from `org.apache.util.introspection.TypeConversionHandlerImpl`, add converters within its constructor and register your conversion handler using the `runtime.conversion.handler.class` configuration property, or to directly provide Velocity with a living instance of a `org.apache.util.introspection.TypeConversionHandler` using the `runtime.conversion.handler.instance` configuration property.
+
+*Velocity Engine 2.0 backward compatibility note*: the [`org.apache.util.introspection.ConversionHandler`](apidocs/org/apache/velocity/util/introspection/ConversionHandler.html) interface has been deprecated in favor of the [`org.apache.util.introspection.TypeConversionHandler`](apidocs/org/apache/velocity/util/introspection/TypeConversionHandler.html) interface. The new interface let one specify converters towards a `java.lang.reflect.Type` rather than a `java.lang.class`.
## Template Encoding for Internationalization
Modified: velocity/site/cms/trunk/content/engine/2.1/upgrading.mdtext
URL: http://svn.apache.org/viewvc/velocity/site/cms/trunk/content/engine/2.1/upgrading.mdtext?rev=1854721&r1=1854720&r2=1854721&view=diff
==============================================================================
--- velocity/site/cms/trunk/content/engine/2.1/upgrading.mdtext (original)
+++ velocity/site/cms/trunk/content/engine/2.1/upgrading.mdtext Sun Mar 3 14:30:12 2019
@@ -57,6 +57,7 @@ Read below for futher details.
+ the `UberspectLoggable` interface has been removed.
+ the `directive.if.tostring.nullcheck` configuration property has been superseded by the `directive.if.emptycheck` property, which defaults to true. It means that all empty objects (strings and collections) as long as zero numbers, do evaluate to false (see the complete [boolean context evaluation](configuration.html#if-directive) rules.). You may want to set `directive.if.emptycheck` to false to maximize backward compatibility with 1.x.
+ inside a macro, the rendering of null arguments uses the local reference literal - to revert to the 1.7 behavior, you can set the boolean property `velocimacro.preserve.arguments.literals` to true (since 2.1). The macros will then use the provided argument literals in such cases.
++ since 2.1, the [`org.apache.util.introspection.ConversionHandler`](apidocs/org/apache/velocity/util/introspection/ConversionHandler.html) interface has been deprecated in favor of the [`org.apache.util.introspection.TypeConversionHandler`](apidocs/org/apache/velocity/util/introspection/TypeConversionHandler.html) interface. The new interface let one specify converters towards a `java.lang.reflect.Type` rather than a `java.lang.class`.
### VTL Changes:
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=1854721&r1=1854720&r2=1854721&view=diff
==============================================================================
--- velocity/site/cms/trunk/content/engine/devel/configuration.mdtext (original)
+++ velocity/site/cms/trunk/content/engine/devel/configuration.mdtext Sun Mar 3 14:30:12 2019
@@ -275,13 +275,16 @@ Introspection is the process of mapping
>
> Some alternate Uberspectors are provided within the Velocity package. Please refer to the [Customizing Introspection](developer-guide.html#customizing-introspection) section for a detailed list. You would for instance use `runtime.introspector.uberspect = org.apache.velocity.util.introspection.SecureUberspector` to avoid template authors to instanciate new classes or to use reflection, or use `runtime.introspector.uberspect = org.apache.velocity.util.introspection.UberspectImpl, org.apache.velocity.util.introspection.UberspectPublicFields` to expose Java public fields in your templates.
-**`runtime.conversion.handler.class = org.apache.velocity.util.introspection.ConversionHandlerImpl`**
+**`runtime.conversion.handler.class = org.apache.velocity.util.introspection.TypeConversionHandlerImpl`**
> This configuration option is only taken into account by the default uberspector (UberspectImpl) and its subclasses (like SecureUberspector). It can be set to:
>
>- `none`: the only accepted conversions for method arguments will be the ones accepted by Java, typically widening number conversions. This reflects the behavior of Velocity 1.x.
->- *classname*: the name of a class implementing the interface [org.apache.velocity.util.introspection.ConversionHandler](apidocs/org/apache/velocity/util/introspection/ConversionHandler.html).
+>- *classname*: the name of a class implementing the interface [org.apache.velocity.util.introspection.TypeConversionHandler](apidocs/org/apache/velocity/util/introspection/TypeConversionHandler.html) or the deprecated (since 2.1) interface [org.apache.velocity.util.introspection.ConversionHandler](apidocs/org/apache/velocity/util/introspection/ConversionHandler.html).
>
-> The default conversion handler will try to convert values between all number, boolean and string types. Failed conversions will throw a MethodInvocationException (or call the registered MethodExceptionEventHandler, if any). Watch out for conversions towards boolean: non-zero numbers and the "true" String are true, everything else is false. This differs slighly from the `#if($reference)` truthness rules, where all non-null numbers and all non-null and non-empty strings are true.
+> The default conversion handler will try to convert values between all number, boolean and string types (along with a Locale to string conversion since 2.1). Failed conversions will throw a MethodInvocationException (or call the registered MethodExceptionEventHandler, if any). Watch out for conversions towards boolean: non-zero numbers and the "true" String are true, everything else is false. This differs slighly from the `#if($reference)` truthness rules, where all non-null numbers and all non-null and non-empty strings are true.
+
+**`runtime.conversion.handler.instance`** = *Java Object instance*
+> This configuration option is only taken into account by the default uberspector (UberspectImpl) and its subclasses (like SecureUberspector). It can be set to a living Java instance of an object implementing the interface [org.apache.velocity.util.introspection.TypeConversionHandler](apidocs/org/apache/velocity/util/introspection/TypeConversionHandler.html) or the deprecated (since 2.1) interface [org.apache.velocity.util.introspection.ConversionHandler](apidocs/org/apache/velocity/util/introspection/ConversionHandler.html).
## Context
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=1854721&r1=1854720&r2=1854721&view=diff
==============================================================================
--- velocity/site/cms/trunk/content/engine/devel/developer-guide.mdtext (original)
+++ velocity/site/cms/trunk/content/engine/devel/developer-guide.mdtext Sun Mar 3 14:30:12 2019
@@ -1402,7 +1402,9 @@ You can also provide custom [`Converter<
}
}
-You'll then need to register your uberspector with `runtime.introspection.uberspect = mypackage.MyUberspector`. Another approach would be to inherit from ConversionHandlerImpl, add converters within its constructor and register your conversion handler using the `runtime.conversion.handler` configuration property.
+You'll then need to register your uberspector with `runtime.introspection.uberspect = mypackage.MyUberspector`. Another approach would be to inherit from `org.apache.util.introspection.TypeConversionHandlerImpl`, add converters within its constructor and register your conversion handler using the `runtime.conversion.handler.class` configuration property, or to directly provide Velocity with a living instance of a `org.apache.util.introspection.TypeConversionHandler` using the `runtime.conversion.handler.instance` configuration property.
+
+*Velocity Engine 2.0 backward compatibility note*: the [`org.apache.util.introspection.ConversionHandler`](apidocs/org/apache/velocity/util/introspection/ConversionHandler.html) interface has been deprecated in favor of the [`org.apache.util.introspection.TypeConversionHandler`](apidocs/org/apache/velocity/util/introspection/TypeConversionHandler.html) interface. The new interface let one specify converters towards a `java.lang.reflect.Type` rather than a `java.lang.class`.
## Template Encoding for Internationalization
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=1854721&r1=1854720&r2=1854721&view=diff
==============================================================================
--- velocity/site/cms/trunk/content/engine/devel/upgrading.mdtext (original)
+++ velocity/site/cms/trunk/content/engine/devel/upgrading.mdtext Sun Mar 3 14:30:12 2019
@@ -57,6 +57,7 @@ Read below for futher details.
+ the `UberspectLoggable` interface has been removed.
+ the `directive.if.tostring.nullcheck` configuration property has been superseded by the `directive.if.emptycheck` property, which defaults to true. It means that all empty objects (strings and collections) as long as zero numbers, do evaluate to false (see the complete [boolean context evaluation](configuration.html#if-directive) rules.). You may want to set `directive.if.emptycheck` to false to maximize backward compatibility with 1.x.
+ inside a macro, the rendering of null arguments uses the local reference literal - to revert to the 1.7 behavior, you can set the boolean property `velocimacro.preserve.arguments.literals` to true (since 2.1). The macros will then use the provided argument literals in such cases.
++ since 2.1, the [`org.apache.util.introspection.ConversionHandler`](apidocs/org/apache/velocity/util/introspection/ConversionHandler.html) interface has been deprecated in favor of the [`org.apache.util.introspection.TypeConversionHandler`](apidocs/org/apache/velocity/util/introspection/TypeConversionHandler.html) interface. The new interface let one specify converters towards a `java.lang.reflect.Type` rather than a `java.lang.class`.
### VTL Changes: