👋

VelocityTools 3.x で toolbox.xml の書き方が変わった話

に公開
Java
velocity
基盤更改
toolbox
sturts
tech

基盤更改シリーズ：本記事は、現在実務で従事しているJava（主にStruts2からStruts7）への大規模更改プロジェクトにおける知見をまとめた連載の第3弾です。

既存のレガシーシステムをモダンに刷新していく過程で直面した、具体的な技術的課題とその解決策を記録として残します。

はじめに

基盤更改の一環で、VelocityTools を 1.x 系 → 3.x 系へ更新しました。

それに伴い、toolbox.xml の書き方が従来の形式から変更されており、
初見だと「書き方が間違っているのでは？」と戸惑うポイントでもあります。

本記事では、VelocityTools 1.x と 2.x / 3.x の違いにフォーカスし、
toolbox.xml の書式がどのように変わったのかを整理します。

何が変わったのか

VelocityTools は 1.x 系から 2.x / 3.x 系にかけて、
toolbox.xml の 設定体系が整理されています。

旧形式（VelocityTools 1.x）

  • tool 単位で scope を指定
  • key / scope / class をそれぞれ記述する必要がある
  • XML が冗長になりやすい
<toolbox>
  <tool>
    <key>esc</key>
    <scope>application</scope>
    <class>org.apache.velocity.tools.generic.EscapeTool</class>
  </tool>
</toolbox>

新形式（VelocityTools 2.x / 3.x）

  • toolbox 単位で scope を指定
  • tool は key と class のみを定義
  • XML がシンプルに整理された
<tools>
  <toolbox scope="application">
    <tool key="esc" class="org.apache.velocity.tools.generic.EscapeTool" />
    <tool key="dateTool" class="org.apache.velocity.tools.generic.DateTool" />
  </toolbox>
</tools>

変更点のまとめ

  • scope の指定位置

    • 1.x：tool 単位
    • 2.x / 3.x：toolbox 単位

  • 設定の考え方

    • toolbox = スコープの集合
    • tool = key と class の定義

VelocityTools 側の設計変更により、
設定の責務が明確化された形になります。

ListTool → CollectionTool について

VelocityTools 1.x 系には
org.apache.velocity.tools.generic.ListTool が存在していましたが、
3.x 系では削除されています。

代替として、VelocityTools 2.0 以降では
org.apache.velocity.tools.generic.CollectionTool が導入されています。

CollectionTool は、ListTool や SortTool などの機能を統合した
より汎用的なユーティリティとして提供されており、
本件でもこちらを使用しています。

使用している依存関係

<dependency>
  <groupId>org.apache.velocity.tools</groupId>
  <artifactId>velocity-tools-generic</artifactId>
  <version>3.1</version>
</dependency>

VelocityTools 3.x を使用している場合は、
toolbox.xml も 新形式を前提にする必要があります。

まとめ

  • VelocityTools 1.x と 3.x では toolbox.xml の書き方が異なる
  • 新形式では scope を toolbox 単位で定義する
  • ListTool は廃止され、CollectionTool が代替となっている

基盤更改で VelocityTools を更新する場合は、
toolbox.xml の形式変更も忘れずに対応する必要があります。

Discussion