velocity-commits mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From cbris...@apache.org
Subject svn commit: r1754153 - in /velocity/site/cms/trunk/content/engine: devel/configuration.mdtext devel/developer-guide.mdtext devel/left.nav devel/upgrading.mdtext devel/user-guide.mdtext index.mdtext
Date Tue, 26 Jul 2016 16:21:03 GMT
Author: cbrisson
Date: Tue Jul 26 16:21:03 2016
New Revision: 1754153

URL: http://svn.apache.org/viewvc?rev=1754153&view=rev
Log:
[site] review configuration and dev guide pages, document new conversion handler feature

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/left.nav
    velocity/site/cms/trunk/content/engine/devel/upgrading.mdtext
    velocity/site/cms/trunk/content/engine/devel/user-guide.mdtext
    velocity/site/cms/trunk/content/engine/index.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=1754153&r1=1754152&r2=1754153&view=diff
==============================================================================
--- velocity/site/cms/trunk/content/engine/devel/configuration.mdtext (original)
+++ velocity/site/cms/trunk/content/engine/devel/configuration.mdtext Tue Jul 26 16:21:03
2016
@@ -18,21 +18,21 @@ Below are listed the configuration keys
 
 ## Logging
 
-`runtime.log.instance = *Java Object instance*`
+**`runtime.log.instance`** = *Java Object instance*
 
 > Living Java instance, that must implement the interface org.slf4j.Logger. This property
can only be set programmatically. By default, Velocity uses the SLF4J static discovery mechanism,
see the [Logging](developer-guide.html#logging) section in the dev guide.
 
-`runtime.log.name = Velocity`
+**`runtime.log.name = Velocity`**
 
 > If no living Logger instance has been given using the previous property, Velocity will
get a Logger object using the provided name.
 
-`runtime.log.invalid.references = true`
+**`runtime.log.invalid.references = true`**
 
 > Property to turn off the log output when a reference isn't valid. Good thing to turn
off in production, but very valuable for debugging.
 
 ## Character Encoding
 
-`input.encoding = UTF-8`
+**`input.encoding = UTF-8`**
 
 > Character encoding for input (templates). If not specified, Velocity relies on the 'file.encoding'
system property.
 
@@ -40,92 +40,98 @@ Below are listed the configuration keys
 
 ### #define() Directive
 
-`define.provide.scope.control = false`
+**`define.provide.scope.control = false`**
 
 > Used to turn on the automatic provision of the $define scope control during #define()
calls. The default is false. Set it to true if you want a local, managed namespace you can
put references in when within a #define block or if you want it for more advanced #break usage.
 
 ### #evaluate() Directive
 
-`evaluate.provide.scope.control = false`
+**`evaluate.provide.scope.control = false`**
 
 > Used to turn on the automatic provision of the $evaluate scope during #evaluate() or
Velocity[Engine].evaluate(...) calls. The default is false.  Set it to true if you want a
local, managed namespace you can put references in during an evaluation or if you want it
for more advanced #break usage.
 
 ### #foreach() Directive
 
-`foreach.provide.scope.control = true`
+**`foreach.provide.scope.control = true`**
 
 > Used to control the automatic provision of the $foreach scope during #foreach calls.
 This gives access to the foreach status information (e.g. $foreach.index or $foreach.hasNext).
The default is true. Set it to false if unused and you want a tiny performance boost.
 
-`directive.foreach.maxloops = -1`
+**`directive.foreach.maxloops = -1`**
 
 > Maximum allowed number of loops for a #foreach() statement.
 
-`directive.foreach.skip.invalid = true`
+**`directive.foreach.skip.invalid = true`**
 
 > Tells #foreach to simply skip rendering when the object it is iterating over is not
or cannot produce a valid Iterator.
 
 ### #if() Directive
 
-`directive.if.tostring.nullcheck = true`
+**`directive.if.tostring.nullcheck = true`**
 
 > Default behavior is to check return value of toString() and treat an object with toString()
that returns null as null. If all objects have toString() methods that never return null,
this check is unnecessary and can be disabled to gain performance. In Velocity 1.5, no such
null check was performed.
 
 ### #set() Directive
 
-`directive.set.null.allowed = false`
+**`directive.set.null.allowed = false`**
 
 > If true, having a right hand side of a #set() statement with an invalid reference or
null value will set the left hand side to null. If false, the left hand side will stay the
same.
 
 ### #include() and #parse() Directives
 
-`directive.include.output.errormsg.start =  <!-- include error :`
-`directive.include.output.errormsg.end =   see error log --> `
+**`directive.include.output.errormsg.start =  <!-- include error :`**
+**`directive.include.output.errormsg.end =   see error log --> `**
 
 > Defines the beginning and ending tags for an in-stream error message in the case of
a problem with the #include() directive. If both the .start and .end tags are defined, an
error message will be output to the stream, of the form '.start msg .end' where .start and
.end refer to the property values. Output to the render stream will only occur if both the
.start and .end (next) tag are defined.
 
-`directive.parse.max.depth = 10`
+**`directive.parse.max.depth = 10`**
 
 > Defines the allowable parse depth for a template. A template may #parse() another template
which itself may have a #parse() directive.  This value prevents runaway #parse() recursion.
 
-`template.provide.scope.control = false`
+**`template.provide.scope.control = false`**
 
 > Used to turn on the automatic provision of the $template scope control during #parse
calls and template.merge(...) calls. The default is false. Set it to true if you want a secure
namespace for your template variables or more advanced #break control.
 
 ## Resource Management
 
-`resource.manager.logwhenfound = true`
+**`resource.manager.class = org.apache.velocity.runtime.resource.ResourceManagerImpl`**
+
+> Replace the Velocity default Resource Manager class. A resource manager implementation
must implement the (`org.apache.velocity.runtime.resource.ResourceManager`)[apidocs/org/apache/velocity/runtime/resource/ResourceManager.html]
interface. A description of the requirements of a resource manager is out of scope for this
document. Implementors are encouraged to review the default implementation.
+
+The following resource management configuration keys only apply to the default Resource Manager.
+
+**`resource.manager.logwhenfound = true`**
 
 > Switch to control logging of 'found' messages from resource manager. When a resource
is found for the first time, the resource name and classname of the loader that found it will
be noted in the runtime log.
 
-`resource.manager.cache.class`
+**`resource.manager.cache.class = org.apache.velocity.runtime.resource.ResourceCacheImpl`**
 
-> Declares the class to be used for resource caching.  The current default is `org.apache.velocity.runtime.resource.ResourceCacheImpl`.
When `resource.manager.defaultcache.size` is set to 0, then the default implementation is
the standard Java `ConcurrentHashMap`. Otherwise, a non-zero cache size  uses an LRU Map.
 The default cache size is 89.  Note that the ConcurrentHashMap may be better at thread concurrency.
+> Replace the Velocity default Resource Cache class. A resource cache implementation must
implement the (`org.apache.velocity.runtime.resource.ResourceCache`)[apidocs/org/apache/velocity/runtime/resource/ResourceCache.html]
interface As with the resource manager. A description of the requirements of a resource manager
is out of scope for this document.  Implementors are encouraged to review the default implementation.
 
-`resource.manager.defaultcache.size`
+**`resource.manager.defaultcache.size = 89`**
 
-> Sets the size of the default implementation of the resource manager cache size.  The
default is 89.
+> Sets the size of the default implementation of the resource manager cache size. When
`resource.manager.defaultcache.size` is set to 0, then the default implementation uses the
standard Java `ConcurrentHashMap`. Otherwise, a non-zero cache size uses an LRU Map. The default
cache size is 89. Note that the ConcurrentHashMap may be better at thread concurrency.
 
-`resource.loader = <name> (default = file)`
+**`resource.loader = file`**
 
 > *Multi-valued key.  Will accept CSV for value.*  Public name of a resource loader to
be used.  This public name will then be used in the specification of the specific properties
for that resource loader. Note that as a multi-valued key, it's possible to pass a value like
"file, class" (sans quotes), indicating that following will be configuration values for two
loaders.
 
-`<name>.loader.description = Velocity File Resource Loader`
+** *name*`.loader.description = Velocity File Resource Loader`**
 
 > Description string for the given loader.
 
-`<name>.resource.loader.class = org.apache.velocity.runtime.resource.loader.FileResourceLoader`
+** *name*`.resource.loader.class = org.apache.velocity.runtime.resource.loader.FileResourceLoader`**
 
 > Name of implementation class for the loader.  The default loader is the file loader.
 
-`<name>.resource.loader.path = .`
+** *name*`.resource.loader.path = .`**
 
-> *Multi-valued key.  Will accept CSV for value.* Root(s) from which the loader loads
templates. Templates may live in  subdirectories of this root. ex. homesite/index.vm   This
configuration key applies currently to the FileResourceLoader and JarResourceLoader.
+> *Multi-valued key. Will accept CSV for value.* Root(s) from which the loader loads templates.
Templates may live in  subdirectories of this root. ex. homesite/index.vm   This configuration
key applies currently to the FileResourceLoader and JarResourceLoader.
 
-`<name>.resource.loader.cache = false`
+** *name*`.resource.loader.cache = false`**
 
 > Controls caching of the templates in the loader.  Default is false, to make life easy
for development and debugging.  This should be set to true for production deployment.  When
'true', the `modificationCheckInterval` property applies.  This allows for the efficiency
of caching, with the convenience of controlled reloads - useful in a hosted or ISP environment
where templates can be modifed frequently and bouncing the application or servlet engine is
not desired or permitted.
 
-`<name>.resource.loader.modificationCheckInterval = 2`
+** *name*`.resource.loader.modificationCheckInterval = 2`**
 
 > This is the number of seconds between modification checks when caching is turned on.
 When this is an integer > 0, this represents the number of seconds between checks to see
if the template was modified.  If the template has been modified since last check, then it
is reloaded and reparsed.  Otherwise nothing is done.  When <= 0, no modification checks
will take place, and assuming that the property `cache` (above) is true, once a template is
loaded and parsed the first time it is used, it will not be checked or reloaded after that
until the application or servlet engine is restarted.
 
@@ -141,75 +147,76 @@ Below are listed the configuration keys
 
 ## Velocimacros
 
-`velocimacro.library = VM_global_library.vm `
+**`velocimacro.library = VM_global_library.vm `**
 
 
 > *Multi-valued key.  Will accept CSV for value.* Filename(s) of Velocimacro library to
be loaded when the Velocity Runtime engine starts.  These Velocimacros are accessable to all
templates.  The file is assumed to be relative to the root of the file loader resource path.
 
-`velocimacro.permissions.allow.inline = true`
+**`velocimacro.permissions.allow.inline = true`**
 
 > Determines of the definition of new Velocimacros via the #macro() directive in templates
is allowed.   The default value is true, meaning any template can define and use new Velocimacros.
 Note that depending on other properties, those #macro() statements can replace global definitions.
 
-`velocimacro.permissions.allow.inline.to.replace.global = false `
+**`velocimacro.permissions.allow.inline.to.replace.global = false`**
 
 > Controls if a Velocimacro defind 'inline' in a template can replace a Velocimacro defined
in a library loaded at startup.
 
-`velocimacro.permissions.allow.inline.local.scope = false`
+**`velocimacro.permissions.allow.inline.local.scope = false`**
 
 > Controls 'private' templates namespaces for Velocimacros.  When true, a #macro() directive
in a template  creates a Velocimacro that is accessable only from the defining template. 
This means that Velocimacros cannot be shared unless they are in the global or local library
loaded at startup. (See above.)  It also means that templates cannot interfere with each other.
 This property also allows a technique where there is a 'default' Velocimacro definition in
the global or local library, and a template can 'override' the implementation for use within
that template. This occurrs because when this property is true, the template's namespace is
searched for a Velocimacro before the global namespace, therefore allowing the override mechanism.
 
-`velocimacro.context.localscope = false`
+**`velocimacro.context.localscope = false`**
 
 > Controls whether reference access (set/get) within a Velocimacro will change the context,
or be of local scope in that Velocimacro. This feature is deprecated and has been removed
in Velocity 2.0.  Instead, please use the $macro namespace for storage of references local
to your Velocimacro. (e.g. #set( $macro.foo = 'bar') and $macro.foo)
 
-`velocimacro.library.autoreload = false`
+**`velocimacro.library.autoreload = false`**
 
 > Controls Velocimacro library autoloading.  When set to `true` the source Velocimacro
library for an invoked Velocimacro will be checked for changes, and reloaded if necessary.
 This allows you to change and test Velocimacro libraries without having to restart your application
or servlet container, just like you can with regular templates. This mode only works when
caching is *off* in the resource loaders (e.g. `file.resource.loader.cache = false` ). This
feature is intended for development, not for production.
 
-`velocimacro.arguments.strict = false`
+**`velocimacro.arguments.strict = false`**
 
 > When set to true, will throw a `ParseErrorException` when parsing a template containing
a macro with an invalid number of arguments. Is set to false by default to maintain backwards
compatibility with templates written before this feature became available.
 
-`velocimacro.body.reference = false`
+**`velocimacro.body.reference = false`**
 
 > Defines name of the reference that can be used to get the body content (an AST block)
given for a block macro call (e.g. #@myMacro() has a body #end). The default reference name
is "bodyContent" (e.g. $bodyContent).  This block macro feature was introduced in Velocity
1.7.
 
-`macro.provide.scope.control = false`
+**`macro.provide.scope.control = false`**
 
 > Used to turn on the automatic provision of the $macro scope control during #macro calls.
The default is false. Set it to true if you need a local namespace in macros or more advanced
#break controls.
 
-`<somebodymacro>.provide.scope.control = false`
+**`<somebodymacro>.provide.scope.control = false`**
 
 > Used to turn on the automatic provision of the $<nameofthemacro> scope control
during a call to a macro with a body (e.g. #@foo #set($foo.a=$b) ... $foo.a #end). The default
is false. Set it to true if you happen to need a namespace just for your macro's body content
or more advanced #break controls.
-</p>
 
 ## Strict Reference Setting
 
-`runtime.references.strict = false`
+**`runtime.references.strict = false`**
 
-> New in Velocity 1.6, when set to true Velocity will throw a `MethodInvocationException`
for references that are not defined in the context, or have not been defined with a #set directive.
 This setting will also throw an exception if an attempt is made to call a non-existing property
on an object or if the object is null.  When this property is true then property 'directive.set.null.allowed'
is also set to true. Also, 'directive.foreach.skip.invalid' defaults to true when this property
is true, but explicitly setting 'directive.foreach.skip.invalid' will override this default.
For a complete discussion see <a href="user-guide.html#strict-reference-mode">Strict
References Setting</a>.
-> 
-> `runtime.references.strict.escape = false` Changes escape behavior such that putting
a forward slash before a reference or macro always escapes the reference or macro and absorbs
the forward slash regardless if the reference or macro is defined. For example "\$foo" always
renders as "$foo", or "\#foo()" is always rendered as "#foo()".  This escape behavior is of
use in strict mode since unintended strings of characters that look like references or macros
will throw an exception.  This provides an easy way to escape these references.  However,
even in non-strict mode the developer may find this a more consistent and reliable method
for escaping.
+> When set to true Velocity will throw a `MethodInvocationException` for references that
are not defined in the context, or have not been defined with a #set directive.  This setting
will also throw an exception if an attempt is made to call a non-existing property on an object
or if the object is null.  When this property is true then property `directive.set.null.allowed`
is also set to true. Also, `directive.foreach.skip.invalid` defaults to true when this property
is true, but explicitly setting `directive.foreach.skip.invalid` will override this default.
For a complete discussion see [Strict References Setting](user-guide.html#strict-reference-mode).
+
+**`runtime.references.strict.escape = false`**
+
+> Changes escape behavior such that putting a forward slash before a reference or macro
always escapes the reference or macro and absorbs the forward slash regardless if the reference
or macro is defined. For example "\$foo" always renders as "$foo", or "\#foo()" is always
rendered as "#foo()".  This escape behavior is of use in strict mode since unintended strings
of characters that look like references or macros will throw an exception.  This provides
an easy way to escape these references.  However, even in non-strict mode the developer may
find this a more consistent and reliable method for escaping.
 
 ## String Interpolation
 
-`runtime.interpolate.string.literals = true`
+**`runtime.interpolate.string.literals = true`**
 
 > Controls interpolation mechanism of VTL String Literals.  Note that a VTL StringLiteral
is specifically a string using double quotes that is used in a #set() statement, a method
call of a reference, a parameter to a VM, or as an argument to a VTL directive in general.
 See the VTL reference for further information.
 
 ## Math
 
-`runtime.strict.math = false`
+**`runtime.strict.math = false`**
 
 > Affects all math operations in VTL. If changed to true, this will cause Velocity to
throw a MathException whenever one side of a math operation has a null value (e.g. `#set(
$foo = $null * 5 )`) or when trying to divide by zero.  If this value is left `false`, then
rendering will continue and that math operation will be ignored.
 
 ## Parser Configuration
 
-`parser.pool.class = org.apache.velocity.runtime.ParserPoolImpl`
+**`parser.pool.class = org.apache.velocity.runtime.ParserPoolImpl`**
 
 > This property selects the implementation for the parser pool.  This class must implement
ParserPool. Generally there is no reason to change this though if you are building a high
volume web application you might consider including an alternate implementation that automatically
adjusts the size of the pool.
 
-`parser.pool.size = 20`
+**`parser.pool.size = 20`**
 
 > This property is used by the default pooling implementation to set the number of parser
instances that Velocity will create at startup and keep in a pool.  The default of 20 parsers
should be more than enough for most uses.  In the event that Velocity does run out of parsers,
it will indicate so in the log, and dynamically create overflow instances as needed.  Note
that these extra parsers will not be added to the pool, and will be discarded after use. 
This will result in very slow operation compared to the normal usage of pooled parsers, but
this is considered an exceptional condition.  A web application using Velocity as its view
engine might exhibit this behavior under extremely high concurrency (such as when getting
Slashdotted).  If you see a corresponding message referencing the `parser.pool.size` property
in your log files, please increment this property immediately to avoid performance degradation.
 
@@ -217,57 +224,45 @@ Below are listed the configuration keys
 
 See the [Event Handlers](developer-guide.html#event-handlers) section of the dev guide.
 
-`eventhandler.include.class = `*classname*
+**`eventhandler.include.class`** = *classname*
 > register an [include event handler](apidocs/org/apache/velocity/app/event/IncludeEventHandler.html).
 
-`eventhandler.invalidreference.class = `*classname*
+**`eventhandler.invalidreference.class`** = *classname*
 > register an [invalid reference event handler](apidocs/org/apache/velocity/app/event/InvalidReferenceEventHandler.html).
 
-`eventhandler.methodexception.class = `*classname*
+**`eventhandler.methodexception.class`** = *classname*
 > register a [method exception event handler](apidocs/org/apache/velocity/app/event/MethodExceptionEventHandler.html).
 
-`eventhandler.referenceinsertion.class = `*classname*
+**`eventhandler.referenceinsertion.class`** = *classname*
 > register a [reference insertion event handler](apidocs/org/apache/velocity/app/event/ReferenceInsertionEventHandler.html).
 
-## Pluggable Introspection
+## Introspection
+
+Introspection is the process of mapping properties, methods and iterators of VTL references
to Java objects. The object responsible of the introspection strategy in Velocity is called
an *uberspector*.
 
-`runtime.introspector.uberspect = org.apache.velocity.util.introspection.UberspectImpl`
+**`runtime.introspector.uberspect = org.apache.velocity.util.introspection.UberspectImpl`**
 
 > This property sets the 'Uberspector', the introspection package that handles all introspection
strategies for Velocity. You can specify a comma-separated list of Uberspector classes, in
which case all Uberspectors are chained. The default chaining behaviour is to return the first
non-null value for each introspection call among all provided uberspectors. You can modify
this behaviour (for instance to restrict access to some methods) by subclassing org.apache.velocity.util.introspection.AbstractChainableUberspector
(or implementing directly org.apache.velocity.util.introspection.ChainableUberspector).  This
allows you to create more interesting rules or patterns for Uberspection, rather than just
returning the first non-null value.
 > 
-> Some alternate Uberspectors are provided. 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.
+> 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`**
+> 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).
+>
+> 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.
 
 ## Context
 
-`context.autoreference.key = *name*`
+**`context.autoreference.key = <key name>`**
 
 > This property has no default value. If present, the Context object will become accessible
from the templates under the provided name. For instance, with the configuration "`context.autoreference.key
= self`", then `$self` will contain the context itself. This feature is meant to be used for
debugging purposes.
 
-## Pluggable Resource Manager and Resource Cache
-
-The Resource Manager is the main part of the resource (template and static content) management
system, and is responsible for taking application requests for templates, finding them in
the available resource loaders, and then optionally caching the parsed template.  The Resource
Cache is the mechanism that the Resource Manager uses to cache templates for quick reuse.
While the default versions of these two facilities are suitable for most applications, for
advanced users  it now is possible to replace the default resource manager and resource cache
with custom implementations.
-
-A resource manager implementation must implement the `org.apache.velocity.runtime.resource.ResourceManager`
interface. A description of the requirements of a resource manager is out of scope for this
document.  Implementors are encouraged to review the default implementation. To configure
Velocity to load the replacement implementation, use the configuration key:
-
-    resource.manager.class
-
-This key is also defined as a contstant `RuntimeConstants.RESOURCE_MANAGER_CLASS`
-
-A resource cache implementation must implement the `org.apache.velocity.runtime.resource.ResourceCache`
interface As with the resource manager, a description of the requirements of a resource manager
is out of scope for this document.  Implementors are encouraged to review the default implementation.
To configure Velocity to load the replacement implementation, use the configuration key:
-
-    resource.manager.cache.class
-
-This key is also defined as a contstant `RuntimeConstants.RESOURCE_MANAGER_CACHE_CLASS`
-
-A resource cache implementation may want to limit the cache size (rather than providing an
unbounded cache which could consume all available memory).  To configure Velocity to set the
size for your cache, use the configuration key:
-
-    resource.manager.cache.size
-
-This key is also defined as a contstant `RuntimeConstants.RESOURCE_MANAGER_CACHE_SIZE`
-
 ## String Interning
 
-`runtime.string.interning = true`
+**`runtime.string.interning = true`**
 > This property specifies whether to use Java (String interning)[https://en.wikipedia.org/wiki/String_interning]
on identifiers. This may save some memory when set to true, and run a little bit faster when
set to false.
 
 ## Configuration Examples

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=1754153&r1=1754152&r2=1754153&view=diff
==============================================================================
--- velocity/site/cms/trunk/content/engine/devel/developer-guide.mdtext (original)
+++ velocity/site/cms/trunk/content/engine/devel/developer-guide.mdtext Tue Jul 26 16:21:03
2016
@@ -125,7 +125,7 @@ That's the basic pattern. It is very sim
 
 ## To Singleton Or Not To Singleton...
 
-As of Velocity 1.2 and later, developers now have two options for using the Velocity engine,
the singleton model and the separate instance model.  The same core Velocity code is used
for both approaches, which are provided to make Velocity easier to integrate into your Java
application.
+Developers have two options for using the Velocity engine, the singleton model and the separate
instance model. The same core Velocity code is used for both approaches, which are provided
to make Velocity easier to integrate into your Java application.
 
 ### Singleton Model
 
@@ -215,7 +215,7 @@ That's really all there is to basic cont
 ### Support for Iterative Objects for #foreach()
 
 As a programmer, you have great freedom in the objects that you put into the context.  But
as with most freedoms, this one comes with a little bit of responsibility, so understand what
Velocity supports, and any issues that may arise.  Velocity supports serveral types of collection
types  suitable for use in the VTL `#foreach()` directive.
-+ `Object []`  Regular object array, not much needs to be said here. Velocity will internally
wrap your array in a class that provides an Iterator interface,  but that shouldn't concern
you as the programmer, or the template author.  Of more interest, is the fact that Velocity
will now allow template authors to treat arrays as fixed-length lists (as of Velocity 1.6).
This means they may call methods like `size()`, `isEmpty()` and `get(int)` on both arrays
and standard java.util.List instances without concerning themselves about the difference.
++ `Object []`  Regular object array, not much needs to be said here. Velocity will internally
wrap your array in a class that provides an Iterator interface,  but that shouldn't concern
you as the programmer, or the template author.  Of more interest, is the fact that Velocity
will now allow template authors to treat arrays as fixed-length lists. This means they may
call methods like `size()`, `isEmpty()` and `get(int)` as well as the `empty` property on
both arrays and standard java.util.List instances without concerning themselves about the
difference.
 + `java.util.Collection`  Velocity will use the `iterator()` method to get an Iterator to
use in the loop, so if you are implementing a Collection interface on your object, please
ensure that `iterator()` returns a working  Iterator.
 + `java.util.Map ` Here, Velocity depends upon the `values()` method of the interface to
get a `Collection` interface, on which `iterator()` is called to retrieve an Iterator for
the loop.
 + `java.util.Iterator` USE WITH CAUTION: This is currently supported only provisionally -
the issue of concern is the 'non-resettablity' of the Iterator.  If a 'naked' Iterator is
placed into the context, and used in more than one #foreach(), subsequent #foreach() blocks
after the first will fail, as the Iterator doesn't reset.
@@ -299,7 +299,7 @@ Dealing with these cases if very straigh
 + The VTL RangeOperator  [ 1..10 ]  and  ObjectArray ["a","b"] are `java.util.ArrayList`
objects when placed in the context or passed to methods.   Therefore, your methods that are
designed to accept arrays created in the template should be written with this in mind.
 + VTL Map references are unsurprisingly stored as `java.util.Map`.
 + Decimal numbers will be Doubles or BigDecimals in the context, integer numbers will be
Integer, Long, or BigIntegers, and strings will be, of course, Strings.
-+ Velocity will properly 'narrow' args to method calls, so calling `setFoo( int i )` with
an int placed into the context via `#set()` will work fine.
++ Since version 2.0, Velocity will convert method arguments between all main Java standard
types (booleans, numbers and strings). If you want to revert to the Velocity 1.x behavior,
where provided conversions were restricted to implicit Java conversions, you can set the property
`runtime.conversion.handler` to `none`.
 
 ### Other Context Issues
 
@@ -543,6 +543,8 @@ There are currently four kinds of resour
     
 + **DataSourceResourceLoader :**  This loader will load resources from a DataSource such
as a database.  This loader is only available under JDK 1.4 and later. For more information
on this loader, please see the javadoc for the class `org.apache.velocity.runtime.resource.loader.DataSourceResourceLoader`.
 
+Advanced users may also want to replace the Resource Manager or the Resource Cache: the Resource
Manager is the main part of the resource (template and static content) management system,
and is responsible for taking application requests for templates, finding them in the available
resource loaders, and then optionally caching the parsed template. The Resource Cache is the
mechanism that the Resource Manager uses to cache templates for quick reuse. While the default
versions of these two facilities are suitable for most applications, it is possible to replace
the default resource manager and resource cache with custom implementations. See the (related
configuration options)[configuration.html#resource-management].
+
 ## Application Attributes
 
 *Application Attributes* are name-value pairs that can be associated with a RuntimeInstance
(either via the `VelocityEngine` or the `Velocity` singleton) and accessed from any part of
the Velocity engine that has access to the RuntimeInstance.
@@ -719,14 +721,14 @@ The following code shows how to register
 
 ## Customizing Introspection
 
-The [runtime.introspector.uberspect configuration property](configuration.html#Pluggable-Introspection]
property takes a list of Uberspector class names that constitute the Velocity introspection
chain. By means it, you can change the way context objects are introspected at runtime to
map VTL properties and methods to Java calls.
+The [`runtime.introspector.uberspect` configuration property](configuration.html#Pluggable-Introspection]
property takes a list of Uberspector class names that constitute the Velocity introspection
chain. By means it, you can change the way context objects are introspected at runtime to
map VTL properties and methods to Java calls.
 
 Here is the list of provided uberspectors (which are found in the (org.apache.velocity.util.introspection)[apidocs/org/apache/velocity/util/introspection/package-summary.html]
package).
 
 ### Standard Uberspectors
 
 - [UberspectImpl](apidocs/org/apache/velocity/util/introspection/UberspectImpl.html)
-> this is the default uberspector. It successively tries to resolve `$foo.bar` into `foo.getBar()`,
`foo.get('bar')` or `foo.isBar()` (plus some case variants), and tries to match methods using
arguments count and type.
+> this is the default uberspector. It successively tries to resolve `$foo.bar` into `foo.getBar()`,
`foo.get('bar')` or `foo.isBar()` (plus some case variants), and tries to match methods using
arguments count and type. Unless you want to fondamentaly change the way Velocity resolves
references methods and properties, this uberspector should appear somewhere within the introspection
chain.
 - [ChainableUberspector](apidocs/org/apache/velocity/util/introspection/ChainableUberspector.html)
(interface) and [AbstractChainableUberspector](apidocs/org/apache/velocity/util/introspection/AbstractChainableUberspector.html)
(meant to be inherited)
 > A Chainable uberspector is an uberspector that wraps the previous uberspector in the
introspection chain.
 - [LinkingUberspector](apidocs/org/apache/velocity/util/introspection/LinkingUberspector.html)
@@ -745,6 +747,48 @@ If an Uberspector implements the [Runtim
 - [UberspectPublicFields](apidocs/org/apache/velocity/util/introspection/UberspectPublicFields)
 > This uberspector exposes the public fields of objects. It can be prepended or suffixed
to other uberspectors, depending on whether you want to priorize or not public fields versus
potentially matching methods.
 
+### Method arguments conversions
+
+Since Velocity 2.0, besides the default conversions implicitly provided by Java (aka [automatic
boxing and unboxing](https://en.wikipedia.org/wiki/Object_type_%28object-oriented_programming%29),
and widening number conversions), method arguments will be converted as needed by the UberspectorImpl
or SecureUberspector using the following conversions:
+
+- boolean to number: `true` is converted to 1, false to 0
+- boolean to string: `true` and `false` are respectively converted to "true" and "false"
+- number to boolean: zero numbers are converted to `false`, everything else to `true`
+- number to string
+- string to boolean: "true" is converted to `true`, every other string (including the null
string) are converted to `false`
+- string to number: if the string does not represent a number or doesn't fit into the expected
number type, an exception is thrown
+- narrowing number conversion: if the number doesn't fit into the expected number type, an
exception is thrown
+
+You can provide a custom conversion handler class by use of the `runtime.conversion.handler`
property. The class must implement the [`org.apache.Velocity.util.introspection.ConversionHandler`](apidocs/org/apache/velocity/util/introspection/ConversionHandler.html)
interface. Set it to `none` to only accept default Java conversions, as for Velocity 1.x.
+
+You can also provide custom [`Converter<T>`](apidocs/org/apache/velocity/util/introspection/Converter.html)
objects that handle a conversion towards a specific type:
+
+    package mypackage;
+    
+    import java.util.Date;
+    import org.apache.velocity.util.introspection.*;
+    
+    public class MyUberspector extends UberspectorImpl
+    {
+        public void init()
+        {
+            super.init();
+            getConversionHandler().addConverter(Integer.class, Date.class, new ConvertToDate());
+            getConversionHandler().addConverter(Long.class, Date.class, new ConvertToDate());
+        }
+        
+        public static class ConvertToDate extends Converter<Date>
+        {
+            @Override
+            public Date convert(Object o)
+            {
+                return new Date(((Number)o).longValue());
+            }
+        }
+    }
+
+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.
+
 ## Template Encoding for Internationalization
 
 Velocity allows you to specify the character encoding of your template resources on a template
by template basis.  The normal resource API's have been extended to take the encoding as an
argument:

Modified: velocity/site/cms/trunk/content/engine/devel/left.nav
URL: http://svn.apache.org/viewvc/velocity/site/cms/trunk/content/engine/devel/left.nav?rev=1754153&r1=1754152&r2=1754153&view=diff
==============================================================================
--- velocity/site/cms/trunk/content/engine/devel/left.nav (original)
+++ velocity/site/cms/trunk/content/engine/devel/left.nav Tue Jul 26 16:21:03 2016
@@ -12,10 +12,10 @@
 * [Configuration](configuration.html)
 * [Glossary](glossary.html)
 * [Javadoc](apidocs/index.html)
+* [Upgrading](upgrading.html)
 ## Developers
 * [License](license.html)
 * [Changes](changes.html)
-* [Upgrading](upgrading.html)
 * [Dependencies](dependencies.html)
 * [Sources](source-repository.html)
 * [Building](build.html)

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=1754153&r1=1754152&r2=1754153&view=diff
==============================================================================
--- velocity/site/cms/trunk/content/engine/devel/upgrading.mdtext (original)
+++ velocity/site/cms/trunk/content/engine/devel/upgrading.mdtext Tue Jul 26 16:21:03 2016
@@ -2,11 +2,13 @@ Title: Apache Velocity Engine - Upgradin
 
 ## Upgrading from earlier versions
 
-Release with the same major number (1.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.
+This page details 
 
-### Upgrading from Velocity 1.7.x to Velocity 2.0.x
+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.
 
-Behavior / API changes:
+## Upgrading from Velocity 1.7.x to Velocity 2.0.x
+
+### Behavior / API changes:
 
 + velocity is now using the SLF4J logging facade. Hence, all methods accepting or returning
a logger now use the org.slf4j.Logger object.
 + the internal Context API now enforces String keys everywhere, this may break custom Context
implementations at compile-time.
@@ -23,19 +25,20 @@ Behavior / API changes:
 + the MethodException event handler now receives an additional argument providing template
name and location infos.
 + all occurences of the class org.apache.commons.collections.ExtendedProperties in the initialization
API have been replaced by org.apache.velocity.util.ExtProperties.
 
-VTL Syntax changes:
+### VTL Changes:
 
 + the hypen ( `-` ) cannot be used in variable names anymore
 + method arguments can be arithmetic expressions
++ method arguments are now converted as needed between all main basic Java standard types
(booleans, numbers and strings). If you want to revert to the 1.x behavior, set the property
`runtime.conversion.handler = none`.
 
-Dependencies changes:
+### Dependencies changes:
 
 + Velocity now requires a JDK version of 1.7 or higher.
 + commons-lang, commons-collections and commons-logging aren't needed any more at runtime.
 + there's a new runtime dependency, slf4j-api 1.7.12
 + you'll need an [SLF4J binding](dependencies.html)
 
-### Upgrading from Velocity 1.6.x to Velocity 1.7.x
+## Upgrading from Velocity 1.6.x to Velocity 1.7.x
 
 There are no changes in the dependencies since Velocity 1.6
 
@@ -48,13 +51,13 @@ There are no changes in the dependencies
 + Removed obsolete Veltag (use VelocityViewTag in VelocityTools project)
 + Removed obsolete WebMacro conversion code.
 
-### Upgrading from Velocity 1.5.x to Velocity 1.6.x
+## Upgrading from Velocity 1.5.x to Velocity 1.6.x
 
 + [Commons Collections](http://commons.apache.org/collections/) has been upgraded to version
3.2.1.
 + [Commons Lang](http://commons.apache.org/lang/) has been upgraded to version 2.4.
 + [Commons Logging](http://commons.apache.org/logging/) is required for compiling and using
CommonsLogLogChute.
 
-### Upgrading from Velocity 1.4 or earlier
+## Upgrading from Velocity 1.4 or earlier
 
 + [JDOM](http://www.jdom.org) has been upgraded to version 1.0.
 + [Commons Collections](http://jakarta.apache.org/commons/collections/) has been upgraded
to version 3.1.

Modified: velocity/site/cms/trunk/content/engine/devel/user-guide.mdtext
URL: http://svn.apache.org/viewvc/velocity/site/cms/trunk/content/engine/devel/user-guide.mdtext?rev=1754153&r1=1754152&r2=1754153&view=diff
==============================================================================
--- velocity/site/cms/trunk/content/engine/devel/user-guide.mdtext (original)
+++ velocity/site/cms/trunk/content/engine/devel/user-guide.mdtext Tue Jul 26 16:21:03 2016
@@ -190,9 +190,9 @@ We might expect these methods to return
     $book.setTitle( "Homage to Catalonia" )
     ## Can't pass a parameter
 
-As of Velocity 1.6, all array references are now "magically" treated as if they are fixed-length
lists.  This means that you can call java.util.List methods on array references.  So, if you
have a reference to an array (let's say this one is a String[] with three values), you can
do:
+All array references are treated as if they are fixed-length lists. This means that you can
call java.util.List methods and properties on array references.  So, if you have a reference
to an array (let's say this one is a String[] with three values), you can do:
 
-    $myarray.isEmpty()
+    $myarray.isEmpty() or $myarray.empty
 
     $myarray.size()
 
@@ -200,7 +200,7 @@ As of Velocity 1.6, all array references
 
     $myarray.set(1, 'test')
 
-Also new in Velocity 1.6 is support for vararg methods. A method like `azpublic void setPlanets(String...
planets)` or even just `public void setPlanets(String[] planets)` can now accept any number
of arguments when called in a template.
+Velocity also supports vararg methods. A method like `azpublic void setPlanets(String...
planets)` or even just `public void setPlanets(String[] planets)` can now accept any number
of arguments when called in a template.
 
     $sun.setPlanets('Earth', 'Mars', 'Neptune')
 
@@ -209,6 +209,8 @@ Also new in Velocity 1.6 is support for
     $sun.setPlanets()
     ## Will just pass in an empty, zero-length array
 
+As of Velocity 2.0, method calls now provides implicit conversions between all Java basic
builtin types: numbers, booleans and strings.
+
 ### Property Lookup Rules
 
 As was mentioned earlier, properties often refer to methods of the parent object. Velocity
is quite clever when figuring out which method corresponds to a requested property. It tries
out different alternatives based on several established naming conventions. The exact lookup
sequence depends on whether or not the property name starts with an upper-case letter. For
lower-case names, such as *$customer.address*, the sequence is

Modified: velocity/site/cms/trunk/content/engine/index.mdtext
URL: http://svn.apache.org/viewvc/velocity/site/cms/trunk/content/engine/index.mdtext?rev=1754153&r1=1754152&r2=1754153&view=diff
==============================================================================
--- velocity/site/cms/trunk/content/engine/index.mdtext (original)
+++ velocity/site/cms/trunk/content/engine/index.mdtext Tue Jul 26 16:21:03 2016
@@ -9,12 +9,12 @@ Velocity permits you to use a simple yet
 The Velocity engine subproject contains the documentation to get started using the Velocity
templating language and embedding Velocity into your own applications. Please select [the
last released version](1.7) to get started. Once you are more familiar with Velocity or if
you need a feature not yet released, you can check out the [Development Site](devel).
 
 + [Engine 1.7 Release](1.7) pages.
-+ [Engine Development Version](devel/) pages.
++ [Engine Development (2.x) Version](devel/) pages.
 
 ## Older Releases
 
 + [Engine 1.6.2 Release](1.6.2)
 + [Engine 1.6.1 Release](1.6.1)
 + [Engine 1.6 Release](1.6)
-+ [Engine 1.6 Release](1.5)
-+ [Engine 1.6 Release](1.4)
++ [Engine 1.5 Release](1.5)
++ [Engine 1.4 Release](1.4)




Mime
View raw message