Apache FreeMarker™ 技术文档

2024-12-23 16:24:50作者：苗圣禹Peter

1. 安装指南

使用 Maven 安装

如果你使用 Maven 进行项目管理，只需在 pom.xml 文件中添加以下依赖：

<dependency>
    <groupId>org.freemarker</groupId>
    <artifactId>freemarker-gae</artifactId>
    <version>{version}</version>
</dependency>

注意：确保没有其他依赖项引入旧版本的 freemarker（groupId 为 freemarker 而不是 org.freemarker），否则可能会导致运行时行为不可预测。

手动安装

如果不使用 Maven，可以直接将 freemarker.jar 文件复制到你的 Java 应用程序的 ClassLoader 可以找到的位置。例如，如果你在 Web 应用程序中使用 FreeMarker，可以将 freemarker.jar 放入 WEB-INF/lib 目录。

FreeMarker 没有强制依赖项，但有一些可选依赖项。通常情况下，你不需要处理这些依赖项，除非你使用了某些需要特定库的特性。

升级到 OpenJDK 9 或更高版本

如果你升级到 OpenJDK 9 或更高版本，并且你在模板中使用 XPath 查询，你需要添加 Apache Xalan 作为依赖项，因为 freemarker.ext.dom 无法再使用 OpenJDK 内置的 XPath 支持。

2. 项目的使用说明

什么是 Apache FreeMarker™？

Apache FreeMarker™ 是一个“模板引擎”，它是一个通用的工具，用于基于模板生成文本输出（从 HTML 到自动生成的源代码）。它是一个 Java 包，供 Java 程序员使用的类库。它本身并不是一个面向最终用户的应用程序，而是程序员可以嵌入到其产品中的工具。FreeMarker 的设计目的是为基于 MVC（模型视图控制器）模式的 servlet 应用程序生成 HTML Web 页面。

使用场景

FreeMarker 通常用于以下场景：

生成动态 HTML 页面。
生成电子邮件模板。
生成源代码、配置文件等。

3. 项目 API 使用文档

基本用法

FreeMarker 的核心 API 主要包括 Configuration 和 Template 类。以下是一个简单的示例，展示如何使用 FreeMarker 生成 HTML 输出：

import freemarker.template.Configuration;
import freemarker.template.Template;
import freemarker.template.TemplateExceptionHandler;

import java.io.File;
import java.io.OutputStreamWriter;
import java.io.Writer;
import java.util.HashMap;
import java.util.Map;

public class FreeMarkerExample {
    public static void main(String[] args) throws Exception {
        // 创建配置实例
        Configuration cfg = new Configuration(Configuration.VERSION_2_3_31);

        // 指定模板文件的位置
        cfg.setDirectoryForTemplateLoading(new File("templates/"));

        // 设置异常处理方式
        cfg.setTemplateExceptionHandler(TemplateExceptionHandler.RETHROW_HANDLER);

        // 获取模板
        Template temp = cfg.getTemplate("example.ftl");

        // 创建数据模型
        Map<String, Object> root = new HashMap<>();
        root.put("message", "Hello, FreeMarker!");

        // 合并模板和数据模型
        Writer out = new OutputStreamWriter(System.out);
        temp.process(root, out);
    }
}

模板示例

以下是一个简单的 FreeMarker 模板文件 example.ftl：

<!DOCTYPE html>
<html>
<head>
    <title>FreeMarker Example</title>
</head>
<body>
    <h1>${message}</h1>
</body>
</html>

常用 API

Configuration：用于配置 FreeMarker 的全局设置。
Template：表示一个模板文件。
TemplateExceptionHandler：用于处理模板解析和执行过程中的异常。

4. 项目安装方式

通过 Maven 安装

如前所述，通过在 pom.xml 中添加依赖项来安装 FreeMarker。

手动安装

将 freemarker.jar 文件复制到你的项目中，并确保它位于 ClassLoader 可以找到的路径中。

构建 FreeMarker

如果你需要从源码构建 FreeMarker，可以按照以下步骤进行：

下载源码发布包或从源码仓库中检出 FreeMarker。
确保你安装了 JDK 8、JDK 16 和 JDK 17（仅用于某些测试）。
在项目根目录下运行 ./gradlew jar（Windows 上运行 gradlew.bat jar）来构建 freemarker.jar。

IDE 设置

IntelliJ IDEA

打开项目：选择 settings.gradle.kts 文件。
配置 Gradle：确保 Gradle JVM 设置为 JDK 17 或更高版本。
导入代码风格和检查配置。

Eclipse

将项目作为 Gradle 项目导入。
配置 Java 编译器和代码格式化器。

通过以上步骤，你可以顺利安装、使用和构建 Apache FreeMarker™ 项目。

freemarker

Apache Freemarker

项目地址：https://gitcode.com/gh_mirrors/fr/freemarker

登录后查看全文

项目优选

收起

本项目是CANN提供的transformer类大模型算子库，实现网络在NPU上加速计算。

本项目是CANN提供的神经网络类计算算子库，实现网络在NPU上加速计算。

Ascend Extension for PyTorch

openEuler内核是openEuler操作系统的核心，既是系统性能与稳定性的基石，也是连接处理器、设备与服务的桥梁。

455

437

ops-math

本项目是CANN提供的数学类基础计算算子库，实现网络在NPU上加速计算。

华为昇腾面向大规模分布式训练的多模态大模型套件，支撑多模态生成、多模态理解。

CANN 学习中心仓，支持在线互动运行、边学边练，提供教程、示例与优化方案，一站式助力昇腾开发者快速上手。