关山难越,谁悲失路之人;萍水相逢,尽是他乡之客。
百度360必应搜狗淘宝本站头条
当前位置:网站首页 > 编程教程 > 技术文章 > 正文

java与es8实战之三:Java API Client有关的知识点串讲

guanshanw 2023-09-26 12:19 20 浏览 0 评论

欢迎访问我的GitHub

这里分类和汇总了欣宸的全部原创(含配套源码):https://github.com/zq2599/blog_demos

本篇概览

  • 本篇是《java与es8实战》系列的第三篇,将一些重要的知识点在这里梳理清楚,为后面的实践奠定基础
  • 一共有七个与Java API Client有关的重要知识点
  1. 关于namespace:每个feature都有自己的package
  2. 命名规则:介绍Java API Client中对象的方法的命名规则
  3. 集合不为空:Java API Client中对象返回的集合,到底要不要做判空?
  4. variant type:繁多的场景和对象,可以通过variant type进行简化
  5. 通过JSON字符串创建API对象:通过builder创建复杂的对象,会导致代码也很复杂,这里提供了一种更简单的方式
  6. 关于异常:有哪些异常类型,各自会在什么场景抛出
  • 接下来逐个去看

命名空间

  • 在REST API文档中,数量众多API是按照特性(feature)来分组的,如下图
  • 在ES的Java库Java API Client中,上图中的各种feature被称为namespace
  • 在ES的Java库Java API Client中,与REST API对应的的类和接口都在统一的包名co.elastic.clients.elasticsearch之下,然后再通过下一级package进行分类,这个分类与上图的feature相对应,例如索引相关的,在REST API中的feature是Index APIs,那么在Java API Client中,完整的package就是co.elastic.clients.elasticsearch.indices,这里面有索引操作所需的请求、响应、服务等各种类,如下图
  • 每一个namespace(也就是REST API中的feature),都有自己的client,例如索引相关的操作都有索引专用的client类负责,实例代码如下,client.indices()返回的是ElasticsearchIndicesClient对象,这是索引操作专用的实例
ElasticsearchClient client = ...
client.indices().create(c -> c.index("products"));
  • 展开上述代码的indices()方法,看看其内部实现,如下所示,每次调用indices方法,都会创建一个ElasticsearchIndicesClient对象,对于其他namespace,例如ingest、license亦是如此,都会创建新的实例
  • 看到这里,经验丰富的您应该发现了问题:在大量并发频繁执行各种namespace操作时,会创建大量client对象,这样会影响系统性能吗?
  • es预判了咱们的预判,如下图,官方说这是轻量级对象(very lightweight),所以,理论上可以放心创建,不必担心其对系统造成的压力
  • 尽管每个namespace都有自己的client,但也有例外,就是searchdocument,它们的代码不在search或者document这样的package下面,而是在core下面,而且可以通过ElasticsearchClient来操作,如下图

命名规则

  • Java API Client是个库,也是个java工程,工程里有自己的内部设计,这算是Java API Client自己的框架部分(framework),另一部分就是专门为使用者提供的大量API
  • 对于API部分,方法的命名规则都是驼峰式(camelCaseNaming),例如查询请求ElasticsearchClient.search()、查询结果的最高评分SearchResponse.maxScore()
  • 对于framework部分,方法命令是下划线作为前缀,例如获取查询类型Query._kind()

五种对象

  • 官方将Java API Client中的对象分为五种
  1. Object mapper:序列化和反序列化工具,这类对象是线程安全、无状态的,通常是单例模式存在于应用中,常在启动时创建
  2. Transport:传输工具,此类对象线程安全,借助底层HTTP客户端工具维护着网络资源,例如负责与es服务端建立连接,在需要关闭连接的时候负责释放所有底层网络资源
  3. Clients:实际处理每个namespace的客户端类,例如负责索引的是ElasticsearchIndicesClient,它们的特点:不可变对象、无状态、线程安全、轻量级(类似于普通bean的资源开销),之所以轻量级,是因为其结构实际上就是对一些API endpoint的包装
  4. Builders:这个在《开篇》中已经详细说明了,就不多赘述,用过builder的您应该会发现,builder当然是可变类,至于是否线程安全似乎和builder没什么关系,因为每创建一次实例时,都要创建一个builder实例,而且,一旦执行完build方法后,这个builder实例就没用了
  5. Requests & other API objects:和请求相关的对象,都是不可变的、线程安全的

集合不会为空

  • 对于单值属性,我们在使用的时候判断是否为空是个常规操作,这样是为了避免直接使用时可能出现的空指针异常
  • 而对于集合,Java API Client 已经确保了API返回的集合非空,我们只需要检查集合中是否有内容,而不必担心集合自身是否等于null的问题,官方给出的演示代码如下
NodeStatistics stats = NodeStatistics.of(b -> b
    .total(1)
    .failed(0)
    .successful(1)
);

