Mailing-List: contact commits-help@velocity.apache.org; run by ezmlm
Precedence: bulk
Reply-To: dev@velocity.apache.org
Content-Type: text/plain; charset="utf-8"
MIME-Version: 1.0
Content-Transfer-Encoding: 7bit
Subject: svn commit: r1777110 - in /velocity/site/cms/trunk/content/engine:
 2.0/dependencies.mdtext 2.0/developer-guide.mdtext
 devel/developer-guide.mdtext
Date: Tue, 03 Jan 2017 11:07:38 -0000
To: commits@velocity.apache.org
From: cbrisson@apache.org
Message-Id: <20170103110739.3B2283A1F5C@svn01-us-west.apache.org>
archived-at: Tue, 03 Jan 2017 11:07:42 -0000

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  );
 >     }
 >