🔖
Payara移行で直面した互換性問題とJSON-B実装

2025/12/02に公開
 Payara移行で直面した互換性問題とJSON-B実装
 はじめにGlassFish 4.1 から Payara 6.11 への移行で最も苦労したのが Jakarta EE への対応と日付型のシリアライズ問題です。
Payara 移行で直面した互換性問題と、カスタムシリアライザ・デシリアライザでの解決方法を書いていきます。

 発生した問題
 問題1: Java EE から Jakarta EE への移行Payara 6.11 では、Java EE から Jakarta EE への移行が必須です。GlassFish 4.1 + Java 8 の環境から Payara 6.11 + Java 21 への移行に伴い、パッケージ名が変更されました。
変更内容:

javax.servlet.* → jakarta.servlet.*

javax.persistence.* → jakarta.persistence.*

javax.ws.rs.* → jakarta.ws.rs.*

 問題2: ZonedDateTime の出力形式変更Payara 移行後、ZonedDateTime の JSON 出力形式が変更されました。
変更前（GlassFish）:
{
  "createdAt": "2024-01-15T10:30:00Z"
}
変更後（Payara）:
{
  "createdAt": "2024-01-15T10:30:00Z[UTC]"
}
この [UTC] 部分が問題でした。既存の VB クライアントが日付型として認識できず、エラーが発生しました。

 問題3: 空文字のデシリアライズエラーGlassFish では許容されていた空文字が、Payara では厳格にエラーとなりました。
GlassFish:
{
  "statusChangedDate": ""
}
↓ 自動的に null として扱われる
Payara:
{
  "statusChangedDate": ""
}
↓ デシリアライズエラーが発生

 問題3.1: 数値フィールドへの空文字送信で落ちる（shotCount / disposedShotCount）日付だけでなく、数値フィールドに空文字を送った場合も JSON-B が厳密化されており、GlassFish では「たまたま通っていた」ケースが Payara では例外になった。
実際に発生した例外は以下の通り。
Caused by: jakarta.json.bind.JsonbException: Unable to deserialize property 'disposedShotCount' because of: Error deserialize JSON value into type: int.
Caused by: java.lang.NumberFormatException: For input string: ""
原因は、リクエスト JSON が次のようになっていたことだった。
"shotCount": "0",
"disposedShotCount": ""
サーバ側のエンティティは int disposedShotCount; のように プリミティブな数値型 で定義されているため、

"0" → int にはパースできるので OK

"" → int にパースできず NumberFormatException
となり、JSON-B（Yasson）がデシリアライズに失敗して 400/500 系のエラーになっていた。

 対応方針: 「数値は最初から数値として送る」今回は「クライアント側（VB）の型定義をサーバ側に合わせる」方針を取った。
修正前（VB側）
Property shotCount As String = "0"
Property disposedShotCount As String = "0"
修正後（VB側）
Property shotCount As Integer
Property disposedShotCount As Integer
VB.NET の Integer は未代入時の初期値が 0 になるため、何も代入しなくても JSON には
"shotCount": 0,
"disposedShotCount": 0
のように 数値リテラルとして シリアライズされるようになった。

これにより、""（空文字）が送られることがなくなり、int へのデシリアライズも正常に完了する。

 代替案として考えたことサーバ側で対処する選択肢もある。
エンティティ側を int → Integer にして null を許容し、カスタムデシリアライザで "" を null に変換する
いったん String disposedShotCount として受け、アプリ側で Integer.parseInt する際に空文字を 0 or null にマッピングする
ただし、「DB カラムも Java のフィールドも数値型なのに、クライアントの都合で文字列を混ぜる」という構造自体が負債なので、今回のケースでは
数値はクライアント側からも素直に数値として送る
という形に寄せるのが最もシンプルで、かつ将来の保守性も高いと判断した。

 この事例からの教訓（数値版）「日付だけでなく、数値フィールドへの空文字送信も Payara / JSON-B ではきっちり怒られる」

