【Java入門】Jacksonの@JsonValueアノテーションの使い方と使うべきタイミング

JavaでオブジェクトをJSONに変換する際、Jacksonの@JsonValueアノテーションは非常に便利な機能です。このアノテーションは主にメソッドレベルで使用され、JavaオブジェクトからJSON文字列を生成する方法を自由に定義できます。

通常、シリアライズされたオブジェクトの内容を出力したい場合はtoString()メソッドをオーバーライドします。しかし、@JsonValueアノテーションを使えば、toString()とは独立して、そのオブジェクトがどのような形式でJSONへシリアライズされるかを明示的に制御することが可能になります。

@JsonValueアノテーションの構文

@Target(value={ANNOTATION_TYPE,METHOD,FIELD})
@Retention(value=RUNTIME)
public @interface JsonValue

この定義からわかるように、@JsonValueはアノテーション型・メソッド・フィールドに適用でき、実行時（RUNTIME）に情報が保持されます。

どんな場面で使うべきか

• オブジェクト全体の構造ではなく、特定の値（IDや氏名など）だけをJSONとして出力したい場合
• enumの定数を任意の文字列としてシリアライズしたい場合
• toString()のデバッグ用出力と、JSONへの変換形式を分けて管理したい場合

コード例

以下の例では、StudentクラスのtoJson()メソッドに@JsonValueを付与しています。これにより、オブジェクトのシリアライズ結果がこのメソッドの戻り値になります。

import com.fasterxml.jackson.annotation.JsonProperty;
import com.fasterxml.jackson.annotation.JsonValue;
import com.fasterxml.jackson.core.JsonProcessingException;
import com.fasterxml.jackson.databind.ObjectMapper;
import java.io.IOException;

public class JsonValueAnnotationTest {
    public static void main(String args[]) throws Exception {
        ObjectMapper mapper = new ObjectMapper();
        String jsonString = mapper.writeValueAsString(new Student());
        System.out.println(jsonString);
    }
}

// Studentクラス
class Student {
    @JsonProperty
    private int studentId = 115;

    @JsonProperty
    private String studentName = "Sai Adithya";

    @JsonValue
    public String toJson() {
        return this.studentName + "," + this.studentId + "," + this.toString();
    }

    @Override
    public String toString() {
        return "Student[" +
                "studentId = " + studentId +
                ", studentName = " + studentName +
                ']';
    }
}

実行結果

"Sai Adithya,115,Student[studentId = 115, studentName = Sai Adithya]"

ポイント解説

上記の出力を見ると、Studentオブジェクトが個別のフィールドを持つJSONオブジェクトとしてではなく、toJson()メソッドの戻り値である1つの文字列としてシリアライズされていることがわかります。つまり、@JsonValueを付けたメソッドの戻り値が、そのオブジェクトのJSON表現そのものになるのです。

このように、デフォルトのシリアライズ挙動を変更したい場合や、APIレスポンスとして簡潔な表現を返したい場合に、@JsonValueアノテーションは有効な選択肢となります。