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

KingbaseES 客户端编程开发框架-Hibernate Spatial 金仓数据库管理系统 KingbaseES 文档版本：V9（V009R001C001B0024） 发布日期：2023 年 10 月 12 日 北京人大金仓信息技术股份有限公司 目 目 录 录 第 1 章 前言 1 1.1 适用读者 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1 1.2 相关文档 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1 1.3 术语 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2 1.4 手册约定 2 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 第 2 章 概述 3 2.1 Hibernate Spatial 简介 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3 2.2 KingbaseES Hibernate Spatial 方言包介绍 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3 第 3 章 Hibernate-Spatial 配置 5 3.1 配置说明 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5 3.2 举例说明 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5 第 4 章 KingbaseES Hibernate Spatial 注意事项 11 版权声明 12 服务周期承诺 13 I 第 1 章 前言 1 第 章 前言 本文档描述了 Hibernate Spatial 的功能和用法，以及 KingbaseES 对其兼容性和支持。 前言部分包含以下主题： • 适用读者 • 相关文档 • 术语 • 手册约定 1.1 适用读者 《KingbaseES Hibernate Spatial 指南》面向所有使用 KingbaseES 数据库的用户，主要是数据库管理员和应用 程序开发人员。 在开始阅读本文档之前，您需要了解以下内容： • KingbaseES 客户端编程开发框架-Hibernate 1.2 相关文档 有关 Hibernate Spatial 的更多信息，请参阅以下资源： Documentation Hibernate Spatial 1 第 1 章 前言 1.3 术语 1.4 手册约定 本文档中可能出现“注意、提示、警告、另请参阅”等标志，它们所代表的含义如下： 注意: 用于突出重要/关键信息、最佳实践等。 提示: 用于突出小窍门、捷径等。 警告: 用于传递设备或环境安全警示信息，若不避免，可能会导致设备损坏、数据丢失、设备性能降低或其 它不可预知的结果。 另请参阅: 用于突出参考、参阅等。 以下程序代码书写约定适用于本文档： 符号 说明 [] 表示包含一个或多个可选项。不需要输入中括号本身。 {} 表示包含两个以上（含两个）的候选，必须在其中选取一个。不需要输入花括号本身。 | 分割中括号或者花括号中的两个或两个以上选项。不需要输入“|”本身。 ... 表示其之前的元素可以被重复。 斜体 表示占位符或者需要提供特定值的变量。 大写 表示系统提供的元素，以便与用户定义的元素相互区分。除出现在方括号中的元素外，应当按 照顺序逐字输入。当然，部分元素在系统中是大小写不敏感的，因此用户可以根据系统说明以 小写形式输入。 小写 表示由用户提供的元素。 2 第 2 章 概述 2 第 章 概述 本章节简单描述了 Hibernate Spatial 的简介，和 KingbaseES 数据库的 Hibernate Spatial 方言包。 • Hibernate Spatial 简介 • KingbaseES Hibernate Spatial 方言包介绍 2.1 Hibernate Spatial 简介 Hibernate Spatial 是 Hibernate 的通用扩展，用于处理地理数据。Hibernate Spatial 允许您以标准化方式处理地 理数据。它从数据库支持地理数据的特定方式中抽象出来，并为地理数据存储和查询功能提供了标准化的跨数据库接 口。 2.2 KingbaseES Hibernate Spatial 方言包介绍 KingbaseES 提供了 Hibernate Spatial 的方言类 PostgisESDialect，目前 KingbaseES 共提供了以下几个方言包 来支持 Hibernate Spatial，以及不同方言包适用的 Hibernate 版本： PostgisESDialect 方言包 适用范围 hibernate-spatial-postgis-kingbase-1.0.jar 3.0.3=< 适用范围 <3.6.0 hibernate-spatial-postgis-kingbase-1.1.jar 3.6.0=< 适用范围 <4.0 hibernate-spatial-postgis-kingbase-4.jar 4.0=< 适用范围 位于 $KINGBASE_HOME/ Interface/ hibernate/ hibernate-spatial/目 录 中。 使 用 时 将 hibernate-spatial-postgis-kingbase-xxx.jar 及其依赖包导入到项目的 Libraries 中并定义相关配置项即可。 Hibernate Spatial 方言包继承自 Hibernate 方言包，但以两个独立的形式发布，两种方言包之间没有直接的关 系。Hibernate Spatial 方言包支持 Hibernate 方言包的所有功能，导入 Hibernate Spatial 方言包后，无需再导入 Hibernate 方言包。 3 第 2 章 概述 图 2.2.1: Hibernate Spatial 流程图 4 第 3 章 HIBERNATE-SPATIAL 配置 3 第 章 Hibernate-Spatial 配置 您可前往 人大金仓官网 下载 Hibernate-Spatial 测试用例 。 3.1 配置说明 使用 Hibernate Spatial 只需将配置文件中 Hibernate 方言包名称替换为对应版本的 Hibernate Spatial 方言包名 称即可。 a. Hibernate Spatial 1 替换为： org.hibernatespatial.postgis.PostgisESDialect b. Hibernate Spatial 1 以上替换为： org.hibernate.spatial.dialect.postgis.PostgisESDialect 3.2 举例说明 以 Hibernate4 为例： a. Hibernate 配置文件 (hibernate.cfg.xml) 示例 org.postgresql.Driver 5 第 3 章 HIBERNATE-SPATIAL 配置 jdbc:postgresql://localhost:54321/testsystem1234561org.hibernate.spatial.dialect.postgis.PostgisESDialectthreadorg.hibernate.cache.NoCacheProvidertruecreate b. Hibernate 映射文件 (event.hbm.xml) 示例 6 第 3 章 HIBERNATE-SPATIAL 配置 c. java 对象 (event) 示例 import java.util.Date; import com.vividsolutions.jts.geom.Point; public class Event { private Long id; private String title; private Date date; private Point location; public Event() { } public Long getId() { return id; } public void setId(Long id) { this.id = id; } public Date getDate() { return date; } public void setDate(Date date) { this.date = date; } public String getTitle() { return title; } public void setTitle(String title) { this.title = title; } 7 第 3 章 HIBERNATE-SPATIAL 配置 public Point getLocation() { return this.location; } public void setLocation(Point location) { this.location = location; } } d. Hibernate 获取 SessionFactory package org.hibernatespatial.util; import org.hibernate.*; import org.hibernate.cfg.*; public class HibernateUtil { private static final SessionFactory sessionFactory; static { try { sessionFactory = new Configuration().configure().buildSessionFactory(); } catch (Throwable ex) { System.err.println("Initial SessionFactory creation failed." + ex); throw new ExceptionInInitializerError(ex); } } public static SessionFactory getSessionFactory() { return sessionFactory; } } e. Hibernate 的 java 使用例子 package org.hibernatespatial.test; import org.hibernate.Session; import org.hibernatespatial.entity.Event; import org.hibernatespatial.util.HibernateUtil; import java.util.Date; 8 第 3 章 HIBERNATE-SPATIAL 配置 import com.vividsolutions.jts.geom.Point; import com.vividsolutions.jts.geom.Geometry; import com.vividsolutions.jts.io.WKTReader; import com.vividsolutions.jts.io.ParseException; public class EventManager { public static void main(String[] args) { EventManager mgr = new EventManager(); if (args[0].equals("store")) { mgr.createAndStoreEvent("My Event", new Date(), assemble(args)); } HibernateUtil.getSessionFactory().close(); } private void createAndStoreEvent(String title, Date theDate, String wktPoint) { WKTReader fromText = new WKTReader(); Geometry geom = null; try { geom = fromText.read(wktPoint); } catch (ParseException e) { throw new RuntimeException("Not a WKT string:" + wktPoint); } if (!geom.getGeometryType().equals("Point")) { throw new RuntimeException("Geometry must be a point. Got a " + geom.getGeometryType()); } Session session = HibernateUtil.getSessionFactory().getCurrentSession(); session.beginTransaction(); Event theEvent = new Event(); theEvent.setTitle(title); theEvent.setDate(theDate); theEvent.setLocation((Point) geom); session.save(theEvent); session.getTransaction().commit(); } 9 第 3 章 HIBERNATE-SPATIAL 配置 /** * 将数组按顺序拼接成以空格符分割的 String 对象 */ private static String assemble(String[] args) { StringBuilder builder = new StringBuilder(); for (int i = 1; i < args.length; i++) { builder.append(args[i]).append(" "); } return builder.toString(); } } 10 第 4 章 KINGBASEES HIBERNATE SPATIAL 注意事项 4 第 章 KingbaseES Hibernate Spatial 注意事 项 a. KingbaseES 提供的 Hibernate Spatial 的方言类 PostgisESDialect 依赖于 PostgisDialect，故使用 1.0、1.1 版 本的 kingbase 方言包时需导入对应版本的 hibernate-spatial-postgis-xxx.jar, 在之后的版本中，这个包集成在 hibernate-spatial 包内，无需另外导入； b. 使用 Hibernate Spatial 需使用 pg 形态的驱动，即直接使用 pg 的驱动类（org.postgresql.Driver）和连接串 （jdbc:postgresql://localhost:54321/test）。pg 形态的驱动位于 $KINGBASE_HOME/Interface/jdbc 目录下, 名称为 postgresql-xxx.jar； c. 该方言包中还包含一个名称为 PostgisESBooleanDialect 的方言包。该方言包用于 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