"" を「実質 0」や「実質 null」として扱うような あいまいな仕様は、ミドルウェア更新のタイミングで必ず爆発する
DB / Java / クライアントの型はできるだけ揃え、

「数値は最初から数値」「null は最初から null」 の世界に寄せていくべき
GlassFish 4.1 時代は「たまたま通っていた」だけであり、Payara 6 ではそのツケが一気に表面化した形になった。

今回の対応を通して、型と表現（JSON）の設計を最初からきちんと揃えておくことの重要性を改めて痛感した。

 問題4: コレクション要素の型不一致によるシリアライズ例外List<String> として定義されたフィールドに、実際には List<Integer> が格納されている場合、GlassFish ではシリアライズ時に暗黙的に文字列化されていました。

しかし、Payara 6 (Jakarta EE 10) では型チェックが厳密になり、ClassCastException が発生してレスポンスの生成に失敗するようになりました。
発生した例外:

JsonbException: Unable to serialize property 'departmentIds' ... Caused by: java.lang.ClassCastException

 解決策の実装
 ステップ1: Java EE から Jakarta EE への一括置換まず、パッケージ名を一括置換しました。
# javax.* を jakarta.* に一括置換
find src -name "*.java" -type f -exec sed -i 's/import javax\./import jakarta./g' {} \;
対象となる主なパッケージ:

javax.servlet.* → jakarta.servlet.*

javax.persistence.* → jakarta.persistence.*

javax.ws.rs.* → jakarta.ws.rs.*

javax.json.* → jakarta.json.*

javax.validation.* → jakarta.validation.*
注意点:

javax.xml.* などは Jakarta EE の対象外なので置換しない
ライブラリの依存関係も Jakarta EE 対応版に更新が必要

 ステップ2: カスタムシリアライザの実装日付型の出力形式を統一するため、3つのカスタムシリアライザを実装しました。

 1. ZonedDateTime 用シリアライザ// UtcZonedDateTimeSerializer.java
package com.kmcj.karte.config;

import java.time.ZonedDateTime;
import java.time.ZoneOffset;
import java.util.Date;
import jakarta.json.bind.serializer.JsonbSerializer;
import jakarta.json.bind.serializer.SerializationContext;
import jakarta.json.stream.JsonGenerator;

/**
 * ZonedDateTime を UTC に正規化し、ISO 8601 (末尾Z固定) で出力するシリアライザ。
 * Payaraアップグレード後の "Z[UTC]" 形式を排除する目的。
 */
public class UtcZonedDateTimeSerializer implements JsonbSerializer<ZonedDateTime> {
    @Override
    public void serialize(ZonedDateTime value, JsonGenerator generator, SerializationContext ctx) {
        if (value == null) {
            generator.writeNull();
            return;
        }
        // ZonedDateTime を UTC に変換してから Date に変換
        Date utcDate = Date.from(value.withZoneSameInstant(ZoneOffset.UTC).toInstant());
        // Date のシリアライザに委譲することで、フォーマットを統一
        ctx.serialize(utcDate, generator);
    }
}

withZoneSameInstant(ZoneOffset.UTC) で UTC に正規化

Date に変換することで、既存の日付フォーマット設定を活用

ctx.serialize() で委譲することで、フォーマット設定を一元管理

 2. OffsetDateTime 用シリアライザ// UtcOffsetDateTimeSerializer.java
package com.kmcj.karte.config;

import java.time.OffsetDateTime;
import java.time.ZoneOffset;
import java.util.Date;
import jakarta.json.bind.serializer.JsonbSerializer;
import jakarta.json.bind.serializer.SerializationContext;
import jakarta.json.stream.JsonGenerator;

/**
 * OffsetDateTime を UTC に正規化し、ISO 8601 (末尾Z固定) で出力するシリアライザ。
 */
public class UtcOffsetDateTimeSerializer implements JsonbSerializer<OffsetDateTime> {
    @Override
    public void serialize(OffsetDateTime value, JsonGenerator generator, SerializationContext ctx) {
        if (value == null) {
            generator.writeNull();
            return;
        }
        Date utcDate = Date.from(value.withOffsetSameInstant(ZoneOffset.UTC).toInstant());
        ctx.serialize(utcDate, generator);
    }
}

OffsetDateTime も同様に UTC に正規化

withOffsetSameInstant(ZoneOffset.UTC) でオフセットを UTC に変換

 3. Date 用シリアライザ// UtcDateSerializer.java
package com.kmcj.karte.config;

import java.text.SimpleDateFormat;
import java.util.Date;
import java.util.TimeZone;
import jakarta.json.bind.serializer.JsonbSerializer;
import jakarta.json.bind.serializer.SerializationContext;
import jakarta.json.stream.JsonGenerator;

/**
 * java.util.Date を UTC の ISO 8601 (末尾Z固定) で出力するシリアライザ。
 */
public class UtcDateSerializer implements JsonbSerializer<Date> {
    private static final ThreadLocal<SimpleDateFormat> FORMATTER = ThreadLocal.withInitial(() -> {
        SimpleDateFormat sdf = new SimpleDateFormat("yyyy-MM-dd'T'HH:mm:ss'Z'");
        sdf.setTimeZone(TimeZone.getTimeZone("UTC"));
        return sdf;
    });

    @Override
    public void serialize(Date date, JsonGenerator generator, SerializationContext serializationContext) {
        if (date == null) {
            generator.writeNull();
            return;
        }
        generator.write(FORMATTER.get().format(date));
    }
}

ThreadLocal を使ってスレッドセーフに

SimpleDateFormat は再利用するが、スレッドセーフでないため ThreadLocal で管理
タイムゾーンを明示的に UTC に設定

 ステップ3: シリアライザの登録JSON-B の設定プロバイダーを作成し、カスタムシリアライザを登録します。
// JsonbConfigProvider.java
package com.kmcj.karte.config;

import java.util.Locale;
import jakarta.json.bind.Jsonb;
import jakarta.json.bind.JsonbBuilder;
import jakarta.json.bind.JsonbConfig;
import jakarta.ws.rs.Produces;
import jakarta.ws.rs.core.MediaType;
import jakarta.ws.rs.ext.ContextResolver;
import jakarta.ws.rs.ext.Provider;

/**
 * JSON-B全体の日時フォーマットをISO 8601（末尾Z、タイムゾーンIDなし）に固定する。
 * Payaraアップグレード後に ZonedDateTime が "Z[UTC]" で出力されるため、VB側での日時変換エラーを防止する。
 */
@Provider
@Produces(MediaType.APPLICATION_JSON)
public class JsonbConfigProvider implements ContextResolver<Jsonb> {
    private final Jsonb jsonb;

    public JsonbConfigProvider() {
        JsonbConfig config = new JsonbConfig()
                .withDateFormat("yyyy-MM-dd'T'HH:mm:ss'Z'", Locale.US)
                .withSerializers(
                        new UtcDateSerializer(),
                        new UtcOffsetDateTimeSerializer(),
                        new UtcZonedDateTimeSerializer()
                );
        this.jsonb = JsonbBuilder.create(config);
    }

    @Override
    public Jsonb getContext(Class<?> type) {
        return jsonb;
    }
}

@Provider アノテーションで JAX-RS に登録

@Produces(MediaType.APPLICATION_JSON) で JSON に適用

ContextResolver<Jsonb> を実装して JSON-B の設定を提供

 ステップ3.5: JSON-B 日付フォーマットの落とし穴と最終的な設計Payara への移行中に、JSON-B の日付フォーマット周りで 二度ハマり ました。

 1. withDateFormat を狭くしすぎて既存データを壊した最初は、JsonbConfigProvider で次のように設定していました。
.withDateFormat("yyyy-MM-dd'T'HH:mm:ss'Z'", Locale.US)
これは
2025-08-30T15:00:00Z
のような ミリ秒なし・末尾 Z 固定 の文字列だけを許容する指定です。
ところが、実際の JSON には

2025-08-30T15:00:00.000Z（Web側・ミリ秒あり）

2025-12-08T16:24:47（タブレット側・Zなし）
のような値も混在しており、java.util.Date にバインドしているフィールドで デシリアライズエラー が発生するようになりました。
このため、java.util.Date / Calendar 向けのフォーマットを、

ミリ秒あり／なし・タイムゾーンあり／なし を許容する形に広げました。
// JsonbConfigProvider.java（抜粋）
JsonbConfig config = new JsonbConfig()
        // java.util.Date / Calendar 用
        // 例:
        //   2025-08-30T15:00:00
        //   2025-08-30T15:00:00.000Z
        //   2025-08-30T15:00:00+09:00
        .withDateFormat("yyyy-MM-dd'T'HH:mm:ss[.SSS][X]", Locale.JAPAN)
        .withSerializers(
                new UtcDateSerializer(),
                new UtcOffsetDateTimeSerializer(),
                new UtcZonedDateTimeSerializer()
        )
        .withDeserializers(
                new UtcZonedDateTimeDeserializer() // ZonedDateTime の入力（Zなし対応）
        );
ここで使っている [.SSS][X] は オプション要素 で、

.SSS … ミリ秒があってもなくても良い

X … タイムゾーン（Z, +09:00 等）があってもなくても良い
という意味になります。
なお、このパターンは数字と固定文字だけなので、Locale.US と Locale.JAPAN のどちらを指定しても挙動は変わりません（今回は日本語環境であることが分かりやすいよう Locale.JAPAN にしていますが、実質どちらでも同じです）。

 2. withDateFormat は java.time.* には効かない問題もう一つハマったのが、withDateFormat が java.time.* には効かない点です。

withDateFormat(...) が効くのは主に

java.util.Date / java.util.Calendar

ZonedDateTime / OffsetDateTime / LocalDateTime などの java.time.* は

デフォルトでは DateTimeFormatter の標準フォーマット でパースされる
そのため、エンティティに ZonedDateTime を持っている箇所では、

2025-12-08T16:24:47Z や +09:00 付き → 問題なし

2025-12-08T16:24:47（タブレットからの Z なし） →

ZonedDateTime.parse(..., ISO_ZONED_DATE_TIME) が失敗し、DateTimeParseException になる
という状況になりました。
これを吸収するために、ZonedDateTime 専用のデシリアライザを追加しています。
// UtcZonedDateTimeDeserializer.java
package com.kmcj.karte.config;

import jakarta.json.bind.serializer.DeserializationContext;
import jakarta.json.bind.serializer.JsonbDeserializer;
import jakarta.json.stream.JsonParser;
import java.lang.reflect.Type;
import java.time.LocalDateTime;
import java.time.ZoneId;
import java.time.ZonedDateTime;
import java.time.format.DateTimeFormatter;
import java.time.format.DateTimeParseException;

/**
 * ZonedDateTime 用のデシリアライザ。
 * 以下のフォーマットを許容する：
 * 1. ISO_ZONED_DATE_TIME (例: "2025-12-08T16:24:47Z", "2025-12-08T16:24:47+09:00")
 * 2. ISO_LOCAL_DATE_TIME (例: "2025-12-08T16:24:47") -> システムデフォルトのタイムゾーンを付与
 */
public class UtcZonedDateTimeDeserializer implements JsonbDeserializer<ZonedDateTime> {

    @Override
    public ZonedDateTime deserialize(JsonParser parser, DeserializationContext ctx, Type rtType) {
        String dateStr = parser.getString();

        // 1. タイムゾーン付き (Z or +09:00) の場合は標準の ISO_ZONED_DATE_TIME でパース
        try {
            return ZonedDateTime.parse(dateStr, DateTimeFormatter.ISO_ZONED_DATE_TIME);
        } catch (DateTimeParseException e) {
            // 失敗したら次へ
        }

        // 2. タイムゾーンなしの場合は ISO_LOCAL_DATE_TIME として読み、
        //    システムデフォルトゾーン（今回の環境では Asia/Tokyo）を付与する
        try {
            LocalDateTime ldt = LocalDateTime.parse(dateStr, DateTimeFormatter.ISO_LOCAL_DATE_TIME);
            return ldt.atZone(ZoneId.systemDefault());
        } catch (DateTimeParseException e) {
            throw new IllegalArgumentException("Failed to parse ZonedDateTime: " + dateStr, e);
        }
    }
}
これにより、
Web クライアント: 2025-08-30T15:00:00.000Z
タブレット: 2025-12-08T16:24:47
将来的なクライアント: 2025-12-08T16:24:47+09:00
といった フォーマットの揺れをサーバ側で吸収 できるようになりました。

 3. 最終的な方針今回の一連のトラブルから得た方針は次の通りです。

java.util.Date / Calendar は、過去との互換性のために 受け側を少し広めに許容 する

（yyyy-MM-dd'T'HH:mm:ss[.SSS][X] のようにオプションを使う）

java.time.* は 型ごとに Serializer / Deserializer をセットで用意 し、

「どう解釈してどう出力するか」を明示する
クライアント（VB / Web / タブレット）が落ち着いてきたら、

受け側フォーマットの許容範囲を徐々に絞っていく
「とりあえず JSON-B のグローバル設定で何とかする」だけではなく、

java.util.Date と java.time.* の扱いの差をちゃんと意識して設計することの重要さを痛感しました。

 補足: 「Z付きISO 8601」が現代的な理由とレガシークライアントとのギャップ今回の移行対応を通して、「Z付きの ISO 8601 を前提にする世界」と「ローカル日時前提のレガシーな世界」のギャップをかなり痛感した。

 Z の意味と現代的な扱い2025-08-30T15:00:00.000Z の末尾に付いている Z は、ISO 8601 で UTC（協定世界時, +00:00） を表す記号で、+00:00 と同じ意味を持つ。
2025-08-30T15:00:00.000Z  ≒  2025-08-30T15:00:00.000+00:00
現代の REST / JSON API では、
サーバ・クライアント間の時差トラブルを避けるために UTC基準
表記は ISO 8601（yyyy-MM-dd'T'HH:mm:ss.SSSX）
タイムゾーンは Z または +09:00 のようなオフセット付き
という前提で設計されていることが多く、「Z付きISO 8601」が実質的な標準になっている。
一方で、2025-12-08T16:24:47 のように タイムゾーン情報が一切ない文字列は、
それが「どこのタイムゾーンの時間なのか」が分からない
サーバ側がローカルなのか UTC なのかを勝手に解釈するしかない
結果として 9時間ズレる・日付が前後する、といった事故につながりやすい
という問題を抱えている。

 VS2010 時代のタブレットアプリとのギャップ今回の環境では、
Web側（ブラウザ/JavaScript）は

2025-08-30T15:00:00.000Z のような UTC + ISO 8601 形式
タブレット側（VB / .NET 4.0 / Visual Studio 2010）は

2025-12-08T16:24:47 のような タイムゾーンなしのローカル日時文字列
をサーバに送ってきていた。
VS2010 時代の .NET / VB では、

DateTime の Kind（Local, Utc, Unspecified）があまり意識されていないコードが多い

ToString("yyyy-MM-ddTHH:mm:ss") のように、ローカル時間をそのまま文字列化する実装がよくある
タイムゾーンや UTC を前提とした API 設計が一般的ではなかった
という背景があり、「Z付きのISO 8601」を前提とする現代のサーバ実装(JSON-B / java.time.*)とのギャップが一気に表面化した。

 今回の方針最終的に、次のような方針に落ち着いている。
API の理想形としては「Z付きISO 8601（UTC）」を標準とする
例: yyyy-MM-dd'T'HH:mm:ss.SSSX で 2025-08-30T15:00:00.000Z
ただし、レガシーな VS2010 タブレットなどの都合もあり、

java.util.Date については yyyy-MM-dd'T'HH:mm:ss[.SSS][X] のように 受け側を広めに許容

ZonedDateTime 用デシリアライザで、Z 付き / オフセット付き / Zなしローカル日時を段階的に解釈して吸収
クライアント（VB / Web / タブレット）が順次修正できた段階で、
サーバ側の受けフォーマットの許容範囲を徐々に 「Z付きISO 8601」へ収束させる
ざっくり言うと、
「長期的には Z付きISO 8601 を前提にした世界に寄せていきつつ、

当面はレガシークライアントの“ローカル日時文化”をサーバ側で面倒を見る」
という折衷案であり、そのための仕組みとして JsonbConfig + カスタム Serializer/Deserializer を整備した、という位置付けになる。

 ステップ4: ApplicationConfig への登録JAX-RS の ApplicationConfig でプロバイダーを登録します。
// ApplicationConfig.java (一部抜粋)
@jakarta.ws.rs.ApplicationPath("api")
public class ApplicationConfig extends Application {
    @Override
    public Set<Class<?>> getClasses() {
        Set<Class<?>> resources = new java.util.HashSet<>();
        addRestResourceClasses(resources);
        resources.add(MultiPartFeature.class);
        // JSON-B のカスタム設定を登録
        resources.add(com.kmcj.karte.config.JsonbConfigProvider.class);
        return resources;
    }
}

 ステップ5: カスタムデシリアライザの実装空文字を安全に null として扱うため、カスタムデシリアライザを実装しました。
// EmptyToNullDateDeserializer.java
package com.kmcj.karte.util;

import jakarta.json.bind.serializer.JsonbDeserializer;
import jakarta.json.bind.serializer.DeserializationContext;
import jakarta.json.stream.JsonParser;
import java.lang.reflect.Type;
import java.time.LocalDate;
import java.time.OffsetDateTime;
import java.time.ZoneId;
import java.time.format.DateTimeFormatter;
import java.time.format.DateTimeParseException;
import java.util.Date;

/**
 * JSON-B の Date デシリアライザで、空文字や null を安全に null へ変換しつつ、
 * 受け取りフォーマットのばらつきを許容するためのユーティリティ。
 */
public class EmptyToNullDateDeserializer implements JsonbDeserializer<Date> {
    @Override
    public Date deserialize(JsonParser parser, DeserializationContext ctx, Type rtType) {
        String text = parser.getString();
        
        // 空文字や null は null として扱う
        if (text == null || text.isBlank()) {
            return null;
        }

        // オフセット付き日時 → ISO日付 → スラッシュ日付 の順で解釈
        try {
            return Date.from(OffsetDateTime.parse(text).toInstant());
        } catch (DateTimeParseException ignored) {
            // fall through
        }

        for (DateTimeFormatter formatter : new DateTimeFormatter[]{
                DateTimeFormatter.ISO_LOCAL_DATE,
                DateTimeFormatter.ofPattern("yyyy/MM/dd")
        }) {
            try {
                LocalDate localDate = LocalDate.parse(text, formatter);
                return Date.from(localDate.atStartOfDay(ZoneId.systemDefault()).toInstant());
            } catch (DateTimeParseException ignored) {
                // try next
            }
        }

        throw new DateTimeParseException("Unsupported date format", text, 0);
    }
}

isBlank() で空文字を判定（isEmpty() より厳密）
複数のフォーマットを試行して柔軟に対応
サポートしていないフォーマットの場合は明確にエラー

 ステップ6: エンティティへの適用カスタムデシリアライザをエンティティのフィールドに適用します。
// MstMold.java (一部抜粋)
@Entity
@Table(name = "mst_mold")
public class MstMold implements Serializable {
    
    @JsonbTypeDeserializer(EmptyToNullDateDeserializer.class)
    @Column(name = "STATUS_CHANGED_DATE")
    @Temporal(TemporalType.DATE)
    private Date statusChangedDate;
    
    // その他のフィールド...
}

@JsonbTypeDeserializer でフィールド単位に適用
すべての Date フィールドに適用する必要がある場合は、グローバル設定も可能

 ステップ7: オブジェクトマッピングによる型変換の明示JPQL で ID (Integer) のリストを直接取得して List<String> に無理やり代入していた箇所を修正しました。

一度関連エンティティ（オブジェクト）のリストとして取得し、そこから ID を取り出して明示的に String に変換することで、型安全性を確保しました。
修正前:
// 戻り値は List<Integer> だが、List<String> 変数で受けていた（警告あり）
List<String> ids = entityManager.createNamedQuery("RelatedEntity.findIdsByParentId")
        .setParameter("parentId", parentEntity.getId())
        .getResultList();
parentEntity.setChildIds(ids); // 実行時に Integer のリストがセットされる
修正後:
// 一度エンティティのリストとして取得
List<RelatedEntity> relatedEntities = entityManager
        .createNamedQuery("RelatedEntity.findByParentId", RelatedEntity.class)
        .setParameter("parentId", parentEntity.getId())
        .getResultList();

// Integer として取り出し、String に明示的に変換
List<String> childIds = relatedEntities.stream()
        .map(e -> e.getChildId()) // Integer取得
        .map(String::valueOf) // String変換
        .collect(Collectors.toList());

parentEntity.setChildIds(childIds);

 動作確認
 シリアライズ（レスポンス）の確認変更前:
{
  "createdAt": "2024-01-15T10:30:00Z[UTC]"
}
変更後:
{
  "createdAt": "2024-01-15T10:30:00Z"
}
VB クライアントで正常に日付型として認識されるようになりました。

 デシリアライズ（リクエスト）の確認GlassFish:
{
  "statusChangedDate": ""
}
自動的に null として扱われる
Payara（対応前）:
{
  "statusChangedDate": ""
}
デシリアライズエラーが発生
Payara（対応後）:
{
  "statusChangedDate": ""
}
null として安全に処理される

 実装時の注意点
 1. ThreadLocal の使用SimpleDateFormat はスレッドセーフではないため、ThreadLocal で管理します。
private static final ThreadLocal<SimpleDateFormat> FORMATTER = ThreadLocal.withInitial(() -> {
    SimpleDateFormat sdf = new SimpleDateFormat("yyyy-MM-dd'T'HH:mm:ss'Z'");
    sdf.setTimeZone(TimeZone.getTimeZone("UTC"));
    return sdf;
});

 2. タイムゾーンの統一すべての日付を UTC に正規化することで、タイムゾーンの問題を回避します。
Date utcDate = Date.from(value.withZoneSameInstant(ZoneOffset.UTC).toInstant());

 3. null チェックの徹底シリアライザ・デシリアライザでは必ず null チェックを行います。
if (value == null) {
    generator.writeNull();
    return;
}

 パフォーマンスへの影響
 ThreadLocal によるオーバーヘッドThreadLocal を使用しているため、スレッドごとに SimpleDateFormat のインスタンスが作成されます。
測定結果:
通常のレスポンス: 平均 50ms
カスタムシリアライザ適用後: 平均 52ms（+2ms）
実用上は問題ないレベルです。

 代替案の検討java.time.format.DateTimeFormatter はスレッドセーフなので、ThreadLocal 不要です。
private static final DateTimeFormatter FORMATTER = 
    DateTimeFormatter.ofPattern("yyyy-MM-dd'T'HH:mm:ss'Z'")
                     .withZone(ZoneId.of("UTC"));
ただし、Date を直接フォーマットできないため、一度 Instant に変換する必要があります。

 トラブルシューティング
 問題: カスタムシリアライザが適用されない原因:

ApplicationConfig に JsonbConfigProvider を登録していない。
解決策:
resources.add(com.kmcj.karte.config.JsonbConfigProvider.class);

 問題: 一部のフィールドだけ古い形式で出力される原因:

シリアライザが登録されていない型がある。
解決策:

必要な型のシリアライザをすべて登録します。
.withSerializers(
    new UtcDateSerializer(),
    new UtcOffsetDateTimeSerializer(),
    new UtcZonedDateTimeSerializer()
)

 問題: デシリアライズで例外が発生する原因:

デシリアライザがエンティティに適用されていない。
解決策:
@JsonbTypeDeserializer(EmptyToNullDateDeserializer.class)
private Date statusChangedDate;

 教訓：型定義の不一致を避ける今回の ClassCastException の根本原因は、DBのカラム定義とエンティティ（特に @Transient フィールド）の型定義が一致していなかったことにあります。
