在 elasticsearch 源代码中,进入到 org.elasticsearch.client 你会发现下图所示的类:
从最外层开始认识它:
1、org.elasticsearch.client.AdminClient 接口
AdminClient 下有两个方法:
- cluster() ,产生一个允许从集群中执行 action 或 操作的 client;
- indices() , 产生一个允许从索引中执行 action 或 操作的 client。
- org.elasticsearch.client.AdminClient.NodeAdminClient 类
- NodeAdminClient 有一个带有 @Inject 注解的构造器,并实现了 接口 AdminClient的两个方法,如下所示
-
@Inject public NodeAdminClient( Settings settings, NodeClusterAdminClient clusterAdminClient, NodeIndicesAdminClient indicesAdminClient) { super(settings); this.indicesAdminClient = indicesAdminClient; this.clusterAdminClient = clusterAdminClient; } @Override public IndicesAdminClient indices() { return indicesAdminClient; } @Override public ClusterAdminClient cluster() { return this.clusterAdminClient; }
@Inject 导致了一个直接的后果:你只能被 @Inject 标注的构造器生成实例。 indices( ) 和 cluster( ) 覆盖了 AdminClient 的同名方法,分别返回 NodeIndicesAdminClient 和 NodeClusterAdminClient 对象。
NodeAdminClient 会继承父类 org.elasticsearch.common.component.AbstractComponent 的 nodeName() 方法以获取当前节点的节点名称。
-
- NodeAdminClient 有一个带有 @Inject 注解的构造器,并实现了 接口 AdminClient的两个方法,如下所示
- org.elasticsearch.client.transport.support.InternalTransportAdminClient 类
- InternalTransportAdminClient 其实与 NodeAdminClient类似,只是它的 indices() 和 cluster() 分别返回 InternalTransportIndicesAdminClient 和 InternalTransportClusterAdminClient.
- NodeAdminClient 和 InternalTransportClusterAdminClient 均没有子类,所以只有当我们需要用到 NodeIndicesAdminClient、NodeClusterAdminClient、InternalTransportIndicesAdminClient、InternalTransportClusterAdminClient时,才考虑创建这两个类的实体。
2、org.elasticsearch.client.Client 接口
Client 为从集群中执行 action 或者 operation 提供了一站式接口,这里的所有的操作都是自然而然的异步执行的,每个 action 或 operation 都有两种风格,一种是简单地返回 一个 org.elasticsearch.action.ActionFuture ,另外是访问一个 org.elasticsearch.action.ActionListener。你可以在 org.elasticsearch.node.Node 启动时候取得一个Client,也可以使用 org.elasticsearch.client.TransportClient远程连接一个或者对个节点。
Client 有以下方法:
- 1close() 关闭客户端
- admin() 返回一个可以执行管理性操作的客户端
- 两个 execute ,用于执行一般性操作,这里的一般性与上文提到的管理性相对
- prepareExecute,准备一个 RequestBuilder 对象,得到 RequestBuilder 对象后再做执行操作,当然,在这之间,也可以做一些个性化设置。
- index(IndexRequest request) ,根据给写的 index 和 type 索引一个 JSON 资源,index和 type由 IndexRequest 提供,IndexRequest 也可以提供 id,若不提供时, id 将自动生成;
- index(IndexRequest request, ActionListener<IndexResponse> listener) 与 index(IndexRequest request) 的区别在于它不会直接返回索引创建的结果,而是将结果转给监听器,由 listener 来通知请求者;
- prepareIndex() 、prepareIndex(String index,String type)、prepareIndex(String index, String type, @Nullable String id), 准备创建索引,但不创建索引;
- update(UpdateRequest request) 基于一个 script 更新文档,返回更新后的结果;
- update(UpdateRequest request, ActionListener<UpdateResponse> listener) 更新,但不返回结果,而是交由监听器;
- prepareUpdate(),prepareUpdate(String index,String type,String id) 准备更新,但不执行更新;
- delete(DeleteRequest request)、delete(DeleteRequest request,ActionListener<DeleteResponse> listener),根据 DeleteRequest 提供的 index、type 和 id 从索引中删除文档;
- prepareDelete()、prepareDelete(String index,String type,String id) 准备删除,但不执行删除;
- bulk(BulkRequest request)、bulk(BulkRequest request,ActionListener<BulkResponse> listener) 批量操作;
- prepareBulk(),准备执行批量操作,但不执行;
- deleteByQuery(DeleteByQueryRequest request)、deleteByQuery(DeleteByQueryRequest request, ActionListener<DeleteByQueryResponse> listener) 基于查询删除索引;
- prepareDelteByQuery(String... indices) 准备删除,但不执行删除;
- get(GetRequest request)、get(GetRequest request,ActionListener<GetResponse> llistener) 根据 GetRequest 提供的 index、type 和 id 获取文档;
- prepareGet()、prepareGet(String index,@Nullable String type,String id) 准备获取,但不执行获取;
- multiGet(MultiGetRequest request)、multiGet(MultiGetRequest request,ActionListener<MultiGetResonse> listener) 批量获取文档;
- prepareMultiGet() ,准备批量获取,但不执行获取操作;
- count(CountRequest request)、count(CountRequest request,ActionListener<CountResponse>listener),获取适应特定 query 的文档数量;
- prepareCount(String.. indices), 准备获取应特定query的文档数量,但不获取;
- search(SearchRequest request)、search(SearchRequest request,ActionListener<SearchResponse> listener),根据SearchRequest 提供的 index、id 和 type 执行搜索;
- prepareSearch(String... indices),准备但不搜索;
- searchScroll(SearchScrollRequest request)、searchScroll(SearchScrollRequest request,ActionListener<SearchResponse> listener)、prepareSearchScroll(String scrollId),通过用于迭代搜索结果;
- multiSearch(MultiSearchRequest request)、multiSearch(MultiSearchRequest request,ActionListener<MultiSearchResponse> listener)、prepareMultiSearch(), 执行多个搜索请求;
- moreLikeThis(MoreLikeThisRequest request)、moreLikeThis(MoreLikeThisRequest request,ActionListener<SearchReponse> listener)、prepareMoreLikeThis(String index,String type,String id) , 类似于 数据库 中的 like 操作,先根据 index、type、id 找到一个 document,再找到跟这个文档 like 的其他文档;
- percolate(PercolateRequest request)、precolate(PercolateRequest request,ActionListener<PercolateResponse> listener)、preparePrecolate(String index,String type),过滤一个请求,返回匹配的结果;
- explain(ExplainRequest request)、explain(ExplainRequest request,ActionListener<ExplainResponse> listener)、prepareExplain(String index,String type,String id),为指定的请求计算一个 score。
3、org.elasticsearch.client.ClusterAdminClient 接口
ClusterAdminClient 提供了针对集群的 action 和 operation 的管理接口,它有如下的方法:
- health(ClusterHealthRequest request)、health(ClusterHealthRequest request,ActionListener<ClusterHealthResponse> listener)、prepareHealth(String... indices) 集群健康状态;
- state(ClusterStateRequest request)、state(ClusterStateRequest request,ActionListener<ClusterStateResponse> listener)、prepareState() 集群的状态;
- updateSettings(ClusterUpdateSettingsRequest request)、updateSettings(ClusterUpdateSettingsRequest request, ActionListener<ClusterUpdateSettingsResponse> listener)、prepareUpdateSettings() 修改集群的设置
- reroute(ClusterRerouteRequest request)、reroute(ClusterRerouteRequest request,ActionListener<ClusterRerouteResponse> listener)、prepareReroute() 对碎片的划分进行重新分配;
- nodesStats(NodesStatsRequest request)、nodesStats(NodesStatsRequest request,ActionListener<NodesStatsResponse> listener)、prepareNodesStats(String... nodesIds) 集群中节点的状态;
- nodesInfo(NodesInfoRequest request)、nodesInfo(NodesInfoRequest request , ActionListener<NodesInfoResponse> listener)、prepareNodesInfo(String... nodesIds) 集群中节点的信息;
- nodesHotThreads(NodesHotThreadsRequest request)、nodesHotThreads(NodeshotThreadsRequest request,ActionListener<NodesHotThreadsResponse> listener)、prepareNodeshotThreads(String... u=nodesIds) 集群节点的活动情况;
- nodesShutdown(NodesShutdownRequest request)、nodesShutdown(NodesShutdownRequest request,ActionListener<NodesShutdownResponse> listener)、prepareNodesShutdown(String... nodesIds) 终止集群中的节点;
- nodesRestart(NodesRestartRequest request)、nodesRestart(NodesRestartRequest request、ActionListener<NodesRestartResponse> listener)、prepareNodesRestart(String... nodesIds) 重启集群中的节点;
4、org.elasticsearch.client.IndicesAdminClient 接口
IndicesAdminClient 提供了针对索引的 action 和 operation 的管理进行操作的接口,它有的方法如下:
- exists(IndicesExistsRequest request)、exists(IndicesExistsRequest request,ActionListener<IndicesExistsResponse> listener)、prepare(String... indices) 索引是否存在;
- typesExists(TypesExistsRequest request)、typesExists(TypesExistsRequest request,ActionListener<TypesExistsResponse> listener)、prepareTypesExists(String... indexs) type是否存在;
- stats(IndicesStatsRequest request)、stats(IndicesStatsRequest request、ActionListener<IndicesStatsResponse> listener)、prepareStats(String... indices),索引统计;
- status(IndicesStatusRequest request)、status(IndicesStatusRequest request,ActionListener<IndicesStatusResponse> listener)、prepareStatus(String... indices),索引状态;
- segments(IndicesSegmentRequest request)、segments(IndicesSegmentsRequest request,ActionListener<IndicesSegmentResponse>listener)、prepareSegments(String... indices), 索引的段;
- create(CreateIndexRequest request)、create(CreateIndexRequest request,ActionListener<CreateIndexResponse> listener)、prepareCreate(String index) 基于显示的设置创建索引;
- delete(DeleteIndexRequest request)、delete(DeleteIndexRequest request,ActionListener<DeleteIndexResponse> listener)、prepareDelete(String index) 基于索引名称删除索引;
- close(CloseIndexRequest request)、close(CloseIndexRequest request,ActionListener<CloseIndexResponse> listener)、prepareClose(String index) 基于索引名称关闭索引;
- open(OpenIndexRequest request)、open(OpenIndexRequest request,ActionListener<OpenIndexResponse> listener)、prepareOpen(String index) 基于索引名称打开索引;
- refresh(RefreshRequest request)、refresh(RefreshRequest request ,ActionListener<RefreshResponse> listener)、prepareRefresh(String... indices),显示地刷新索引;
- flush(FlushRequest request)、flush(FlushRequest request,ActionListener<FlushResponse> listener)、prepareFlush(String... indices) 显示的刷新索引(从节点中释放内存);
- optimize(OptimizeRequest request)、optimize(OptimizeRequest request,ActionListener<OptimizeResponse> listener)、prepareOptimize(String... indices) 显示的有话索引到片段中
- putMapping(PutMappingRequest request)、putMapping(PutMappingRequest request,ActionListener<PutMappingResponse> listener),preparePutMapping(String... indices) 定义映射关系,在这里可以定义解析器 如 : paoding
- deleteMapping(DeleteMappingRequest request)、deleteMapping(DeleteMappingRequest request,ActionListener<DeleteMappingResponse> listener)、prepareDeleteMapping(String。。。 indices) 删除索引的映射;
- gatewaySnapshot(GatewaySnapshotRequest request)、gatewaySnapshot(GatewaySnapshotRequest request, ActionListener<GatewaySnapshotResponse> listener)、prepareGatewaySnapshot(String indices) 为索引执行网关快照;
- aliases(IndicesAliasesRequest request)、aliases(IndicesAliasesrequest request, ActionListener<indicesAliasesResponse> listener)、prepareAliases(),允许为索引添加或删除别名;
- clearCache(ClearIndicesCacheRequest request)、clearCache(ClearIndicesCacheRequest request, ActionListener<ClearIndicesCacheResponse>)、prepareClearCache(String indices),清空索引缓存;
- updateSettings(UpdateSettingsRequest request)、updateSettings(UpdateSettingsRequest request,ActionListener<UpdateSettingsResponse> listener)、prepareUpdateSettings(String... indices),为索引更新设置;
- analyze(AnalyzeRequest request)、analyze(AnalyzeRequest request,ActionListener<AnalyzeResponse> listener)、prepareAnalyze(@Nullable String index,String text) 提取索引后分析的文本;
- putTemplate(PutIndexTemplateRequest request)、putTemplate(PutIndexTemplateRequest request,ActionListener<PutIndexTemplateResponse> listener) 、preparePutTemplate(String name),设置索引模版
- deleteTemplate(DeleteIndexTemplateRequest request)、deleteTemplate(DeleteIndexTemplateRequest request,ActionListener<DeleteIndexTemplateResponse> listener) 、prepareDeleteTemplate(String name),删除索引模版
- validateQuery(ValidateQueryRequest request)、validateQuery(ValidateQueryRequest request, ActionListener<ValidateQueryResponse> listener)、prepareValidateQuery(String... indices),验证查询的正确性
- putWarmer(PutWarmerRequest request)、putWarmer(PutWarmerRequest request, ActionListener<PutWarmerResponse> listener)、preparePutWarmer(String name),适当的时候,将候补搜索变更为可执行状态;
- deleteWarmer(DeleteWarmerRequest request)、deleteWarmer(DeleteWarmerRequest request, ActionListener<DeleteWarmerResponse> listener)、prepareDeleteWarmer(),删除候补索引。
5、一些相关类的详细结构和描述
AdminClient 接口有两个实现类
分别为
org.elasticsearch.client.transport.support.InternalTransportAdminClient和
org.elasticsearch.client.node.NodeAdminClient
各自实现了一个构造子以及AdminClient接口的两个方法,
这两个类的主要区别是:
InternalTransportAdminClient针对内部传输,
NodeAdminClient则侧重于对节点的管理。
org.elasticsearch.client.Client 的子类结构如下图所示:
org.elasticsearch.client.internal.InternalClient接口在Client接口的基础上,添加了一个settings()方法,用于获取当前客户端的Settings。
org.elasticsearch.client.support.AbstractClient实现了InternalClient类,你注意观察一下,会发现AbstractClient里面的所有方法中,除了prepareXxx方法,其他方法最后都跳转到其子类的execute方法中,而prepareXxx方法则在execute之前执行,进行相关属性的指定或设置。
AbstractClient有两个子类,分别是org.elasticsearch.client.transport.support.InternalTransportClient和org.elasticsearch.client.node.NodeClient,这两个类都重写了父类的close()、settings()、threadPool()、admin()和execute等方法,其中,close()方法如下所示:
@Override
public void close() {
// nothing to do here
}
也就是说,这两个类都不执行close操作。
这两个方法唯一的区别在于其针对的操作对象不同,InternalTransportClient针对的是内部传输,而NodeClient则针对节点间操作。
两个类都实现了一个被"@Inject"注解了的构造子,导致实例化这两个类时,只能通过该构造子,而不能使用其他方式。
execute方法的实现我将在后续分析,此处不赘述。
org.elasticsearch.client.ClusterAdminClient和org.elasticsearch.client.IndicesAdminClient的类结构与AdminClient的类结构相似,其中,
ClusterAdminClient的类结构如下所示:
IndicesAdminClient的类结构如下所示:
6、创建客户端的几种方式
使用 java client 有以下几种方式:
- 在一个已经存在的集群中,执行标准的 index 、get、delete 或 search 操作;
- 在一个正在运行的集群中,执行管理任务;
- 在应用中运行集成的 Elasticsearch 或者 执行单元测试或集成测试 启动全部的节点时;
获取Client对象最常用的方法是:
- 第一种
- 创建一个作为集群中节点的嵌入式 Node;
- 从第一步创建的嵌入式 Node 中,请求一个 Client;
- 第二种
- 创建一个连接到集群中的 TransportClient;
- 请注意:我们推荐设置客户端和集群端的版本号为一致,因为当两者版本号不一致时,将会出现很多不协调的问题
当启动一个节点时,它会自动加入同网段的 ES 集群,前提是 ES 的集群名 (cluster.name)参数为一致(该参数默认值为 elasticsearch,你也可在 /src/main/resoureces/elasticsearch.yml 或者 使用代码更改集群名)。
通过 TransportClient 这个接口,我们可以不启动节点就可以和 es集群进行通信,它需要指定 es集群 中其中一台或多台机的 ip地址和端口。
若无特殊情况,我们创建Client的方式如下:
NodeBuilder builder = NodeBuilder.nodebuilder();
//设置 builder ,如 builder.client(false) 等,具体参见
// 分布式搜索 Elasticsearch —— 节点实例化 https://my.oschina.net/exit/blog/805163
Client client = builder.client();