Velocity Official Guide - Using Velocity

[[143748]]

If you are using VelocityViewServlet or other web frameworks, you will not call Velocity directly. However, if you are in a non-web application or a web framework written by yourself, you will call the Velocity engine directly as described above. Another important point to remember is that the Velocity engine must be initialized before using the Velocity merge template.

Velocity Helper Class

Velocity contains an application utility class called Velocity (org.apache.velocity.app.Velocity). This class mainly provides some methods necessary for initializing Velocity, as well as some common methods that simplify the use of Velocity. This is described in the project's javadoc, and you can get more detailed instructions by reading the javadoc. This document is just a tutorial; therefore, if you need to understand the complete API information, javadoc is your best choice.

The Velocity runtime engine is a single instance that provides other services such as resource acquisition, logging, etc. to other users in the same JVM. Therefore, the runtime engine is initialized only once. You can try to initialize it multiple times, but only the first time is valid, and subsequent initialization operations will be ignored. The Velocity tool class provides five methods for configuring the runtime engine.

The five configuration methods are as follows:

• setProperty(String key, Object o)
  Sets the property key to o. The value is usually a string, but in special cases it can be a comma-delimited list of values ​​(such as "foo,bar,woogie"), or other values.
• Object getProperty(String key)
  Get the value corresponding to the attribute key key. It should be noted that the type of the return value is not just a string type
• init()
  Initialize the runtime engine using the properties configured in the default properties file in the jar package
• init(Properties p)
  Initializes the runtime engine using properties of type java.util.Properties parameter input and output
• init( String filename )
  Initializes the runtime engine using the property values ​​in the properties file named filename

It should be noted that in the above five methods, the default properties are the basic configuration, and the additional properties are used to replace the corresponding properties in the default configuration. The default properties that are not replaced will continue to work. This helps you only replace the ones you are interested in, without having to replace the entire thing.

It should also be noted that the init() method can be called multiple times in the application without causing any other problems. However, only the engine configuration in the first call will take effect, and the configuration used in subsequent calls to init() will be ignored.

The most common way to initialize Velocity is usually as follows:
1 Configure the properties you need to replace according to the format in the org/apache/velocity/runtime/defaults/velocity.properties file, put them in the file or in java.util.Properties, and then call init(filename) or init(Properties)
2 Set a single configuration item through the setProperty() method and then call initial(). This method is usually used in high-level applications that have their own configuration management system. For example, it allows applications to configure Velocity based on values ​​generated at runtime.

Once the runtime engine is initialized, you can do whatever you want. Of course, it mainly revolves around rendering templates and outputting content to the output stream. Some methods in the Velocity auxiliary class can help you easily get it done. Here is a brief description of these methods and what they do:

• evaluate( Context context, Writer out, String logTag, String instring )
• evaluate( Context context, Writer writer, String logTag, InputStream instream ) These methods use the passed context object to render an input to the Writer; the input content can be a string or an InputStram. This method is often used to replace tokens in strings, render template content stored in a database or other non-stationery storage, or generate content dynamically.
• invokeVelocimacro( String vmName, String namespace, String params[], Context context, Writer writer )
  This method can be used to call Velocity macros directly, or through the evaluate() method above. You only need to give your vm template a name, create an array for the vm, a context containing the data, and a Writer for outputting the content. It should be noted that the elements in the array provided to the vm here can only be the keys in the context, not other strings passed as parameters to the vm. This may be changed in later versions.

• mergeTemplate( String templateName, Context context, Writer writer ) This method is very convenient for calling the template output and rendering functions provided by Velocity. This method will read and render the template. The file loader will load the template content according to the properties you set, so you can take advantage of the file processing provided by Velocity and the pre-parsed template cache.
• boolean templateExists( String name ) determines whether the currently configured resource loader can load the template file with the channel name name.

