コレクションを表すエンティティの作成

サポートされていないフィールド型

Hibernate ORM は、java.io.Serializable を実装するすべての Java 型に対する他のマッピングがない場合、それをバイナリデータにシリアライズします。データがこの形式で保存されるのを防止するため、Hibernate ORM 拡張機能は次の型を拒否し、アプリケーションの起動時に例外をスローします。このチェックは、プライマリキー、通常のフィールド、埋め込み可能な属性、およびコレクション要素に適用されます。

次の表では、サポートされていないフィールドタイプと、そのサポートされている代替案について説明します。

スキーマ修飾子

@Table アノテーションは、コレクション名のプレフィックスとなる schema 要素（任意）を受け入れます。両方の要素を設定すると、Hibernate ORM 拡張機能はエンティティを <schema name>.<collection name> という名前のコレクションにマッピングします。

スキーマ修飾子は、コレクションの名前のみを変更します。スキーマは、個別のMongoDBデータベースではありません。スキーマで修飾されたすべてのコレクションは、SessionFactoryインスタンスが接続するデータベース内に存在します。これらのコレクションは1つのデータベースを共有しているため、トランザクションは複数のスキーマにまたがることができます。

スキーマ修飾子を適用するには、次の構文を使用します。

@Entity@Table(schema = "<schema name>", name = "<collection name>")public class <EntityName> {
    // Define your fields, constructors, and methods here
}

例

このサンプルMovie.java エンティティクラスは、次の情報を含む Movie エンティティを定義します。

• @Entity クラスをHibernetes ORM エンティティとしてマークする注釈

• @Table Atlasサンプルデータセットからエンティティを moviesコレクションにマッピングする注釈

• @Id と idフィールドをプライマリキーとして指定し、ObjectId の自動生成を構成する @ObjectIdGenerator 注釈

  Tip

  プライマリキー値

  この例では ObjectId フィールドをエンティティのプライマリキーとして指定していますが、@Id アノテーションを使用して String または int フィールドをプライマリキーとして設定することもできます。詳細については、「サポートされていないフィールド型」をご覧ください。

• 映画データを表すプライベート フィールド

• エンティティインスタンス化のためのデフォルトおよびパラメータ付きコンストラクタ

• エンティティのフィールドへのアクセスを提供する getter メソッドと setter メソッド

package org.example;
import com.mongodb.hibernate.annotations.ObjectIdGenerator;import org.bson.types.ObjectId;import java.util.List;
import jakarta.persistence.Entity;import jakarta.persistence.Id;import jakarta.persistence.Table;
@Entity@Table(name = "movies")public class Movie {	@Id	@ObjectIdGenerator	private ObjectId id;	private String title;	private String plot;	private int year;	private List<String> cast;	private List<String> directors;

	public Movie(String title, String plot, int year, List<String> cast, List<String> directors) { 		this.title = title;		this.plot = plot;		this.year = year;		this.cast = cast;        this.directors = directors; 	}
	public Movie() {
	}
	public ObjectId getId() {		return id;	}
	public String getTitle() {		return title;	}
	public void setTitle(String title) {		this.title = title;	}
	public String getPlot() {		return plot;	}
	public void setPlot(String plot) {		this.plot = plot;	}		public int getYear() {		return year;	}
	public void setYear(int year) {		this.year = year;	}
	public List<String> getCast() {		return cast;	}		public void setCast(List<String> cast) {		this.cast = cast;	}
    public List<String> getDirectors() {        return directors;    }
    public void setDirectors(List<String> directors) {        this.directors = directors;    }}

シーケンスで生成されたIDをエンティティに追加する

@GeneratedValue および @SequenceGenerator アノテーションを使用して、シーケンス生成された ID をエンティティに追加できます。次の例では、movies_SEQ カウンターから 50 のブロックで ID を予約します。

@Id@GeneratedValue(    strategy = GenerationType.SEQUENCE,    generator = "movies_SEQ")@SequenceGenerator(    name = "movies_SEQ",    sequenceName = "movies_SEQ",    allocationSize = 50)private Long id;

アノテーションは、Hibernate ORM 拡張機能が ID を作成する方法を制御します。

• @GeneratedValue Hibernate ORM 拡張に、id フィールドの値を作成するよう指示します。その strategy と generator 属性は、拡張機能が ID を作成する方法を定義します。

  • strategy: AUTO または SEQUENCE。AUTO を使用すると、Hibernate ORM 拡張はシーケンスを使用します。また、@SequenceGenerator を宣言する必要はありません。SEQUENCE を使用すると、Hibernate ORM 拡張機能は generator 属性で名前が付けられたシーケンス ジェネレータを使用します。

  • generator: 使用する @SequenceGenerator の名前。この属性を省略した場合、Hibernate ORM 拡張機能は、movies テーブルの movies_SEQ のように、エンティティのテーブルにちなんでシーケンスに名前を付けます。

