POJO カスタマイズ

Overview

このガイドでは、MongoDB Java ドライバーにおける BSON と POJO の間のカスタムデータ変換を定義する方法を学ぶことができます。 POJOに関するガイドでは、1 つ以上の POJO クラスとそのプロパティに対するデータ変換の方法を指示するクラスを含む PojoCodecProviderを指定する方法を示します。

ClassModelクラスとPropertyModelクラスを使用してデータ変換を指定する方法を示します。 より具体的なカスタマイズについては、「高度な構成 」のセクションを参照してください。

規則や注釈などのヘルパーを使用してよく行われる直列化アクションの指定方法も紹介します。

同じコレクション内のドキュメントで複数の POJO クラスを直列化する場合は、「識別子」セクションを参照してください。

条件付きシリアル化を実装する必要がある場合、または列挙型、ジェネリック、インターフェース型、または抽象型を使用する必要がある場合は、「高度な構成 」のセクションを参照してください。

BSON と POJO 間でデータを変換するために事前定義された動作のみを使用する必要がある場合は、『 PojoCodecProviderドキュメント データ形式: POJO 』ガイド に示されている の 自動 設定を使用できます。

PojoCodecProvider のカスタマイズ

このセクションでは、データ変換ロジックと POJO クラスを PojoCodecProvider で指定する方法について説明します。PojoCodecProvider は、データ変換で使用するコーデックを指定する CodecProvider インターフェイスの実装です。BSON と POJO の間でデータ変換を行う場合は、この実装を使用します。

PojoCodecProvider.builder() メソッドを使用して PojoCodecProvider インスタンスを作成できます。ビルダにメソッドを連鎖させて、次のいずれかを登録することもできます。

• 個々の POJO クラス

• POJO クラスを含むパッケージ名

• 特定の POJO クラスの変換ロジックを記述する ClassModel のインスタンス

次の例は、「org.example.pojos」という名前のパッケージで POJO を指定する方法と、PojoCodecProvider を CodecRegistry に追加する方法を示しています。

import org.bson.codecs.configuration.CodecProvider;
import org.bson.codecs.configuration.CodecRegistry;
import org.bson.codecs.pojo.PojoCodecProvider;
import static org.bson.codecs.configuration.CodecRegistries.fromRegistries;
import static org.bson.codecs.configuration.CodecRegistries.fromProviders;
import static com.mongodb.MongoClientSettings.getDefaultCodecRegistry;
CodecProvider pojoCodecProvider = PojoCodecProvider.builder().register("org.example.pojos").build();
CodecRegistry pojoCodecRegistry = fromRegistries(getDefaultCodecRegistry(), fromProviders(pojoCodecProvider));
// Call withCodecRegistry(pojoCodecRegistry) on an instance of MongoClient, MongoDatabase, or MongoCollection

このクラスの詳細については、 PojoCodecProvider.Builder を参照してください API ドキュメント。

ClassModel<Flower> classModel = ClassModel.builder(Flower.class).build();

Conventions

Convention インターフェースには、ClassModel または PropertyModel の動作を変更する構成オプションが含まれています。PojoCodecProvider.Builder.conventions() または ClassModelBuilder.conventions() の呼び出しで Convention を指定できます。

BSON ライブラリで定義された Convention インスタンスには、Conventions クラスの次の静的フィールドからアクセスできます。

次のいずれかの方法を指定して Conventions を指定できます。

• PojoCodecProvider.Builder.conventions()

• ClassModelBuilder.conventions()

カスタムの Convention を作成するには、Convention インターフェースを実装するクラスを作成し、ClassModelBuilder インスタンスにアクセスできる apply() メソッドを上書きします。

注釈

POJO クラスの getter メソッドと setter メソッドに注釈を適用できます。これらの注釈により、特定のフィールド、メソッド、またはクラスの ClassModel と PropertyModel の動作を構成します。

次の注釈は、org.bson.codecs.pojo.annotations パッケージから使用できます。

