KingbaseES客户端编程开发框架-Hibernate.pdf

KingbaseES 客户端编程开发框架-Hibernate 金仓数据库管理系统 KingbaseES 文档版本：V9（V009R001C001B0024） 发布日期：2023 年 10 月 12 日 北京人大金仓信息技术股份有限公司 目 目 录 录 第 1 章 前言 1 1.1 适用读者 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1 1.2 相关文档 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1 1.3 术语 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1 1.4 手册约定 2 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 第 2 章 概述 3 2.1 Hibernate 简介 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3 2.2 Hibernate 驱动包和方言包 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3 2.3 Hibernate 开发流程 4 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 第 3 章 Hibernate 环境配置 6 3.1 Hibernate 工程搭建 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6 3.2 Hibernate 的配置文件说明 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6 3.3 服务的配置方法和参数说明 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7 第 4 章 Hibernate 编程指南 8 4.1 Hibernate 映射文件示例 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8 4.2 Hibernate 的 java 对象示例 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8 4.3 Hibernate 的 java 使用示例 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9 第 5 章 Hibernate 注意事项 11 版权声明 12 服务周期承诺 13 I 第 1 章 前言 1 第 章 前言 本文档描述了 KingbaseES 对 hibernate 框架的兼容，并提供了相关的搭建方法和配置方法。详细介绍了 KingbaseES 数据库对 Hibernate 的支持情况，以及在 KingbaseES 数据库使用 Hibernate 时应该注意的问题。 前言部分包含以下主题： • 适用读者 • 相关文档 • 术语 • 手册约定 1.1 适用读者 KingbaseES Hibernate 指南面向所有使用 KingbaseES 数据库的用户，主要是使用 Hibernate 进行应用程序开发 的开发人员。 1.2 相关文档 有关 Hibernate 的更多信息，请参阅以下资源： Hibernate ORM Documentation - 5.6 1.3 术语 $KINGBASE_HOME : KingbaseES 的安装路径。 1 第 1 章 前言 1.4 手册约定 本文档中可能出现“注意、提示、警告、另请参阅”等标志，它们所代表的含义如下： 注意: 用于突出重要/关键信息、最佳实践等。 提示: 用于突出小窍门、捷径等。 警告: 用于传递设备或环境安全警示信息，若不避免，可能会导致设备损坏、数据丢失、设备性能降低或其 它不可预知的结果。 另请参阅: 用于突出参考、参阅等。 以下程序代码书写约定适用于本文档： 符号 说明 [] 表示包含一个或多个可选项。不需要输入中括号本身。 {} 表示包含两个以上（含两个）的候选，必须在其中选取一个。不需要输入花括号本身。 | 分割中括号或者花括号中的两个或两个以上选项。不需要输入“|”本身。 ... 表示其之前的元素可以被重复。 斜体 表示占位符或者需要提供特定值的变量。 大写 表示系统提供的元素，以便与用户定义的元素相互区分。除出现在方括号中的元素外，应当按 照顺序逐字输入。当然，部分元素在系统中是大小写不敏感的，因此用户可以根据系统说明以 小写形式输入。 小写 表示由用户提供的元素。 2 第 2 章 概述 2 第 章 概述 本部分描述了 Hibernate 的简介、驱动包和方言包以及开发流程。 • Hibernate 简介 • Hibernate 驱动包和方言包 • Hibernate 开发流程 2.1 Hibernate 简介 Hibernate 是一个开放源代码的对象关系映射框架，它对 JDBC 进行了非常轻量级的对象封装，它将 POJO 与 数据库表建立映射关系，是一个全自动的 ORM 框架，Hibernate 可以自动生成 SQL 语句，自动执行，使得 Java 程 序员可以熟练地使用对象编程思维来操纵数据库。 2.2 Hibernate 驱动包和方言包 KingbaseES 提供了 Hibernate 的方言类 Kingbase8Dialect，目前 KingbaseES 共提供了以下几个方言包来支持 Hibernate： 方言包 适用范围 hibernate-2.0.dialect.jar 2.0<= 适用范围 <2.1 hibernate-2.1.dialect.jar 2.1<= 适用范围 <3.0 hibernate-3.0.dialect.jar 3.0<= 适用范围 <3.0.3 hibernate-3.0.3.dialect.jar 3.0.3<= 适用范围 <3.6.0 hibernate-4.dialect.jar 3.6.0<= 适用范围 3 第 2 章 概述 Kingbase8Dialect 位于 $KINGBASE_HOME/Interface/hibernate/ 目录中。使用时将 hibernatexxxdialect.jar 导 入到项目的 Libraries 中并定义相关配置项即可。 也可以在 maven 项目的 pom.xml 文件中添加依赖, 根据需求选择需要的版本： cn.com.kingbaseKesDialect-for-hibernate2.01.0.0cn.com.kingbaseKesDialect-for-hibernate2.11.0.0cn.com.kingbaseKesDialect-for-hibernate3.01.0.0cn.com.kingbaseKesDialect-for-hibernate3.0.31.0.0cn.com.kingbaseKesDialect-for-hibernate41.0.0 2.3 Hibernate 开发流程 hibernate 首先通过配置文件 cfg.xml 初始化数据库，创建 SessionFactory，进而得到 session 也就是一个数据库 连接。cfg 文件中包括数据库驱动、URL、数据库名称以及密码等等参数，最重要的是将表或者视图的 hbm 文件写入 4 第 2 章 概述 cfg 文件，否则是无法使用 Hibernate 服务的。当用户操作数据库表或视图的时候，hibernate 加载此表的 hibernate mapping 文件，也就是 hbm.xml 文件。hbm 文件主要是映射数据库表与持久化类 POJO。通过 hbm 文件可以将实 体对象与数据库表或者视图对应，从而间接的操作数据库表或者视图。 图 2.3.1: Hibernate 使用原理图 5 第 3 章 HIBERNATE 环境配置 3 第 章 Hibernate 环境配置 本部分描述如何配置 Hibernate 的开发环境，包括工程搭建、配置文件、配置方法和参数。 • Hibernate 工程搭建 • Hibernate 的配置文件说明 • 服务的配置方法和参数说明 3.1 Hibernate 工程搭建 要使用 Hibernate 进行开发，需要先搭建环境。以下两种方法均可完成搭建环境： • 创建好项目之后，在/lib 目录下导入 hibernate 的核心 jar 包以及 hibernatexxxdialect.jar 方言包。 • 使用 Maven 工具来管理 jar 包，修改 pom.xml 配置来导入 hibernate 核心 jar 包以及 hibernatexxxdialect.jar 方言包。 3.2 Hibernate 的配置文件说明 定义 hibernate 配置文件，根据用户选择更改以下配置文件。 a. 在 hibernate.properties 中增加如下声明： hibernate.dialect = org.hibernate.dialect.Kingbase8Dialect b. 在 hibernate.cfg.xml 中增加如下声明： org.hibernate.dialect. Kingbase8Dialect c. 在 persistence.xml 中增加如下声明： 6 第 3 章 HIBERNATE 环境配置 注意: hibernatexxxdialect.jar 方言包全部依赖于 1.6 以上版本 JDK 生成。 3.3 服务的配置方法和参数说明 Hibernate 配置文件示例 create-droptruefalseorg.hibernate.dialect.Kingbase8Dialectcom.kingbase8.Driverjdbc:kingbase8://localhost:54321/ testtesttest 配置时按照实际使用情况修改”dialect” 、”connection.driver_class” 等参数。 7 第 4 章 HIBERNATE 编程指南 4 第 章 Hibernate 编程指南 本章节列举了部分使用 Hibernate 进行的开发程序示例，如下所示： • Hibernate 映射文件示例 • Hibernate 的 java 对象示例 • Hibernate 的 java 使用示例 4.1 Hibernate 映射文件示例 下例程序为 Hibernate 的映射文件配置： 4.2 Hibernate 的 java 对象示例 下例为 Hibernate 的 Java 对象示例： 8 第 4 章 HIBERNATE 编程指南 package hibernate_test; public class TestDb { private String username; private Long id; private boolean btest; public Long getId() { return id; } public void setId(Long id) { this.id = id; } public String getUsername() { return username; } public void setUsername(String myname) { this.username = myname; } public boolean getBtest() { return btest; } public void setBtest(boolean bbtest) { this.btest = bbtest; } } 4.3 Hibernate 的 java 使用示例 下例为 Hibernate 的 Java 使用示例： String name = "username"; Long id = 0; boolean btest = false; SessionFactory sessionFactory = new Configuration().configure() .buildSessionFactory(); Session session = sessionFactory.openSession(); Transaction tx = session.beginTransaction(); TestDb user = new TestDb(); user.setUsername(name); user.setId(id); 9 第 4 章 HIBERNATE 编程指南 user.setBtest(btest); session.save(user); TestDb obj = (TestDb) session.load(TestDb.class, new Long(id)); System.out.println(obj.getUsername()); tx = session.beginTransaction(); obj = (TestDb) session.load(TestDb.class, new Long(id)); obj.setUsername("update_test" + id); session.update(obj); tx.commit(); 注意: KingbaseES 兼容 Hibernate 的基本框架，更多 Hibernate 编程开发操作可以参考： Hibernate JavaDoc(6.0.0.CR2) 10 第 5 章 HIBERNATE 注意事项 5 第 章 Hibernate 注意事项 a. HQL（JPA QL）不支持 KingbaseES 特有的函数，包括：TO_HEX、UNICODE、SETSEED、STRPOS、 GET_BIT、GET_BYTE、SET_BIT、SET_BYTE、EMPTY_BLOB、EMPTY_CLOB、CAST、ARRAY_NDIMS、ARRAY_FILL、UNNEST 和 ARRAY_LENGTH 等。 b. HQL（JPA QL）不支持某些操作符，包括：+、^、%、&、|、||、# 和 ~ 等，以及 UNION、UNION ALL、 INTERSECT、EXCEPT。 c. 不支持 INTERVAL 数据类型以及返回值为 INTERVAL 的系统函数，包括：AGE、DATE_FORMAT、ISFINITE、STR_VALID 和 TIMEOFDAY。 d. 对于近义的系统函数，只支持常用的名称，例如：sqrt（dsqrt）、cbrt（dcbrt）等。 e. 对于重载的系统函数，只支持常用的参数及返回值类型，例如：LEFT(expr1 TEXT, expr2 INTEGER)、 REPLICATE(expr1 TEXT, expr2 INTEGER)、RIGHT(expr1 TEXT, expr2 INTEGER) 和 SUB- STRING(expr1 TEXT, [FROM] expr2 INTEGER[,[FOR] expr3 INTEGER]) 等。 f. 使用原生查询时，某些函数的返回值与 KingbaseES 有差异，例如：SIGN() 应返回整型值但实际返回浮点型。 g. 只有在查询时才可使用 Query.getSingleResult() 方法，例如因为该方法会添加 Limit 子句，call function() 执行 函数取返回值时使用该方法会构造一个不合法的 SQL 语句。 h. 3.0.3 和 4 两个版本的方言包中还包含一个名称为 KingbaseBooleanDialect 的方言包，对应的 AcbaseT 的方言 包名称为 AcbaseTBooleanDialect。该方言包用于 hibernate 使用 Java 的 boolean 类型映射数据库的 numeric 类型且使用 hibernate 默认的 BooleanType 时，hibernate 执行操作可以将 hql 中 boolean 类型的 true 或者 false 转换成 1 或者 0。如：HQL 语句 select p.name FROM Person p where p.sex=true 会转换为 SQL 语 句 select person0_.name as col_0_0_ from person person0_ where person0_.sex=1 。 11 版权声明 版权声明 北京人大金仓信息技术股份有限公司（简称：人大金仓）版权所有，并保留对本手册及本声明的一切权利。 未得到人大金仓的书面许可，任何人不得以任何方式或形式对本手册内的任何部分进行复制、摘录、备份、修 改、传播、翻译成其他语言、将其全部或部分用于商业用途。 免责声明 本手册内容依据现有信息制作，由于产品版本升级或其他原因，其内容有可能变更。人大金仓保留在没有任何通 知或者提示的情况下对手册内容进行修改的权利。 本手册仅作为使用指导，人大金仓在编写本手册时已尽力保证其内容准确可靠，但并不确保手册内容完全没有错 误或遗漏，本手册中的所有信息也不构成任何明示或暗示的担保。 技术支持 • 人大金仓官方网站：http://www.kingbase.com.cn/ • 人大金仓文档中心：http://help.kingbase.com.cn/ • 全国服务热线：400-601-1188 • 人大金仓技术支持与反馈信箱：support@kingbase.com.cn 12 服务周期承诺 服务周期承诺 由于市场需求在不断变化，技术创新和发展的进程不断加剧，产品的版本更迭不可避免。人大金仓对于产品版本 生命周期的有效管理，有助于您提前规划项目，更好地从产品服务终止上过渡。 表 1: KingbaseES 产品生命周期里程碑 关键里程碑点 定义 产品发布日期 产品正式发布版本，即 GA（general availability）版本的发布日期。 停止销售日期 正式停止销售的日期，版本停止接受订单日。该日之后，产品将不再销售。 停止功能升级日期 在该日期之后，不再提供新特性和新硬件支持。但依旧提供错误修复、安全修复、功 能维护等服务。 停止功能维护日期 在该日期之后，不再维护功能，修复问题。但依旧提供安全修复等服务 停止安全维护日期 在该日期之后，不再发布补丁版本修复中高风险漏洞，仅提供有限的支持。 产品服务终止日期 停止提供产品服务和支持的日期。包括软件维护版本，缺陷修复，以及针对该产品的 所有服务支持（包括服务热线和远程/现场支持）。 服务周期策略 金仓数据库管理系统 KingbaseES 产品确保以下的服务周期： 1）产品自发布之日起至产品停止功能升级（包含新特性、新硬件支持）之日不少于 5 年。 2）产品停止功能升级之日起至产品停止功能维护（主要包括问题修复）之日不少于 4 年。 3）产品功能维护停止之日起至产品停止安全维护（包括中高风险漏洞修复）之日不少于 2 年。 服务终止策略 金仓数据库管理系统 KingbaseES 产品确保在销售后，至少提供 6 年的服务支持。 注意: 人大金仓将会综合各方因素来确定产品服务终止日期。并将在实际产品服务终止日期之前至少 90 天，通过公 13 服务周期承诺 开方式宣布产品服务终止日期。 14