@Embeddableのネストは実現可能でしょうか？

[mazeneko]

※意図したニュアンスを保って英訳できる自信がなかったので日本語で記載します。

相談したいこと

いつもDomaをたのしく使わせていただいております！（ありがとうございます！）

いま、クラスのモデリングをしていくうちに@Embeddableをネストしなければテーブルにマッピングできなさそうな状況に当たっています。
現状@Embeddableをネストすることはできないと思うのですが、Domaとしては現実的に実現可能でしょうか？
また、@Embeddableを使う他にいい案があれば知恵をお借りしたいです。

起こっていること

シンプルな例にしたかったのですが、いい例が思いつかなかったので実際に書いているコードをできるだけシンプルにして掲載させていただきます。

まず、現状のDomaで実現できるコードとしていまこのようなEntityを書いています。
MemberEditedEventが永続化したいクラスです。

また、MemberPatchはWebAPIのリクエストボディにするクラスでも使いたい（JacksonでJsonからデシリアライズしたい）という都合も裏にあります。

import java.time.LocalDateTime;
import java.util.Optional;
import java.util.stream.Stream;

import org.seasar.doma.Embeddable;
import org.seasar.doma.Entity;
import org.seasar.doma.Id;

import lombok.With;

@With
record Member(
    Long id,
    String name,
    Optional<String> kana,
    Optional<String> address) {

  public Member apply(MemberEditedEvent event) {
    return this
        .withName(event.patch().name().orElse(this.name()))
        .withKana(event.patch().kana()
            .or(() -> event.patch().clearAddressIfEmpty().orElse(false) ? Optional.empty() : this.kana()))
        .withAddress(event.patch().address()
            .or(() -> event.patch().clearAddressIfEmpty().orElse(false) ? Optional.empty() : this.address()));
  }

  // ... more code ...
}

@Entity
record MemberEditedEvent(
    @Id Long id,
    LocalDateTime createdAt,
    String createdBy,
    Long memberId,
    MemberPatch patch) {
}

@Embeddable
record MemberPatch(
    Optional<String> name,
    Optional<String> kana,
    Optional<Boolean> clearKanaIfEmpty,
    Optional<String> address,
    Optional<Boolean> clearAddressIfEmpty) {

  public MemberPatch {
    final var hasChange = Stream
        .of(
            name,
            kana,
            address)
        .anyMatch(Optional::isPresent);
    final var hasClearIfEmpty = Stream
        .of(
            clearKanaIfEmpty,
            clearAddressIfEmpty)
        .flatMap(Optional::stream)
        .anyMatch(clearIfEmpty -> clearIfEmpty);
    if (!hasChange && !hasClearIfEmpty) {
      throw new IllegalArgumentException("changes are required");
    }
  }
}

そしていま、MemberPatchのclearXxxIfEmptyのあたりが冗長でイマイチなので、
こんな風にClearableFieldPatchを作ってやりたいと思っています。

※ClearableFieldPatchですが、newValueだけだとテーブルから復元(またはJsonからデシリアライズ)するときに変更なしなのか値のクリアなのか区別がつかなくなってしまうのでclearを添えています。

import java.time.LocalDateTime;
import java.util.Optional;
import java.util.stream.Stream;

import org.seasar.doma.Embeddable;
import org.seasar.doma.Embedded;
import org.seasar.doma.Entity;
import org.seasar.doma.Id;

import lombok.With;

@With
record Member(
    Long id,
    String name,
    Optional<String> kana,
    Optional<String> address) {

  public Member apply(MemberEditedEvent event) {
    return this
        .withName(
            event.patch().name().orElse(this.name()))
        .withKana(
            event.patch().kana().map(ClearableFieldPatch::newValue).orElse(this.kana()))
        .withAddress(
            event.patch().address().map(ClearableFieldPatch::newValue).orElse(this.address()));
  }

  // ... more code ...
}

@Entity
record MemberEditedEvent(
    @Id Long id,
    LocalDateTime createdAt,
    String createdBy,
    Long memberId,
    MemberPatch patch) {
}

@Embeddable
record MemberPatch(
    Optional<String> name,
    @Embedded(prefix = "kana_") Optional<ClearableFieldPatch<String>> kana,
    @Embedded(prefix = "address_") Optional<ClearableFieldPatch<String>> address) {

  public MemberPatch {
    final var hasChange = Stream
        .of(
            name,
            kana,
            address)
        .anyMatch(Optional::isPresent);
    if (!hasChange) {
      throw new IllegalArgumentException("Changes are required.");
    }
  }
}

@Embeddable
record ClearableFieldPatch<T>(
    boolean clear,
    Optional<T> newValue) {

  public ClearableFieldPatch {
    if (clear && newValue.isPresent()) {
      throw new IllegalArgumentException("If you're clearing, don't set the value.");
    }
    if (!clear && newValue.isEmpty()) {
      throw new IllegalArgumentException("If you're not clearing, set the value.");
    }
  }
}

こうなったとき、@Embeddableがネストできないとやりたいことが実現できないな～、となっているのが現状です。

もちろん、変更前の状態でとどめておいたり、これらのクラスとは別にEntity用のクラスを作って変換するなどすれば対応はできるのですが、
できれば理想としているクラスそのままでテーブルにマッピングしたいな～という想いがあります。

込み入った内容になってしまい恐縮ですが、お力添えいただけるとうれしいです。

[nakamura-to]

ネストを実装することは技術的には可能なのですが、一旦ネスト以外の方法で意見交換させてください。

例えばですが、次のようにするのはいかがですか？
（@Embeddableは型パラメーターを持てない仕様があるのでClearableFieldPatchを少し変更しています）

@Entity
record MemberEditedEvent(
    @Id Long id,
    LocalDateTime createdAt,
    String createdBy,
    Long memberId,
    Optional<String> name,
    @Embedded(prefix = "kana_") ClearableFieldPatch kana,
    @Embedded(prefix = "address_") ClearableFieldPatch address) {
}

@Embeddable
record ClearableFieldPatch(boolean clear, String newValue) {}

MemberPatchが必要ならば、次のようにMemberEditedEventのセカンダリーのコンストラクタやファクトリメソッドで使っても良いと思います。

record MemberPatch(Optional<String> name, ClearableFieldPatch kana, ClearableFieldPatch address) {}

@Entity
record MemberEditedEvent(
    @Id Long id,
    LocalDateTime createdAt,
    String createdBy,
    Long memberId,
    Optional<String> name,
    @Embedded(prefix = "kana_") ClearableFieldPatch kana,
    @Embedded(prefix = "address_") ClearableFieldPatch address) {

  MemberEditedEvent(Long id, LocalDateTime createdAt, String createdBy, Long memberId, MemberPatch memberPatch) {
    this(id, createdAt, createdBy, memberId, memberPatch.name(), memberPatch.kana(), memberPatch.address());
  }
}

ネストはコードの見通しを悪くしてしまうので、できるだけ避けた方が良いのかなと思います。

[nakamura-to]

MemberEditedEventにmemberPatch()を持たせても良いと思います。

@Entity
record MemberEditedEvent(
    @Id Long id,
    LocalDateTime createdAt,
    String createdBy,
    Long memberId,
    Optional<String> name,
    ClearableFieldPatch kana,
    ClearableFieldPatch address) {

  MemberEditedEvent(Long id, LocalDateTime createdAt, String createdBy, Long memberId, MemberPatch memberPatch) {
    this(id, createdAt, createdBy, memberId, memberPatch.name(), memberPatch.kana(), memberPatch.address());
  }

  public MemberPatch memberPatch() {
    return new MemberPatch(name, kana, address);
  }
}

[mazeneko]

さっそくの回答ありがとうございます！
いただいた案なのですが、私の設計方針にはすこし合わないところがあるのです。

例として出したコードではシンプルにするためにいろいろ削ってしまっていたのですが、
私はコーディングにおいて、

• 不正な状態のインスタンスはコンストラクタでそもそも作れないようにする
• 誤ったデータは型エラーでそもそも渡せないようにする

というところを大切にしています。いわゆる ValueObject ですね。

なので実際には、このようにドメイン知識を表現したクラスをたくさん定義しています。

import org.seasar.doma.DataType;

import com.fasterxml.jackson.annotation.JsonValue;

import lombok.NonNull;

/**
 * 会員の氏名
 */
@DataType
public record MemberName(@NonNull @JsonValue String value) {
  public static final int MAX_LENGTH = 100;

  public MemberName {
    if (value.isBlank()) {
      throw new IllegalArgumentException("会員の氏名はブランクにできません。[入力された値:%s]".formatted(value));
    }
    if (MAX_LENGTH < value.length()) {
      throw new IllegalArgumentException("会員の氏名は%d文字以内にしてください。[入力された値:%s]".formatted(MAX_LENGTH, value));
    }
  }

  @Override
  public final String toString() {
    return value;
  }
}

MemberPatchも実際にはこんな風になっていて、
MemberPatchでは「会員を変更するパッチには必ず１つ以上の変更が含まれている」という知識を表現/保証しています。

@Embeddable
record MemberPatch(
    @NonNull Optional<MemberName> name,
    @NonNull @Embedded(prefix = "kana_") Optional<ClearableFieldPatch<MemberKana>> kana,
    @NonNull @Embedded(prefix = "address_") Optional<ClearableFieldPatch<Address>> address) {

  public MemberPatch {
    final var hasChange = Stream
        .of(
            name,
            kana,
            address)
        .anyMatch(Optional::isPresent);
    if (!hasChange) {
      throw new IllegalArgumentException("Changes are required.");
    }
  }
}

そしてMemberEditedEventなどのクラスではMemberPatchを直接フィールドとして持つことによってMemberPatchなしではインスタンスを作れないようにし、
「会員を変更するパッチには必ず１つ以上の変更が含まれている」というルールが常に守られている状況を享受しています。
なので「MemberPatch以外からでもMemberEditedEventを作れてしまう」「MemberPatchはあとから生成する」というのは避けたいところなのです。

※ちなみに例としてMemberPatchは他のクラスでもこのように使っています。

/**
 * 会員を編集するコマンド
 */
public record EditMemberCommand(
    /** 会員ID */
    @NonNull Identifier<Member> memberId,
    /** 会員を編集するパッチ */
    @NonNull MemberPatch patch) {

  /**
   * 会員が編集されたイベントを作成します。
   * 
   * @param eventCreationMeta イベントを作成するためのメタデータ
   * @return 会員が編集されたイベント
   */
  public MemberEditedEvent toEvent(EventCreationMeta eventCreationMeta) {
    return new MemberEditedEvent(
        eventCreationMeta.eventId(),
        eventCreationMeta.eventCreatedAt(),
        eventCreationMeta.eventCreatedBy(),
        memberId,
        patch);
  }
}

つまり私が解決したいことは「型による安全性や責務のきれいさを重視して作ったクラスを、そのままテーブルにマッピングしたい」というところなので、
「Embeddableをネストしたい」というタイトルはすこし本質からズレていたかもしれません。

Embeddableをネストできるのがいちばん手近だった…という感じですね。
ご指摘いただいているジェネリクスが使えない仕様も絡んでくると思いますので、悩ましいところですね…。

[nakamura-to]

ありがとうございます。
実現したいことを理解できました。

一番最初に提示いただいたデータ構造を利用する前提で案を2つほど挙げてみます。

案1: ClearableFieldPatchをExternal Domainで扱う方法

ClearableFieldPatchから@Embeddableを外し、次のような@ExternalDomainが注釈されたDomainConverterの実装クラスでシリアライズ/デシリアライズします。この方法では@Embeddableのネストが解消され型パラメータも使えます。

@ExternalDomain
public class ClearableFieldPatchConverter implements DomainConverter<ClearableFieldPatch<?>, String> {

  @Override
  public String fromDomainToValue(ClearableFieldPatch<?> clearableFieldPatch) {
    // シリアライズ（例えばJSONに変換）
  }

  @Override
  public ClearableFieldPatch<?> fromValueToDomain(String value) {
    // デシリアライズ（例えばJSONから変換）;
  }
}

（データベースがJSON型をサポートしていれば、上記コードを少し変更してJSON型に対応させることも可能です）

案2: ドメインモデルとDBのデータモデルを分ける方法

やりたい方法ではないかもしれませんが、ドメインモデルとデータモデルを別クラスで表現すればDomaの制約に縛られずに綺麗なドメインモデルを維持できます。ただし、Repositoryなどのレイヤで、ドメインモデルからDomaのアノテーションが注釈されたデータモデルへ変換したり、その逆を行ったりが必要となります。

全てのモデルについて両者を分離するのは手間だと思いますので、一部に限定して適用しても良いかもしれません。

[mazeneko]

ありがとうございます！
参考になります。

案1: ClearableFieldPatchをExternal Domainで扱う方法

これは目からうろこでした！
過去に値の自由度が高いフィールドをRepositoryでJsonに変換してTextに保存するとかはやったことがあったのですが、
たしかにExternalDomainでやるという手もありますね！
なるべくJsonは乱用しないほうが固いかなという気持ちこそありますが、これはけっこう有力候補かもしれません。

ちなみにデータベースはPostgresを使っています。

案2: ドメインモデルとDBのデータモデルを分ける方法

じつは経緯として、以前は「ドメインモデルを完全にPOJOにしてやろう！」と思って、
全てのモデルについてExternalDomainを用意したり、Repositoryでテーブル用のデータモデルとの変換をするようにしていたんです。
たださすがに手間で辛くなったので、アノテーションなどある程度は許容することにしたのです。

なのでこちらの案は私にとってなじみ深いやり方になっています。
こちらもどうしようもなかった時の回避策として有力ですね。

※実際いまでも、1対多のデータを持っているクラスなど「これはドメインモデルのままではテーブルにマッピングしようがないな…」というクラスはこの手法にしています。

[nakamura-to]

なるべくJsonは乱用しないほうが固いかなという気持ちこそありますが、これはけっこう有力候補かもしれません。

ちなみにデータベースはPostgresを使っています。

こういう感じのコードを書くとJSONB型にマッピングできます（シリアライズ/デシリアライズは実装ください）。ただし、PGobjectクラスを使うのでPostgreSQLのJDBCドライバへの依存が必要です。

@ExternalDomain
public class ClearableFieldPatchConverter extends JdbcTypeProvider<ClearableFieldPatch<?>> {

  private static final ClearableFieldPatchType TYPE = new ClearableFieldPatchType();

  @Override
  public JdbcType<ClearableFieldPatch<?>> getJdbcType() {
    return TYPE;
  }
}

class ClearableFieldPatchType extends AbstractJdbcType<ClearableFieldPatch<?>> {

  protected ClearableFieldPatchType() {
    super(Types.OTHER);
  }

  @Override
  protected ClearableFieldPatch<?> doGetValue(ResultSet resultSet, int index) throws SQLException {
    String value = resultSet.getString(index);
    return value == null ? null : deserialize(value);
  }

  @Override
  protected void doSetValue(
      PreparedStatement preparedStatement, int index, ClearableFieldPatch<?> value)
      throws SQLException {
    var obj = new PGobject();
    obj.setValue(serialize(value));
    obj.setType("jsonb");
    preparedStatement.setObject(index, obj);
  }

  @Override
  protected ClearableFieldPatch<?> doGetValue(CallableStatement callableStatement, int index)
      throws SQLException {
    String value = callableStatement.getString(index);
    return value == null ? null : deserialize(value);
  }

  @Override
  protected String doConvertToLogFormat(ClearableFieldPatch<?> value) {
    return value.toString();
  }

  private ClearableFieldPatch<?> deserialize(String value) {
    // TODO デシリアライズ
    return null;
  }

  private String serialize(ClearableFieldPatch<?> value) {
    // TODO シリアライズ
    return null;
  }
}

ドキュメントはこちらです。
https://docs.domaframework.org/ja/3.10.0/domain/#direct-mapping-of-external-domain-classes-to-the-database

サポートするか確約できませんが、@Embeddableのネストは実現性を検討してみます。

[mazeneko]

くわしいところまで丁寧にありがとうございます！

この方針でいっぺんやってみることにします！🤲

[mazeneko]

その後の状況の共有です！

試行錯誤してみたのですが、やはりClearableFieldPatchのようなものを持たせるにはドメインモデルとデータモデルの分離は避けられなさそうです…。

jacksonのObjectMapperの用意に課題がある

前提として、これは私がSpringを使っているゆえの問題です。
jsonへの変換をするならSpringのDIコンテナに登録されているjackson2ObjectMapperBuilderを使いたいのですが、
ExternalDomainでSpringのbeanを取ってくるのが難しいという問題に当たりました。
(サービスクラスでDIしてApplicationReadyEventなどの時に無理やりstaticフィールドに置いておくなどすれば取れなくはないですが…)

ジェネリクスを使っているのでデシリアライズできない

これが解決できなさそうな問題でした。
シリアライズについてはObjectMapperを用意すれば簡単にできるのですが、ClearableFieldPatchがジェネリクスなため、ExternalDomainではnewValueの型がわからずデシリアライズできないという状況でした。無念…。