XStream完全ガイド：JavaオブジェクトとXMLの簡単相互変換

XStreamは、JavaオブジェクトとXMLの間でシリアライズ（オブジェクトからXMLへ）およびデシリアライズ（XMLからオブジェクトへ）を簡単に行うためのライブラリです。リフレクションを利用することで、変換対象のオブジェクトに特別な変更を加えることなく、柔軟な変換を実現します。設定ファイルやデータ交換フォーマットとしてXMLを手軽に扱いたい場合に非常に強力なツールとなります。

しかし、その手軽さの裏には重大なセキュリティリスクも存在します。本記事では、基本的な使い方から応用的なテクニック、そして最も重要なセキュリティ対策まで、XStreamを安全に使いこなすための知識を網羅的に解説します。

1.1. プロジェクトへの導入

MavenまたはGradleを利用してプロジェクトにXStreamを追加するのが最も簡単な方法です。

Mavenの場合 (pom.xml):

<dependency> <groupId>com.thoughtworks.xstream</groupId> <artifactId>xstream</artifactId> <version>1.4.20</version> <!-- 執筆時点での推奨バージョン -->
</dependency>

Gradleの場合 (build.gradle):

implementation 'com.thoughtworks.xstream:xstream:1.4.20' // 執筆時点での推奨バージョン

1.2. シリアライズ (Javaオブジェクト → XML)

JavaオブジェクトをXML文字列に変換する「シリアライズ」は非常に直感的です。

まず、変換対象となるPOJO（Plain Old Java Object）を用意します。

// User.java
public class User { private long id; private String name; private String email; public User(long id, String name, String email) { this.id = id; this.name = name; this.email = email; } // getter, setter は省略
}

次に、XStreamのインスタンスを生成し、toXML()メソッドを呼び出します。

import com.thoughtworks.xstream.XStream;
public class SerializationExample { public static void main(String[] args) { User user = new User(1, "Taro Yamada", "taro@example.com"); XStream xstream = new XStream(); // ★★★ 実際の利用では、この後に必ずセキュリティ設定が必要です ★★★ String xml = xstream.toXML(user); System.out.println(xml); }
}

出力結果:

<User> <id>1</id> <name>Taro Yamada</name> <email>taro@example.com</email>
</User>

このように、クラス名がルート要素、フィールド名が子要素としてXMLが生成されます。パッケージ名なども含まれることがありますが、これは後述するエイリアス機能でカスタマイズ可能です。

1.3. デシリアライズ (XML → Javaオブジェクト)

XML文字列からJavaオブジェクトに復元する「デシリアライズ」も同様に簡単です。fromXML()メソッドを使用します。

import com.thoughtworks.xstream.XStream;
public class DeserializationExample { public static void main(String[] args) { String xml = "<User>" + " <id>2</id>" + " <name>Hanako Suzuki</name>" + " <email>hanako@example.com</email>" + "</User>"; XStream xstream = new XStream(); // ★★★ 実際の利用では、この後に必ずセキュリティ設定が必要です ★★★ xstream.alias("User", User.class); // XMLの要素名とクラスをマッピング User user = (User) xstream.fromXML(xml); System.out.println("ID: " + user.getId()); System.out.println("Name: " + user.getName()); }
}
// Userクラスは先ほどの例と同じ

fromXML()を使う際には、xstream.alias("User", User.class)のように、XMLの要素名がどのクラスに対応するのかを教えてあげる必要があります。これにより、XStreamは<User>タグを見つけたときにUserクラスのインスタンスを生成しようとします。

2.1. ホワイトリスト方式による許可クラスの明示的な指定

最も効果的で推奨される対策は、「許可するクラス」を明示的に指定するホワイトリスト方式です。これにより、意図しないクラスがデシリアライズされるのを防ぎます。

XStream 1.4.18以降では、デフォルトでホワイトリストモードが有効になっており、セキュリティ設定をしないとデシリアライズに失敗するようになっています。これは安全な方向への大きな一歩です。

具体的な設定方法は以下の通りです。

XStream xstream = new XStream();
// --- ▼▼▼ セキュリティ設定（必須） ▼▼▼ ---
// 1. デフォルトのパーミッションをクリアし、何も許可しない状態にする
xstream.addPermission(NoTypePermission.NONE);
// 2. 基本的な型（プリミティブ型、String、Collectionなど）を許可する
xstream.addPermission(PrimitiveTypePermission.PRIMITIVES);
xstream.addPermission(ArrayTypePermission.ARRAYS);
xstream.addPermission(CollectionTypePermission.COLLECTIONS);
// 3. デシリアライズを許可したい自前のクラスを明示的に指定する
xstream.allowTypes(new Class[]{User.class, Department.class}); // 複数のクラスを指定可能
// もしくはパッケージ単位で指定
// xstream.allowTypesByWildcard(new String[] { "com.myproject.model.**" });
// --- ▲▲▲ セキュリティ設定（ここまで） ▲▲▲ ---
xstream.alias("User", User.class);
User user = (User) xstream.fromXML(xml);

この設定により、たとえ攻撃者がjava.lang.ProcessBuilderのような危険なクラスを実行させようとするXMLを送ってきても、許可リストにないためXStreamがデシリアライズを拒否し、ForbiddenClassExceptionをスローしてくれます。

3.1. エイリアス (Aliasing) – XMLの見た目を整える

デフォルトでは、クラス名やフィールド名がそのままXMLの要素名になります。しかし、XMLのスキーマが決められていたり、より分かりやすい名前に変更したい場合があります。その際に使うのがエイリアスです。

• xstream.alias("別名", 対象クラス): クラス名に対応する要素名を変更します。
• xstream.aliasField("別名", 対象クラス, "フィールド名"): フィールドに対応する要素名を変更します。
• xstream.useAttributeFor(対象クラス, "フィールド名"): フィールドを要素ではなく属性として出力します。
• xstream.addImplicitCollection(対象クラス, "リストのフィールド名"): リストを囲む親要素を省略します。

import com.thoughtworks.xstream.XStream;
import java.util.Arrays;
import java.util.List;
// --- 対象クラス ---
class Article { private long articleId; private String title; private List<String> tags; // constructor, getters...
}
// --- 実行コード ---
XStream xstream = new XStream();
xstream.alias("article", Article.class); // Articleクラスを<article>要素に
xstream.useAttributeFor(Article.class, "articleId"); // articleIdを属性に
xstream.aliasField("headline", Article.class, "title"); // titleフィールドを<headline>要素に
xstream.addImplicitCollection(Article.class, "tags"); // <tags>を囲む親要素を削除
xstream.alias("tag", String.class); // List<String>の各要素を<string>から<tag>に
Article article = new Article(101, "XStream Guide", Arrays.asList("java", "xml"));
String xml = xstream.toXML(article);
System.out.println(xml);

出力結果:

<article articleId="101"> <headline>XStream Guide</headline> <tag>java</tag> <tag>xml</tag>
</article>

このように、コード側でマッピングルールを定義することで、POJO自体には手を加えることなく、出力されるXMLを柔軟に制御できます。

3.2. アノテーション (Annotations) – POJOにマッピング情報を記述する

エイリアスによる設定は柔軟ですが、マッピングルールが増えるとコードが煩雑になりがちです。代替案として、POJOのクラスやフィールドにアノテーションを付与することで、マッピング情報をクラス定義自体に埋め込むことができます。

アノテーションを利用するには、まずxstream.processAnnotations(対象クラス)を呼び出し、アノテーションを処理するようXStreamに指示する必要があります。

主なアノテーション:

アノテーションを使用した例:

import com.thoughtworks.xstream.XStream;
import com.thoughtworks.xstream.annotations.*;
import java.util.List;
@XStreamAlias("product") // クラスのエイリアス
class Product { @XStreamAsAttribute // 属性として出力 @XStreamAlias("id") // 属性名のエイリアス private int productId; @XStreamAlias("productName") // 要素名のエイリアス private String name; @XStreamOmitField // このフィールドはXMLに出力しない private String internalCode; @XStreamImplicit(itemFieldName = "category") // Listを囲む要素を省略し、各要素名を "category" にする private List<String> categories; // constructor, getters...
}
// --- 実行コード ---
XStream xstream = new XStream();
xstream.processAnnotations(Product.class); // アノテーションを有効化
Product product = new Product(987, "Super Gadget", "SG-001", Arrays.asList("electronics", "new"));
String xml = xstream.toXML(product);
System.out.println(xml);

出力結果:

<product id="987"> <productName>Super Gadget</productName> <category>electronics</category> <category>new</category>
</product>

アノテーションを使うことで、マッピング定義がPOJOに集約され、どのようなXMLになるかが見通しやすくなるというメリットがあります。

3.3. コンバータ (Converters) – 独自の変換ロジックを実装する

日付フォーマットの変更や、特定のロジックに基づいた値の変換など、標準の機能だけでは対応できない複雑な変換を行いたい場合があります。そのために用意されているのがコンバータです。

com.thoughtworks.xstream.converters.Converterインターフェースを実装することで、独自の変換ロジックを作成できます。

Converterインターフェースの主要メソッド:

• void marshal(Object source, HierarchicalStreamWriter writer, MarshallingContext context): オブジェクトからXMLへの変換ロジックを記述します（シリアライズ）。
• Object unmarshal(HierarchicalStreamReader reader, UnmarshallingContext context): XMLからオブジェクトへの変換ロジックを記述します（デシリアライズ）。
• boolean canConvert(Class type): このコンバータがどのクラスを対象とするかを返します。

例：Date型を “yyyy-MM-dd” 形式の文字列に変換するコンバータ

import com.thoughtworks.xstream.converters.basic.AbstractSingleValueConverter;
import java.text.ParseException;
import java.text.SimpleDateFormat;
import java.util.Date;
// 単一の値と文字列を相互変換する簡単なコンバータ
public class DateConverter extends AbstractSingleValueConverter { private final SimpleDateFormat formatter = new SimpleDateFormat("yyyy-MM-dd"); @Override public boolean canConvert(Class type) { return type.equals(Date.class); } @Override public String toString(Object obj) { return formatter.format((Date) obj); } @Override public Object fromString(String str) { try { return formatter.parse(str); } catch (ParseException e) { throw new RuntimeException(e); } }
}
// --- 実行コード ---
XStream xstream = new XStream();
xstream.registerConverter(new DateConverter()); // 作成したコンバータを登録
Date date = new Date();
String xml = xstream.toXML(date);
System.out.println(xml); // <date>2025-07-13</date> のような形式で出力される

コンバータを登録することで、XStreamはDateオブジェクトを見つけると自動的にこのコンバータを使用するようになります。これにより、非常に細かいレベルでの変換制御が可能になります。

Javaのエコシステムには、オブジェクトとデータフォーマットを相互変換するためのライブラリが多数存在します。特に有名なのが、JSONを主に扱うJacksonとGson、そしてXMLを扱うJAXBです。