freeMarker（六）——程序开发指南入门

学习笔记，选自freeMarker中文文档，译自 Email: ddekany at users.sourceforge.net

1.创建Configuration实例

　　首先，你应该创建一个 freemarker.template.Configuration 实例， 然后调整它的设置。Configuration 实例是存储 FreeMarker 应用级设置的核心部分。同时，它也处理创建和 缓存 预解析模板(比如 Template 对象)的工作。

　　也许你只在应用(可能是servlet)生命周期的开始执行一次：

 1 // Create your Configuration instance, and specify if up to what FreeMarker
 2 // version (here 2.3.22) do you want to apply the fixes that are not 100%
 3 // backward-compatible. See the Configuration JavaDoc for details.
 4 Configuration cfg = new Configuration(Configuration.VERSION_2_3_22);
 5 
 6 // Specify the source where the template files come from. Here I set a
 7 // plain directory for it, but non-file-system sources are possible too:
 8 cfg.setDirectoryForTemplateLoading(new File("/where/you/store/templates"));
 9 
10 // Set the preferred charset template files are stored in. UTF-8 is
11 // a good choice in most applications:
12 cfg.setDefaultEncoding("UTF-8");
13 
14 // Sets how errors will appear.
15 // During web page *development* TemplateExceptionHandler.HTML_DEBUG_HANDLER is better.
16 cfg.setTemplateExceptionHandler(TemplateExceptionHandler.RETHROW_HANDLER);

　　从现在开始，应该使用单实例配置(也就是说，它是单例的)。 请注意不管一个系统有多少独立的组件来使用 FreeMarker， 它们都会使用他们自己私有的 Configuration 实例。

警告：不需要重复创建 Configuration 实例； 它的代价很高，尤其是会丢失缓存。Configuration 实例就是应用级别的单例。

　　当使用多线程应用程序(比如Web网站)，Configuration 实例中的设置就不能被修改。它们可以被视作为 "有效的不可改变的" 对象， 也可以继续使用 安全发布 技术 (参考 JSR 133 和相关的文献)来保证实例对其它线程也可用。比如， 通过final或volatile字段来声明实例，或者通过线程安全的IoC容器，但不能作为普通字段。 (Configuration 中不处理修改设置的方法是线程安全的。)

2.创建数据模型

　　在简单的示例中你可以使用 java.lang 和 java.util 包中的类， 还有用户自定义的Java Bean来构建数据对象：

• 使用 java.lang.String 来构建字符串。

• 使用 java.lang.Number 来派生数字类型。

• 使用 java.lang.Boolean 来构建布尔值。

• 使用 java.util.List 或Java数组来构建序列。

• 使用 java.util.Map 来构建哈希表。

• 使用自定义的bean类来构建哈希表，bean中的项和bean的属性对应。比如， product 的 price 属性 (getProperty())可以通过 product.price 获取。(bean的action也可以通过这种方式拿到； 要了解更多可以参看 这里)

　　我们为 模板开发指南部分演示的第一个例子 来构建数据模型。为了方便说明，这里再展示一次示例：

(root)
  |
  +- user = "Big Joe"
  |
  +- latestProduct
      |
      +- url = "products/greenmouse.html"
      |
      +- name = "green mouse"

　　下面是构建这个数据模型的Java代码片段：

 1 // Create the root hash
 2 Map<String, Object> root = new HashMap<>();
 3 // Put string ``user'' into the root
 4 root.put("user", "Big Joe");
 5 // Create the hash for ``latestProduct''
 6 Map<String, Object> latest = new HashMap<>();
 7 // and put it into the root
 8 root.put("latestProduct", latest);
 9 // put ``url'' and ``name'' into latest
10 latest.put("url", "products/greenmouse.html");
11 latest.put("name", "green mouse");

　　在真实应用系统中，通常会使用应用程序指定的类来代替 Map， 它会有JavaBean规范规定的 getXxx/isXxx 方法。比如有一个和下面类似的类：

 1 public class Product {
 2 
 3     private String url;
 4     private String name;
 5     ...
 6     
 7     // As per the JavaBeans spec., this defines the "url" bean property
 8     public String getUrl() {
 9         return url;
10     }
11     
12     // As per the JavaBean spec., this defines the "name" bean property
13     public String getName() {
14         return name;
15     }
16     
17     ...
18     
19 }

　　将它的实例放入数据模型中，就像下面这样：

1 Product latestProducts = getLatestProductFromDatabaseOrSomething();
2 root.put("latestProduct", latestProduct);