DBのカラムは INT で定義されていますが、エンティティ側では JSON レスポンスの表示都合に合わせて @Transient を付けた List<String> フィールドを用意していました。

GlassFish 4.1 (Java EE 7) 時代は、DB から取得した List<Integer> をこの List<String> フィールドにセットしても、JSON-B (EclipseLink MOXy 等) が暗黙的に型変換を行ってくれていたため、表面上は動いていました。
しかし、Payara 6 (Jakarta EE 10) への移行で仕様が厳格化されたことにより、この「型が違うものを無理やり突っ込む」実装が許容されなくなり、ClassCastException として顕在化しました。
教訓:

表示するときのデータ型にバックエンドは引っ張られないようにする: フロントエンドの表示都合（Stringで欲しいなど）を、バックエンドのデータ構造（DBはInteger）に持ち込まない。

DBとJavaの型は必ず合わせる: DBが数値ならJavaも数値として扱う。

暗黙の型変換に頼らない: フレームワークがやってくれるだろうという期待は、将来の移行時に負債となる。
「動いているからヨシ」ではなく、**「正しい型で定義され、正しくマッピングされているか」**を常に意識することが、将来的なトラブルを防ぐ一番の近道だと痛感しました。

 まとめPayara 移行で直面した互換性問題と、その解決策として実装したカスタムシリアライザ・デシリアライザについて解説しました。
重要なポイント:
Jakarta EE への移行はパッケージ名の一括置換で対応
日付型の出力形式は UTC に統一してタイムゾーン問題を回避
空文字のデシリアライズはカスタムデシリアライザで対応

ThreadLocal でスレッドセーフを確保
これにより、レガシーな VB クライアントとの互換性を維持しつつ、GlassFish 4.1 から Payara 6.11 への移行を実現できました。
Payara移行で直面した互換性問題とJSON-B実装

はじめに

発生した問題

問題1: Java EE から Jakarta EE への移行

問題2: ZonedDateTime の出力形式変更

問題3: 空文字のデシリアライズエラー

問題3.1: 数値フィールドへの空文字送信で落ちる（shotCount / disposedShotCount）

対応方針: 「数値は最初から数値として送る」

代替案として考えたこと

この事例からの教訓（数値版）

問題4: コレクション要素の型不一致によるシリアライズ例外

解決策の実装

ステップ1: Java EE から Jakarta EE への一括置換

ステップ2: カスタムシリアライザの実装

1. ZonedDateTime 用シリアライザ

2. OffsetDateTime 用シリアライザ

3. Date 用シリアライザ

ステップ3: シリアライザの登録

ステップ3.5: JSON-B 日付フォーマットの落とし穴と最終的な設計

1. withDateFormat を狭くしすぎて既存データを壊した

2. withDateFormat は java.time.* には効かない問題

3. 最終的な方針

補足: 「Z付きISO 8601」が現代的な理由とレガシークライアントとのギャップ

Z の意味と現代的な扱い

VS2010 時代のタブレットアプリとのギャップ

今回の方針

ステップ4: ApplicationConfig への登録

ステップ5: カスタムデシリアライザの実装

ステップ6: エンティティへの適用

ステップ7: オブジェクトマッピングによる型変換の明示

動作確認

シリアライズ（レスポンス）の確認

デシリアライズ（リクエスト）の確認

実装時の注意点

1. ThreadLocal の使用

2. タイムゾーンの統一

3. null チェックの徹底

パフォーマンスへの影響

ThreadLocal によるオーバーヘッド

代替案の検討

トラブルシューティング

問題: カスタムシリアライザが適用されない

問題: 一部のフィールドだけ古い形式で出力される

問題: デシリアライズで例外が発生する

教訓：型定義の不一致を避ける

まとめ

Discussion

1. `withDateFormat` を狭くしすぎて既存データを壊した

2. `withDateFormat` は java.time.* には効かない問題
