文档章节

FreeMarker配置(Configuration)

空心大白菜
 空心大白菜
发布于 2013/11/12 14:50
字数 2346
阅读 15899
收藏 21

基础

Configuration 是一个存放应用级别(application level)公共配置信息,以及模版(Template)可使用的全局共享变量的一个对象。同时它还负责模版(Template)实例的创建以及缓存。Configuration 实际上是freemarker.template.Configuration 对象的实例,使用其构造函数创建。通常应用使用一个共享的单实例Configuration 对象。

Configuration 对象可被Template 对象的方法使用,每一个模版实例都关联与一个Configuration 实例,它是通过Template 的构造函数被关联进去的,通常是你使用这个方法来Configuration.getTemplate 获得模版对象的。

 

共享变量

共享变量是那些定义给所有模版(Template)使用的变量。你可以通过configuration对象的setSharedVariable 方法来添加共享变量。

Configuration cfg = new Configuration(); ... cfg.setSharedVariable("wrap", new WrapDirective()); cfg.setSharedVariable("company", "Foo Inc."); // Using ObjectWrapper.DEFAULT_WRAPPER

所有与该configuration 对象关联的模版实例都就可以通过获得to_upper 转换器,company 来获得字符串,因此你不需要再一次次的往root 中添加这些变量了。如果你往root 添加同名的变量,那么你新添加的变量将会覆盖之前的共享变量。

警告!

如果configuration 对象被多线程调用,那么不要使用TemplateModel 实现类作为共享变量,因为他们是非线程安全的,例如基于servlet 的web 站点就是这种情况。

Configuration 对象初始化时已经包含一些共享转换器变量:

名字类

name class
capture_output freemarker.template.utility.CaptureOutput
compress freemarker.template.utility.StandardCompress
html_escape freemarker.template.utility.HtmlEscape
normalize_newlines freemarker.template.utility.NormalizeNewlines
xml_escape freemarker.template.utility.XmlEscape

 

 

配置参数

配置参数是那些可以影响FreeMarker 运行行为的那些命名参数。例如locale,number_format

配置参数存储在Configuration实例中,它可以被模版实例(Template)修改。例如,你在Configuration中设置了locale等于"en_US",那么所有的模版对象都会使用,"en_US"除非你在单个模版实例中利用setLocale方法修改了默认配置。因此configuration设置的参数可以当作是默认参数,它可以被Template一级设置的参数覆盖,而它们两者设置的参数信息又可以被环境中设置的参数所覆盖(也就是模版文件指令设置的)如下:

${1.2}
<#setting locale="en_US">
${1.2}


这种调用方式你可以想象成3 个层(配置对象层,模版层,运行环境层)下面表格中显示了每一层对于参数的设置:

Setting A Setting B Setting C Setting D Setting E Setting F
Layer 3:Environment 1 - - 1 - -
Layer 2:Template 2 2 - - 2 -
Layer 1:Configuration 3 3 3 3 - -

那么配置参数的最终结果分别是:A = 1, B = 2, C = 3, D = 1, E = 2.而F 参数很可能就是null。

如果要查询可设置的参数列表,你可以查阅FreeMarker API 文档的以下两个部分:
所有层的配置

freemarker.core.Configurable.setSetting(String, String)


Coniguration 层的配置

freemarker.template.Configuration.setSetting(String,String)

加载模板


模版加载器

模版加载器是基于抽象路径("index.ftl"或"products/catalog.ftl")加载原始数据的那些对象,而究竟加载何种资源(目录中的文件数据还是数据库中的数据)取决于具体的加载器实现。当你调用cfg.getTemplate 时,FreeMarker 将会询问你之前配置给Configuration 对象的模版加载器,有该模版加载器负责文件的载入。

内建的模版加载器
你可以用以下三个方法来设置模版加载的三种方式

void setDirectoryForTemplateLoading(File dir);


或者

void setClassForTemplateLoading(Class cl, String prefix);


或者

void setServletContextForTemplateLoading(Object servletContext, String path);


以上第一种方式显示的指定了一个文件系统中的目录,FreeMarker 将会在此目录记载模版,不用说,此目录必须存在,否在会抛出异常。

第二种方式以一个Class作为一个输入参数,当你想使用ClassLoader的方式来加载模版的时候,你就可以使用这种方式,这种方式将会调用来寻找模版文件,同时这种模版加载的方式要比前一种稳定一些尤其是在生产系统中。你可以很容易的把资源文件,以及图标等打包到.jar 文件中。

第三种方式把web 应用的上下文以及基路径(相对与WEN-INF 的父路进来说)作为参数。该种方式的模版加载器将会从web 应用上下文种加载模版。

从多个位置加载模版

