From commits-return-3310-archive-asf-public=cust-asf.ponee.io@velocity.apache.org Tue Jun 26 12:03:23 2018 Return-Path: X-Original-To: archive-asf-public@cust-asf.ponee.io Delivered-To: archive-asf-public@cust-asf.ponee.io Received: from mail.apache.org (hermes.apache.org [140.211.11.3]) by mx-eu-01.ponee.io (Postfix) with SMTP id DBCA0180662 for ; Tue, 26 Jun 2018 12:03:20 +0200 (CEST) Received: (qmail 79311 invoked by uid 500); 26 Jun 2018 10:03:20 -0000 Mailing-List: contact commits-help@velocity.apache.org; run by ezmlm Precedence: bulk List-Help: List-Unsubscribe: List-Post: List-Id: Reply-To: dev@velocity.apache.org Delivered-To: mailing list commits@velocity.apache.org Received: (qmail 79253 invoked by uid 99); 26 Jun 2018 10:03:19 -0000 Received: from Unknown (HELO svn01-us-west.apache.org) (209.188.14.144) by apache.org (qpsmtpd/0.29) with ESMTP; Tue, 26 Jun 2018 10:03:19 +0000 Received: from svn01-us-west.apache.org (localhost [127.0.0.1]) by svn01-us-west.apache.org (ASF Mail Server at svn01-us-west.apache.org) with ESMTP id 5EB4B3A028C for ; Tue, 26 Jun 2018 10:03:19 +0000 (UTC) Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit Subject: svn commit: r1834410 [2/8] - in /velocity/site/production: engine/2.0/ engine/devel/ tools/2.0/ tools/devel/ Date: Tue, 26 Jun 2018 10:03:19 -0000 To: commits@velocity.apache.org From: cbrisson@apache.org X-Mailer: svnmailer-1.0.9 Message-Id: <20180626100319.5EB4B3A028C@svn01-us-west.apache.org> Modified: velocity/site/production/engine/2.0/developer-guide.html URL: http://svn.apache.org/viewvc/velocity/site/production/engine/2.0/developer-guide.html?rev=1834410&r1=1834409&r2=1834410&view=diff ============================================================================== --- velocity/site/production/engine/2.0/developer-guide.html (original) +++ velocity/site/production/engine/2.0/developer-guide.html Tue Jun 26 10:03:18 2018 @@ -345,45 +345,45 @@ h2:hover > .headerlink, h3:hover > .head
  • 'Merge' the template and your data to produce the ouput.

    • In code, using the singleton pattern via the org.apache.velocity.app.Velocity class, this looks like

    -
    import java.io.StringWriter;
-import org.apache.velocity.VelocityContext;
-import org.apache.velocity.Template;
-import org.apache.velocity.app.Velocity;
-import org.apache.velocity.exception.ResourceNotFoundException;
-import org.apache.velocity.exception.ParseErrorException;
-import org.apache.velocity.exception.MethodInvocationException;
+
    import java.io.StringWriter;
+import org.apache.velocity.VelocityContext;
+import org.apache.velocity.Template;
+import org.apache.velocity.app.Velocity;
+import org.apache.velocity.exception.ResourceNotFoundException;
+import org.apache.velocity.exception.ParseErrorException;
+import org.apache.velocity.exception.MethodInvocationException;
 
-Velocity.init();
+Velocity.init();
 
-VelocityContext context = new VelocityContext();
+VelocityContext context = new VelocityContext();
 
-context.put( "name", new String("Velocity") );
+context.put( "name", new String("Velocity") );
 
-Template template = null;
+Template template = null;
 
 try