• @SequenceGenerator シーケンスジェネレーターを指定します:

  • name：@GeneratedValue generator 属性が参照する名前。

  • sequenceName: カウンタードキュメントの名前。省略した場合、Hibernate ORM拡張機能はジェネレーターのnameを使用します。

  • initialValue: 最初に生成される ID が開始する値。デフォルトは 1 です。

  • allocationSize: 各ブロックで予約されるIDの数。

IDの保存場所

Hibernate ORM拡張機能は、カウンタードキュメントをhibernate_sequencesという名前の固定コレクションに保存します。各シーケンスは、次のフィールドを持つ1つのカウンタードキュメントを使用します。

• _id はシーケンス名です。

• next_value Hibernate ORM拡張機能が次のIDを生成するために進めるカウンター値です。これはシーケンスジェネレーターのinitialValueと一致している必要があり、デフォルトは1です。

• increment は、一度に予約されるIDの数です。これは、シーケンスジェネレーターのallocationSize値と一致する必要があります。一致しない場合、SessionFactoryは起動に失敗します。

Hibernate ORM拡張機能は、IDをブロック単位で取得します。これにより、データベースへの問い合わせ回数が削減されます。同時に行われたリクエストには、それぞれ異なるIDが割り当てられます。

スキーママネジメントを有効にする

スキーママネジメントは、エンティティが必要とするデータベースオブジェクトを作成するためのHibernate ORMの方法です。Hibernate ORM拡張機能は、これを使用して、シーケンス生成IDのカウンタードキュメントを作成します。

スキーママネジメントを有効にするには、jakarta.persistence.schema-generation.database.actionプロパティをhibernate.propertiesまたはpersistence.xmlファイルに設定します。次のいずれかの値を使用します。

• create: カウンタードキュメントを作成し、SessionFactoryが閉じるときにそれらを保持します。

• create-drop: SessionFactoryが開かれるときにカウンタードキュメントを作成し、閉じるときに削除します。

次の例では create を使用します。

jakarta.persistence.schema-generation.database.action=create

スキーママネジメントと手動カウンター設定を無効にする

スキーママネジメントをオフにする場合は、シーケンスで生成されるIDのカウンタードキュメントを手動で作成できます。次のプロパティを設定します。

jakarta.persistence.schema-generation.database.action=none

次に、各シーケンスに対して、hibernate_sequences コレクション内に 1 つのカウンター ドキュメントを作成します。カウンター ドキュメントの _id は、シーケンス ジェネレーターの sequenceName と一致する必要があります。

次の例では、MongoDB Java ドライバーを使用して、指定したデータベースの hibernate_sequences コレクションに movies_SEQ カウンタードキュメントを挿入します。

// Replace the placeholders with your connection string and database name.MongoClient client = MongoClients.create("<connection string>");MongoDatabase database = client.getDatabase("<database name>");
database.getCollection("hibernate_sequences").insertOne(        new Document("_id", "movies_SEQ")                .append("next_value", new BsonInt64(1))                .append("increment", new BsonInt64(50)));

{  "_id": "movies_SEQ",  "next_value": 1,  "increment": 50}

この挿入により、示されているカウンタードキュメントが作成されます。next_value をジェネレーターの initialValue に設定し、increment をその allocationSize に設定します。

エンティティを保存して生成されたIDを読み取る

次の例では、新しい Movie エンティティを保存し、生成された ID を出力します。ID は、シーケンスの開始点によって異なります。1 から始まる新しいカウンターの場合、出力は次のようになります。

var movie = new Movie();movie.setTitle("The Matrix");session.persist(movie);System.out.println("Movie created with ID: " + movie.getId());

Movie created with ID: 1

サポートされていない構成

Hibernate ORM エクステンションは、以下のシーケンス関連のストラテジー、タイプ、および設定をサポートしていません。

• IDENTITY および TABLE 生成戦略

• BigInteger および BigDecimal 生成された識別子タイプ

• . 文字を含むシーケンス名またはスキーマ

• 3部構成の名前や catalog 属性など、カタログで修飾されたシーケンス名

• シーケンス options

• @GenericGenerator および @TableGenerator ジェネレーター、@IdGeneratorType アノテーションを使用するカスタムジェネレーター、identity、table、increment などの名前付きレガシージェネレーター

