java與es8實戰之三：Java API Client有關的知識點串講

正式使用官方的Java API Client操作ES之前，將與之有關的重要知識點先做一輪串講，後面開始編碼時，疑點已掃清，可以愉快而順暢的實現業務功能 ...

歡迎訪問我的GitHub

這裡分類和彙總了欣宸的全部原創(含配套源碼)：https://github.com/zq2599/blog_demos

本篇概覽

本篇是《java與es8實戰》系列的第三篇，將一些重要的知識點在這裡梳理清楚，為後面的實踐奠定基礎
一共有七個與Java API Client有關的重要知識點

關於namespace：每個feature都有自己的package
命名規則：介紹Java API Client中對象的方法的命名規則
集合不為空：Java API Client中對象返回的集合，到底要不要做判空？
variant type：繁多的場景和對象，可以通過variant type進行簡化
通過JSON字元串創建API對象：通過builder創建複雜的對象，會導致代碼也很複雜，這裡提供了一種更簡單的方式
關於異常：有哪些異常類型，各自會在什麼場景拋出

接下來逐個去看

命名空間

在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，但也有例外，就是search和document，它們的代碼不在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中的對象分為五種

Object mapper：序列化和反序列化工具，這類對象是線程安全、無狀態的，通常是單例模式存在於應用中，常在啟動時創建
Transport：傳輸工具，此類對象線程安全，藉助底層HTTP客戶端工具維護著網路資源，例如負責與es服務端建立連接，在需要關閉連接的時候負責釋放所有底層網路資源
Clients：實際處理每個namespace的客戶端類，例如負責索引的是ElasticsearchIndicesClient，它們的特點：不可變對象、無狀態、線程安全、輕量級（類似於普通bean的資源開銷），之所以輕量級，是因為其結構實際上就是對一些API endpoint的包裝
Builders：這個在《開篇》中已經詳細說明瞭，就不多贅述，用過builder的您應該會發現，builder當然是可變類，至於是否線程安全似乎和builder沒什麼關係，因為每創建一次實例時，都要創建一個builder實例，而且，一旦執行完build方法後，這個builder實例就沒用了
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中一共有兩大類異常

第一類是由es服務端返回的錯誤引發的，例如es服務端的校驗未通過，或者es服務端自己內部出現異常等，這些情況下拋出的異常是ElasticsearchException
第二類是因為請求未能成功到達es服務端而引發的，例如網路故障，es服務不可用等，這些情況下拋出的異常是TransportException，這些是lower-level implementation拋出的，有個例外：如果這些問題發生在RestClientTransport對象的方法中，那麼拋出的異常類型是ResponseException

以上就是Java API Client相關的重要知識點，在寫代碼之前先瞭解它們算是打好基礎，然後，接下來精彩的實戰篇即將開幕

歡迎關註博客園：程式員欣宸

學習路上，你不孤單，欣宸原創一路相伴...