-{
-  template = Velocity.getTemplate("mytemplate.vm");
-}
-catch( ResourceNotFoundException rnfe )
-{
-  // couldn't find the template
-}
-catch( ParseErrorException pee )
-{
-  // syntax error: problem parsing the template
-}
-catch( MethodInvocationException mie )
-{
-  // something invoked in the template
-  // threw an exception
-}
-catch( Exception e )
-{}
+{
+  template = Velocity.getTemplate("mytemplate.vm");
+}
+catch( ResourceNotFoundException rnfe )
+{
+  // couldn't find the template
+}
+catch( ParseErrorException pee )
+{
+  // syntax error: problem parsing the template
+}
+catch( MethodInvocationException mie )
+{
+  // something invoked in the template
+  // threw an exception
+}
+catch( Exception e )
+{}
 
-StringWriter sw = new StringWriter();
+StringWriter sw = new StringWriter();
 
-template.merge( context, sw );
+template.merge( context, sw );
 
    
 
 
@@ -392,60 +392,60 @@ h2:hover > .headerlink, h3:hover > .head
 
    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
    
 
    This is the legacy pattern, where there is only one instance of the Velocity engine in the JVM (or web application, depending) that is shared by all. This is very convenient as it allows localized configuration and sharing of resources.  For example, this is a very appropriate model for use in a Servlet 2.2+ compliant web application as each web application can have its own instance of Velocity, allowing that web application's servlet to share resources like templates, a logger, etc. The singleton is accessable via the org.apache.velocity.app.Velocity class, and and example of use:
    
-
    import org.apache.velocity.app.Velocity;
-import org.apache.velocity.Template;
+
    import org.apache.velocity.app.Velocity;
+import org.apache.velocity.Template;
 
 ...
 
-/*
- *  Configure the engine
- */
-
-Velocity.setProperty(
-    Velocity.RUNTIME_LOG_NAME, "mylog");
-
-/*
- *  now initialize the engine
- */
+/*
+ *  Configure the engine
+ */
+
+Velocity.setProperty(
+    Velocity.RUNTIME_LOG_NAME, "mylog");
+
+/*
+ *  now initialize the engine
+ */
 
-Velocity.init();
+Velocity.init();
 
 ...
 
-Template t = Velocity.getTemplate("foo.vm");
+Template t = Velocity.getTemplate("foo.vm");
 
    
 
 
 
    Separate Instance
    
 
    New in version 1.2, the separate instance allows you to create, configure and use as many instances of Velocity as you wish in the same JVM (or web application.)  This is useful when you wish to support separate configurations, such as template directories, loggers, etc in the same application.  To use separate instances, use the org.apache.velocity.app.VelocityEngine class.  An example, which parallels the above singleton example, looks like:
    
-
    import org.apache.velocity.app.VelocityEngine;
-import org.apache.velocity.Template;
+
    import org.apache.velocity.app.VelocityEngine;
+import org.apache.velocity.Template;
 
 ...
 
-/*
- *  create a new instance of the engine
- */
+/*
+ *  create a new instance of the engine
+ */
 
-VelocityEngine ve = new VelocityEngine();
+VelocityEngine ve = new VelocityEngine();
 
-/*
- *  configure the engine.  In this case, we are using
- *  a specific logger name
- */
+/*
+ *  configure the engine.  In this case, we are using
+ *  a specific logger name
+ */
 
-ve.setProperty(
-    VelocityEngine.RUNTIME_LOG_NAME, "mylog");
+ve.setProperty(
+    VelocityEngine.RUNTIME_LOG_NAME, "mylog");
 
-/*
- *  initialize the engine
- */
+/*
+ *  initialize the engine
+ */
 
-ve.init();
+ve.init();
 
 ...
 
-Template t = ve.getTemplate("foo.vm");
+Template t = ve.getTemplate("foo.vm");
 
    
 
 
@@ -458,8 +458,8 @@ h2:hover > .headerlink, h3:hover > .head
 
    While Velocity allows you to create your own context classes to support special needs and techniques (like a context that accesses an LDAP server directly, for example), a good basic implementation class called VelocityContext is provided for you as part of the distribution.
    
 
    VelocityContext is suitable for all general purpose needs, and we strongly recommended that you use it. Only in exceptional and advanced cases will you need to extend or create your own context implementation.
    
 
    Using VelocityContext is as simple as using a normal Java Hashtable class. While the interface contains other useful methods, the two main methods you will use are
    
