velocity-commits mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From cbris...@apache.org
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 GMT
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  );
 >     }
 > 



Mime
View raw message