{"id":47672996,"url":"https://github.com/zhyt1985/udbx4j","last_synced_at":"2026-04-05T07:03:17.861Z","repository":{"id":346396864,"uuid":"1189752823","full_name":"zhyt1985/udbx4j","owner":"zhyt1985","description":null,"archived":false,"fork":false,"pushed_at":"2026-03-23T17:10:13.000Z","size":10156,"stargazers_count":1,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-03-24T15:06:17.051Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"Java","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/zhyt1985.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-03-23T16:24:40.000Z","updated_at":"2026-03-23T17:10:42.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/zhyt1985/udbx4j","commit_stats":null,"previous_names":["zhyt1985/udbx4j"],"tags_count":1,"template":false,"template_full_name":null,"purl":"pkg:github/zhyt1985/udbx4j","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/zhyt1985%2Fudbx4j","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/zhyt1985%2Fudbx4j/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/zhyt1985%2Fudbx4j/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/zhyt1985%2Fudbx4j/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/zhyt1985","download_url":"https://codeload.github.com/zhyt1985/udbx4j/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/zhyt1985%2Fudbx4j/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":31306711,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-04-02T12:59:32.332Z","status":"ssl_error","status_checked_at":"2026-04-02T12:54:48.875Z","response_time":89,"last_error":"SSL_connect returned=1 errno=0 peeraddr=140.82.121.5:443 state=error: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2026-04-02T13:02:38.613Z","updated_at":"2026-04-02T13:02:47.066Z","avatar_url":"https://github.com/zhyt1985.png","language":"Java","funding_links":[],"categories":[],"sub_categories":[],"readme":"# udbx4j\n\n超图 UDBX 空间数据格式的 Java 读写库\n\n[![Java](https://img.shields.io/badge/Java-17-orange.svg)](https://openjdk.org/projects/jdk/17/)\n[![License](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE)\n[![Maven Central](https://img.shields.io/maven-central/v/io.github.zhyt1985/udbx4j)](https://central.sonatype.com/artifact/io.github.zhyt1985/udbx4j)\n\n\u003e **🎉 v1.0.0 已发布！** 现已发布到 Maven Central，可通过 Maven 依赖使用。\n\n## 简介\n\n`udbx4j` 是超图 UDBX 空间数据格式的纯 Java 读写库。UDBX（Universal Spatial Database Extension）基于 SQLite 存储，支持矢量（点/线/面/CAD）和栅格空间数据。\n\n本项目实现了对 UDBX 格式的独立读写，无需依赖 SuperMap iObjects Java 组件。\n\n## 特性\n\n- ✅ **高性能** - 纯 Java 实现，零 JNI 开销\n  - 单线程读取性能提升 **92.5%**（实测：0.34ms vs 4.5ms 基线）\n  - 多线程并发扩展 **3.49 倍**（实测：7.94M vs 2.27M ops/s）\n  - 批量写入性能提升 **10-50 倍**（使用 addFeaturesBatch API）\n  - 分页查询内存开销仅 **+22%**\n- ✅ **高稳定性** - 无 JNI 内存泄漏风险\n  - JVM GC 自动管理内存，零泄漏\n  - 无许可依赖，部署更简单\n  - 详细的 Java 异常堆栈，易调试\n- ✅ **纯 Java 实现** - 无需原生依赖\n  - 单个 JAR 包，跨平台无障碍\n  - 支持 GraalVM Native Image\n- ✅ **完整的数据集支持**\n  - 纯属性表（Tabular）\n  - 矢量数据：点、线、面（Point/Line/Region）\n  - 三维矢量：PointZ、LineZ、RegionZ\n  - CAD 数据集\n- ✅ **标准生态集成** - JDBC + JTS\n  - 无缝集成 Spring Boot、连接池、监控\n  - 支持 HikariCP、MyBatis、Hibernate\n- ✅ **SpatiaLite 兼容** - GAIA Geometry 格式支持\n- ✅ **轻量级** - 基于 JDBC + SQLite，无重型依赖\n- ✅ **测试驱动** - Spec 测试 + 集成测试双重保障\n\n## 快速开始\n\n### 环境要求\n\n- Java 17 或更高版本\n- Maven 3.6+\n\n### Maven 依赖\n\n```xml\n\u003cdependency\u003e\n    \u003cgroupId\u003eio.github.zhyt1985\u003c/groupId\u003e\n    \u003cartifactId\u003eudbx4j\u003c/artifactId\u003e\n    \u003cversion\u003e1.0.0\u003c/version\u003e\n\u003c/dependency\u003e\n```\n\n### 代码示例\n\n#### 打开 UDBX 文件\n\n```java\nimport com.supermap.udbx.UdbxDataSource;\n\n// 打开现有 UDBX 文件\ntry (UdbxDataSource dataSource = UdbxDataSource.open(\"path/to/data.udbx\")) {\n    // 列出所有数据集\n    dataSource.getDatasetNames().forEach(System.out::println);\n}\n```\n\n#### 读取点数据\n\n```java\nimport com.supermap.udbx.dataset.PointDataset;\nimport com.supermap.udbx.dataset.PointFeature;\n\ntry (UdbxDataSource dataSource = UdbxDataSource.open(\"points.udbx\")) {\n    PointDataset dataset = (PointDataset) dataSource.getDataset(\"PointData\");\n\n    // 遍历所有要素\n    for (PointFeature feature : dataset) {\n        System.out.printf(\"ID: %d, X: %.2f, Y: %.2f%n\",\n            feature.getId(),\n            feature.getGeometry().getX(),\n            feature.getGeometry().getY());\n    }\n}\n```\n\n#### 创建新数据集\n\n```java\nimport com.supermap.udbx.UdbxDataSource;\nimport com.supermap.udbx.core.DatasetType;\nimport com.supermap.udbx.core.FieldInfo;\nimport com.supermap.udbx.core.FieldType;\nimport com.supermap.udbx.dataset.PointDataset;\nimport com.supermap.udbx.dataset.PointFeature;\nimport com.supermap.udbx.geometry.gaia.GaiaPoint;\n\n// 创建新 UDBX 文件\ntry (UdbxDataSource dataSource = UdbxDataSource.create(\"output.udbx\")) {\n    // 创建字段信息\n    List\u003cFieldInfo\u003e fields = List.of(\n        new FieldInfo(\"名称\", FieldType.CHAR, 50),\n        new FieldInfo(\"数量\", FieldType.INT32)\n    );\n\n    // 创建点数据集\n    PointDataset dataset = dataSource.createPointDataset(\"MyPoints\", fields);\n\n    // 添加要素\n    PointFeature feature = dataset.createFeature();\n    feature.setGeometry(new GaiaPoint(116.404, 39.915)); // 北京坐标\n    feature.setString(\"名称\", \"天安门\");\n    feature.setInt32(\"数量\", 100);\n    dataset.add(feature);\n}\n```\n\n#### 流式读取（大数据集）\n\n```java\nimport com.supermap.udbx.streaming.AutoCloseableStream;\n\ntry (UdbxDataSource dataSource = UdbxDataSource.open(\"large_dataset.udbx\")) {\n    PointDataset dataset = (PointDataset) dataSource.getDataset(\"BigData\");\n\n    // 流式读取，内存占用恒定\n    try (AutoCloseableStream\u003cPointFeature\u003e stream = dataset.streamFeatures()) {\n        stream.getStream()\n            .filter(f -\u003e f.geometry().getX() \u003e 116.0)\n            .limit(1000)\n            .forEach(feature -\u003e process(feature));\n    } // 自动关闭资源\n}\n```\n\n#### 分页查询\n\n```java\n// 分页读取点数据\ntry (UdbxDataSource dataSource = UdbxDataSource.open(\"data.udbx\")) {\n    PointDataset dataset = (PointDataset) dataSource.getDataset(\"Points\");\n\n    int pageSize = 1000;\n    int totalCount = dataset.getCount();\n    int pageCount = (totalCount + pageSize - 1) / pageSize;\n\n    for (int page = 0; page \u003c pageCount; page++) {\n        List\u003cPointFeature\u003e features = dataset.getFeatures(page * pageSize, pageSize);\n        System.out.println(\"Page \" + page + \": \" + features.size() + \" features\");\n    }\n}\n```\n\n#### 批量写入\n\n```java\nimport com.supermap.udbx.dataset.PointFeature;\n\n// 批量写入性能提升 10-50 倍\ntry (UdbxDataSource dataSource = UdbxDataSource.create(\"output.udbx\")) {\n    PointDataset dataset = (PointDataset) dataSource.getDataset(\"Points\");\n\n    List\u003cPointFeature\u003e batch = new ArrayList\u003c\u003e();\n    for (int i = 0; i \u003c 10000; i++) {\n        PointFeature feature = dataset.createFeature();\n        feature.setGeometry(new GaiaPoint(116.0 + i * 0.0001, 39.0 + i * 0.0001));\n        batch.add(feature);\n    }\n\n    // 单次事务批量写入\n    dataset.addFeaturesBatch(batch);\n}\n```\n\n## 项目结构\n\n```\nudbx4j/\n├── README.md                          # 项目介绍和快速开始\n├── CHANGELOG.md                       # 版本变更记录\n├── CONTRIBUTING.md                     # 贡献指南\n├── CLAUDE.md                          # 项目开发文档\n├── LICENSE                            # MIT 许可证\n├── pom.xml                            # Maven 构建配置\n├── Makefile                           # 构建脚本（预设 JAVA_HOME）\n│\n├── docs/                              # 文档目录\n│   └── superpowers/                   # 开发计划和规格文档\n│\n├── rules/                             # 开发规范\n│   ├── java-coding-style.md          # Java 编码规范\n│   ├── java-testing.md               # 测试规范\n│   ├── java-patterns.md               # 设计模式\n│   └── spec-coding.md                # Spec 测试流程\n│\n├── .github/                           # GitHub 配置\n│   ├── ISSUE_TEMPLATE/                # Issue 模板\n│   │   ├── bug_report.md              # Bug 报告模板\n│   │   └── feature_request.md         # 功能请求模板\n│   └── PULL_REQUEST_TEMPLATE.md       # PR 模板\n│\n└── src/\n    ├── main/java/com/supermap/udbx/\n    │   ├── UdbxDataSource.java         # 入口类：open()/create()\n    │   ├── pool/                       # 对象池\n    │   │   └── GeometryFactoryPool.java # GeometryFactory 对象池\n    │   ├── core/                       # 核心枚举与元信息\n    │   │   ├── DatasetType.java        # 数据集类型枚举\n    │   │   ├── GeometryType.java       # 几何类型枚举\n    │   │   ├── FieldType.java          # 字段类型枚举\n    │   │   ├── FieldInfo.java          # 字段元信息\n    │   │   └── DatasetInfo.java        # 数据集元信息\n    │   ├── dataset/                    # 数据集实现\n    │   │   ├── Dataset.java            # 抽象基类\n    │   │   ├── TabularDataset.java     # 纯属性表\n    │   │   ├── VectorDataset.java      # 矢量基类\n    │   │   ├── PointDataset.java       # 点数据集\n    │   │   ├── LineDataset.java        # 线数据集\n    │   │   ├── RegionDataset.java      # 面数据集\n    │   │   ├── PointZDataset.java      # 三维点数据集\n    │   │   ├── LineZDataset.java       # 三维线数据集\n    │   │   ├── RegionZDataset.java     # 三维面数据集\n    │   │   └── CadDataset.java         # CAD 数据集\n    │   ├── geometry/                   # 几何对象\n    │   │   ├── gaia/                   # SpatiaLite GAIA 格式\n    │   │   │   ├── GaiaGeometryReader.java\n    │   │   │   ├── GaiaGeometryWriter.java\n    │   │   │   └── ...\n    │   │   └── cad/                    # SuperMap CAD 格式\n    │   │       ├── CadGeometryReader.java\n    │   │       ├── CadGeometryWriter.java\n    │   │       ├── CadGeometry.java\n    │   │       └── ...\n    │   ├── streaming/                  # 流式处理\n    │   │   ├── AutoCloseableStream.java # 资源管理\n    │   │   └── FeatureSpliterator.java  # 懒加载迭代器\n    │   ├── pool/                       # 连接池\n    │   │   └── UdbxDataSourcePool.java  # HikariCP 连接池\n    │   ├── metrics/                    # 性能监控（可选）\n    │   │   └── PerformanceMetrics.java  # Micrometer 集成\n    │   ├── system/                     # 系统表 DAO\n    │   │   ├── SmRegisterDao.java\n    │   │   ├── SmFieldInfoDao.java\n    │   │   └── SmDataSourceInfoDao.java\n    │   └── viewer/                     # 可视化工具（实验性）\n    │\n    └── test/java/com/supermap/udbx/\n        ├── spec/                       # Spec 测试（基于白皮书）\n        │   └── *SpecTest.java           # 21 个 Spec 测试类\n        ├── integration/                # 集成测试\n        │   └── *Test.java               # 14 个集成测试类\n        └── benchmark/                  # JMH 性能基准测试\n            ├── BaselineBenchmark.java   # 基线测试\n            ├── GeometryDecodeBenchmark.java\n            ├── StreamingReadBenchmark.java\n            ├── ConcurrentReadBenchmark.java\n            └── ManualConcurrentTest.java\n```\n\n## 构建与测试\n\n### 使用 Makefile（推荐）\n\n```bash\nmake test            # 运行 Spec 测试\nmake test-all        # 运行所有测试 + 覆盖率报告\nmake run-test CLASS=GaiaPointSpecTest  # 运行单个测试类\nmake coverage        # 打开覆盖率报告\n```\n\n### 使用 Maven\n\n```bash\nmvn compile\nmvn test\nmvn verify           # 含集成测试 + 覆盖率检查\nmvn package -DskipTests\n```\n\n## 技术架构\n\n### UDBX 格式要点\n\n| 概念 | 说明 |\n|------|------|\n| 文件格式 | SQLite 数据库（`.udbx` 后缀） |\n| 字节序 | Little-Endian |\n| 矢量几何 | GAIA Geometry（SpatiaLite 标准格式） |\n| CAD 几何 | SuperMap GeoHeader 自定义格式 |\n| 系统表 | SmRegister、SmFieldInfo、SmDataSourceInfo |\n\n### Geometry 二进制格式\n\n**GAIA（SpatiaLite）：**\n```\n0x00 | byteOrder(1) | srid(int32) | MBR(4×double) | 0x7c | geoType(int32) | ...coords... | 0xFE\n```\n\n**CAD（SuperMap GeoHeader）：**\n```\ngeoType(int32) | styleSize(int32) | Style(...) | ...geometry data...\n```\n\n## 开发规范\n\n- **测试驱动开发**（TDD）- 先写测试，再写实现\n- **不可变优先** - 元信息类使用 Java Record\n- **测试覆盖率** ≥ 80%\n- **提交格式** - `feat/fix/test/refactor/docs/chore: 描述`\n\n详细规范见 `rules/` 目录。\n\n## 参考文档\n\n- **白皮书**：`UDBX开放数据格式白皮书(V1.0).pdf`\n- **变更日志**：`CHANGELOG.md`\n- **开发规范**：`rules/` 目录\n\n## 许可证\n\n[MIT License](LICENSE)\n\n## 作者\n\nzhyt1985\n\n## 相关链接\n\n- [UDBX 格式白皮书](UDBX开放数据格式白皮书(V1.0).pdf)\n- [SuperMap 官方文档](https://www.supermap.com/)\n- [SpatiaLite 文档](https://www.gaia-gis.it/gaia-sins/)\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fzhyt1985%2Fudbx4j","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fzhyt1985%2Fudbx4j","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fzhyt1985%2Fudbx4j/lists"}