Velocity魔法堂系列三：模板与宿主环境通信-阿里云开发者社区

一、前言　　　　　　　　　　　　　　　　　　　　　　　　　　

Velocity作为历史悠久的模板引擎不单单可以替代JSP作为Java Web的服务端网页模板引擎，而且可以作为普通文本的模板引擎来增强服务端程序文本处理能力。而且Velocity被移植到不同的平台上，如.Net的 NVelocity和js的Velocity.js，虽然各平台在使用和实现上略有差别，但大部分语法和引擎核心的实现是一致的，因此学习成本降低不少哦。

最好的学习资源——官网：http://velocity.apache.org/

本系列打算采用如下结构对Velocity进行较为全面的学习，若有不妥或欠缺望大家提出，谢谢。

1. 入门示例

2. VTL语法详解

3. 模板与宿主环境通信

4. 基础配置项

5. 深入模板引擎及调优配置

二、模板与宿主环境通信　　　　　　　　　　　　　　　　　　　

模板指的是使用VTL编写的Velocity模板，宿主环境指的是Java代码调用部分。而两者通信的纽带就是引擎上下文对象( VelocityContext实例 )，下面是常用的 VelocityContext实例方法。

// 构造函数，入参为上下文的键值对集
VelocityContext(Map context)
// 添加上下文的键值对
Object put(String key, Object value)
// 从上下文获取指定键的值
Object get(String key)
// 检查上下文中是否存在指定的键值对
boolean containsKey(Object key)
// 获取所有键
Object[] getKeys()
// 移除指定键
Object remove(Object key)
// 获取上下文链中邻近的上下文对象
Context getChainedContext()

三、宿主环境向模板传值　　　　　　　　　　　　　　　　　　　　

// 1. 通过构造函数传值
HashMap<String, String> baseCtx = new HashMap<String, String>();
baseCtx.put("version", "1");
VelocityContext ctx = new VelocityContext(baseCtx);

// 2. 通过put传值
ctx.put("author", "fsjohnhuang");

注意键值对中值的数据类型为

Integer、Long等简单数据类型的装箱类型；

String类型；

Object子类；

Object[] 数组类型，从1.6开始Velocity将数组类型视为 java.util.List 类型看待，因此模板中可调用 size() 、 get(intindex) 和 isEmpty() 的变量方法；

java.util.Collection子类；

java.util.Map子类；

java.util.Iterator对象；

java.util.Enumeration对象。

除此之外，我们还可以将一个静态类赋予到上下文对象中，如 java.lang.Math静态类

ctx.put("Math", java.lang.Math.class);

四、模板向宿主环境传值　　　　　　　　　　　　　　　　　　　　　　

1. 通信示例1——通过引擎上下文对象获取变量

模板文件frm.vm

#set($action="./submit")
<form action="$action">
  .........
</form>

Java代码部分

VelocityContext ctx = new VelocityContext();
VelocityEngine ve = new VelocityEngine();
StringWriter sw = new StringWriter();
ve.mergeTemplate("frm.vm", ctx, sw);
String actionStr = ctx.get("action");
System.out.println(actionStr); // 显示./submit

2. 通信示例2——通过副作用修改变量、属性值

模板文件change.vm

$people.put("john", "john huang")
#set($version = $version + 1)

Java代码部分

VelocityContext ctx = new VelocityContext();
ctx.put("version", 1);
HashMap<String, String> people = new HashMap<String,String>();
ctx.put("people", people);
VelocityEngine ve = new VelocityEngine();
StringWriter sw = new StringWriter();
ve.mergeTemplate("change.vm", ctx, sw);
System.out.println(ctx.get("version")); // 显示2
System.out.println(people.get("john")); //显示john huang

上述示例表明在模板中对引用类型实例进行操作时，操作结果将影响到该引用类型实例本身，因此必须谨慎操作。

五、引擎上下文链　　　　　　　　　　　　　　　　　　　　　　　　　　

所谓引擎上下文链就是将原有的上下文对象赋予给新建的上下文对象，从而达到上下文内的键值对复用。具体代码如下：

VelocityContext ctx1 = new VelocityContext();
ctx1.put("name", "fsjohuang");
ctx1.put("version", 1);
VelocityContext ctx2 = new VelocityContext(ctx1);
ctx2.put("version", 2);

System.out.println(ctx2.get("name")); // 显示fsjohnhuang
System.out.println(ctx2.get("version")); // 显示2

就是当前上下文对象没有该键值对时，则查询上下文链的对象有没有该键值对，有则返回，无则继续找链上的其他上下文对象，直到找到该键值对或遍历完所有链上的上下文对象。

但VelocityContext实例除了put、get方法外，还有remove、getKeys、containsKey方法，它们的行为又是如何的呢？下面我们通过源码来了解吧！

六、从源码看引擎上下文　　　　　　　　　　　　　　　　　　　　　　　　

从源码 public class VelocityContext extends AbstractContext implements Cloneable 得知VelocityContext继承自AbstractContext抽象类，且实现了抽象类的internalGet、internalPut、internalContainsKey、internalGetKeys和internalRemove方法，实际开发中常用的put、get等方法却是由AbstractContext提供的，而put、get方法内部在调用对应的internalGet、internalPut方法外再进行了其他处理。这是一种由子类提供具体实现，父类提供对外接口的设计方式（但与纯面向接口编程又有些区别）。

VelocityContext类源码片段：

public class VelocityContext extends AbstractContext implements Cloneable
{
  private Map context = null;
  
  public Object internalGet( String key )
  {
      return context.get( key );
  }

  public Object internalPut( String key, Object value )
  {
      return context.put( key, value );
  }

  public  boolean internalContainsKey(Object key)
  {
      return context.containsKey( key );
  }

  public  Object[] internalGetKeys()
  {
      return context.keySet().toArray();
  }

  public  Object internalRemove(Object key)
  {
      return context.remove( key );
  }
}

从上面可知VelocityContext内置一个Map实例，而各实例方法均为对该Map实例的操作。

AbstractContext类源码片段：

public abstract class AbstractContext extends InternalContextBase
    implements Context
{
    // 上下文对象链中邻近的上下文对象
    private   Context  innerContext = null;

    // 只将键值对存放在当前上下文对象的Map对象中
    public Object put(String key, Object value)
    {
        /*
         * don't even continue if key is null
         */
        if (key == null)
        {
            return null;
        }
        
        return internalPut(key.intern(), value);
    }

     // 从当前上下文对象的HashMap对象获取键值
     //  失败再从上下文链中寻找
     public Object get(String key)
    {
        if (key == null)
        {
            return null;
        }


        Object o = internalGet( key );

        if (o == null && innerContext != null)
        {
            o = innerContext.get( key );
        }

        return o;
    }

    // 搜索整条上下文链的对象是否包含指定键值对
    public boolean containsKey(Object key)
    {
        if (key == null)
        {
            return false;
        }

        boolean exists = internalContainsKey(key);
        if (!exists && innerContext != null)
        {
            exists = innerContext.containsKey(key);
        }
        
        return exists;
    }

    // 仅返回当前上下文对象的Map对象的键
    public Object[] getKeys()
    {
        return internalGetKeys();
    }

    // 仅移除当前上下文对象的Map对象指定的键值对
    // 上下文链上的其他对象不受影响
     public Object remove(Object key)
    {
        if (key == null)
        {
            return null;
        }

        return internalRemove(key);
    }
}