始めに
Apache Velocity(.vmファイル)を触る機会があるため備忘録も兼ねて記載する。
Apache Velocityとは
Apache Velocity（アパッチ・ベロシティ）は、オープンソースのJavaベースの汎用テンプレートエンジン。Apacheプロジェクト内のJakarta内のサブプロジェクトである。MVCモデルにもとづきJavaコードをWebページから切り離すことができるので、JSPやPHPによる開発と比べてきれいなWebアプリケーションの開発を期待できる。また、HTMLだけでなくXMLやSQL文などテキストファイルならどのようなものにでも適用できる高い汎用性をもっている。
出典: フリー百科事典『ウィキペディア（Wikipedia）』
簡単に言うとJSPやHTMLなどのフロント（MVCのViewのところ）を記載するファイルで基本的にはHTMLと記法は似ている。
決定的な特徴はHTMLのソース内に変数の設定や、条件分岐、繰り返し制御分を記載できること(JSPやThymeleafなどでも出来るが)
要は動的にWebページを作れるテンプレートエンジンと言うこと。
主な特徴：
-
テンプレートとロジックの分離
→ プログラムのロジックと表示部分（ビュー）を分離し、保守性を向上。 -
シンプルなテンプレート構文
→#set,#if,#foreachなどの直感的な構文を提供。 -
Javaオブジェクトとの連携が容易
→ Javaのオブジェクトをテンプレート内で簡単に利用可能。
.vm ファイルとは？
Velocityのテンプレートファイルは .vm（Velocity Macro） という拡張子を持ちます。
.vm ファイルは、静的なコンテンツ（HTML, XML, SQLなど）と動的なデータ（Javaオブジェクト）を組み合わせるためのスクリプトを記述するファイルです。
.vm ファイルの例：
例1: 基本的なVelocityテンプレート
<html>
<head><title>Velocity Example</title></head>
<body>
<h1>ようこそ、$name さん！</h1>
<p>今日は $date です。</p>
</body>
</html>
ポイント
-
$nameや$dateはJava側から渡されたデータ（コンテキスト変数）。 -
$.の後に続く変数名がプレースホルダーとして動的に置き換えられる。
Velocityの基本構文
1. 変数の使用
Velocityでは $変数名 の形で変数をテンプレートに埋め込めます。
こんにちは、$userName さん！
→ Javaコードで context.put("userName", "田中"); を渡しておけば、こんにちは、田中 さん！ となる。
2. 条件分岐 (#if, #elseif, #else)
#if($userAge >= 18)
あなたは成人です。
#else
あなたは未成年です。
#end
3. ループ (#foreach)
<ul>
#foreach($item in $items)
<li>$item</li>
#end
</ul>
Java側で設定：
List<String> items = Arrays.asList("リンゴ", "バナナ", "オレンジ");
context.put("items", items);
出力結果：
<ul>
<li>リンゴ</li>
<li>バナナ</li>
<li>オレンジ</li>
</ul>
4. コメント (##)
Velocityのコメントは ## を使って記述。
## これはコメントです。出力には影響しません。
VelocityをJavaで使用する方法
1. MavenでVelocityをインストール
<dependency>
<groupId>org.apache.velocity</groupId>
<artifactId>velocity</artifactId>
<version>1.7</version>
</dependency>
2. 基本的なVelocityのJavaコード
import org.apache.velocity.VelocityContext;
import org.apache.velocity.app.VelocityEngine;
import java.io.StringWriter;
import java.util.Properties;
public class VelocityExample {
public static void main(String[] args) {
// Velocityエンジンの初期化
VelocityEngine ve = new VelocityEngine();
ve.init();
// コンテキストにデータを設定
VelocityContext context = new VelocityContext();
context.put("name", "田中");
context.put("date", "2025年2月2日");
// テンプレートの文字列
String template = "<h1>ようこそ、$name さん！</h1>\n<p>今日は $date です。</p>";
// テンプレートを処理
StringWriter writer = new StringWriter();
ve.evaluate(context, writer, "logTag", template);
// 結果を出力
System.out.println(writer.toString());
}
}
実行結果
<h1>ようこそ、田中 さん！</h1>
<p>今日は 2025年2月2日 です。</p>
Velocityの応用
1. テンプレートファイル (.vm) を読み込む
import org.apache.velocity.Template;
import org.apache.velocity.VelocityContext;
import org.apache.velocity.app.VelocityEngine;
import java.io.StringWriter;
public class VelocityFromFile {
public static void main(String[] args) {
// Velocityエンジンの初期化
VelocityEngine ve = new VelocityEngine();
ve.init();
// テンプレートの読み込み
Template template = ve.getTemplate("templates/example.vm", "UTF-8");
// コンテキストの作成
VelocityContext context = new VelocityContext();
context.put("name", "佐藤");
context.put("date", "2025年2月2日");
// テンプレートの適用
StringWriter writer = new StringWriter();
template.merge(context, writer);
// 結果を出力
System.out.println(writer.toString());
}
}
templates/example.vm ファイル内容
<h1>ようこそ、$name さん！</h1>
<p>今日は $date です。</p>
Velocityの活用例
-
Webページのテンプレートエンジン
- JavaのWebアプリで、HTMLをテンプレート化。
-
メールの自動生成
- システム通知メールの内容をテンプレート化し、カスタマイズ。
-
SQLクエリの自動生成
-
.vmファイルで動的にSQLを生成し、複雑な検索クエリを作成。
-
-
コードの自動生成
- ソースコードや設定ファイルをテンプレートから生成。
Velocityのメリットとデメリット
メリット
シンプルで直感的なテンプレート構文
Javaオブジェクトとの統合が容易
ロジックとビューの分離ができる
高速なレンダリング
デメリット
JavaScriptや他のモダンなテンプレートエンジン（Thymeleafなど）に比べてやや古い
.vm ファイルのデバッグが難しい
強力なデータバインディングやリアクティブ機能はない
まとめ
Apache Velocityは、シンプルなテンプレートエンジンとして、HTMLの生成やメールの自動化、SQLクエリの動的作成など幅広く利用できます。.vm ファイルを活用し、Javaオブジェクトのデータをテンプレートに埋め込んで、動的コンテンツを生成するのが基本的な使い方です。
Thymeleafなどの新しいテンプレートエンジンが普及していますが、Velocityは依然としてシンプルで軽量な選択肢として有用です。