-
    public Object put(String key, Object value);
-public Object get(String key);
+
    public Object put(String key, Object value);
+public Object get(String key);
 
    
 
 
@@ -475,16 +475,16 @@ public Object get(String key);
 +  Any public class with a public Iterator iterator() method that never returns null.  As a last resort, Velocity will look for an iterator() method. This provides great flexibility and automatic support for java.util.Iterable interface.
    
 
    In the case of the Iterator and Enumeration, it is recommended that they are placed in the context only when it cannot be avoided, and you should let Velocity find the appropriate reusable iterative interface when that is sufficient and possible.
    
 
    There are good reasons to use the java.util.Iterator interface directly (large data sets via JDBC, for example), but if it can be avoided, it might be better to use something else. By 'directly' , we meant doing something like:
    
-
    Vector v = new Vector();
-v.addElement("Hello");
-v.addElement("There");
+
    Vector v = new Vector();
+v.addElement("Hello");
+v.addElement("There");
 
-context.put("words", v.iterator() );
+context.put("words", v.iterator() );
 
    
 
 
 
    where the Iterator itself is placed into the context. Instead, if you simply did:
    
-
    context.put("words", v );
+
    context.put("words", v );
 
    
 
 
@@ -492,7 +492,7 @@ context.put("words", v.iterato
 
    This above isn't meant to give the impression that iterating over collections in Velocity is something that requires great care and thought.  Rather, the opposite is true, in general.  Just be careful when you place an Iterator into the context.
    
 
    Support for "Static Classes"
    
 
    Not all classes are instantiable.  Classes like java.lang.Math do not provide any public constructor, and yet may contain useful static methods. In order to access these static methods from a template, you can simply add the class itself to the context:
    
-
    context.put("Math", Math.class);
+
    context.put("Math", Math.class);
 
    
 
 
@@ -500,18 +500,18 @@ context.put("words", v.iterato
 
    Context Chaining
    
 
    An innovative feature of Velocity's context design is the concept of context chaining. Also sometimes referred to as context wrapping, this advanced feature allows you to connect separate contexts together in a manner that makes it appear as one 'contiguous' context to the template.
    
 
    This is best illustrated by an example:
    
-
    VelocityContext context1 = new VelocityContext();
+
    VelocityContext context1 = new VelocityContext();
 
-context1.put("name","Velocity");
-context1.put("project", "Jakarta");
-context1.put("duplicate", "I am in context1");
+context1.put("name","Velocity");
+context1.put("project", "Jakarta");
+context1.put("duplicate", "I am in context1");
 
-VelocityContext context2 = new VelocityContext( context1 );
+VelocityContext context2 = new VelocityContext( context1 );
 
-context2.put("lang", "Java" );
-context2.put("duplicate", "I am in context2");
+context2.put("lang", "Java" );
+context2.put("duplicate", "I am in context2");
 
-template.merge( context2, writer );
+template.merge( context2, writer );
 
    
 
 
@@ -524,15 +524,15 @@ template.merge( context2, writer );
 
    Objects Created in the Template
    
 
    There are two common situations where the Java code must deal with objects created at runtime in the template:
    
 
    When a template author calls a method of an object placed into the context by Java code.
    
-
    #set($myarr = ["a","b","c"] )
-$foo.bar( $myarr )
+
    #set($myarr = ["a","b","c"] )
+$foo.bar( $myarr )
 
    
 
 
 
    When a template adds objects to the context, the Java code can access those objects after the merge process is complete.
    
-
    #set($myarr = ["a","b","c"] )
-#set( $foo = 1 )
-#set( $bar = "bar")
+
    #set($myarr = ["a","b","c"] )
+#set( $foo = 1 )
+#set( $bar = "bar")
 
    
 
 
@@ -562,14 +562,13 @@ $foo.bar( $myarr )
 
    The Velocity Helper Class
    
 
    Velocity contains an application utility class called Velocity ( org.apache.velocity.app.Velocity ).  The purpose of this class is to provide the necessary methods required to initialize Velocity, as well as useful utility routines to make life easier in using Velocity. This class is documented  in the project's javadoc, so please look there for definitive details. This documentation is intended to be of a tutorial nature; therefore for compete API information, the Javadoc is the definitive source.
    
 
    The Velocity runtime engine is a singleton instance that provides resource, logging and other services to all Velocity users running in the same JVM. Therefore, the runtime engine is initialized only once.  You can attempt to initialize Velocity more than once, but only the first initialization will apply.  The rest of the attempts will be ignored.  The Velocity utility class currently provides five methods used in configuration of the runtime engine.
    
-
    The five configuration methods are:
-+ setProperty( String key, Object o )
    
-
    Sets the property `key` with the value `o`. The value is typically a String, but in special cases can also be a comma-separated list of values (in a single String, ex."foo, bar, woogie") as well as other things that will arise.
-
    
-
-
+
    The five configuration methods are:
    
 
      
 
    • 
+
      setProperty( String key, Object o )
      
+
      Sets the property key with the value o. The value is typically a String, but in special cases can also be a comma-separated list of values (in a single String, ex."foo, bar, woogie") as well as other things that will arise.
      
+
      • 
+
    • 
 
      Object getProperty( String key )
      
 
      Returns the value of the property key.  Note that you must be aware of the type of the return value, as they can be things other than Strings.
      
 
      • 
@@ -615,40 +614,40 @@ $foo.bar( $myarr )
 
 
    
 
    Once we know about these basic helpers, it is easy to write a Java program that uses Velocity.  Here it is:
    
-
    import java.io.StringWriter;
-import org.apache.velocity.app.Velocity;
-import org.apache.velocity.VelocityContext;
+
    import java.io.StringWriter;
+import org.apache.velocity.app.Velocity;
+import org.apache.velocity.VelocityContext;
 
-public class Example2
-{
-    public static void main( String args[] )
-    {
-        /* first, we init the runtime engine.  Defaults are fine. */
+public class Example2
+{
+    public static void main( String args[] )
+    {
+        /* first, we init the runtime engine.  Defaults are fine. */
 
-        Velocity.init();
+        Velocity.init();
 
-        /* lets make a Context and put data into it */
+        /* lets make a Context and put data into it */
 
-        VelocityContext context = new VelocityContext();
+        VelocityContext context = new VelocityContext();
 
-        context.put("name", "Velocity");
-        context.put("project", "Jakarta");
+        context.put("name", "Velocity");
+        context.put("project", "Jakarta");
 
-        /* lets render a template */
+        /* lets render a template */
 
-        StringWriter w = new StringWriter();
+        StringWriter w = new StringWriter();
 
-        Velocity.mergeTemplate("testtemplate.vm", context, w );
-        System.out.println(" template : " + w );
+        Velocity.mergeTemplate("testtemplate.vm", context, w );
+        System.out.println(" template : " + w );
 
-        /* lets make our own string to render */
+        /* lets make our own string to render */
 
-        String s = "We are using $project $name to render this.";
-        w = new StringWriter();
-        Velocity.evaluate( context, w, "mystring", s );
-        System.out.println(" string : " + w );
-    }
-}
+        String s = "We are using $project $name to render this.";
+        w = new StringWriter();
+        Velocity.evaluate( context, w, "mystring", s );
+        System.out.println(" string : " + w );
+    }
+}
 
    
 
 
@@ -660,7 +659,7 @@ $foo.bar( $myarr )
 
 
 
    where the template we used, testtemplate.vm, is
    
-
    Hi!  This $name from the $project project.
+
    Hi!  This $name from the $project project.
 
    
 
 
@@ -695,18 +694,18 @@ see the Javadoc API documentation.
    
 
    If we wanted to use a different directory than the current directory to load our template from, we could do something like this:
    
 
     ...
 
-import java.util.Properties;
+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");
-    Velocity.init( p );
+public static void main( String args[] )
+{
+    /* first, we init the runtime engine.  */
+
+    Properties p = new Properties();
+    p.setProperty("file.resource.loader.path", "/opt/templates");
+    Velocity.init( p );
 
-    /* lets make a Context and put data into it */
+    /* lets make a Context and put data into it */
 
     ...
 
    
@@ -715,19 +714,19 @@ see the Javadoc API documentation.
    
 
    And the same if you want to use a VelocityEngine object rather than the singleton engine:
    
 
     ...
 
-import java.util.Properties;
+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 );
+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 */
+    /* lets make a Context and put data into it */
 
     ...
 
    
@@ -1049,13 +1048,13 @@ see the Javadoc API documentation.
    
 
    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.
    
 
    This feature was designed for applications that need to communicate between the application layer and custom parts of the Velocity engine, such as loggers, resource loaders, resource managers, etc.
    
 
    The Application Attribute API is very simple.  From the application layer, there is a method of the VelocityEngine and the Velocity classes:
    
-
    public void setApplicationAttribute( Object key, Object value );
+
    public void setApplicationAttribute( Object key, Object value );
 
    
 
 
 
    through which an application can store on Object under an application (or internal component) specified key.  There are no restrictions on the key or the value.  The value for a key may be set at any time - it is not required that this be set before init() is called.
    
 
    Internal components can access the key-value pairs if they have access to the object via the RuntimeServices interface, using the method
    
-
    public Object getApplicationAttribute( Object key );
+
    public Object getApplicationAttribute( Object key );
 
    
 
 
@@ -1067,13 +1066,13 @@ see the Javadoc API documentation.
    
 
    org.apache.velocity.app.event.IncludeEventHandler
    
 
    
 
    The IncludeEventHandler can be used to modify the template that is included in a page with #include or #parse.  For example, this may be used to make all includes relative to the current directory or to prevent access to unauthorized resources. Multiple IncludeEventHandler's may be chained, with the return value of the final call used as the name of the template to retrieve.
    
-
    public IncludeEventHandler extends EventHandler
-{
-    public String includeEvent( Context context,
-                                String includeResourcePath, 
-                                String currentResourcePath, 
-                                String directiveName );
-}
+
    public IncludeEventHandler extends EventHandler
+{
+    public String includeEvent( Context context,
+                                String includeResourcePath, 
+                                String currentResourcePath, 
+                                String directiveName );
+}
 
    
 
 
@@ -1086,25 +1085,25 @@ see the Javadoc API documentation.
    
 
    org.apache.velocity.app.event.InvalidReferenceEventHandler
    
 
    
 
    Normally, when a template contains a bad reference an error message is logged and (unless it is part of a #set or #if), the reference is included verbatim in a page.  With the InvalidReferenceEventHandler this behavior can be changed.  Substitute values can be inserted, invalid references may be logged, or an exception can be thrown.  Multiple InvalidReferenceEventHandler's may be chained.  The exact manner in which chained method calls behave will differ per method.  (See the javadoc for the details).
    
-
    public InvalidReferenceEventHandler extends EventHandler
-{
-    public Object invalidGetMethod( Context context, 
-                                    String reference, 
-                                    Object object, 
-                                    String property, 
-                                    Info info);
-
-    public boolean invalidSetMethod( Context context, 
-                                     String leftreference, 
-                                     String rightreference, 
-                                     Info info);
-
-    public Object invalidMethod( Context context, 
-                                 String reference,
-                                 Object object, 
-                                 String method, 
-                                 Info info);
-}
+
    public InvalidReferenceEventHandler extends EventHandler
+{
+    public Object invalidGetMethod( Context context, 
+                                    String reference, 
+                                    Object object, 
+                                    String property, 
+                                    Info info);
+
+    public boolean invalidSetMethod( Context context, 
+                                     String leftreference, 
+                                     String rightreference, 
+                                     Info info);
+
+    public Object invalidMethod( Context context, 
+                                 String reference,
+                                 Object object, 
+                                 String method, 
+                                 Info info);
+}
 
    
 
 
@@ -1116,14 +1115,14 @@ see the Javadoc API documentation.
    
 
    org.apache.velocity.app.event.MethodExceptionEventHandler
    
 
    
 
    When a user-supplied method throws an exception, the MethodExceptionEventHandler is invoked with the Class, method name and thrown Exception.  The handler can either return a valid Object to be used as the return value of the method call or throw the passed-in or new Exception, which will be wrapped and propogated to the user as a MethodInvocationException.  While MethodExceptionEventHandler's can be chained only the first handler is actually called -- all others are ignored.
    
-
    public interface MethodExceptionEventHandler extends EventHandler
-{
-    public Object methodException( Context context,
-                                   Class claz, 
-                                   String method, 
-                                   Exception e )
-         throws Exception;
-}
+
    public interface MethodExceptionEventHandler extends EventHandler
+{
+    public Object methodException( Context context,
+                                   Class claz, 
+                                   String method, 
+                                   Exception e )
+         throws Exception;
+}
 
    
 
 
@@ -1135,12 +1134,12 @@ see the Javadoc API documentation.
    
 
    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( Context context,
-                                     String reference, 
-                                   Object value  );
-}
+
    public interface  ReferenceInsertionEventHandler extends EventHandler
+{
+    public Object referenceInsert( Context context,
+                                   String reference, 
+                                   Object value  );
+}
 
    
 
 
@@ -1154,15 +1153,15 @@ see the Javadoc API documentation.
    
 
    
 
    Registering Event Handlers
    
 
    You may register event handlers in either of two manners.  The easiest way to register event handlers is to specify them in velocity.properties.  (Event handlers configured in this manner are referred to as "global" event handlers).  For example, the following property will escape HTML entities in any inserted reference.
    
-
    eventhandler.referenceinsertion.class = org.apache.velocity.app.event.implement.EscapeHtmlReference
+
    eventhandler.referenceinsertion.class = org.apache.velocity.app.event.implement.EscapeHtmlReference
 
    
 
 
 
    Most event handler interfaces will also permit event handlers to be chained together.  Such a chain may be in a comma separated list or as additional lines with a property/value pair. For example, the following event handler properties install two ReferenceInsertionEventHandler's.  The first will apply to references starting with "msg" (for example $msgText) and will escape HTML entities (e.g. turning & into &amp;).  The second will escape all references starting with "sql" (for example $sqlText) according to SQL escaping rules. (note that in these examples, the first two properties given relate to the event handler configuration while the second two properties are used by the specific event handler implementation).
    
-
    eventhandler.referenceinsertion.class = org.apache.velocity.app.event.implement.EscapeHtmlReference
-eventhandler.referenceinsertion.class = org.apache.velocity.app.event.implement.EscapeSqlReference
-eventhandler.escape.html.match = /msg.*/
-eventhandler.escape.sql.match = /sql.*/
+
    eventhandler.referenceinsertion.class = org.apache.velocity.app.event.implement.EscapeHtmlReference
+eventhandler.referenceinsertion.class = org.apache.velocity.app.event.implement.EscapeSqlReference
+eventhandler.escape.html.match = /msg.*/
+eventhandler.escape.sql.match = /sql.*/
 
    
 
 
@@ -1170,43 +1169,43 @@ eventhandler.escape.sql.match = /sql.*/
 
    The following code shows how to register an event handler with an EventCartridge and a context.
    
 
     ...
 
-import org.apache.velocity.app.event.EventCartridge;
-import org.apache.velocity.app.event.ReferenceInsertionEventHandler;
-import org.apache.velocity.app.event.implement.EscapeHtmlReference;
-import org.apache.velocity.app.event.implement.EscapeSqlReference;
+import org.apache.velocity.app.event.EventCartridge;
+import org.apache.velocity.app.event.ReferenceInsertionEventHandler;
+import org.apache.velocity.app.event.implement.EscapeHtmlReference;
+import org.apache.velocity.app.event.implement.EscapeSqlReference;
 
  ...
 
-public class Test
-{
-    public void myTest()
-    {
+public class Test
+{
+    public void myTest()
+    {
      ...
 
-    /**
-     * Make a cartridge to hold the event handlers 
-     */
-         EventCartridge ec = new EventCartridge();
-
-    /*
-     * then register and chain two escape-related handlers 
-     */
-         ec.addEventHandler(new EscapeHtmlReference());
-         ec.addEventHandler(new EscapeSqlReference());
-
-    /*
-     * and then finally let it attach itself to the context
-     */
-         ec.attachToContext( context );
-
-    /*
-     * now merge your template with the context as you normally
-     * do
-     */
+    /**
+     * Make a cartridge to hold the event handlers 
+     */
+         EventCartridge ec = new EventCartridge();
+
+    /*
+     * then register and chain two escape-related handlers 
+     */
+         ec.addEventHandler(new EscapeHtmlReference());
+         ec.addEventHandler(new EscapeSqlReference());
+
+    /*
+     * and then finally let it attach itself to the context
+     */
+         ec.attachToContext( context );
+
+    /*
+     * now merge your template with the context as you normally
+     * do
+     */
 
      ...
-    }
-}
+    }
+}
 
    
 
 
@@ -1573,29 +1572,29 @@ eventhandler.escape.sql.match = /sql.*/
 
 
    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 interface. Set it to none to only accept default Java conversions, as for Velocity 1.x.
    
 
    You can also provide custom Converter<T> objects that handle a conversion towards a specific type:
    
-
    package mypackage;
+
    package mypackage;
 
-import java.util.Date;
-import org.apache.velocity.util.introspection.*;
+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 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>
-    {
+    public static class ConvertToDate extends Converter<Date>
+    {
         @Override
-        public Date convert(Object o)
-        {
-            return new Date(((Number)o).longValue());
-        }
-    }
-}
+        public Date convert(Object o)
+        {
+            return new Date(((Number)o).longValue());
+        }
+    }
+}
 
    
 
 
@@ -1622,36 +1621,35 @@ eventhandler.escape.sql.match = /sql.*/
 
 
 
    Now make a little Java program that includes code similar to:
    
