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:
