SDK（Java版本）说明

环境准备

目前该产品在做内部调整，不支持新购、续费、升级等操作，订单有效期内可继续正常使用，本文档仅供订单期内用户参考。请留意服务到期时间，做好备选方案，感谢您的支持理解。

• 环境要求使用Java 1.8及以上版本。

• 查看Java版本执行命令 java -version。

下载SDK

如已购买IP地理位置库（离线版）商品，可进入实例详情，下载以下三个文件

• 离线数据库（数据文件）

• 授权证书文件（license）

• SDK（Java语言）

安装SDK

方式一：在 IntelliJ IDEA 项目中导入JAR包

1. 下载SDK（Java语言）JAR。

2. 将SDK JAR文件拷贝到您的项目中。

3. 在 IntelliJ IDEA 中选择您的工程，选择File > Project Structure > Modules > Dependencies > + > JARs or directories。

4. 选中您在第2步拷贝的SDK JAR文件，导入到External Libraries中。

注意：

1. SDK JAR包未发布到线上仓库，仅支持直接引入使用

2. SDK JAR包内仅包含SDK 的开发代码，未包含需要的其他第三方JAR包代码，在使用时需要手动加入相应的第三方依赖如下（使用时可根据实际情况做调整，其中commons-codec的版本必须为1.11或以上版本）：

        <dependency>
            <groupId>org.apache.commons</groupId> 
            <artifactId>commons-lang3</artifactId>
            <version>3.10</version>
        </dependency>
       <!--1.0.4版本已经移除-->
        <dependency>
            <groupId>com.google.guava</groupId>
            <artifactId>guava</artifactId>
            <version>28.2-jre</version>
        </dependency>
        <dependency>
            <groupId>commons-codec</groupId>
            <artifactId>commons-codec</artifactId>
            <version>1.11</version>
        </dependency>
        <dependency>
            <groupId>com.alibaba</groupId>
            <artifactId>fastjson</artifactId>
            <version>1.2.83</version>
        </dependency>
        <dependency>
            <groupId>org.slf4j</groupId>
            <artifactId>slf4j-api</artifactId>
            <version>1.7.26</version>
        </dependency>

快速入门

重要类介绍：

• com.alibaba.sec.domain.FastGeoConf目前有如下字段，分别是： 

  • properties：用户自定加载的字段，不填写则加载所有字段，在使用时可选择性加载其中需要的属性，这样能显著降低内存的占用空间。具体字段含义参考下文附件

  • licenseFilePath：读取授权文件存放路径

  • dataFilePath：读取离线数据文件存放路径

  1.0.4及以上版本支持通过非文件路径的方式加载离线许可证和离线数据

  • licenseBytes：读取授权文件字节数组

  • dataBytes：读取离线数据文件字节数组

  • licenseInput：读取授权文件字节流

  • dataInput：读取离线数据文件字节流

  • filterEmptyValue：用于控制查询结果是否返回内容为空的字段（ 默认不启用此功能）

  重要

  properties与filterEmptyValue()区别，properties设置返回的字段，无论是否为空值，filterEmptyValue启用后字段为空值时，不在结果集中显示该空值字段。

• com.alibaba.sec.client.FastIPGeoClient是用户使用SDK的客户端对象，需要通过构造函数实例化

使用方法：

1. 将加载字段、license文件路径、数据文件路径封装成一个 com.alibaba.sec.domain.FastGeoConf

2. 通过静态方法获取单例（能保证在数据文件和license文件路径一样的情况下的实例只会在内存里面生成一份）com.alibaba.sec.client.FastIPGeoClient.getSingleton(com.alibaba.sec.domain.FastGeoConf）

3. 通过 FastIPGeoClient.search(String ip)方法来检索IP的地址位置等相关信息，返回的数据为json格式，键值对都是 FastGeoConf.properties里指定的字段（若未指定，则加载所有字段。在明确实际要用到字段的情况下，生产环境建议固定字段，避免因为新数据字段增加导致内存占用增加），值不在时用空字符串 "" 代替。

4. 在使用时需要显式的捕获异常：LicenseException，FastIPGeoException，根据异常的编码做相应处理，具体异常列表参考下文附件。

调用实例：

import com.alibaba.sec.client.FastIPGeoClient;
import com.alibaba.sec.domain.FastGeoConf;
import com.alibaba.sec.exception.FastIPGeoException;
import com.alibaba.sec.license.exception.LicenseException;

import java.util.Arrays;
import java.util.HashSet;

public class GeoClientTest {
    private static final String DATA_FILE_PATH = "${path}/ipv4.dex";
    private static final String LICENSE_FILE_PATH = "${path}/license.lic";

    public static void main(String[] args) throws Exception {
        FastGeoConf geoConf = new FastGeoConf();
        geoConf.setDataFilePath(DATA_FILE_PATH);
        geoConf.setLicenseFilePath(LICENSE_FILE_PATH);
        //指定sdk返回字段，不指定字段默认返回全部，可节省内存开销
        HashSet<String> set = new HashSet<>(Arrays.asList(
                "country", "province", "province_code",
                "city", "city_code", "county", "county_code",
                "isp", "isp_code", "routes",
                "longitude", "latitude"
        ));
        geoConf.setProperties(set);
        geoConf.filterEmptyValue();  //空值字段，不在结果中返回
        //通过构造方法初始化（非单例，旧版SDK中使用）
        //FastIPGeoClient fastIpGeoClient = new FastIPGeoClient(geoConf);
        //通过静态方法（单例）, 推荐使用该方法，sdk需升级到最新版本
        FastIPGeoClient fastIpGeoClient = FastIPGeoClient.getSingleton(geoConf);
        String result;
        try {
            result = fastIpGeoClient.search("47.100.XX.XX");
            System.out.println(result);
        } catch (LicenseException e) {
            e.printStackTrace();
        } catch (FastIPGeoException e) {
            e.printStackTrace();
        }
    }
}

LicenseException错误码： 

UNKNOWN(500, "未知异常"),
ALREADY_EXIST(100, "文件已经存在"),
NOT_ABS_PATH(101, "不是绝对路径"),
DIR_NOT_EXIST(102, "文件夹不存在"),  
LICENSE_INVALID(501, "证书异常"),   //证书不合法
SYSTEM_TIME_ERR(502, "系统时间异常"), 
LICENSE_WILL_EXPIRE(503, "证书即将过期，请提前申请，过期后将无法使用"),
LICENSE_EXPIRE(504, "证书过期, 请重新申请"), 
LICENSE_DELAY_ERR(505, "证书延期异常"),
LICENCE_ERR_ECHO(506, "非法回应"),  //证书不合法，证书内部校验返回值失败
LICENSE_ERR_RATELIMIT(507, "超过购买的qps阈值");

FastIPGeoException错误编码： 

UNKNOWN(1500, "未知异常"), 
INVALID_DAT(1501, "文件内容不合法"),
NOT_MATCH(1503, "文件不匹配"); //用户的license类型和文件类型不匹配

附件

properties字段含义：