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 2017/01/03 11:07:38 UTC
svn commit: r1777110 - in /velocity/site/cms/trunk/content/engine:
2.0/dependencies.mdtext 2.0/developer-guide.mdtext
devel/developer-guide.mdtext
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 );
> }
>