　　如果latestProduct 是 Map类型， 模板就可以是相同的，比如 ${latestProduct.name} 在两种情况下都好用。

　　根root本身也无需是 Map，只要是有 getUser() 和 getLastestProduct() 方法的对象即可。

注意：如果配置设置项 object_wrapper 的值是用于所有真实步骤， 这里描述的行为才好用。任何由 ObjectWrapper 包装成的哈希表 可以用作根root，也可以在模板中和点、 [] 操作符使用。 如果不是包装成哈希表的对象不能作为根root，也不能像那样在模板中使用。

3.获取模板

　　模板代表了 freemarker.template.Template 实例。典型的做法是从 Configuration 实例中获取一个 Template 实例。无论什么时候你需要一个模板实例， 都可以使用它的 getTemplate 方法来获取。在 之前 设置的目录中的 test.ftl 文件中存储 示例模板，那么就可以这样来做：

Template temp = cfg.getTemplate("test.ftl");

　　当调用这个方法的时候，将会创建一个 test.ftl 的 Template 实例，通过读取 /where/you/store/templates/test.ftl 文件，之后解析(编译)它。Template 实例以解析后的形式存储模板， 而不是以源文件的文本形式。

　　Configuration 缓存 Template 实例，当再次获得 test.ftl 的时候，它可能再读取和解析模板文件了， 而只是返回第一次的 Template 实例。

4.合并模板和数据模型

　　我们已经知道，数据模型+模板=输出，我们有了一个数据模型 (root) 和一个模板 (temp)， 为了得到输出就需要合并它们。这是由模板的 process 方法完成的。它用数据模型root和 Writer 对象作为参数，然后向 Writer 对象写入产生的内容。 为简单起见，这里我们只做标准的输出：

1 Writer out = new OutputStreamWriter(System.out);
2 temp.process(root, out);

　　这会向你的终端输出你在模板开发指南部分的 第一个示例 中看到的内容。

　　Java I/O 相关注意事项：基于 out 对象，必须保证 out.close() 最后被调用。当 out 对象被打开并将模板的输出写入文件时，这是很电影的做法。其它时候， 比如典型的Web应用程序，那就 不能 关闭 out 对象。FreeMarker 会在模板执行成功后 (也可以在 Configuration 中禁用) 调用 out.flush()，所以不必为此担心。

　　请注意，一旦获得了 Template 实例， 就能将它和不同的数据模型进行不限次数 (Template实例是无状态的)的合并。此外， 当 Template 实例创建之后 test.ftl 文件才能访问，而不是在调用处理方法时。

5.将代码放在一起

　　这是一个由之前的代码片段组合在一起的源程序文件。 千万不要忘了将 freemarker.jar 放到 CLASSPATH 中。

 1 import freemarker.template.*;
 2 import java.util.*;
 3 import java.io.*;
 4 
 5 public class Test {
 6 
 7     public static void main(String[] args) throws Exception {
 8         
 9         /* ------------------------------------------------------------------------ */    
10         /* You should do this ONLY ONCE in the whole application life-cycle:        */    
11     
12         /* Create and adjust the configuration singleton */
13         Configuration cfg = new Configuration(Configuration.VERSION_2_3_22);
14         cfg.setDirectoryForTemplateLoading(new File("/where/you/store/templates"));
15         cfg.setDefaultEncoding("UTF-8");
16         cfg.setTemplateExceptionHandler(TemplateExceptionHandler.RETHROW);
17 
18         /* ------------------------------------------------------------------------ */    
19         /* You usually do these for MULTIPLE TIMES in the application life-cycle:   */    
20 
21         /* Create a data-model */
22         Map root = new HashMap();
23         root.put("user", "Big Joe");
24         Map latest = new HashMap();
25         root.put("latestProduct", latest);
26         latest.put("url", "products/greenmouse.html");
27         latest.put("name", "green mouse");
28 
29         /* Get the template (uses cache internally) */
30         Template temp = cfg.getTemplate("test.ftl");
31 
32         /* Merge data-model with template */
33         Writer out = new OutputStreamWriter(System.out);
34         temp.process(root, out);
35         // Note: Depending on what `out` is, you may need to call `out.close()`.
36         // This is usually the case for file output, but not for servlet output.
37     }
38 }

注意:为了简单起见，这里压制了异常(在方法签名中声明了异常)， 而在正式运行的产品中不要这样做。

 

译自 Email: ddekany at users.sourceforge.net

转载于:https://www.cnblogs.com/fx-blog/p/6292818.html