Through the above documents, we have already understood these basic auxiliary methods, and now we can write Java programs using Velocity:

 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, initialize the runtime engine, using the default configuration */   
  
 Velocity.init(); 
  
 /* Create a Context object and put the data into it */   
  
        VelocityContext context = new VelocityContext(); 
  
        context.put( "name" , "Velocity" );
        context.put( "project" , "Jakarta" ); 
  
 /* Render template */   
  
        StringWriter w = new StringWriter(); 
 
        Velocity.mergeTemplate( "testtemplate.vm" , context, w );
        System.out.println( " template : " + w ); 
  
 /* Render string */   
  
        String s = "We are using $project $name to render this." ;
        w = new StringWriter();
        Velocity.evaluate( context, w, "mystring" , s );
        System.out.println( " string : " + w );
 }
 }

Before running the program, we need to put the template file testtemplate.vm in the same directory as the program (because we use the default configuration, the template loading path specified in the default configuration is the current directory of the program). After running the above code, it will output:

template : Hi! This Velocity from the Jakarta project.
string : We are using Jakarta Velocity to render this.

The content of the template file testtemplate.vm is:

Hi! This $name from the $project project.

Well, that's all we need to do to render a template using Velocity. There is no need to call both mergeTemplate() and evaluate() in the code, but we use both here for demonstration purposes. You usually only need to use one of the methods. But whether to call one or both depends on the specific requirements of your program.

This may seem a little different from the basic process described at the beginning of the article, but they are actually the same. First, you still need to create a context and put the data you need in it. The difference in the examples described above is the use of the mergeTemplate() method, which calls the method in the underlying Runtime class to load the template and then merge the content. In the second example above, the template is dynamically created through a string, which is similar to the operation of selecting a template in the basic mode; the subsequent merge() method calls the underlying method to merge the template content.

So the above example is the same basic process as described at the beginning of the article, except that some tool methods here do the repetitive hard work; it also demonstrates that in addition to getting template content from template files, you can also create template content dynamically.

abnormal

Velocity may throw exceptions during the parsing and merging of templates. These exceptions all inherit from RuntimeException, so there is no need to catch them explicitly. Each exception contains specific properties to provide specific information to the caller. These exception classes are placed in the org.apache.velocity.exception package, and there are the following types:

1. ResourceNotFoundException
Thrown when the resource management system cannot find the corresponding resource for the request.
2. ParseErrorException
Thrown when an error occurs while parsing the Velocity template syntax
3. TemplateInitException
Thrown at the first stage of template parsing, indicating an error in the initialization of a Velocity macro or directive
4.MethodInvocationException
When a method of an object in Context is called when rendering a template, it is thrown when an error occurs. This exception wraps the exception thrown by the method of the calling object and passes it to the application, allowing you to handle problems in these objects at runtime.

Each time any of the above exceptions are thrown, they will be recorded in the runtime log. You can read the javadoc api documentation for more details.

Other details

Although the above code uses default properties, it is very simple to set custom properties. All you need to do is create a properties file, add the properties you need to customize to the file, and then pass the file path to the init(String) method in the Velocity tool class; or create a java.util.Poperties object, add the custom properties to this object, and then pass it to the init(Properties) method of the Velocity tool class. The latter method is more flexible because you can load a properties file through the load() method of Properties, or better yet, dynamically pass in runtime settings in your application or framework. You can easily combine all the properties used by your application into a properties file.

If you want to load template files from another directory instead of the current directory, we can do it in the following way

 ... 
 
 import java.util.Properties;
 ... 
 
 public static void main( String args[] )
 {
 /* First, we initialize the runtime engine */ 
  
    Properties p = new Properties();
    p.setProperty("file.resource.loader.path", "/opt/templates");
 Velocity.init( p ); 
  
 ...

In order to run the above code smoothly, you need to have a /opt/templates directory and put the file testtemplate.vm in this directory. If you do the above and still have problems, you can check the velocity.log file to determine the specific cause. After all, reading the error log is your only choice to locate the problem.

 ... 
  
   VelocityEngine velocityEngine = new VelocityEngine();
   ExtendedProperties eprops = null ;
 if ( props == null ) {
 eprops = new ExtendedProperties();
 } else {
 eprops = ExtendedProperties .convertProperties(props);
 } 
  
 // Now, we use an object instance to set properties
   eprops.setProperty("name", object); 
  
 ...
   velocityEngine.setExtendedProperties(eprops);
 velocityEngine.init();
 ...

You might consider trying the [Apply Attributes] feature described in the following section.