[DOCS] restructure java clients docs pages (#25517)
This commit converts the low level client and high level client chapters into two parts, which allows each high level client supported api to be on a separate page and show up in the index on the right.
This commit is contained in:
Luca Cavanna
GitHub
parent
8296618640
commit
3c5eb6cd1b
|
|
@ -1,4 +1,4 @@
|
|||
=== Supported APIs
|
||||
== Supported APIs
|
||||
|
||||
The Java High Level REST Client supports the following APIs:
|
||||
|
||||
|
|
|
|||
|
|
@ -1,8 +1,8 @@
|
|||
[[java-rest-high-document-index]]
|
||||
==== Index API
|
||||
=== Index API
|
||||
|
||||
[[java-rest-high-document-index-request]]
|
||||
===== Index Request
|
||||
==== Index Request
|
||||
|
||||
An `IndexRequest` requires the following arguments:
|
||||
|
||||
|
|
@ -15,7 +15,7 @@ include-tagged::{doc-tests}/CRUDDocumentationIT.java[index-request-string]
|
|||
<3> Document id
|
||||
<4> Document source provided as a `String`
|
||||
|
||||
===== Providing the document source
|
||||
==== Providing the document source
|
||||
The document source can be provided in different ways:
|
||||
|
||||
["source","java",subs="attributes,callouts,macros"]
|
||||
|
|
@ -39,7 +39,7 @@ include-tagged::{doc-tests}/CRUDDocumentationIT.java[index-request-shortcut]
|
|||
<1> Document source provided as `Object` key-pairs, which gets converted to
|
||||
JSON format
|
||||
|
||||
===== Optional arguments
|
||||
==== Optional arguments
|
||||
The following arguments can optionally be provided:
|
||||
|
||||
["source","java",subs="attributes,callouts,macros"]
|
||||
|
|
@ -94,7 +94,7 @@ include-tagged::{doc-tests}/CRUDDocumentationIT.java[index-request-pipeline]
|
|||
<1> The name of the ingest pipeline to be executed before indexing the document
|
||||
|
||||
[[java-rest-high-document-index-sync]]
|
||||
===== Synchronous Execution
|
||||
==== Synchronous Execution
|
||||
|
||||
["source","java",subs="attributes,callouts,macros"]
|
||||
--------------------------------------------------
|
||||
|
|
@ -102,7 +102,7 @@ include-tagged::{doc-tests}/CRUDDocumentationIT.java[index-execute]
|
|||
--------------------------------------------------
|
||||
|
||||
[[java-rest-high-document-index-async]]
|
||||
===== Asynchronous Execution
|
||||
==== Asynchronous Execution
|
||||
|
||||
["source","java",subs="attributes,callouts,macros"]
|
||||
--------------------------------------------------
|
||||
|
|
@ -113,7 +113,7 @@ provided as an argument.
|
|||
<2> Called in case of failure. The raised exception is provided as an argument.
|
||||
|
||||
[[java-rest-high-document-index-response]]
|
||||
===== Index Response
|
||||
==== Index Response
|
||||
|
||||
The returned `IndexResponse` allows to retrieve information about the executed
|
||||
operation as follows:
|
||||
|
|
|
|||
|
|
@ -1,8 +1,8 @@
|
|||
[[java-rest-high-document-delete]]
|
||||
==== Delete API
|
||||
=== Delete API
|
||||
|
||||
[[java-rest-high-document-delete-request]]
|
||||
===== Delete Request
|
||||
==== Delete Request
|
||||
|
||||
A `DeleteRequest` requires the following arguments:
|
||||
|
||||
|
|
@ -14,7 +14,7 @@ include-tagged::{doc-tests}/CRUDDocumentationIT.java[delete-request]
|
|||
<2> Type
|
||||
<3> Document id
|
||||
|
||||
===== Optional arguments
|
||||
==== Optional arguments
|
||||
The following arguments can optionally be provided:
|
||||
|
||||
["source","java",subs="attributes,callouts,macros"]
|
||||
|
|
@ -56,7 +56,7 @@ include-tagged::{doc-tests}/CRUDDocumentationIT.java[delete-request-version-type
|
|||
<1> Version type
|
||||
|
||||
[[java-rest-high-document-delete-sync]]
|
||||
===== Synchronous Execution
|
||||
==== Synchronous Execution
|
||||
|
||||
["source","java",subs="attributes,callouts,macros"]
|
||||
--------------------------------------------------
|
||||
|
|
@ -64,7 +64,7 @@ include-tagged::{doc-tests}/CRUDDocumentationIT.java[delete-execute]
|
|||
--------------------------------------------------
|
||||
|
||||
[[java-rest-high-document-delete-async]]
|
||||
===== Asynchronous Execution
|
||||
==== Asynchronous Execution
|
||||
|
||||
["source","java",subs="attributes,callouts,macros"]
|
||||
--------------------------------------------------
|
||||
|
|
@ -75,7 +75,7 @@ provided as an argument.
|
|||
<2> Called in case of failure. The raised exception is provided as an argument.
|
||||
|
||||
[[java-rest-high-document-delete-response]]
|
||||
===== Delete Response
|
||||
==== Delete Response
|
||||
|
||||
The returned `DeleteResponse` allows to retrieve information about the executed
|
||||
operation as follows:
|
||||
|
|
|
|||
|
|
@ -1,6 +1,8 @@
|
|||
[[java-rest-high]]
|
||||
== Java High Level REST Client
|
||||
= Java High Level REST Client
|
||||
|
||||
[partintro]
|
||||
--
|
||||
The Java High Level REST Client works on top of the Java Low Level REST client.
|
||||
Its main goal is to expose API specific methods, that accept request objects as
|
||||
an argument and return response objects, so that request marshalling and
|
||||
|
|
@ -16,8 +18,12 @@ The Java High Level REST Client depends on the Elasticsearch core project.
|
|||
It accepts the same request arguments as the `TransportClient` and returns
|
||||
the same response objects.
|
||||
|
||||
--
|
||||
|
||||
include::usage.asciidoc[]
|
||||
|
||||
include::apis.asciidoc[]
|
||||
|
||||
include::apis/index.asciidoc[]
|
||||
|
||||
include::../license.asciidoc[]
|
||||
|
|
|
|||
|
|
@ -1,8 +1,11 @@
|
|||
[[java-rest-high-usage]]
|
||||
=== Getting started
|
||||
== Getting started
|
||||
|
||||
This section describes how to get started with the high-level REST client from
|
||||
getting the artifact to using it in an application.
|
||||
|
||||
[[java-rest-high-usage-maven]]
|
||||
==== Maven Repository
|
||||
=== Maven Repository
|
||||
|
||||
The high-level Java REST client is hosted on
|
||||
http://search.maven.org/#search%7Cga%7C1%7Cg%3A%22org.elasticsearch.client%22[Maven
|
||||
|
|
@ -12,7 +15,7 @@ The High Level REST Client is subject to the same release cycle as
|
|||
Elasticsearch. Replace the version with the desired client version.
|
||||
|
||||
[[java-rest-high-usage-maven-maven]]
|
||||
===== Maven configuration
|
||||
==== Maven configuration
|
||||
|
||||
Here is how you can configure the dependency using maven as a dependency manager.
|
||||
Add the following to your `pom.xml` file:
|
||||
|
|
@ -27,7 +30,7 @@ Add the following to your `pom.xml` file:
|
|||
--------------------------------------------------
|
||||
|
||||
[[java-rest-high-usage-maven-gradle]]
|
||||
===== Gradle configuration
|
||||
==== Gradle configuration
|
||||
|
||||
Here is how you can configure the dependency using gradle as a dependency manager.
|
||||
Add the following to your `build.gradle` file:
|
||||
|
|
@ -40,7 +43,7 @@ dependencies {
|
|||
--------------------------------------------------
|
||||
|
||||
[[java-rest-high-usage-dependencies]]
|
||||
==== Dependencies
|
||||
=== Dependencies
|
||||
|
||||
The High Level Java REST Client depends on the following artifacts and their
|
||||
transitive dependencies:
|
||||
|
|
@ -50,7 +53,7 @@ transitive dependencies:
|
|||
|
||||
|
||||
[[java-rest-high-usage-initialization]]
|
||||
==== Initialization
|
||||
=== Initialization
|
||||
|
||||
A `RestHighLevelClient` instance needs a <<java-rest-low-usage-initialization,REST low-level client>>
|
||||
to be built as follows:
|
||||
|
|
|
|||
|
|
@ -8,5 +8,3 @@ include::overview.asciidoc[]
|
|||
include::low-level/index.asciidoc[]
|
||||
|
||||
include::high-level/index.asciidoc[]
|
||||
|
||||
include::license.asciidoc[]
|
||||
|
|
|
|||
|
|
@ -1,4 +1,3 @@
|
|||
[[java-rest-license]]
|
||||
== License
|
||||
|
||||
Copyright 2013-2017 Elasticsearch
|
||||
|
|
|
|||
|
|
@ -1,4 +1,4 @@
|
|||
=== Common configuration
|
||||
== Common configuration
|
||||
|
||||
The `RestClientBuilder` supports providing both a `RequestConfigCallback` and
|
||||
an `HttpClientConfigCallback` which allow for any customization that the Apache
|
||||
|
|
@ -8,7 +8,7 @@ configuration that the `RestClient` is initialized with. This section
|
|||
describes some common scenarios that require additional configuration for the
|
||||
low-level Java REST Client.
|
||||
|
||||
==== Timeouts
|
||||
=== Timeouts
|
||||
|
||||
Configuring requests timeouts can be done by providing an instance of
|
||||
`RequestConfigCallback` while building the `RestClient` through its builder.
|
||||
|
|
@ -34,7 +34,7 @@ RestClient restClient = RestClient.builder(new HttpHost("localhost", 9200))
|
|||
.build();
|
||||
--------------------------------------------------
|
||||
|
||||
==== Number of threads
|
||||
=== Number of threads
|
||||
|
||||
The Apache Http Async Client starts by default one dispatcher thread, and a
|
||||
number of worker threads used by the connection manager, as many as the number
|
||||
|
|
@ -55,7 +55,7 @@ RestClient restClient = RestClient.builder(new HttpHost("localhost", 9200))
|
|||
.build();
|
||||
--------------------------------------------------
|
||||
|
||||
==== Basic authentication
|
||||
=== Basic authentication
|
||||
|
||||
Configuring basic authentication can be done by providing an
|
||||
`HttpClientConfigCallback` while building the `RestClient` through its builder.
|
||||
|
|
@ -104,7 +104,7 @@ RestClient restClient = RestClient.builder(new HttpHost("localhost", 9200))
|
|||
.build();
|
||||
--------------------------------------------------
|
||||
|
||||
==== Encrypted communication
|
||||
=== Encrypted communication
|
||||
|
||||
Encrypted communication can also be configured through the
|
||||
`HttpClientConfigCallback`. The
|
||||
|
|
@ -130,7 +130,7 @@ RestClient restClient = RestClient.builder(new HttpHost("localhost", 9200))
|
|||
.build();
|
||||
--------------------------------------------------
|
||||
|
||||
==== Others
|
||||
=== Others
|
||||
|
||||
For any other required configuration needed, the Apache HttpAsyncClient docs
|
||||
should be consulted: https://hc.apache.org/httpcomponents-asyncclient-4.1.x/ .
|
||||
|
|
|
|||
|
|
@ -1,5 +1,8 @@
|
|||
[[java-rest-low]]
|
||||
== Java Low Level REST Client
|
||||
= Java Low Level REST Client
|
||||
|
||||
[partintro]
|
||||
--
|
||||
|
||||
The low-level client's features include:
|
||||
|
||||
|
|
@ -19,9 +22,12 @@ The low-level client's features include:
|
|||
|
||||
* optional automatic <<sniffer,discovery of cluster nodes>>
|
||||
|
||||
--
|
||||
|
||||
include::usage.asciidoc[]
|
||||
|
||||
include::configuration.asciidoc[]
|
||||
|
||||
include::sniffer.asciidoc[]
|
||||
|
||||
include::../license.asciidoc[]
|
||||
|
|
|
|||
|
|
@ -1,5 +1,5 @@
|
|||
[[sniffer]]
|
||||
=== Sniffer
|
||||
== Sniffer
|
||||
|
||||
Minimal library that allows to automatically discover nodes from a running
|
||||
Elasticsearch cluster and set them to an existing `RestClient` instance.
|
||||
|
|
@ -8,7 +8,7 @@ Nodes Info api and uses jackson to parse the obtained json response.
|
|||
|
||||
Compatible with Elasticsearch 2.x and onwards.
|
||||
|
||||
==== Maven Repository
|
||||
=== Maven Repository
|
||||
|
||||
The low-level REST client is subject to the same release cycle as
|
||||
elasticsearch. Replace the version with the desired sniffer version, first
|
||||
|
|
@ -17,7 +17,7 @@ and the elasticsearch version that the client can communicate with. Sniffer
|
|||
supports fetching the nodes list from elasticsearch 2.x and onwards.
|
||||
|
||||
|
||||
===== Maven configuration
|
||||
==== Maven configuration
|
||||
|
||||
Here is how you can configure the dependency using maven as a dependency manager.
|
||||
Add the following to your `pom.xml` file:
|
||||
|
|
@ -31,7 +31,7 @@ Add the following to your `pom.xml` file:
|
|||
</dependency>
|
||||
--------------------------------------------------
|
||||
|
||||
===== Gradle configuration
|
||||
==== Gradle configuration
|
||||
|
||||
Here is how you can configure the dependency using gradle as a dependency manager.
|
||||
Add the following to your `build.gradle` file:
|
||||
|
|
@ -43,7 +43,7 @@ dependencies {
|
|||
}
|
||||
--------------------------------------------------
|
||||
|
||||
==== Usage
|
||||
=== Usage
|
||||
|
||||
Once a `RestClient` instance has been created, a `Sniffer` can be associated
|
||||
to it. The `Sniffer` will make use of the provided `RestClient` to periodically
|
||||
|
|
@ -132,20 +132,3 @@ Sniffer sniffer = Sniffer.builder(restClient)
|
|||
|
||||
Note that this last configuration parameter has no effect in case sniffing
|
||||
on failure is not enabled like explained above.
|
||||
|
||||
==== License
|
||||
|
||||
Copyright 2013-2017 Elasticsearch
|
||||
|
||||
Licensed under the Apache License, Version 2.0 (the "License");
|
||||
you may not use this file except in compliance with the License.
|
||||
You may obtain a copy of the License at
|
||||
|
||||
http://www.apache.org/licenses/LICENSE-2.0
|
||||
|
||||
Unless required by applicable law or agreed to in writing, software
|
||||
distributed under the License is distributed on an "AS IS" BASIS,
|
||||
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
|
||||
See the License for the specific language governing permissions and
|
||||
limitations under the License.
|
||||
|
||||
|
|
|
|||
|
|
@ -1,8 +1,11 @@
|
|||
[[java-rest-low-usage]]
|
||||
=== Getting started
|
||||
== Getting started
|
||||
|
||||
This section describes how to get started with the low-level REST client from
|
||||
getting the artifact to using it in an application.
|
||||
|
||||
[[java-rest-low-usage-maven]]
|
||||
==== Maven Repository
|
||||
=== Maven Repository
|
||||
|
||||
The low-level Java REST client is hosted on
|
||||
http://search.maven.org/#search%7Cga%7C1%7Cg%3A%22org.elasticsearch.client%22[Maven
|
||||
|
|
@ -15,7 +18,7 @@ and the elasticsearch version that the client can communicate with. The
|
|||
low-level REST client is compatible with all elasticsearch versions.
|
||||
|
||||
[[java-rest-low-usage-maven-maven]]
|
||||
===== Maven configuration
|
||||
==== Maven configuration
|
||||
|
||||
Here is how you can configure the dependency using maven as a dependency manager.
|
||||
Add the following to your `pom.xml` file:
|
||||
|
|
@ -30,7 +33,7 @@ Add the following to your `pom.xml` file:
|
|||
--------------------------------------------------
|
||||
|
||||
[[java-rest-low-usage-maven-gradle]]
|
||||
===== Gradle configuration
|
||||
==== Gradle configuration
|
||||
|
||||
Here is how you can configure the dependency using gradle as a dependency manager.
|
||||
Add the following to your `build.gradle` file:
|
||||
|
|
@ -43,7 +46,7 @@ dependencies {
|
|||
--------------------------------------------------
|
||||
|
||||
[[java-rest-low-usage-dependencies]]
|
||||
==== Dependencies
|
||||
=== Dependencies
|
||||
|
||||
The low-level Java REST client internally uses the
|
||||
http://hc.apache.org/httpcomponents-asyncclient-dev/[Apache Http Async Client]
|
||||
|
|
@ -59,7 +62,7 @@ http://hc.apache.org/httpcomponents-asyncclient-dev/[Apache Http Async Client]
|
|||
|
||||
|
||||
[[java-rest-low-usage-initialization]]
|
||||
==== Initialization
|
||||
=== Initialization
|
||||
|
||||
A `RestClient` instance can be built through the corresponding
|
||||
`RestClientBuilder` class, created via `RestClient#builder(HttpHost...)`
|
||||
|
|
@ -108,7 +111,7 @@ http://hc.apache.org/httpcomponents-asyncclient-dev/httpasyncclient/apidocs/org/
|
|||
|
||||
|
||||
[[java-rest-low-usage-requests]]
|
||||
==== Performing requests
|
||||
=== Performing requests
|
||||
|
||||
Once the `RestClient` has been created, requests can be sent by calling one of
|
||||
the available `performRequest` or `performRequestAsync` method variants.
|
||||
|
|
@ -167,7 +170,7 @@ void performRequestAsync(String method, String endpoint,
|
|||
--------------------------------------------------
|
||||
|
||||
[[java-rest-low-usage-requests-arguments]]
|
||||
===== Request Arguments
|
||||
==== Request Arguments
|
||||
|
||||
The following are the arguments accepted by the different methods:
|
||||
|
||||
|
|
@ -188,7 +191,7 @@ request success or failure
|
|||
`headers`:: optional request headers
|
||||
|
||||
[[java-rest-low-usage-responses]]
|
||||
==== Reading responses
|
||||
=== Reading responses
|
||||
|
||||
The `Response` object, either returned by the synchronous `performRequest` methods or
|
||||
received as an argument in `ResponseListener#onSuccess(Response)`, wraps the
|
||||
|
|
@ -226,7 +229,7 @@ response, just without the document as it was not found.
|
|||
|
||||
|
||||
[[java-rest-low-usage-example]]
|
||||
==== Example requests
|
||||
=== Example requests
|
||||
|
||||
Here are a couple of examples:
|
||||
|
||||
|
|
@ -304,7 +307,7 @@ latch.await();
|
|||
--------------------------------------------------
|
||||
|
||||
[[java-rest-low-usage-logging]]
|
||||
==== Logging
|
||||
=== Logging
|
||||
|
||||
The Java REST client uses the same logging library that the Apache Async Http
|
||||
Client uses: https://commons.apache.org/proper/commons-logging/[Apache Commons Logging],
|
||||
|
|
|
|||
|
|
@ -1,11 +1,13 @@
|
|||
[[java-rest-overview]]
|
||||
== Overview
|
||||
|
||||
The Java REST Client comes with 2 flavors:
|
||||
The Java REST Client comes in 2 flavors:
|
||||
|
||||
* <<java-rest-low>>: which is the official low-level client for Elasticsearch.
|
||||
It allows to communicate with an Elasticsearch cluster through http and is compatible
|
||||
with all elasticsearch versions.
|
||||
* <<java-rest-low>>: the official low-level client for Elasticsearch.
|
||||
It allows to communicate with an Elasticsearch cluster through http.
|
||||
Leaves requests marshalling and responses un-marshalling to users.
|
||||
It is compatible with all Elasticsearch versions.
|
||||
|
||||
* <<java-rest-high>>: which is the official high-level client for Elasticsearch. It adds support
|
||||
part of the elasticsearch document level and search API on top of the low-level client.
|
||||
* <<java-rest-high>>: the official high-level client for Elasticsearch.
|
||||
Based on the low-level client, it exposes API specific methods and takes care
|
||||
of requests marshalling and responses un-marshalling.
|
||||
Loading…
Reference in New Issue