Java API 2.3
This section describes the Java API that elasticsearch provides. All elasticsearch operations are executed using a Client object. All operations are completely asynchronous in nature (either accepts a listener, or returns a future).
Additionally, operations on a client may be accumulated and executed in Bulk.
Note, all the APIs are exposed through the Java API (actually, the Java API is used internally to execute them).
Elasticsearch is hosted on Maven Central.
For example, you can define the latest version in your pom.xml file:
<dependency>
<groupId>org.elasticsearch</groupId>
<artifactId>elasticsearch</artifactId>
<version>${es.version}</version>
</dependency>
<dependency>
<groupId>org.elasticsearch</groupId>
<artifactId>elasticsearch</artifactId>
<version>2.3.5</version>
</dependency>
三、Dealing with JAR dependency conflicts 處理jar的依賴沖突
If you want to use Elasticsearch in your Java application, you may have to deal with version conflicts with third party dependencies like Guava and Joda. For instance, perhaps Elasticsearch uses Joda 2.8, while your code uses Joda 2.1.
You have two choices:
- The simplest solution is to upgrade. Newer module versions are likely to have fixed old bugs. The further behind you fall, the harder it will be to upgrade later. Of course, it is possible that you are using a third party dependency that in turn depends on an outdated version of a package, which prevents you from upgrading.
- The second option is to relocate the troublesome dependencies and to shade them either with your own application or with Elasticsearch and any plugins needed by the Elasticsearch client.
The "To shade or not to shade" blog post describes all the steps for doing so.
- 最簡單的解決方法就是升級。較新模塊的版本可能會有固定的舊bug。在你解決后，升級后將更難。當然你使用第三方依賴可能會反過來依賴一個過時的版本來阻礙你的升級。
- 第二個選擇就是遷移這令人煩惱的依賴，對於需要使用到es客戶端的你自己的應用、es和es的插件 隱藏它們
這個 隱藏不隱藏的博客介紹了完整的步驟
https://www.elastic.co/blog/to-shade-or-not-to-shade
四、Embedding jar with dependencies 植入依賴的jar
If you want to create a single jar containing your application and all dependencies, you should not use maven-assembly-plugin for that because it can not deal with META-INF/services structure which is required by Lucene jars.
Instead, you can use maven-shade-plugin and configure it as follow:
<plugin>
<groupId>org.apache.maven.plugins</groupId>
<artifactId>maven-shade-plugin</artifactId>
<version>2.4.1</version>
<executions>
<execution>
<phase>package</phase>
<goals><goal>shade</goal></goals>
<configuration>
<transformers>
<transformerimplementation="org.apache.maven.plugins.shade.resource.ServicesResourceTransformer"/>
</transformers>
</configuration>
</execution>
</executions>
</plugin>
Note that if you have a main class you want to automatically call when running java -jar yourjar.jar, just add it to the transformers:
注意，如果你有一個主類，你想自動調用java -jar yourjar.jar運行時，只要把它加到transformers：
<transformerimplementation="org.apache.maven.plugins.shade.resource.ManifestResourceTransformer"> <mainClass>org.elasticsearch.demo.Generate</mainClass> </transformer>
Elasticsearch and Lucene classes need to be in the same JBoss module.
You should define a module.xml file like this:
<?xml version="1.0" encoding="UTF-8"?> <modulename="org.elasticsearch"> <resources> <!-- Elasticsearch --> <resource-rootpath="elasticsearch-2.0.0.jar"/> <!-- Lucene --> <resource-rootpath="lucene-core-5.1.0.jar"/> <resource-rootpath="lucene-analyzers-common-5.1.0.jar"/> <resource-rootpath="lucene-queries-5.1.0.jar"/> <resource-rootpath="lucene-memory-5.1.0.jar"/> <resource-rootpath="lucene-highlighter-5.1.0.jar"/> <resource-rootpath="lucene-queryparser-5.1.0.jar"/> <resource-rootpath="lucene-sandbox-5.1.0.jar"/> <resource-rootpath="lucene-suggest-5.1.0.jar"/> <resource-rootpath="lucene-misc-5.1.0.jar"/> <resource-rootpath="lucene-join-5.1.0.jar"/> <resource-rootpath="lucene-grouping-5.1.0.jar"/> <resource-rootpath="lucene-spatial-5.1.0.jar"/> <resource-rootpath="lucene-expressions-5.1.0.jar"/> <!-- Insert other resources here --> </resources> <dependencies> <modulename="sun.jdk"export="true"> <imports> <includepath="sun/misc/Unsafe"/> </imports> </module> <modulename="org.apache.log4j"/> <modulename="org.apache.commons.logging"/> <modulename="javax.api"/> </dependencies> </module>
You can use the Java client in multiple ways:
Obtaining an elasticsearch Client is simple. The most common way to get a client is by creating a TransportClient that connects to a cluster.
The client must have the same major version (e.g.
2.x
, or
5.x
) as the nodes in the cluster. Clients may connect to clusters which have a different minor version (e.g.
2.3.x
) but it is possible that new funcionality may not be supported. Ideally, the client should have the same version as the cluster.
你能用多種方式來使用java客戶端：
- 在現有的集群上執行標准的 index / get / delete / search 操作
- 在運行的集群上執行管理任務
獲得一個es客戶端很簡單。最常見的方式是得到一個通過創建 TransportClient 來連接集群的客戶端連接
客戶端必須有相同的主版本（例如2.x，或5.x）作為集群的節點。客戶端們的小版本不一樣是可以連接到集群的，但是可能新的不知道。理論上，客戶端應該和集群的版本相同。
6.1 Transport Client 傳輸客戶端
The TransportClient connects remotely to an Elasticsearch cluster using the transport module. It does not join the cluster, but simply gets one or more initial transport addresses and communicates with them in round robin fashion on each action (though most actions will probably be "two hop" operations).
TransportClient 遠程連接到一個es集群使用傳輸模塊。他不加入到集群，僅僅是得到一個或多個初始傳輸地址和在每個動作中與他們交流的循環方式（雖然大多數的行動可能會“two hop”行動）。
1 // on startup 2 Client client =TransportClient.builder().build() 3 .addTransportAddress(newInetSocketTransportAddress(InetAddress.getByName("host1"),9300)) 4 .addTransportAddress(newInetSocketTransportAddress(InetAddress.getByName("host2"),9300)); 5 // on shutdown 6 client.close();
Note that you have to set the cluster name if you use one different than "elasticsearch":
你得注意當你使用一個不同的es時需要設置集群的名稱。
1 Settings settings =Settings.settingsBuilder() 2 .put("cluster.name","myClusterName").build(); 3 Client client =TransportClient.builder().settings(settings).build(); 4 //Add transport addresses and do something with the client...
The Transport client comes with a cluster sniffing feature which allows it to dynamically add new hosts and remove old ones. When sniffing is enabled, the transport client will connect to the nodes in its internal node list, which is built via calls to addTransportAddress. After this, the client will call the internal cluster state API on those nodes to discover available data nodes. The internal node list of the client will be replaced with those data nodes only. This list is refreshed every five seconds by default. Note that the IP addresses the sniffer connects to are the ones declared as the publish address in those node’s elasticsearch config.
傳輸客戶端配備一個集群監聽功能，允許它動態的添加新的主機和刪除舊的主機。當監聽都能被啟用時，通過調用addTransportAddress，傳輸客戶端將連接到內部節點列表中的節點。之后，這個客戶端將調用那些節點內部客戶端狀態API來發現可用的數據節點。客戶端的內部節點列表只會被那些數據節點替換。這個列表默認5秒刷新一次。需要注意的是IP地址監聽連接 會作為那些節點es配置文件中的publish地址來聲明。
Keep in mind that the list might possibly not include the original node it connected to if that node is not a data node. If, for instance, you initially connect to a master node, after sniffing, no further requests will go to that master node, but rather to any data nodes instead. The reason the transport client excludes non-data nodes is to avoid sending search traffic to master only nodes.
請牢記，如果原始節點不是數據節點，這個列表可能會不包括原始節點。例如，如果你開始的時候連接一個主節點，開啟監聽后，沒有新的請求到主節點，而是去其它數據節點。傳輸客戶端排除非數據節點的原因是為了發送搜索流到僅僅作為節點的主節點。
In order to enable sniffing, set client.transport.sniff to true:
為了啟用監聽功能 ，設置client.transport.sniff為true:
1 Settings settings =Settings.settingsBuilder() 2 .put("client.transport.sniff",true).build(); 3 TransportClient client =TransportClient.builder().settings(settings).build();
Other transport client level settings include:
其它傳輸客戶端級別設置包括：
| Parameter | Description |
|---|---|
|
|
Set to 設置為true時，忽略連接節點的集群名稱驗證（從0.19.4開始） |
|
|
The time to wait for a ping response from a node. Defaults to 等待一個節點的響應時間。默認為5秒 |
|
|
How often to sample / ping the nodes listed and connected. Defaults to 獲取節點列表和連接的頻率。默認為5秒 |
6.2 Connecting a Client to a Client Node 連接客戶端到一個節點
You can start locally a Client Node and then simply create a TransportClient in your application which connects to this Client Node.
This way, the client node will be able to load whatever plugin you need (think about discovery plugins for example).
您可以在本地啟動客戶端節點，然后簡單地創建一個TransportClient應用來連接到該客戶端節點。
通過這種方式，客戶端節點將能夠加載你需要任何插件（思考下發現插件的例子）。
七、Document APIs 文檔API
This section describes the following CRUD APIs:
本章節介紹下面的CRUD API ：
Single document APIs 單文檔api
Multi-document APIs 多文檔api
All CRUD APIs are single-index APIs. The
index
parameter accepts a single index name, or an
alias
which points to a single index.
八、Search API
The search API allows one to execute a search query and get back search hits that match the query. It can be executed across one or more indices and across one or more types. The query can provided using the query Java API. The body of the search request is built using the SearchSourceBuilder. Here is an example:
1 import org.elasticsearch.action.search.SearchResponse; 2 import org.elasticsearch.action.search.SearchType; 3 import org.elasticsearch.index.query.QueryBuilders.*; 4 5 SearchResponse response = client.prepareSearch("index1","index2") 6 .setTypes("type1","type2") 7 .setSearchType(SearchType.DFS_QUERY_THEN_FETCH) 8 .setQuery(QueryBuilders.termQuery("multi","test"))// Query 9 .setPostFilter(QueryBuilders.rangeQuery("age").from(12).to(18))// Filter 10 .setFrom(0).setSize(60).setExplain(true) 11 .execute() 12 .actionGet();
Note that all parameters are optional. Here is the smallest search call you can write: