Apache Velocity开发者指南：模板引擎深入解析

4星 · 超过85%的资源需积分: 4 48 浏览量更新于2024-07-31 收藏 630KB PDF 举报

"Apache Velocity开发指南" Apache Velocity是一个基于Java的模板引擎，它作为一个简单而强大的开发工具，使得创建和渲染格式化并展示数据的文档变得轻而易举。本开发者指南旨在提供对Velocity基础概念的概述，帮助你深入理解其工作原理，并指导如何在实际应用中有效地使用它。 1. **介绍与入门** 开始使用Velocity时，你需要了解其基本概念和安装步骤。Velocity的工作流程是将模板语言与应用程序的数据相结合，生成动态内容。指南的这部分会引导你快速上手。 2. **资源** 在Velocity中，资源指的是模板、库和其他在渲染过程中使用的文件。理解如何管理和访问这些资源是关键，包括如何设置资源加载器和缓存策略。 3. **Velocity如何工作** Velocity的核心模式是“分离逻辑和表现”。这一章节解释了如何通过基本的模板语法来实现数据和模板的分离，以及Velocity引擎如何处理这些模板。 4. **单例还是非单例** 这部分讨论了在Velocity中使用单例模型（Singleton Model）和独立实例（Separate Instance）的优缺点，以及它们在不同场景下的适用性。 5. **上下文(Context)** 上下文是模板引擎中的核心组件，用于存储和传递数据。这里将介绍其基础知识，如如何支持迭代对象以配合`#foreach()`指令，对静态类的支持，上下文链，以及由模板创建的对象和其他上下文问题。 6. **在一般应用程序中使用Velocity** 这一章涵盖了如何在通用应用中集成Velocity，包括使用Velocity助手类，处理异常，以及其他一些细节问题。 7. **应用属性** 应用属性允许你自定义Velocity的行为。了解如何设置和使用这些属性对于优化性能和满足特定需求至关重要。 8. **配置事件处理器** 事件处理器可以扩展Velocity的功能，如捕获和处理模板中的特定事件。了解如何配置它们可以增强模板引擎的灵活性。 9. **Velocity配置键值** 本节提供了关于Velocity配置键值的详细信息，帮助你正确配置和定制Velocity引擎。 10. **配置日志** 日志系统对于调试和监控非常重要。指南介绍了如何配置Velocity的日志，包括使用Log4j和创建自定义日志器的示例。 11. **配置资源加载器（模板加载器）** 资源加载器决定了Velocity如何查找和加载模板。这里将讲解各种加载器，以及配置示例和插件式资源管理器及资源缓存。 12. **模板编码与国际化** 如果你的应用需要支持多语言，那么理解模板编码和国际化策略是必要的。Velocity提供了解决方案以适应不同的文本编码和语言需求。 13. **Velocity与XML** Velocity可以方便地处理XML数据，本节将介绍如何在XML文档处理中利用Velocity的优势。 14. **总结** 最后，开发者指南总结了主要概念和重要点，帮助你巩固所学知识。通过深入学习这个指南，你将能够熟练掌握Apache Velocity，为你的Java应用构建高效、灵活的模板系统。

Context Chaining

An innovative feature of Velocity's context design is the concept of context chaining. Also sometimes referred to ascontext

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

context1.put("name","Velocity");

context1.put("project", "Jakarta");

context1.put("duplicate", "I am in context1");

VelocityContext context2 = new VelocityContext( context1 );

context2.put("lang", "Java" );

context2.put("duplicate", "I am in context2");

template.merge( context2, writer );

In the code above, we have set up context2 such that it chains context1. This means that in the template, you can access any of the

items that were put into either of the two VelocityContext objects, as long as there is no duplication of the keys used to add

objects. If that is the case, as it is above for the key 'duplicate', the object stored in the nearest context in the chain will be

available. In this example above, the object returned would be the string "I am in context2".

Note that this duplication, or 'covering', of a context item does not in any way harm or alter the covered object. So in the example

above, the string "I am in context1" is alive and well, still accessable via context1.get("duplicate"). But in the example above, the

value of the reference '$duplicate' in the template would be 'I am in context2', and the template has no access to the covered string

'I am in context1'.

Note also that you have to be careful when you are relying on the template to add information to a context that you will examine

later after the rendering. The changes to the context via #set() statements in a template will affect only the outer context. So

make sure that you don't discard the outer context, expecting the data from the template to have been placed onto the inner one.

This feature has many uses, the most common so far is providing layered data access and toolsets.

As mentioned before, the Velocity context mechanism is also extendable, but beyond the current scope of this guide. If you are

interested, please see the classes in the package org.apache.velocity.contextto see how the provided contexts are put

together. Futher, there are a few examples in the examples/context_example directory in the distribution which show alternate

implementations, including [a goofy] one that uses a database as the backing storage.

Please note that these examples are unsupported and are there for demonstration/educational purposes only.

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 )

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")

Dealing with these cases if very straighforward, as there are just a few things to know:

• The VTL RangeOperator [ 1..10 ] and ObjectArray ["a","b"] are java.util.ArrayList objects when placed in the context

or passed to methods. Therefore, your methods that are designed to accept arrays created in the template should be written

with this in mind.

• VTL Map references are unsurprisingly stored as java.util.Map.

• Decimal numbers will be Doubles or BigDecimals in the context, integer numbers will be Integer, Long, or BigIntegers,

and strings will be, of course, Strings.

Apache Velocity

Developer's Guide

• Velocity will properly 'narrow' args to method calls, so calling setFoo( int i ) with an int placed into the context via

#set() will work fine.

Other Context Issues

One of the features provided by the VelocityContext (or any Context derived from AbstractContext) is node specific introspection

caching. Generally, you as a the developer don't need to worry about this when using the VelocityContext as your context.

However, there is currently one known usage pattern where you must be aware of this feature.

The VelocityContext will accumulate intropection information about the syntax nodes in a template as it visits those nodes. So, in

the following situation:

• You are iterating over the same template using the same VelocityContext object.

• Template caching is off.

• You request the Template from getTemplate() on each iteration.

It is possible that your VelocityContext will appear to 'leak' memory (it is really just gathering more introspection information.)

What happens is that it accumulates template node introspection information for each template it visits, and as template caching is

off, it appears to the VelocityContext that it is visiting a new template each time. Hence it gathers more introspection information

and grows. It is highly recommended that you do one or more of the following:

• Create a new VelocityContext for each excursion down through the template render process. This will prevent the

accumulation of introspection cache data. For the case where you want to reuse the VelocityContext because it's populated

with data or objects, you can simply wrap the populated VelocityContext in another, and the 'outer' one will accumulate the

introspection information, which you will just discard. Ex. VelocityContext useThis = new VelocityContext

( populatedVC );This works because the outer context will store the introspection cache data, and get any requested data

from the inner context (as it is empty.) Be careful though -if your template places data into the context and it's expected

that it will be used in the subsequent iterations, you will need to do one of the other fixes, as any template #set() statements

will be stored in the outermost context. See the discussion inContext chaining for more information.

• Turn on template caching. This will prevent the template from being re-parsed on each iteration, resulting the the

VelocityContext being able to not only avoid adding to the introspection cache information, but be able to use it resulting in

a performance improvement.

• Reuse the Template object for the duration of the loop iterations. Then you won't be forcing Velocity, if the cache is turned

off, to reread and reparse the same template over and over, so the VelocityContext won't gather new introspection

information each time.

Using Velocity

If you are using VelocityViewServlet or other web frameworks, you may never call Velocity directly. However, if you use

Velocity for non-web purposes, or create your own web framework you will need to directly call the Velocity Engine similar

tothe fundamental pattern shown earlier. One important additional thing to remember is to initialize the Velocity Engine before

using it to merge templates.

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.

• 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.

Apache Velocity

Developer's Guide

剩余30页未读，继续阅读

zhang_haisong

粉丝: 0
资源: 3

Apache Velocity开发者指南：模板引擎深入解析

velocity文档

Velocity-API.chm--采用官方文档制作-超值的Velocity API参考文档。

Apache Velocity - Velocity User Guide

Apache Velocity - VTL Reference

apache-solr-velocity-1.4.1-dev.jar

apache-solr-velocity-1.4.1.jar

apache-solr-velocity-3.5.0.jar

Apache-Solr-RCE-via-Velocity-template

velocity-site:Apache Velocity网站

velocity-1.5.jar，velocity-1.6.2-dep.jar，velocity-tools-1.3.jar

最新资源