Hibernate.org社区文档

第四章 额外模块

4.1. Bean 验证
4.1.1. 添加 Bean 验证
4.1.2. 配置
4.1.3. 捕捉违规
4.1.4. 数据库架构
4.2. Hibernate Validator 3
4.2.1. 描述
4.2.2. 与 Hibernate 注释集成
4.3. Hibernate Search
4.3.1. 描述
4.3.2. 与 Hibernate 注释集成

Hibernate 注释主要针对持久化元数据。该项目还与一些外部模块进行了很好的集成。

4.1. Bean 验证

Bean 验证标准化了域模型级别约束的定义和声明方式。例如，您可以表达某个属性永远不应为 null，帐户余额应严格为正等等。这些域模型约束在 bean 本身中通过注释其属性来声明。然后 Bean 验证可以读取它们并检查约束违规。无需重复任何这些规则（表示层、数据访问层），即可在应用程序的不同层中执行验证机制。遵循 DRY 原则，Bean 验证及其参考实现 Hibernate Validator 的设计正是出于此目的。

Hibernate 和 Bean 验证之间的集成在两个层面进行。首先，它能够检查一个类的内存中实例是否有约束违规。其次，它可以将约束应用于 Hibernate 元模型，并将它们合并到生成的数据库架构中。

每个约束注释都与一个验证器实现相关联，该实现负责检查实体实例上的约束。验证器还可以（可选地）将约束应用于 Hibernate 元模型，允许 Hibernate 生成表达该约束的 DDL。通过适当的事件侦听器，您可以在 Hibernate 执行的插入、更新和删除操作上执行检查操作。

在运行时检查实例时，Hibernate Validator 以一系列 ConstraintViolation 形式返回有关约束违规的信息。除了其他信息之外，ConstraintViolation 还会包含一个错误描述消息，其中可以嵌入带有注释的参数值捆绑（例如大小限制），以及可以外化到 ResourceBundle 的消息字符串。

要启用 Hibernate-Bean 验证集成，只需在您的 classpath 中添加一个 Bean 验证提供程序（最好是 Hibernate Validation 4）。

默认情况下，无需配置。

Default 组在实体插入和更新时经过验证，数据库模型也会根据 Default 组进行相应更新。

您可以通过设置验证模式自定义 Bean 验证集成。使用 javax.persistence.validation.mode 属性，例如可在 persistence.xml 文件或 hibernate.cfg.xml 文件中设置。有多种选项可供选择

注意

您可以通过将属性设置为 callback, dll 同时使用 callback 和 ddl


<persistence ...>

  <persistence-unit ...>

    ...

    <properties>

      <property name="javax.persistence.validation.mode"

                value="callback, ddl"/>

    </properties>

  </persistence-unit>

</persistence>

这等效于 auto，但如果不存在 Bean 验证提供者，则会引发异常。

如果您希望在插入、更新和删除过程中验证不同的组，请使用

每个属性都接受用逗号 (,) 分隔的验证组的完全限定类名

示例 4.1. 使用自定义组进行验证


<persistence ...>

  <persistence-unit ...>

    ...

    <properties>

      <property name="javax.persistence.validation.group.pre-update"

                value="javax.validation.group.Default, com.acme.group.Strict"/>

      <property name="javax.persistence.validation.group.pre-remove"

                value="com.acme.group.OnDelete"/>

      <property name="org.hibernate.validator.group.ddl"

                value="com.acme.group.DDL"/>

    </properties>

  </persistence-unit>

</persistence>

注意

您可以在 hibernate.cfg.xml、hibernate.properties 或以编程方式中设置这些属性。

如果发现实体无效，则通过 ConstraintViolationException 传播约束违反列表，该列表公开 ConstraintViolations 集合。

当违反发生在提交时，此异常被包装在 RollbackException 中。否则，将返回 ConstraintViolationException（例如，当调用 flush() 时。请注意，通常，可捕获的违规会在更高的级别（例如，通过 JSF-Bean 验证集成在 Seam/JSF 2 中，或通过显式调用 Bean 验证在业务层）中进行验证。

应用程序代码很少会找到 Hibernate 引发的 ConstraintViolationException。此异常应被视为致命异常，并且应放弃持久性上下文（EntityManager 或 Session）。

Hibernate 使用 Bean Validation 约束生成精确的数据库架构

这些约束可以直接在实体属性上声明，也可以通过使用约束组合间接声明。

4.2. Hibernate Validator 3

警告

我们强烈建议您使用 Hibernate Validator 4 和 Bean Validation 集成。将 Hibernate Validator 3 视为传统内容。

注解是一种非常方便和优雅的方式，可为域模型指定不变约束。例如，您可以表达某个属性永远不能为空，账户余额应严格为正等等。这些域模型约束在 bean 本身中通过注解其属性来声明。然后验证器可以读取这些属性并检查约束是否遭到违反。验证机制可以在应用程序的不同层中执行，而无需为任何这些规则（表示层、数据访问层）添加重复项。遵循 DRY 原则，Hibernate Validator 便是出于此目的而设计的。

Hibernate Validator 在两个层级上工作。首先，它能够检查类的不变内存实例约束。其次，它可以将约束应用于 Hibernate 元模型，并将它们合并到生成的数据库架构中。

每个约束注解都与验证器实现相关联，后者负责检查实体实例上的约束。验证器（可选）还可以将约束应用于 Hibernate 元模型，从而允许 Hibernate 生成表达约束的 DDL。使用适当的事件侦听器，可以在 Hibernate 执行的插入和更新操作上执行检查操作。Hibernate Validator 并不限于与 Hibernate 一起使用。您可以在应用程序的任何地方轻松使用它。

在运行时检查实例时，Hibernate Validator 在 InvalidValue 数组中返回有关约束违规的信息。除其他信息外，InvalidValue 包含错误描述消息，可以将参数值捆绑嵌入到注释（例如长度限制）中，并且消息字符串可以外化为 ResourceBundle。

如果 Hibernate Validator (hibernate-validator.jar) 在类路径中可用，则 Hibernate 注释将通过两种方式集成

对于没有验证规则的实体，运行时性能成本为 null。

要禁用约束传播到 DDL，请在配置文件中将 hibernate.validator.apply_to_ddl 设置为 false。这种需求非常罕见，不建议这样做。

要禁用实体更改前验证，请在配置文件中将 hibernate.validator.autoregister_listeners 设置为 false。这种需求非常罕见，不建议这样做。

请查看 Hibernate Validator 参考文档以获取更多信息。

4.3. Hibernate Search

像 Apache Lucene™ 这样的全文搜索引擎是一种功能非常强大的技术，可以为应用程序带来免费文本/高效查询。在处理对象域模型时会遇到几个不匹配项（使索引保持最新，索引结构和域模型之间的不匹配、查询不匹配...）Hibernate Search 可以使用一些注释来索引您的域模型，负责数据库/索引同步，并从免费文本查询中为您返回常规的受管对象。Hibernate Search 在内部使用 Apache Lucene。

前提是 hibernate-search.jar 存在于类路径中，Hibernate Search 可以与 Hibernate 注释透明地集成。如果您不想自动注册 Hibernate Search 事件侦听器，则可以将 hibernate.search.autoregister_listeners 设置为 false。这种需求非常罕见，不建议这样做。

请查看 Hibernate Search 参考文档以获取更多信息。

版权所有 © 2004 Red Hat Inc. 和各种作者