正式使用官方的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相關的重要知識點,在寫代碼之前先瞭解它們算是打好基礎,然後,接下來精彩的實戰篇即將開幕