如果你想从多个位置加载模版的话,你可以分别创建与不同位置对应的单个模版加载器,然后把它们包裹到一个名叫MultiTemplateLoader模版加载器中,最终通过方法setTemplateLoader(TemplateLoader loader)把其设置给Configuration 对象,以下有一个从两个不同位置加载模版的例子:

import freemarker.cache.*; // template loaders live in this package ... FileTemplateLoader ftl1 = new FileTemplateLoader(new File("/tmp/templates")); FileTemplateLoader ftl2 = new FileTemplateLoader(new File("/usr/data/templates")); ClassTemplateLoader ctl = new ClassTemplateLoader(getClass(), ""); TemplateLoader[] loaders = new TemplateLoader[] { ftl1, ftl2, ctl }; MultiTemplateLoader mtl = new MultiTemplateLoader(loaders); cfg.setTemplateLoader(mtl); 


FreeMarker 将会首先在路径/tmp/templates中搜索模版文件,如果没有找到那么回到路径/usr/data/templates中搜索,如果还没有找到,那么则会尝试用class-loader的方式加载。

从其他资源中获取模版文件

如果在这些内建的模版加载器中没有一个符合你的要求,那么你可以自己定制一个模版加载器,只需要实现freemarker.cache.TemplateLoader 接口就可以了,然后通过方法setTemplateLoader(TemplateLoader loader)把其传递给Configuration对象。

缓存模版

FreeMarker缓存模版的意思就是,当你通过getTemplate方法获取一个模版的时候,FreeMarker不仅会返回一个Template对象,而且会缓存该对象,当你下一次以相同的路径请求模版的时候,它就会返回缓存中的模版对象。如果你改变了模版文件,那么当你下一次获取模版的时候,FreeMarker会自动重新加载,重新解析模版。虽然如此,但是如果直接判断一个文件是否修改过是一个耗时的操作,那么FreeMarker 在Configuration 对象级别提供了一个配置参数“update delay”。该参数的意思是FreeMarker多长时间去判断一次模版的版本,默认设置是5秒钟,也就是每个5秒就会判断模版是否经过修改,如果你想实时的判断,那么设置该参数为0。另外一点需要注意,并不是所有的加载器都支持这种判断方式,举例来说基于class-loader 的模版加载器就不会发现你修改过模版文件。

对于删除缓存中的模版FreeMarker 是这么做的,你可以使用Configuration 对象方法clearTemplateCache 以手工的方式清楚缓存中的模版对象。而实际上缓存部分可以作为一个组建加入到FreeMarker 中(也就是它可以使用第三方缓存方案)你可以通过设置cache_storage 这个参数来实现。对大多数开发者来FreeMarker 自带的freemarker.cache.MruCacheStorage 实现已经足够了。这个缓存使用2 个级别的Most Recently Used(最近最多用)策略。在第一个级别,所有的缓存条目都是使用强引用(strongly referenced:条目并不会被JVM 所清楚,与其相对的弱引用softly reference)直到达到最大时间,那些最近最少使用的条目就会被迁移到二级缓存。在这个级别条目都是使用弱引用直到达到过期。若引用与强引用的区域的大小是可以在构造函数中设置的,例如你想把强引用区域设置为20,弱引用区域设置为250,那你可以使用以下代码:

cfg.setCacheStorage(new freemarker.cache.MruCacheStorage(20, 250))


由于MruCacheStorage 是默认的缓存实现,那么你也可以这样设置:

cfg.setSetting(Configuration.CACHE_STORAGE_KEY,"strong:20, soft:250");


当你创建一个新的Configuration时,其默认使用MruCacheStorage缓存实现且默认的值maxStrongSize等于0,maxSoftSize等于Integer.MAX_VALUE(也就是理论最大值)。但是对于高负荷的系统来说,我们建议maxStrongSize 设置成一个非0 的数值,不然会导致频繁的重新加载,重新解析模版。

 

异常处理

可能产生的异常

FreeMarker 产生的异常一般可归以下几类:

FreeMarker 初始化阶段产生的异常: 通常在你的应用中仅需要初始化FreeMarker 一次,而当在这个时间段类产生的异常就叫做初始化异常。

加载解析模版期的异常:当你通过Configuration.getTemplate()方法获取模版的时候(如果模版之前没有被缓存),将会产生两类异常:

  • IOException:由于模版没有找到,或在读取模版的时候发生其他的IO异常,比如你没有读取该文件的权限等等;
  • freemarker.core.ParseException 由于模版文件的语法使用不正确;

执行期间的异常:当你调用Template.process(...)方法的时候,会抛出两类异常:

  • IOException 往输出写数据时候发生的错误;
  • freemarker.template.TemplatException其他运行期产生的异常,比如一个最常见的错误就是模版引用了一个不存在的变量;

 

原文由motomagice@yahoo.com.cn翻译自FreeMarker官方手册《Programmer's Guide》。 

本文转载自:http://www.yshjava.cn/post/466.html

共有 人打赏支持
空心大白菜
粉丝 16
博文 48
码字总数 15363
作品 0
宝山
程序员
私信 提问
加载中

评论(3)

Kervon
Kervon
采用字符串模板时怎么引入外部定义的宏定义文件呢??大神求指导
空心大白菜
空心大白菜

引用来自“撕花焚玉”的评论

大神我是实在没办法了,,,,我是springmvc集成的freemarker,ftl文件是放在jar中,我是用ClassTemplateLoader ctl = new ClassTemplateLoader(this.getClass(), "/");
读取的ftl,但是我重复修改ftl文件,就会造成这个ftl文件的目录其他的文件被清掉,造成访问404,其他目录的页面就是好的,我现在 要是知道怎么让freemarker重新刷新一下节点的方法就好了,,大神求助啊
你的ftl不是在jar里么?怎么同目录的文件会被清掉呢?它是通过getResource的方式获取内容的啊 再说打到jar包不就失去修改模板的灵活性了?jar的升级都不方便。 如果要从classpath下读取,可采用如下方式 new FileTemplateLoader(ResourceUtils.getFile("classpath:template"));
撕花焚玉
撕花焚玉
大神我是实在没办法了,,,,我是springmvc集成的freemarker,ftl文件是放在jar中,我是用ClassTemplateLoader ctl = new ClassTemplateLoader(this.getClass(), "/");
读取的ftl,但是我重复修改ftl文件,就会造成这个ftl文件的目录其他的文件被清掉,造成访问404,其他目录的页面就是好的,我现在 要是知道怎么让freemarker重新刷新一下节点的方法就好了,,大神求助啊
FreeMarker在eclipse中的入门例子

今天海浪为大家分享一个FreeMarker在eclipse中的入门例子。 一、在eclipse中创建FreeMarker模板 在FreeMarker中模板的概念就是:包含一些由${…}包围的特殊代码的文件。这些特殊代码是FreeM...

oecp
2011/04/26
0
0
freemaker开发学习《一》

 FreeMarker是一个非常优秀的模板引擎,这个模板引擎可用于任何场景,FreeMarker负责将数据模型中的数据合并到模板中,从而生成标准输出.FreeMarker可以提供昜好的团队协作,对于界面开发人...

xiaml
2014/04/25
0
0
FreeMarker在eclipse中的入门例子

刚接触FreeMarker时,只是简单的了解FreeMarker的一些概念及工作原理,至于如何使用FreeMarker还不是非常清楚。随着学习的深入,才渐渐对FreeMarker有了更深入的理解。本文将从基础应用着手,...

oecp
2011/05/16
0
0
在Spring+FreeMarker框架中使用Shiro的Tag标签

目前Freemarker对Shrio的标签还不支持,不过已经有人贡献出来第三方面解决方案,如下: 1、下载shiro-freemarker-tags GitHub地址:https://github.com/jagregory/shiro-freemarker-tags 可以...

zkool
2014/01/19
0
0
JAVAEE——宜立方商城10:使用freemarker实现网页静态化、ActiveMq同步生成静态网页、Sso单点登录系统分析

1. 学习计划 1、使用freemarker实现网页静态化 2、ActiveMq同步生成静态网页 2. 网页静态化 可以使用Freemarker实现网页静态化。 2.1. 什么是freemarker FreeMarker是一个用Java语言编写的模...

kent鹏
08/01
0
0

没有更多内容

加载失败,请刷新页面

加载更多

rabbitmq学习

使用docker安装rabbit docker run -d --hostname my-rabbit --name rabbit -p 8080:15672 rabbitmq:management--hostname:指定容器主机名称--name:指定容器名称-p:将mq端口号映射到本地...

元谷
21分钟前
1
0
想知道谁是你的最佳用户?基于Redis实现排行榜周期榜与最近N期榜

本文由云+社区发表 前言 业务已基于Redis实现了一个高可用的排行榜服务,长期以来相安无事。有一天,产品说:我要一个按周排名的排行榜,以反映本周内用户的活跃情况。于是周榜(按周重置更新...

腾讯云加社区
24分钟前
2
0
函数计算性能福利篇(二) —— 业务冷启动优化

继前一篇《函数计算性能福利篇——系统冷启动优化》,我们再来看看近期函数计算推出的 Initializer 功能之后,带来的一波高能性能优化成果。 背景 函数计算是一个事件驱动的全托管 serverle...

阿里云官方博客
29分钟前
1
0
开源版本说明

1527
31分钟前
2
0
Mysql经验-------持续更新

单表行数超过 500 万行或者单表容量超过 2GB,才推荐进行分库分表。 说明:如果预计三年后的数据量根本达不到这个级别,请不要在创建表时就分库分表。

DoLo-lty
33分钟前
1
0

没有更多内容

加载失败,请刷新页面

加载更多

返回顶部
顶部