From 537077279adf4e33499a8e69849d434f7388586f Mon Sep 17 00:00:00 2001 From: lion Date: Sat, 13 Sep 2025 00:21:25 +0800 Subject: [PATCH] Java IPv6 support is ready --- binding/java/ReadMe.md | 93 ++++++++++++++++----- binding/java/pom.xml | 32 ++++--- binding/java/src/main/java/xdb/Version.java | 5 -- 3 files changed, 93 insertions(+), 37 deletions(-) delete mode 100644 binding/java/src/main/java/xdb/Version.java diff --git a/binding/java/ReadMe.md b/binding/java/ReadMe.md index 8f8e7fc..3556643 100644 --- a/binding/java/ReadMe.md +++ b/binding/java/ReadMe.md @@ -7,10 +7,42 @@ org.lionsoul ip2region - 2.7.0 + 3.1.0 ``` +### 关于 IPv4 和 IPv6 +该 xdb 查询客户端实现同时支持对 IPv4 和 IPv6 的查询，使用方式如下： +```java +import org.lionsoul.ip2region.xdb.Version; + +// 如果是 IPv4: 设置 xdb 路径为 v4 的 xdb 文件，IP版本指定为 Version.IPv4 +final String dbPath = "../../data/ip2region_v4.xdb"; // 或者你的 ipv4 xdb 的路径 +final Version version = Version.IPv4; + +// 如果是 IPv6: 设置 xdb 路径为 v6 的 xdb 文件，IP版本指定为 Version.IPv6 +final String dbPath = "../../data/ip2region_v6.xdb"; // 或者你的 ipv6 xdb 路径 +final Version version = Version.IPv6; + +// dbPath 指定的 xdb 的 IP 版本必须和 version 指定的一致，不然查询执行的时候会报错 +// 备注：以下演示直接使用 dbPath 和 version 变量 +``` + +### 文件验证 +建议您主动去验证 xdb 文件的适用性，因为后期的一些新功能可能会导致目前的 Searcher 版本无法适用你使用的 xdb 文件，验证可以避免运行过程中的一些不可预测的错误。 你不需要每次都去验证，例如在服务启动的时候，或者手动调用命令验证确认版本匹配即可，不要在每次创建的 Searcher 的时候运行验证，这样会影响查询的响应速度，尤其是高并发的使用场景。 +```java +try { + Searcher.verifyFromFile(dbPath); +} catch (Exception e) { + // 适用性验证失败！！！ + // 当前查询客户端实现不适用于 dbPath 指定的 xdb 文件的查询. + // 应该停止启动服务，使用合适的 xdb 文件或者升级到适合 dbPath 的 Searcher 实现。 + return; +} + +// 有验证通过，前使用的 Searcher 可以安全的用于对 dbPath 指向的 xdb 的查询操作 +``` + ### 完全基于文件的查询 ```java @@ -20,19 +52,19 @@ import java.util.concurrent.TimeUnit; public class SearcherTest { public static void main(String[] args) { - // 1、创建 searcher 对象 - String dbPath = "ip2region.xdb file path"; + // 1、使用上述的 version 和 dbPath 创建 searcher 对象 Searcher searcher = null; try { - searcher = Searcher.newWithFileOnly(dbPath); + searcher = Searcher.newWithFileOnly(version, dbPath); } catch (IOException e) { System.out.printf("failed to create searcher with `%s`: %s\n", dbPath, e); return; } - // 2、查询 + // 2、查询，IPv4 或者 IPv6 的地址都支持 try { String ip = "1.2.3.4"; + // ip = "2001:4:112:ffff:ffff:ffff:ffff:ffff"; // IPv6 long sTime = System.nanoTime(); String region = searcher.search(ip); long cost = TimeUnit.NANOSECONDS.toMicros((long) (System.nanoTime() - sTime)); @@ -59,7 +91,7 @@ import java.util.concurrent.TimeUnit; public class SearcherTest { public static void main(String[] args) { - String dbPath = "ip2region.xdb file path"; + // 备注：version 和 dbPath 来源，请看上面的版本描述 // 1、从 dbPath 中预先加载 VectorIndex 缓存，并且把这个得到的数据作为全局变量，后续反复使用。 byte[] vIndex; @@ -73,15 +105,16 @@ public class SearcherTest { // 2、使用全局的 vIndex 创建带 VectorIndex 缓存的查询对象。 Searcher searcher; try { - searcher = Searcher.newWithVectorIndex(dbPath, vIndex); + searcher = Searcher.newWithVectorIndex(version, dbPath, vIndex); } catch (Exception e) { System.out.printf("failed to create vectorIndex cached searcher with `%s`: %s\n", dbPath, e); return; } - // 3、查询 + // 3、查询，IPv4 或者 IPv6 地址都支持 try { String ip = "1.2.3.4"; + // ip = "2001:4:112:ffff:ffff:ffff:ffff:ffff"; // IPv6 long sTime = System.nanoTime(); String region = searcher.search(ip); long cost = TimeUnit.NANOSECONDS.toMicros((long) (System.nanoTime() - sTime)); @@ -108,10 +141,11 @@ import java.util.concurrent.TimeUnit; public class SearcherTest { public static void main(String[] args) { - String dbPath = "ip2region.xdb file path"; + // 备注：version 和 dbPath 来源，请看上面的版本描述 // 1、从 dbPath 加载整个 xdb 到内存。 - byte[] cBuff; + // 从这个 release 版本开始，xdb 的 buffer 使用 LongByteArray 来存储，避免 xdb 文件过大的时候 int 类型的溢出 + LongByteArray cBuff; try { cBuff = Searcher.loadContentFromFile(dbPath); } catch (Exception e) { @@ -122,15 +156,16 @@ public class SearcherTest { // 2、使用上述的 cBuff 创建一个完全基于内存的查询对象。 Searcher searcher; try { - searcher = Searcher.newWithBuffer(cBuff); + searcher = Searcher.newWithBuffer(version, cBuff); } catch (Exception e) { System.out.printf("failed to create content cached searcher: %s\n", e); return; } - // 3、查询 + // 3、查询，IPv4 和 IPv6 都支持 try { String ip = "1.2.3.4"; + // ip = "2001:4:112:ffff:ffff:ffff:ffff:ffff"; // IPv6 long sTime = System.nanoTime(); String region = searcher.search(ip); long cost = TimeUnit.NANOSECONDS.toMicros((long) (System.nanoTime() - sTime)); @@ -165,21 +200,31 @@ mvn compile package 可以通过 `java -jar ip2region-{version}.jar search` 命令来测试查询： ```bash -➜ java git:(v2.0_xdb) ✗ java -jar target/ip2region-2.6.0.jar search +➜ java git:(fr_java_ipv6) ✗ java -jar target/ip2region-3.1.0.jar search java -jar ip2region-{version}.jar search [command options] options: --db string ip2region binary xdb file path --cache-policy string cache policy: file/vectorIndex/content ``` -例如：使用默认的 data/ip2region.xdb 文件进行查询测试： +例如：使用默认的 data/ip2region_v4.xdb 文件进行 IPv4 的查询测试： ```bash -➜ java git:(v2.0_xdb) ✗ java -jar target/ip2region-2.6.0.jar search --db=../../data/ip2region.xdb -ip2region xdb searcher test program, cachePolicy: vectorIndex +➜ java git:(fr_java_ipv6) ✗ java -jar target/ip2region-3.1.0.jar search --db=../../data/ip2region_v4.xdb +ip2region xdb searcher test program +source xdb: ../../data/ip2region_v4.xdb (IPv4, vectorIndex) type 'quit' to exit ip2region>> 1.2.3.4 -{region: 美国|0|华盛顿|0|谷歌, ioCount: 7, took: 82 μs} -ip2region>> +{region: 美国|华盛顿|0|谷歌, ioCount: 7, took: 82 μs} +``` + +例如：使用默认的 data/ip2region_v6.xdb 文件进行 IPv6 的查询测试： +```bash +➜ java git:(fr_java_ipv6) ✗ java -jar target/ip2region-3.1.0.jar search --db=../../data/ip2region_v6.xdb +ip2region xdb searcher test program +source xdb: ../../data/ip2region_v6.xdb (IPv6, vectorIndex) +type 'quit' to exit +ip2region>> 240e:3b7:3272:d8d0:db09:c067:8d59:539e +{region: 中国|广东省|深圳市|家庭宽带, ioCount: 14, took: 424 μs} ``` 输入 ip 即可进行查询测试，也可以分别设置 `cache-policy` 为 file/vectorIndex/content 来测试三种不同缓存实现的查询效果。 @@ -189,7 +234,7 @@ ip2region>> 可以通过 `java -jar ip2region-{version}.jar bench` 命令来进行 bench 测试，一方面确保 `xdb` 文件没有错误，一方面可以评估查询性能： ```bash -➜ java git:(v2.0_xdb) ✗ java -jar target/ip2region-2.6.0.jar bench +➜ java git:(fr_java_ipv6) ✗ java -jar target/ip2region-3.1.0.jar bench java -jar ip2region-{version}.jar bench [command options] options: --db string ip2region binary xdb file path @@ -197,10 +242,14 @@ options: --cache-policy string cache policy: file/vectorIndex/content ``` -例如：通过默认的 data/ip2region.xdb 和 data/ip.merge.txt 文件进行 bench 测试： +例如：通过默认的 data/ip2region_v4.xdb 和 data/ipv4_source.txt 文件进行 IPv4 的 bench 测试： ```bash -➜ java git:(v2.0_xdb) ✗ java -jar target/ip2region-2.6.0.jar bench --db=../../data/ip2region.xdb --src=../../data/ip.merge.txt -Bench finished, {cachePolicy: vectorIndex, total: 3417955, took: 8s, cost: 2 μs/op} +java -jar target/ip2region-3.1.0.jar bench --db=../../data/ip2region_v4.xdb --src=../../data/ipv4_source.txt +``` + +例如：通过默认的 data/ip2region_v6.xdb 和 data/ipv6_source.txt 文件进行 IPv6 的 bench 测试： +```bash +java -jar target/ip2region-3.1.0.jar bench --db=../../data/ip2region_v6.xdb --src=../../data/ipv6_source.txt ``` 可以通过分别设置 `cache-policy` 为 file/vectorIndex/content 来测试三种不同缓存实现的效果。 diff --git a/binding/java/pom.xml b/binding/java/pom.xml index 9b4a32d..dea3fc7 100644 --- a/binding/java/pom.xml +++ b/binding/java/pom.xml @@ -33,6 +33,17 @@ + + + lionsoul + https://oss.sonatype.org/content/repositories/snapshots/ + + + lionsoul + https://oss.sonatype.org/service/local/staging/deploy/maven2/ + + + https://github.com/lionsoul2014/ip2region/issues Github issues @@ -174,18 +185,19 @@ + + + org.sonatype.central + central-publishing-maven-plugin + 0.7.0 + true + + lionsoul + true + + - - - oss-parent - https://oss.sonatype.org/content/repositories/snapshots/ - - - oss-parent - https://oss.sonatype.org/service/local/staging/deploy/maven2/ - - diff --git a/binding/java/src/main/java/xdb/Version.java b/binding/java/src/main/java/xdb/Version.java deleted file mode 100644 index 986f689..0000000 --- a/binding/java/src/main/java/xdb/Version.java +++ /dev/null @@ -1,5 +0,0 @@ -package xdb; - -public class Version { - -}