次のコード スニペットは、前述の注釈をいくつか使用した Product というサンプル POJO を示しています。

import org.bson.BsonType;
import org.bson.codecs.pojo.annotations.BsonCreator;
import org.bson.codecs.pojo.annotations.BsonDiscriminator;
import org.bson.codecs.pojo.annotations.BsonId;
import org.bson.codecs.pojo.annotations.BsonIgnore;
import org.bson.codecs.pojo.annotations.BsonProperty;
import org.bson.codecs.pojo.annotations.BsonRepresentation;
@BsonDiscriminator(value="AnnotatedProduct", key="_cls")
public class Product {
    @BsonProperty("modelName")
    private String name;
    @BsonId()
    @BsonRepresentation(BsonType.OBJECT_ID)
    private String serialNumber;
    @BsonIgnore
    private List<Product> relatedItems;
    @BsonCreator
    public Product(@BsonProperty("modelName") String name) {
        this.name = name;
    }
    // ...
}

ClassModel<Product> classModel = ClassModel.builder(Product.class).
       conventions(Arrays.asList(Conventions.ANNOTATION_CONVENTION)).build();

サンプル POJO の注釈は、次の動作を指定します。

• 指定された弁別子のキーと値を持つ POJO を参照し、書込み (write) 操作時に "AnnotatedProduct" の値を持つ cls フィールドを BSON ドキュメントに追加

• ドキュメント内の POJO の name フィールドと値と BSON の modelName フィールドと値の間で変換

• ドキュメント内の POJO の serialNumber フィールドと値と BSON ドキュメントの _id フィールドと値の間で変換

• データを変換するときに relatedItems フィールドと値を省略

• POJO をインスタンス化するときに Product(String name) コンストラクターを使用

