Java IPv6 support is ready

binding/java/ReadMe.md

@@ -7,10 +7,42 @@
 <dependency>
     <groupId>org.lionsoul</groupId>
     <artifactId>ip2region</artifactId>
-    <version>2.7.0</version>
+    <version>3.1.0</version>
 </dependency>
 ```
 
+### 关于 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 对象
+        // 1、使用上述的 version 和 dbPath 创建 searcher 对象
-        String dbPath = "ip2region.xdb file path";
         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
+➜  java git:(fr_java_ipv6) ✗ java -jar target/ip2region-3.1.0.jar search --db=../../data/ip2region_v4.xdb
-ip2region xdb searcher test program, cachePolicy: vectorIndex
+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}
+{region: 美国|华盛顿|0|谷歌, ioCount: 7, took: 82 μs}
-ip2region>>
+```
+
+例如：使用默认的 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
+java -jar target/ip2region-3.1.0.jar bench --db=../../data/ip2region_v4.xdb --src=../../data/ipv4_source.txt
-Bench finished, {cachePolicy: vectorIndex, total: 3417955, took: 8s, cost: 2 μs/op}
+```
+
+例如：通过默认的 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 来测试三种不同缓存实现的效果。

binding/java/pom.xml

@@ -33,6 +33,17 @@
         </developer>
     </developers>
 
+    <distributionManagement>
+		<snapshotRepository>
+			<id>lionsoul</id>
+			<url>https://oss.sonatype.org/content/repositories/snapshots/</url>
+		</snapshotRepository>
+		<repository>
+			<id>lionsoul</id>
+			<url>https://oss.sonatype.org/service/local/staging/deploy/maven2/</url>
+		</repository>
+	</distributionManagement>
+
     <issueManagement>
         <url>https://github.com/lionsoul2014/ip2region/issues</url>
         <system>Github issues</system>
@@ -174,18 +185,19 @@
                             </execution>
                         </executions>
                     </plugin>
+                    <!--use the Central Portal: https://central.sonatype.org/publish/publish-portal-maven/ instead-->
+                    <plugin>
+                        <groupId>org.sonatype.central</groupId>
+                        <artifactId>central-publishing-maven-plugin</artifactId>
+                        <version>0.7.0</version>
+                        <extensions>true</extensions>
+                        <configuration>
+                            <publishingServerId>lionsoul</publishingServerId>
+                            <autoPublish>true</autoPublish>
+                        </configuration>
+                    </plugin>
                 </plugins>
             </build>
-            <distributionManagement>
-                <snapshotRepository>
-                    <id>oss-parent</id>
-                    <url>https://oss.sonatype.org/content/repositories/snapshots/</url>
-                </snapshotRepository>
-                <repository>
-                    <id>oss-parent</id>
-                    <url>https://oss.sonatype.org/service/local/staging/deploy/maven2/</url>
-                </repository>
-            </distributionManagement>
         </profile>
     </profiles>
 

binding/java/src/main/java/xdb/Version.java

@@ -1,5 +0,0 @@
-package xdb;
-
-public class Version {
-
-}