// The `failures` list was not provided.
// - it's not null
assertNotNull(stats.failures());
  • 出于好奇,去看看NodeStatistics源码,构造方法如下,failures来自ApiTypeHelper.unmodifiable
	private NodeStatistics(Builder builder) {

		this.failures = ApiTypeHelper.unmodifiable(builder.failures);
		this.total = ApiTypeHelper.requireNonNull(builder.total, this, "total");
		this.successful = ApiTypeHelper.requireNonNull(builder.successful, this, "successful");
		this.failed = ApiTypeHelper.requireNonNull(builder.failed, this, "failed");

	}
  • 再去看ApiTypeHelper.unmodifiable,如下,已确保了failures不为空
    public static <T> List<T> unmodifiable(@Nullable List<T> list) {
        if (list == null) {
            return undefinedList();
        }
        if (list == UNDEFINED_LIST) {
            return list;
        }
        return Collections.unmodifiableList(list);
    }
  • 因此,再使用API返回的集合时,集合对象自身始终非空

variant type

  • variant type是Java API Client中常见的对象类型,这个该如何翻译呢,个人觉得是不确定类型的意思,不专业,期待您的指正
  • 举个例子,查询是最常见的操作了,下面列举三种查询,第一个是普通的不分词查询
{
  "query":{"term":{ "interests":"youyong"}}
}
  • 分词查询
{
  "query":{"match":{"interests": "changge"}}
}
  • 以及复杂的全文本查询
{
  "query": {
    "intervals" : {
      "my_text" : {
        "all_of" : {
          "ordered" : false,
          "intervals" : [
            {
              "match" : {
                "query" : "my favorite books",
                "max_gaps" : 0,
                "ordered" : true
              }
            },
            {
              "any_of" : {
                "intervals" : [
                  { "match" : { "query" : "java tutorials" } },
                  { "match" : { "query" : "cold porridge" } }
                ]
              }
            }
          ]
        }
      }
    }
  }
}
  • 对查询来说,在Java API Client中,有个Query对象代表了查询行为,这就是个典型的variant type,至于对应的真实query是哪种,可以在builder时指定,例如下面指定了类型是term
Query query = new Query.Builder()
    .term(t -> t                          
        .field("name")                    
        .value(v -> v.stringValue("foo"))
    )
    .build();  
  • 上述query有对应的方法返回其值,例如上面的value可以这样获取
query.term().value().stringValue()
  • 如果在设置的时候,并非用stringValue方法,而是其他类型,那么上面的代码在获取String类型的值时会抛出IllegalStateException异常
  • variant type配有对应的isXXX方法返回其是否属于某个类型,例如Query就有query.isTerm()表示自己是不是term查询
  • 还可以用_kind()返回当前类型,下面是示例
switch(query._kind()) { 
    case Term:
        doSomething(query.term());
        break;
    case Intervals:
        doSomething(query.intervals());
        break;
    default:
        doSomething(query._kind(), query._get()); 
}
  • 可见有了variant type,在 queries, aggregations, field mappings, analyzers等多种场景下,我们不需要使用各种具体的类,只要用最抽象的variant type,再配置builder pattern即可,这对服务提供者和服务消费者都是有效的简化

通过JSON字符串创建API对象

  • 下面是kibana页面上,用JSON创建索引的操作截图
  • 如果要在代码中实现上述效果,该如何做呢?一层一层的创建mapping、proterties、field对象?那可真是麻烦…
  • 在Java API Client中,可以通过json字符串反序列化为API对象,首先,将上述JSON放入名为some-index.json的文件中,然后执行以下代码,即可用json文件创建req对象
InputStream input = this.getClass()
    .getResourceAsStream("some-index.json"); 

CreateIndexRequest req = CreateIndexRequest.of(b -> b
    .index("some-index")
    .withJson(input) 
);

boolean created = client.indices().create(req).acknowledged();
  • 再来段更复杂的,一个API对象,既通过JSON反序列化生成,同时又能调用对象的方法设置一些属性
Reader queryJson = new StringReader(
    "{" +
    "  \"query\": {" +
    "    \"range\": {" +
    "      \"@timestamp\": {" +
    "        \"gt\": \"now-1w\"" +
    "      }" +
    "    }" +
    "  }," +
    "  \"size\": 100" + 
    "}");

Reader aggregationJson = new StringReader(
    "{" +
    "  \"size\": 0, " + 
    "  \"aggregations\": {" +
    "    \"hours\": {" +
    "      \"date_histogram\": {" +
    "        \"field\": \"@timestamp\"," +
    "        \"interval\": \"hour\"" +
    "      }," +
    "      \"aggregations\": {" +
    "        \"max-cpu\": {" +
    "          \"max\": {" +
    "            \"field\": \"host.cpu.usage\"" +
    "          }" +
    "        }" +
    "      }" +
    "    }" +
    "  }" +
    "}");

SearchRequest aggRequest = SearchRequest.of(b -> b
    .withJson(queryJson) 
    .withJson(aggregationJson) 
    .ignoreUnavailable(true) 
);

Map<String, Aggregate> aggs = client
    .search(aggRequest, Void.class)
    .aggregations();