public class Product {
    @BsonProperty("modelName")
    private String name;
    @BsonId()
    @BsonRepresentation(BsonType.OBJECT_ID)
    private String serialNumber;
    @BsonIgnore
    private List<Product> relatedItems;
    @BsonExtraElements
    private Document additionalInfo;
    // ...

{
  "name": "MDB0123",
  "serialNumber": "62e2...",
  "dimensions": "3x4x5",
  "weight": "256g"
}

ProductWithBsonExtraElements [
  name=MDB0123,
  serialNumber=62eb...,
  relatedItems=null,
  additionalInfo=Document{{dimensions=3x4x5, weight=256g}}
]

弁別子

弁別子は、特定のドキュメント スキーマを識別するプロパティです。弁別子キーは、スキーマを識別するために使用するドキュメント フィールドを識別します。弁別子の値は、ドキュメント フィールドのデフォルト値を識別します。

弁別子を使用して、同じコレクションから異なるオブジェクト クラスに逆シリアル化するときに使用するオブジェクト クラスを CodecProvider に指示します。POJO を MongoDB コレクションにシリアル化する場合、POJO プロパティ データで特に指定されていない限り、関連付けられたコーデックによって弁別子のキー値フィールドが設定されます。

次のいずれかを実行することにより、POJO で弁別子を設定して有効にすることができます。

• POJO クラスの弁別子を指定するには、@BsonDiscriminator アノテーションを使用します。

• POJO クラスに関連付けられた ClassModelBuilder で enableDiscriminator(true) を呼び出す

@BsonDiscriminator アノテーションを含む次の POJO クラスの例と、弁別子フィールドを含むドキュメントの例を参照してください。

@BsonDiscriminator(value="AnonymousUser", key="_cls")
public class AnonymousUser {
    // class code
}
@BsonDiscriminator(value="RegisteredUser", key="_cls")
public class RegisteredUser {
    // class code
}

以下は、1 つの MongoDB コレクション内の前述の POJO から作成されたサンプル ドキュメントを示しています。

{ "_cls": "AnonymousUser", "_id": ObjectId("<Object ID>"),  ... }
{ "_cls": "RegisteredUser", "_id": ObjectId("<Object ID>"), ... }

高度な構成

public class UserRecordPojo {
     private User user;
     // ...
}

ClassModel<UserRecordPojo> userRecordPojo = ClassModel.builder(UserRecordPojo.class).enableDiscriminator(true).build();
ClassModel<User> userModel = ClassModel.builder(User.class).enableDiscriminator(true).build();
ClassModel<FreeUser> freeUserModel = ClassModel.builder(FreeUser.class).enableDiscriminator(true).build();
ClassModel<SubscriberUser> subscriberUserModel = ClassModel.builder(SubscriberUser.class).enableDiscriminator(true).build();
PojoCodecProvider pojoCodecProvider = PojoCodecProvider.builder().register(userRecordPojo, userModel, freeUserModel, subscriberUserModel).build();
CodecRegistry pojoCodecRegistry = fromRegistries(getDefaultCodecRegistry(), fromProviders(pojoCodecProvider));

public class CourteousAgeSerialization implements PropertySerialization<Integer> {
    @Override
    public boolean shouldSerialize(Integer value) {
        return (value < 30);
    }
}

public class BirthdayInvitation {
    private String name;
    private Integer age;
    private LocalDateTime eventDateTime;
    // ...
}

ClassModelBuilder<BirthdayInvitation> classModel = ClassModel.builder(BirthdayInvitation.class);
((PropertyModelBuilder<Integer>) classModel.getProperty("age"))
        .propertySerialization(new CourteousAgeSerialization());
PojoCodecProvider pojoCodecProvider = PojoCodecProvider.builder().register(classModel.build()).build();
CodecRegistry pojoCodecRegistry = fromRegistries(getDefaultCodecRegistry(), fromProviders(pojoCodecProvider));

// constructor with parameters for name, age, and eventDateTime, respectively
BirthdayInvitation invitation = new BirthdayInvitation(
        "Galadriel",
        7582,
        LocalDateTime.of(2021, Month.JANUARY, 18, 30, 0)
    );

{ "_id" : ObjectId("..."), "eventDateTime" : ..., "name" : "Galadriel" }

public class ApplicationUser {
    private Optional<Address> optionalAddress;
    private Optional<Subscription> optionalSubscription;
    // ...
}

public class OptionalPropertyCodecProvider implements PropertyCodecProvider {
    @Override
    @SuppressWarnings({"rawtypes", "unchecked"})
    public <T> Codec<T> get(final TypeWithTypeParameters<T> type, final PropertyCodecRegistry registry) {
        // Check the main type and number of generic parameters
        if (Optional.class.isAssignableFrom(type.getType()) && type.getTypeParameters().size() == 1) {
            // Get the codec for the concrete type of the Optional, as its declared in the POJO.
            Codec<?> valueCodec = registry.get(type.getTypeParameters().get(0));
            return new OptionalCodec(type.getType(), valueCodec);
        } else {
            return null;
        }
    }
    private static final class OptionalCodec<T> implements Codec<Optional<T>> {
        private final Class<Optional<T>> encoderClass;
        private final Codec<T> codec;
        private OptionalCodec(final Class<Optional<T>> encoderClass, final Codec<T> codec) {
            this.encoderClass = encoderClass;
            this.codec = codec;
        }
        @Override
        public void encode(final BsonWriter writer, final Optional<T> optionalValue, final EncoderContext encoderContext) {
            if (optionalValue != null && optionalValue.isPresent()) {
                codec.encode(writer, optionalValue.get(), encoderContext);
            } else {
                writer.writeNull();
            }
        }
        @Override
        public Optional<T> decode(final BsonReader reader, final DecoderContext context) {
            return Optional.of(codec.decode(reader, context));
        }
        @Override
        public Class<Optional<T>> getEncoderClass() {
            return encoderClass;
        }
    }
}

CodecProvider pojoCodecProvider = PojoCodecProvider.builder()
        .register("org.example.pojos")
        .register(new OptionalPropertyCodecProvider())
        .build();