• エンティティを hibernate_sequences コレクションにマッピングする

• insert ... select 生成済 ID のインライン割り当てを必要とするステートメント

UUIDの保存場所

Hibernate ORM拡張機能は、java.util.UUID値をサブタイプ4のBSON Binary値として保存します。次の例のドキュメントには、生成されたUUIDを持つ_idフィールドがあります。

{  "_id": {    "$binary": {      "base64": "FXvL4sBrQoueEByraiJUmA==",      "subType": "04"    }  },  "title": "The Matrix"}

@Id フィールドが String の場合、Hibernate ORM 拡張機能は生成された UUID を BSON Binary 値ではなく BSON String として保存します。

BSONフィールドタイプのマッピングの詳細については、このガイドのMongoDB BSONフィールドセクションを参照してください。

エンティティを保存し、生成されたUUIDを読み取る

次の例では、新しい UuidItem エンティティを保存し、生成された ID を出力します。

var item = new UuidItem();item.setTitle("The Matrix");session.persist(item);System.out.println("UuidItem created with ID: " + item.getId());

UuidItem created with ID: 157bcbe2-c06b-428b-9e10-1cab6a225498

UUIDの制限事項

Hibernate ORM拡張機能には、UUIDで生成されたIDを使用する場合、以下の制限があります。

• Hibernate ORM拡張機能は、レガシー識別子ジェネレーター名uuid、uuid.hex、uuid2、およびguidをサポートしていません。これらの名前のいずれかを指定すると、アプリケーションの起動時にHibernate ORM拡張機能がFeatureNotSupportedExceptionをスローします。代わりに@UuidGeneratorまたは@GeneratedValue(strategy = GenerationType.UUID)を使用してください。

• エンティティを永続化する前に@UuidGenerator @Idフィールドの値を割り当てると、Hibernate ORM拡張機能はjakarta.persistence.EntityExistsExceptionをスローします。UUID値を自分で割り当てるには、@Idフィールドからジェネレーターアノテーションを削除します。

複合キーのストレージ

Hibernate ORM拡張機能は、複合キーを_idサブドキュメントとして保存します。上記のBookエンティティは、次の形式のドキュメントを生成します。

{  "_id": { "bookNo": 2, "publisherId": 10 },  "title": "My Book"}

Hibernate ORM拡張機能は、_idサブドキュメントのコンポーネントを、宣言した順序ではなく、コンポーネント名でアルファベット順に並べ替えます。この順序は、埋め込み可能オブジェクトをクラスとして宣言するか、レコードとして宣言するかに関係なく同じです。

複合キーの制限

Hibernate ORM拡張機能は、以下のいずれかの方法で複合キーを宣言すると、アプリケーションの起動時にFeatureNotSupportedExceptionをスローします。

• @jakarta.persistence.IdClassアノテーションまたは複数の@Id属性で宣言された、集約されていない識別子。代わりに@EmbeddedIdでキーを宣言してください。

• 識別子として埋め込み可能な @Struct 集計。代わりにプレーンな @Embeddable を使用してください。

• ネストされた @Embeddable やコレクションなど、基本値ではないコンポーネント。複合キーのすべてのコンポーネントは、基本値である必要があります。

• @jakarta.persistence.MapsId アノテーションを使用する派生 ID を含む、識別子内の関連付け。

また、> や < などの順序演算子を使用して、複合識別子全体を比較することもできません。代わりに個々のコンポーネントを比較してください。

1 対 1 の関係

1 対 1 の関係とは、1 つのデータベースのレコードが別のデータベースの 1 つのレコードのみに関連付けられている場合を指します。MongoDBでは、埋め込みドキュメントフィールドを持つコレクションを作成して、1 対 1 の関係をモデル化できます。Hibernetes ORM 拡張機能では、@Struct 集計埋め込み可能ファイルを使用して埋め込みドキュメントフィールドを作成できます。

この例では、このガイドのエンティティの定義の例と同様に、エンティティ内に @Struct 集計埋め込み可能型を持つフィールドを定義します。サンプルMovie.java エンティティクラスには、次の情報が含まれています。

• @Entity エンティティを定義し、それを moviesコレクションにマッピングする @Table アノテーション

• @Id idフィールドをプライマリキーとして指定する @ObjectIdGenerator 注釈

• 映画のタイトルを表す Stringフィールド

• @Struct 映画情報とチームの情報を表す集計埋め込みフィールド

次の例は1 対 1 の関係を表します。各 Movie エンティティは 1 つの Awards 埋め込み可能と 1 つの Studio 埋め込み可能に関連付けられているためです。

@Entity@Table(name = "movies")public class Movie {
    @Id    @ObjectIdGenerator    private ObjectId id;    private String title;    private Awards awards;    private Studio studio;
    public Movie(String title, Awards awards, Studio studio) {        this.title = title;        this.awards = awards;        this.studio = studio;    }
    public Movie() {
    }
    // Getter and setter methods
}

次のサンプルコードでは、Awards @Struct 集計埋め込み可能を作成します。

@Embeddable@Struct(name = "Awards")public class Awards {    private int wins;    private int nominations;    private String text;
    public Awards(int wins, int nominations, String text) {       this.wins = wins;       this.nominations = nominations;       this.text = text;    }
    public Awards() {
    }
    // Getter and setter methods
}

次のサンプルコードでは、Studio @Struct 集計埋め込み可能を作成します。

@Embeddable@Struct(name = "Studio")public class Studio {    private String name;    private String location;    private int foundedYear;
    public Studio(String name, String location, int foundedYear) {        this.name = name;        this.location = location;        this.foundedYear = foundedYear;    }
    public Studio() {
    }
    // Getter and setter methods
}

1 対多の関係

1 対多の関係とは、1 つのデータベースのレコードが別のデータベースの多くのレコードに関連付けられている場合を指します。MongoDBでは、埋め込みドキュメントのリストを保存するコレクションフィールドを定義して、1 対多の関係をモデル化できます。Hibernetes ORM 拡張機能を使用すると、@Struct 集計埋め込み可能ファイルのリストを使用して埋め込みドキュメントフィールドを作成できます。

この例では、このガイドの エンティティの定義例 と同様に、エンティティに @Struct 集計埋め込み可能ファイルのリストを保存するフィールドを定義します。サンプルMovie.java エンティティクラスには、次の情報が含まれています。

• @Entity エンティティを定義し、それを moviesコレクションにマッピングする @Table アノテーション

• @Id idフィールドをプライマリキーとして指定する @ObjectIdGenerator 注釈

• 映画のタイトルを表す Stringフィールド

• 複数の Writer @Struct 集計埋め込み可能性を保存するリストフィールド。これは書込み情報を表す

次の例は1 対多の関係を表しています。各 Movie エンティティは複数の Writer 埋め込み可能に関連付けられているためです。

@Entity@Table(name = "movies")public class Movie {    @Id    @ObjectIdGenerator    @Column(name = "_id")    private ObjectId id;    private String title;    private List<Writer> writers;
    public Movie(String title, List<Writer> writers) {        this.title = title;        this.writers = writers;    }
    public Movie() {
    }
    // Getter and setter methods
}

次のサンプルコードでは、Writer @Struct 集計埋め込み可能を作成します。

@Embeddable@Struct(name = "Writer")public class Writer {    private String name;
    public Writer() {    }
    public Writer(String name) {        this.name = name;    }
    // Getter and setter methods
}

ネストされた埋め込み可能オブジェクト

flattened embeddableは、@Struct aggregate embeddableの中にネストできます。flattened embeddableは、@Embeddableアノテーションを含みますが、@Structアノテーションを含まないクラスです。Hibernate ORM拡張機能は、flattened embeddableのフィールドを、別のネストされたドキュメントとしてではなく、親の埋め込みドキュメントのフィールドとして保存します。

以下のサンプルコードは、Addressのフラット化された埋め込み可能オブジェクトをフィールドとして含む、Studio @Struct集計埋め込み可能オブジェクトを作成します。

@Embeddable@Struct(name = "Studio")public class Studio {    private String name;    private Address address;
    public Studio() {    }
    public Studio(String name, Address address) {        this.name = name;        this.address = address;    }
    // Getter and setter methods
}

以下のサンプルコードは、Address フラット化埋め込み可能オブジェクトを作成します。このクラスは @Struct アノテーションを省略しています。

@Embeddablepublic class Address {    private String city;    private String country;
    public Address() {    }
    public Address(String city, String country) {        this.city = city;        this.country = country;    }
    // Getter and setter methods
}

Studioフィールドを含むエンティティを永続化すると、AddressフィールドはStudioフィールドの埋め込みドキュメントのフィールドになります。次の例のドキュメントには、Addressフラット化された埋め込み可能なフィールドを保存するstudioという名前のStudioフィールドがあります。

{  "_id": { "$oid": "..." },  "title": "Breathless",  "studio": {    "name": "Les Films Impéria",    "city": "Paris",    "country": "France"  }}