-
    <div class="source"><pre>
-...
+
    ...
 
-SAXBuilder builder;
-Document root = null;
+SAXBuilder builder;
+Document root = null;
 
-try
-{
-    builder = new SAXBuilder(
-        "org.apache.xerces.parsers.SAXParser" );
-    root = builder.build("test.xml");
-}
-catch( Exception ee)
-{}
+try
+{
+    builder = new SAXBuilder(
+        "org.apache.xerces.parsers.SAXParser" );
+    root = builder.build("test.xml");
+}
+catch( Exception ee)
+{}
 
-VelocityContext vc = new VelocityContext();
-vc.put("root", root.getRootElement());
+VelocityContext vc = new VelocityContext();
+vc.put("root", root.getRootElement());
 
 
-...
+...
 
    
 
 
 
    Now, make a regular Velocity template:
    
-
    <html>
-  <body>
+
    <html>
+  <body>
     The document title is
-      $root.getChild("document").getChild("properties")
+      $root.getChild("document").getChild("properties")
               .getChild("title").getText()
-  </body>
+  </body>
 
    
 
 
@@ -1666,30 +1664,30 @@ vc.put("root", root.getRootEle
 ## and use it as
 
 #set( $sometext = " < " )
-<text>#xenc($sometext)</text>
+<text>#xenc($sometext)</text>
 
    
 
 
 
    where the escapeEntities() is a method that does the escaping for you. Another trick would be to create an encoding utility that takes the context as a constructor parameter and only implements a method:
    
-
    public String get(String key)
-{
-    Object obj = context.get(key)
-    return (obj != null)
-        ? Escape.getText( obj.toString() )
-        : "";
-}
+
    public String get(String key)
+{
+    Object obj = context.get(key)
+    return (obj != null)
+        ? Escape.getText( obj.toString() )
+        : "";
+}
 
    
 
 
 
    Put it into the context as "xenc". Then you can use it as:
    
-
    <text>$xenc.sometext</text>
+
    <text>$xenc.sometext</text>
 
    
 
 
 
    This takes advantage of Velocity's introspection process - it will try to call get("sometext") on the $xenc object in the Context - then the xenc object can then get the value from the Context, encode it, and return it.
    
 
    Alternatively, since Velocity makes it easy to implement custom Context objects, you could implement your own context which always applies the encoding to any string returned. Be careful to avoid rendering the output of method calls directly, as they could return objects or strings (which might need encoding). Place them first into the context with a #set() directive and the use that, for example:
    
-
    #set( $sometext = $jdomElement.getText() )
-<text>$sometext</text>
+
    #set( $sometext = $jdomElement.getText() )
+<text>$sometext</text>
 
    
 
 
@@ -1698,18 +1696,17 @@ vc.put("root", root.getRootEle
 
    Velocity can be integrated into the Java Scripting Language Framework (as defined by the JSR-223 API).
    
 
    This section is a brief illustration of how to use Velocity Scripting framework through the JSR-223 API.
    
 
    Hello World example:
    
-
    // get script manager, create a new Velocity script engine factory and get an engine from it
-ScriptEngineManager manager = new ScriptEngineManager();
-manager.registerEngineName("velocity", new VelocityScriptEngineFactory());
-ScriptEngine engine = manager.getEngineByName("velocity");
-
-
-System.setProperty(VelocityScriptEngine.VELOCITY_PROPERTIES, "path/to/velocity.properties");
-String script = "Hello $world";
-Writer writer = new StringWriter();
-engine.getContext().setWriter(writer);
-Object result = engine.eval(script);
-System.out.println(writer);
+
    // get script manager, create a new Velocity script engine factory and get an engine from it
+ScriptEngineManager manager = new ScriptEngineManager();
+manager.registerEngineName("velocity", new VelocityScriptEngineFactory());
+ScriptEngine engine = manager.getEngineByName("velocity");
+
+System.setProperty(VelocityScriptEngine.VELOCITY_PROPERTIES, "path/to/velocity.properties");
+String script = "Hello $world";
+Writer writer = new StringWriter();
+engine.getContext().setWriter(writer);
+Object result = engine.eval(script);
+System.out.println(writer);
 
    
 
 

Modified: velocity/site/production/engine/2.0/source-repository.html
URL: http://svn.apache.org/viewvc/velocity/site/production/engine/2.0/source-repository.html?rev=1834410&r1=1834409&r2=1834410&view=diff
==============================================================================
--- velocity/site/production/engine/2.0/source-repository.html (original)
+++ velocity/site/production/engine/2.0/source-repository.html Tue Jun 26 10:03:18 2018
@@ -256,7 +256,7 @@ h2:hover > .headerlink, h3:hover > .head
 
    The Subversion client can go through a proxy, if you configure it to do so. First, edit your "servers" configuration file to indicate which proxy to use. The file's location depends on your operating system. On Linux or Unix it is located in the directory "~/.subversion". On Windows it is in "%APPDATA%\Subversion". (Try "echo %APPDATA%", note this is a hidden directory.)
    
 
    There are comments in the file explaining what to do. If you don't have that file, get the latest Subversion client and run any command; this will cause the configuration directory and template files to be created.
    
 
    Example: Edit the 'servers' file and add something like:
    
-
    [global]
+
    [global]
 http-proxy-host = your.proxy.name
 http-proxy-port = 3128