创建实体来表示集合

不支持的字段类型

当 Hibernate ORM 没有其他映射到该类型时，它会将实现 java.io.Serializable 的任何Java类型序列化为二进制数据。为了防止您的数据以这种格式存储，Hibernate ORM 扩展会拒绝以下类型，并在应用程序启动时引发异常。此检查适用于主节点 (primary node in the replica set)键、普通字段、可嵌入属性和集合元素。

下表描述了不支持的字段类型及其支持的替代项：

模式限定符

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

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

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

@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 创建计数器文档。

要启用模式管理，请在 hibernate.properties 或 persistence.xml文件中设立jakarta.persistence.schema-generation.database.action属性。使用以下值之一：

• create：创建计数器文档并在 SessionFactory 关闭时保留这些文档。

• create-drop: Creates the counter documents when the SessionFactory opens and drops them when it closes.

以下示例使用 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 进行内联分配的语句

复合密钥存储

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
}

嵌套可嵌入对象

您可以将展平的可嵌入对象嵌套在 @Struct 聚合可嵌入对象中。扁平化嵌入式类是包含 @Embeddable 注解但不包含 @Struct 注解的类。 Hibernate ORM 扩展将展平嵌入式文档的字段存储为父嵌入式文档的字段，而不是单独的嵌套文档。

以下示例代码创建一个 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 注解：

@Embeddable
public 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"
  }
}