Apache VelocityとJavaで、雛形から予約確認メールを作ってみよう

Velocity（ベロシティ）とは

Velocityは、jakartaプロジェクトが提供すらJavaベースのテンプレートエンジンです。

雛形となるテキストを用意しておき、テキストの中で動的に変わる部分は、後述するVTL構文で記述しておきます。実行時にVTL構文で記載されているところは、そのプロパティ名などに対応するJavaオブジェクトの値に置き換えられます。

Velocityのメリット

例えば、ECサイトなどで送られる購入確認メールなどで使用するテキストは、顧客名や購入金額が異なるだけで、大部分は同じ内容になることが多いです。

Velocityを使うことで、雛形となるテキストは外部ファイル等に保存しておき、必要な時に雛形から動的に変わる部分（VTL）を置換したテキストを作成しメール配信等でつかえます。

また、固定の文言が変わる時は、外部に保存しておいた雛形ファイルを編集すれは、手軽に変更できるメリットもあります。

Velocityのインストール

それでは、Velocityをインストールしていきましょう。

VelocityはJava VM上で動作するテンプレートエンジンであるため、事前準備としてJDK（Javaの開発環境）が必要です。

Velocityのダウンロードは以下のサイトで行います。
http://velocity.apache.org/download.cgi

ページ中段のほうにある「Binaries」から「velocity-engine-core-x.x.jar」のリンクをクリックしてjarファイルをダウンロードします。（x-xはバージョン）

MavenでVelocityのインストール

Mavenを使って、パッケージ管理している場合はpom.xmlに次の設定を追加します。

<dependency>
  <groupId>org.apache.velocity</groupId>
  <artifactId>velocity-engine-core</artifactId>
  <version>2.2</version>
</dependency>

Velocityを使ってみよう

今回は、次のような予約確認メールのテキストを、雛形のファイルから作るサンプルコードを作ります。

この度は、当店のご予約ありがとうございます。
お客様のご予約日時は次の通りです。

お客様ID: 12345678
お客様名： 山田 太郎 様
予約日時： 2021年1月2日 11時00分

ご来店をお待ちしております。

STEP1. 予約確認メールの雛形（.vm）を作る

予約確認メールの内容から、送信メールごとに動的に変わる部分をVTL（Velocity Template Language）で変数化した雛形ファイルを作成します。VTLについては後述する内容で解説しますが、動的に変わる部分を「$」から始まる変数名で記述します。

この度は、当店のご予約ありがとうございます。
お客様のご予約日時は次の通りです。

お客様ID: $reserve.Id
お客様名： $reserve.Name 様
予約日時： $reserve.reserveTime

ご来店をお待ちしております。

雛形の作成ができたら、mail.vmというファイル名で保存しておきましょう。

STEP2. 予約データモデル（Javaクラス）を作る

次は、予約データを保持するReserveクラスを作成します。
ここで宣言するプロパティ名は、先ほど作成した雛形ファイルのVTLで定義した変数名と一致させておく必要があります。

/**
 予約データクラス
*/
public class Reserve {
    private String id;         // お客様ID
    private String name;       // お客様名
    private Date reserveTime;  // 予約日時

    public Reserve(String id, String name, Date reserveTime) {
        this.id = id;
        this.name = name;
        this.reserveTime = reserveTime;
    }
    public String getId(){
        return id;
    }
    public String getName(){
        return name;
    }
    public Date getReserveTime(){
        return reserveTime;
    }
}

STEP3. 雛形ファイルとモデルをマージして出力

雛形ファイルとモデルクラスの準備ができたら、最後はこの２つをマージする処理を記述していきます。

import java.io.StringWriter;
import org.apache.velocity.Template;
import org.apache.velocity.VelocityContext;
import org.apache.velocity.app.Velocity;
import org.apache.velocity.exception.ResourceNotFoundException;
import org.apache.velocity.exception.ParseErrorException;
import org.apache.velocity.exception.MethodInvocationException;

public class Sample{
    public static void main(String args[]){
        // 予約データを作成
        Reserve reserve = new Reserve("1234567", 
                                      "山田 太郎",
                                      "");
        //Velocityのエンジンを初期化します。
        Velocity.init();

        //コンテキストに予約データを設定します。
        //ここで指定する名前は、雛形ファイルで指定したVTLの名前と合わせる必要があります。
        VelocityContext context = new VelocityContext();
        context.put("reserve", visitor);

        StringWriter sw = new StringWriter();
        //テンプレートの読込
        Template template = Velocity.getTemplate("order.vm", "EUC-JP");
        //テンプレートとデータをマージ
        template.merge(context,sw);
        //マージ結果をコンソールに出力
        System.out.println(sw.toString());
        sw.flush();
  }
}

VTL構文を詳しく知る

前のサンプルコードでは、$変数名で動的な値を定義する構文のみを使用しましたが、VTLにはさまざまな構文があり、ifによる分岐や、foreachでコレクションの数だけ繰り返す処理など、柔軟な制御が行えるようになっています。

変数を出力

変数を出力する構文には、大きく次の２つがあります。

ポテパンダの一言メモ

変数を出力する構文について、${変数名}や$!{変数名}など、本来は中括弧をつけるのが正しい構文ですが、一般的には中括弧は省略して使われています。

条件分岐

#if、#elseif、#elseを使って条件によって出力内容を切り替えることも可能です。

#if( $score >= 80 )
$score 点です。すばらしい。
#elseif( $score >= 50 ) 
$score 点です。がんばりました。
#else
$score 点です。もう少し頑張りましょう。
#end

条件には、==、=、>、<、<=、>=などの比較演算子が使用可能です。

公式ドキュメントも確認してみよう

VelocityのVTL構文には、この記事では紹介しきれないほどに便利な構文が多数あります。

構文の詳細を確認したい場合は、次の公式ドキュメント（英語）を参照すると、すべてのVTL構文についての説明がありますので、こちらもチェックしてみましょう。

http://velocity.apache.org/engine/devel/vtl-reference.html

【関連記事】
▶ java.util.dateクラスについて｜使い方やjava.sql.dateとの違いを解説！