关于异常

  • 在Java API Client中一共有两大类异常
  1. 第一类是由es服务端返回的错误引发的,例如es服务端的校验未通过,或者es服务端自己内部出现异常等,这些情况下抛出的异常是ElasticsearchException
  2. 第二类是因为请求未能成功到达es服务端而引发的,例如网络故障,es服务不可用等,这些情况下抛出的异常是TransportException,这些是lower-level implementation抛出的,有个例外:如果这些问题发生在RestClientTransport对象的方法中,那么抛出的异常类型是ResponseException
  • 以上就是Java API Client相关的重要知识点,在写代码之前先了解它们算是打好基础,然后,接下来精彩的实战篇即将开幕

欢迎关注头条号:程序员欣宸

  • 学习路上,你不孤单,欣宸原创一路相伴...

java与es8实战之三:Java API Client有关的知识点串讲

相关推荐

七条简单命令让您玩转Git
七条简单命令让您玩转Git

凭借着出色的协作能力、快速部署效果与代码构建辅助作用,Git已经得到越来越多企业用户的青睐。除了用于开发商业及消费级应用之外,众多科学及政府机构也开始尝试使用这...

2023-10-07 12:14 guanshanw

基本完整的关于Git分支branch的操作
基本完整的关于Git分支branch的操作

Git使用背景项目中要用到dev或者其他分支开发完代码,需要将该分支合并到master的需求操作步骤下面以dev名称为lex为分支名为例来操作一遍客户端操作:...

2023-10-07 12:14 guanshanw

Git 进阶(合并与变基)
Git 进阶(合并与变基)

在Git中整合来自不同分支的修改主要有两种方法:合并(merge)以及变基(rebase)合并(merge)merge流程图merge的原理是找到这两个分...

2023-10-07 12:13 guanshanw

Git学习笔记 003 Git进阶功能 part5 合并(第一部分)

合并(merge)是很常用的操作。尤其是一个庞大的很多人参与开发的企业级应用。一般会设定一个主分支,和多个副分支。在副分支开发完成后,合并到主分支中。始终保持主分支是一个完整的,稳定的最新状态的分支。...

非标题党,三张图帮你理解git merge和git rebase的区别
非标题党,三张图帮你理解git merge和git rebase的区别

初始场景:基于正常的开发分支修改几个小bug,然后在合并到开发分支上。gitmergegitcheckoutfeaturegitmergeho...

2023-10-07 12:13 guanshanw

git 初次使用(01)
git 初次使用(01)

先从github上克隆代码下来:使用vscode克隆代码如下图,填写上github仓库地址:vscode有时候克隆代码速度比较慢,可以用命令行方式克隆gitc...

2023-10-07 12:12 guanshanw

Git 远程操作

4.Git远程操作命令说明gitremote远程版本库操作gitfetch从远程获取版本库gitpull下载远程代码并合并gitpush上传远程代码并合并4.1远程版本库操作gitre...

Git常用命令-总结
Git常用命令-总结

创建git用户$gitconfig--globaluser.name"YourName"$gitconfig--globaluser.em...

2023-10-07 12:12 guanshanw

git中删除从别人clone下来项目的git信息,并修改为自己的分支

如果你从别人的Git存储库中克隆了一个项目,并想要删除与该存储库相关的Git信息,并将其修改为你自己的分支,则可以执行以下步骤:使用gitclone命令克隆存储库:gitclone<u...

git系列-回滚和放弃本地修改

回滚历史提交就是reset的功能。这种情况是已经提交远程仓库,需要回滚到之前的提交。gitreset--hardcommitId//注:强制提交后,当前版本后面的提交版本将会删掉!gi...

GIT使用小技巧大全
GIT使用小技巧大全

在大型软件工程的开发过程中,版本控制是无法绕过去的;目前来说,最火的版本控制软件就是GIT了。早两年SVN比较火,不过被大神linus喷了几次后,就日落西山了,...

2023-10-07 12:11 guanshanw

git相关命令-上
git相关命令-上

这些命令都是看了文档后,个人觉得比较有用的一些,展示给大家。回到远程仓库的状态抛弃本地所有的修改,回到远程仓库的状态。gitfetch--all&...

2023-10-07 12:10 guanshanw

Git命令行接口:掌握Git的必备技能
Git命令行接口:掌握Git的必备技能

Git是一款强大的分布式版本控制工具,它支持命令行界面操作。熟练掌握Git命令行接口,是开发者使用Git的必备技能之一。在这篇文章中,我们将介绍Git命令行接口...

2023-10-07 12:10 guanshanw

Git命令详解
Git命令详解

相信各位小伙伴们应该都对git有一些了解,毕竟作为代码管理的神器,就算不是IT行业的小伙伴肯定也或多或少的听说过一些。今天就来和小伙伴们分享一下自己总结的常用命...

2023-10-07 12:10 guanshanw

工作7年收集到的git命令
工作7年收集到的git命令

概念git中的术语解释:仓库也叫版本库(repository)stage:暂存区,add后会存到暂存区,commit后提交到版本库git安装linux...

2023-10-07 12:10 guanshanw

取消回复欢迎 发表评论: