创建实体来表示集合

不支持的字段类型

Hibernate ORM 在没有该类型的其他映射时，会将实现 java.io.Serializable 的任何 Java 类型序列化为二进制数据。为防止您的数据以此格式存储，Hibernate ORM 扩展会拒绝以下类型，并在您的应用程序启动时抛出异常。此检查应用于主键、普通字段、可嵌入属性和集合元素。

下表介绍了不支持的字段类型及其支持的替代方案：

模式限定符

@Table 注解接受一个可选的 schema 元素，该元素作为集合名称的前缀。当您同时设置这两个元素时，Hibernate ORM 扩展会将该实体映射到名为 <schema name>.<collection name> 的集合中。

模式限定符仅更改集合的名称。模式不是单独的 MongoDB 数据库。每个模式限定的集合都驻留在您的 SessionFactory 实例连接到的数据库中。由于这些集合共享一个数据库，因此一个事务可以跨越多个模式。

使用以下语法应用模式限定符：

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

例子

此示例Movie.java 实体类定义了一个 Movie 实体，其中包含以下信息：

• @Entity 将该类标记为 Hibernate ORM 实体的注解

• @Table 注释，用于将实体映射到Atlas示例数据集中的 movies集合

• @Id 和 @ObjectIdGenerator 注解，用于将 id字段指定为主主键并配置自动 ObjectId 生成

  提示

  主键值

  此示例将 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 的固定集合中。每个序列使用一个包含以下字段的计数器文档：

• _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 集合中针对每个序列创建一个计数器文档。计数器文档的 _id 必须与序列生成器的 sequenceName 匹配。

以下示例使用 MongoDB Java 驱动程序将 movies_SEQ 计数器文档插入到您指定的数据库的 hibernate_sequences 集合中：

// 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 生成的标识符类型

• 包含 . 字符的序列名称或模式

• 由目录限定的序列名称，例如三部分名称或 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 String，而不是 BSON Binary 值。

要了解有关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 限制

当您使用 UUID 生成的 ID 时，Hibernate ORM 扩展具有以下限制：

• 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 注解的派生标识。

您也不能使用 > 或 < 等排序操作符来比较整个复合标识符。请改用比较各个组件。

一对一关系

A One-to-One relationship is when a record in one database is associated with exactly one record in another database. In MongoDB, you can create a collection with an embedded document field to model a One-to-One relationship. The Hibernate ORM extension allows you to create embedded document fields by using @Struct aggregate embeddables.

The example defines a field with a @Struct aggregate embeddable type in an entity similar to the Define an Entity example in this guide. The sample Movie.java entity class includes the following information:

• @Entity 和 @Table 注解，用于定义实体并将其映射到 movies集合

• @Id 以及将 id字段指定为主键的 @ObjectIdGenerator 注解

• 表示电影标题的字符串字段

• @Struct 聚合表示电影奖项和工作室信息的可嵌入式字段

The following example represents a One-to-One relationship because each Movie entity is associated with one Awards embeddable and one Studio embeddable:

@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
}

一对多关系

一对多关系是指一个数据库中的一条记录与另一个数据库中的多条记录相关联。在MongoDB中，您可以定义一个集合字段来存储嵌入式文档列表，以对一对多关系进行建模。Hibernate ORM 扩展允许您使用 @Struct 聚合可嵌入对象的列表来创建嵌入式文档字段。

The example defines a field that stores a list of @Struct aggregate embeddables in an entity similar to the Define an Entity Example in this guide. The sample Movie.java entity class includes the following information:

• @Entity 和 @Table 注解，用于定义实体并将其映射到 movies集合

• @Id 以及将 id字段指定为主键的 @ObjectIdGenerator 注解

• 表示电影标题的字符串字段

• 存储多个 Writer @Struct 聚合可嵌入对象的列表字段，表示作者信息

The following example represents a One-to-Many relationship because each Movie entity is associated with multiple Writer embeddables:

@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聚合 embeddable 中。flattened embeddable 是一个包含 @Embeddable 注解但不包含 @Struct 注解的类。Hibernate ORM 扩展将 flattened embeddable 的字段存储为父嵌入式文档的字段，而不是作为单独的嵌套文档。

以下示例代码创建了一个 Studio @Struct 聚合可嵌入对象，其中包含一个 Address 扁平化可嵌入对象作为字段：

@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 字段的嵌入式文档的字段。以下示例文档具有一个名为 studio 的 Studio 字段，该字段存储其 Address 扁平化可嵌入对象的字段：

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