Author: cbrisson
Date: Tue Jan 3 11:07:38 2017
New Revision: 1777110
URL: http://svn.apache.org/viewvc?rev=1777110&view=rev
Log:
[site/engine] reflect events API change, remove obsolete NullSetEventHandler
doc, reflect configuration API change
Modified:
velocity/site/cms/trunk/content/engine/2.0/dependencies.mdtext
velocity/site/cms/trunk/content/engine/2.0/developer-guide.mdtext
velocity/site/cms/trunk/content/engine/devel/developer-guide.mdtext
Modified: velocity/site/cms/trunk/content/engine/2.0/dependencies.mdtext
URL:
http://svn.apache.org/viewvc/velocity/site/cms/trunk/content/engine/2.0/dependencies.mdtext?rev=1777110&r1=1777109&r2=1777110&view=diff
==============================================================================
--- velocity/site/cms/trunk/content/engine/2.0/dependencies.mdtext (original)
+++ velocity/site/cms/trunk/content/engine/2.0/dependencies.mdtext Tue Jan 3
11:07:38 2017
@@ -25,4 +25,3 @@ Here is a list of slf4j bindings:
+ [LogBack](http://logback.qos.ch/) - full featured logging framework
+ [WebApp SLF4J Logger](https://github.com/arkanovicz/webapp-slf4j-logger) -
redirects logs towards the J2EE container log
-
Modified: velocity/site/cms/trunk/content/engine/2.0/developer-guide.mdtext
URL:
http://svn.apache.org/viewvc/velocity/site/cms/trunk/content/engine/2.0/developer-guide.mdtext?rev=1777110&r1=1777109&r2=1777110&view=diff
==============================================================================
--- velocity/site/cms/trunk/content/engine/2.0/developer-guide.mdtext (original)
+++ velocity/site/cms/trunk/content/engine/2.0/developer-guide.mdtext Tue Jan
3 11:07:38 2017
@@ -476,27 +476,32 @@ If we wanted to use a different director
...
-And, assuming you have a directory `/opt/templates` and the template
`testtemplate.vm` is in there, then things would work just fine. If you try
this and have a problem, be sure to look at the velocity.log for information -
the error messages are pretty good for figuring out what is wrong.
+And the same if you want to use a VelocityEngine object rather than the
singleton engine:
-If you need to place objects into the Velocity properties then you cannot use
the Velocity.init(Properties p) method. Instead you should create a new
instance of the `org.apache.velocity.util.ExtProperties` class, copy all
properties from an existing Properties object into the ExtProperties and then
add new properties with your objects to the ExtProperties object.
+ ...
+ import java.util.Properties;
...
- VelocityEngine velocityEngine = new VelocityEngine();
- ExtProperties eprops = null;
- if (props==null) {
- eprops = new ExtProperties();
- } else {
- eprops = ExtProperties.convertProperties(props);
- }
-
- // Now set the property with your object instance
- eprops.setProperty("name", object);
+ public static void main( String args[] )
+ {
+ /* first, we init the runtime engine. */
+
+ Properties p = new Properties();
+ p.setProperty("file.resource.loader.path", "/opt/templates");
+ VelocityEngine engine = new VelocityEngine();
+ engine.init( p );
+
+ /* lets make a Context and put data into it */
...
- velocityEngine.setExtendedProperties(eprops);
- velocityEngine.init();
- ...
+
+
+And, assuming you have a directory `/opt/templates` and the template
`testtemplate.vm` is in there, then things would work just fine. If you try
this and have a problem, be sure to look at the velocity.log for information -
the error messages are pretty good for figuring out what is wrong.
+
+If you need to place objects into the Velocity properties, you may do so: the
`java.util.Properties` class *does* accept Object values (which will only
invalidate the use of its `load` and `store` methods).
+
+To combine multiple properties files, you may call several times
`setProperties(Properties)`, `setProperty(String, Object)` or
`addProperty(String, Object)` before calling `init()`.
You may want to also consider using the Application Attributes feature
described in the following section.
@@ -845,7 +850,9 @@ Note that internal components cannot set
## Event Handlers
-Velocity contains a fine-grained event handling system that allows you to
customize the operation of the engine. For example, you may change the text of
references that are inserted into a page, modify which templates are actually
included with `#include` or `#parse`, or capture all invalid references.
+Velocity contains a fine-grained event handling system that allows you to
customize the operation of the engine. Those events are synchronous, and act as
callback handlers.
+
+For example, you may change the text of references that are inserted into a
page, modify which templates are actually included with `#include` or `#parse`,
or capture all invalid references.
All event handler interfaces available in Velocity are in the package
`org.apache.velocity.app.event`. You may create your own implementation or use
one of the sample implementations in the package
`org.apache.velocity.app.event.implement`. (See the javadocs for more details
on the provided implementations).
@@ -855,7 +862,8 @@ All event handler interfaces available i
>
> public IncludeEventHandler extends EventHandler
> {
-> public String includeEvent( String includeResourcePath,
+> public String includeEvent( Context context,
+> String includeResourcePath,
> String currentResourcePath,
> String directiveName );
> }
@@ -899,7 +907,8 @@ All event handler interfaces available i
>
> public interface MethodExceptionEventHandler extends EventHandler
> {
-> public Object methodException( Class claz,
+> public Object methodException( Context context,
+> Class claz,
> String method,
> Exception e )
> throws Exception;
@@ -909,28 +918,14 @@ All event handler interfaces available i
>
> + `org.apache.velocity.app.event.implement.PrintExceptions`
-
-### `org.apache.velocity.app.event.NullSetEventHandler`
-
-> When a #set() rejects an assignment due to the right hand side being an
invalid or null reference, this is normally logged. The `NullSetEventHandler`
allows you to 'veto' the logging of this condition. Multiple
`NullSetEventHandler`'s can be chained; each event handler is called in
sequence until a false is returned.
->
-> public interface NullSetEventHandler extends EventHandler
-> {
-> public boolean shouldLogOnNullSet( String lhs,
-> String rhs );
-> }
->
-> Available implementations include:
->
-> + *none provided*
-
### `org.apache.velocity.app.event.ReferenceInsertionEventHandler`
> A `ReferenceInsertionEventHandler` allows the developer to intercept each
> write of a reference ($foo) value to the output stream and modify that
> output. Multiple `ReferenceInsertionEventHandler`'s may be chained with
> each step potentially altering the inserted reference.
>
> public interface ReferenceInsertionEventHandler extends EventHandler
> {
-> public Object referenceInsert( String reference,
+> public Object referenceInsert( Context context,
+ String reference,
> Object value );
> }
>
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=1777110&r1=1777109&r2=1777110&view=diff
==============================================================================
--- velocity/site/cms/trunk/content/engine/devel/developer-guide.mdtext
(original)
+++ velocity/site/cms/trunk/content/engine/devel/developer-guide.mdtext Tue Jan
3 11:07:38 2017
@@ -475,28 +475,33 @@ If we wanted to use a different director
/* lets make a Context and put data into it */
...
-
-And, assuming you have a directory `/opt/templates` and the template
`testtemplate.vm` is in there, then things would work just fine. If you try
this and have a problem, be sure to look at the velocity.log for information -
the error messages are pretty good for figuring out what is wrong.
-If you need to place objects into the Velocity properties then you cannot use
the Velocity.init(Properties p) method. Instead you should create a new
instance of the `org.apache.velocity.util.ExtProperties` class, copy all
properties from an existing Properties object into the ExtProperties and then
add new properties with your objects to the ExtProperties object.
+And the same if you want to use a VelocityEngine object rather than the
singleton engine:
...
- VelocityEngine velocityEngine = new VelocityEngine();
- ExtProperties eprops = null;
- if (props==null) {
- eprops = new ExtProperties();
- } else {
- eprops = ExtProperties.convertProperties(props);
- }
-
- // Now set the property with your object instance
- eprops.setProperty("name", object);
-
- ...
- velocityEngine.setExtendedProperties(eprops);
- velocityEngine.init();
- ...
+ import java.util.Properties;
+ ...
+
+ public static void main( String args[] )
+ {
+ /* first, we init the runtime engine. */
+
+ Properties p = new Properties();
+ p.setProperty("file.resource.loader.path", "/opt/templates");
+ VelocityEngine engine = new VelocityEngine();
+ engine.init( p );
+
+ /* lets make a Context and put data into it */
+
+ ...
+
+
+And, assuming you have a directory `/opt/templates` and the template
`testtemplate.vm` is in there, then things would work just fine. If you try
this and have a problem, be sure to look at the velocity.log for information -
the error messages are pretty good for figuring out what is wrong.
+
+If you need to place objects into the Velocity properties, you may do so: the
`java.util.Properties` class *does* accept Object values (which will only
invalidate the use of its `load` and `store` methods).
+
+To combine multiple properties files, you may call several times
`setProperties(Properties)`, `setProperty(String, Object)` or
`addProperty(String, Object)` before calling `init()`.
You may want to also consider using the Application Attributes feature
described in the following section.
@@ -845,7 +850,9 @@ Note that internal components cannot set
## Event Handlers
-Velocity contains a fine-grained event handling system that allows you to
customize the operation of the engine. For example, you may change the text of
references that are inserted into a page, modify which templates are actually
included with `#include` or `#parse`, or capture all invalid references.
+Velocity contains a fine-grained event handling system that allows you to
customize the operation of the engine. Those events are synchronous, and act as
callback handlers.
+
+For example, you may change the text of references that are inserted into a
page, modify which templates are actually included with `#include` or `#parse`,
or capture all invalid references.
All event handler interfaces available in Velocity are in the package
`org.apache.velocity.app.event`. You may create your own implementation or use
one of the sample implementations in the package
`org.apache.velocity.app.event.implement`. (See the javadocs for more details
on the provided implementations).
@@ -855,7 +862,8 @@ All event handler interfaces available i
>
> public IncludeEventHandler extends EventHandler
> {
-> public String includeEvent( String includeResourcePath,
+> public String includeEvent( Context context,
+> String includeResourcePath,
> String currentResourcePath,
> String directiveName );
> }
@@ -899,7 +907,8 @@ All event handler interfaces available i
>
> public interface MethodExceptionEventHandler extends EventHandler
> {
-> public Object methodException( Class claz,
+> public Object methodException( Context context,
+> Class claz,
> String method,
> Exception e )
> throws Exception;
@@ -909,28 +918,14 @@ All event handler interfaces available i
>
> + `org.apache.velocity.app.event.implement.PrintExceptions`
-
-### `org.apache.velocity.app.event.NullSetEventHandler`
-
-> When a #set() rejects an assignment due to the right hand side being an
invalid or null reference, this is normally logged. The `NullSetEventHandler`
allows you to 'veto' the logging of this condition. Multiple
`NullSetEventHandler`'s can be chained; each event handler is called in
sequence until a false is returned.
->
-> public interface NullSetEventHandler extends EventHandler
-> {
-> public boolean shouldLogOnNullSet( String lhs,
-> String rhs );
-> }
->
-> Available implementations include:
->
-> + *none provided*
-
### `org.apache.velocity.app.event.ReferenceInsertionEventHandler`
> A `ReferenceInsertionEventHandler` allows the developer to intercept each
> write of a reference ($foo) value to the output stream and modify that
> output. Multiple `ReferenceInsertionEventHandler`'s may be chained with
> each step potentially altering the inserted reference.
>
> public interface ReferenceInsertionEventHandler extends EventHandler
> {
-> public Object referenceInsert( String reference,
+> public Object referenceInsert( Context context,
+ String reference,
> Object value );
> }
>
