全部产品

SDK(Java版本)说明

环境准备

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

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

下载SDK

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

  • 离线数据库(数据文件)

  • 授权证书文件(license)

  • SDK(Java语言)

注意

续费、升级商品套餐一定要同步更新license证书文件,如果license证书过期,则SDK会直接不可用。

安装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.68</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. 在使用时需要显式的捕获异常:LicenseExceptionFastIPGeoException,根据异常的编码做相应处理,具体异常列表参考下文附件。

调用实例

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("221.206.131.10");
            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 字段含义:

字段

含义

示例值

country

国家(或地区)中文

中国

country_code

国家(或地区)两位字母

CN

country_en

国家(或地区)英文

China

province

省(二级)中文

黑龙江省

province_code

省(二级)数字代码

230000

province_en

省(二级)英文/拼音

Heilongjiang

city

市(三级)中文

牡丹江市

city_code

市(三级)数字代码

231000

city_en

市(三级)英文/拼音

Mudanjiang

county

区(四级)中文

阳明区

county_code

区(四级)数字代码

231003

isp

运营商

中国联通

isp_code

运营商数字代码

100026

routes

运营商线路

中国联通

longitude

经度

129.634645

latitude

纬度

44.596328