From 3c5eb6cd1b39e1350e262a0dc2b23685fb27d9ea Mon Sep 17 00:00:00 2001 From: Luca Cavanna Date: Tue, 4 Jul 2017 10:58:57 +0200 Subject: [PATCH] [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. --- docs/java-rest/high-level/apis.asciidoc | 2 +- .../java-rest/high-level/apis/_index.asciidoc | 14 +++++----- .../java-rest/high-level/apis/delete.asciidoc | 12 ++++----- docs/java-rest/high-level/index.asciidoc | 8 +++++- docs/java-rest/high-level/usage.asciidoc | 15 ++++++----- docs/java-rest/index.asciidoc | 2 -- docs/java-rest/license.asciidoc | 1 - .../low-level/configuration.asciidoc | 12 ++++----- docs/java-rest/low-level/index.asciidoc | 8 +++++- docs/java-rest/low-level/sniffer.asciidoc | 27 ++++--------------- docs/java-rest/low-level/usage.asciidoc | 25 +++++++++-------- docs/java-rest/overview.asciidoc | 14 +++++----- 12 files changed, 70 insertions(+), 70 deletions(-) diff --git a/docs/java-rest/high-level/apis.asciidoc b/docs/java-rest/high-level/apis.asciidoc index 7ee035bd382..25c1b9f7c40 100644 --- a/docs/java-rest/high-level/apis.asciidoc +++ b/docs/java-rest/high-level/apis.asciidoc @@ -1,4 +1,4 @@ -=== Supported APIs +== Supported APIs The Java High Level REST Client supports the following APIs: diff --git a/docs/java-rest/high-level/apis/_index.asciidoc b/docs/java-rest/high-level/apis/_index.asciidoc index 8fde9bb0ef9..76ce8e46b49 100644 --- a/docs/java-rest/high-level/apis/_index.asciidoc +++ b/docs/java-rest/high-level/apis/_index.asciidoc @@ -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: diff --git a/docs/java-rest/high-level/apis/delete.asciidoc b/docs/java-rest/high-level/apis/delete.asciidoc index 70a248c2f6d..24a085acc39 100644 --- a/docs/java-rest/high-level/apis/delete.asciidoc +++ b/docs/java-rest/high-level/apis/delete.asciidoc @@ -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: diff --git a/docs/java-rest/high-level/index.asciidoc b/docs/java-rest/high-level/index.asciidoc index 5adbf2ae907..56fc257a509 100644 --- a/docs/java-rest/high-level/index.asciidoc +++ b/docs/java-rest/high-level/index.asciidoc @@ -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[] diff --git a/docs/java-rest/high-level/usage.asciidoc b/docs/java-rest/high-level/usage.asciidoc index 0b7d1d596d1..3dcba240ec4 100644 --- a/docs/java-rest/high-level/usage.asciidoc +++ b/docs/java-rest/high-level/usage.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 <> to be built as follows: diff --git a/docs/java-rest/index.asciidoc b/docs/java-rest/index.asciidoc index d4447019924..d06e312bce7 100644 --- a/docs/java-rest/index.asciidoc +++ b/docs/java-rest/index.asciidoc @@ -8,5 +8,3 @@ include::overview.asciidoc[] include::low-level/index.asciidoc[] include::high-level/index.asciidoc[] - -include::license.asciidoc[] diff --git a/docs/java-rest/license.asciidoc b/docs/java-rest/license.asciidoc index 0fb617d2f40..b097fe853b6 100644 --- a/docs/java-rest/license.asciidoc +++ b/docs/java-rest/license.asciidoc @@ -1,4 +1,3 @@ -[[java-rest-license]] == License Copyright 2013-2017 Elasticsearch diff --git a/docs/java-rest/low-level/configuration.asciidoc b/docs/java-rest/low-level/configuration.asciidoc index a75e1620c7e..5fc6d37daa8 100644 --- a/docs/java-rest/low-level/configuration.asciidoc +++ b/docs/java-rest/low-level/configuration.asciidoc @@ -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/ . diff --git a/docs/java-rest/low-level/index.asciidoc b/docs/java-rest/low-level/index.asciidoc index b5ad9d82e28..d59f9e030c5 100644 --- a/docs/java-rest/low-level/index.asciidoc +++ b/docs/java-rest/low-level/index.asciidoc @@ -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 <> +-- include::usage.asciidoc[] include::configuration.asciidoc[] include::sniffer.asciidoc[] + +include::../license.asciidoc[] diff --git a/docs/java-rest/low-level/sniffer.asciidoc b/docs/java-rest/low-level/sniffer.asciidoc index 081ecd3dd66..bd9e9d39de3 100644 --- a/docs/java-rest/low-level/sniffer.asciidoc +++ b/docs/java-rest/low-level/sniffer.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: -------------------------------------------------- -===== 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. - diff --git a/docs/java-rest/low-level/usage.asciidoc b/docs/java-rest/low-level/usage.asciidoc index d97487bd9aa..ab370cedf31 100644 --- a/docs/java-rest/low-level/usage.asciidoc +++ b/docs/java-rest/low-level/usage.asciidoc @@ -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], diff --git a/docs/java-rest/overview.asciidoc b/docs/java-rest/overview.asciidoc index 3c5ea06c1dd..4539406e4c3 100644 --- a/docs/java-rest/overview.asciidoc +++ b/docs/java-rest/overview.asciidoc @@ -1,11 +1,13 @@ [[java-rest-overview]] == Overview -The Java REST Client comes with 2 flavors: +The Java REST Client comes in 2 flavors: -* <>: 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. +* <>: 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. -* <>: 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. +* <>: 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. \ No newline at end of file