[DOCS] Adds getting started content based on the template (#617)

Co-authored-by: Sylvain Wallez <[email protected]>

Author: 2 people

docs/getting-started.asciidoc

@@ -0,0 +1,168 @@
+[[getting-started-java]]
+== Getting started
+
+This page guides you through the installation process of the Java client, shows 
+you how to instantiate the client, and how to perform basic Elasticsearch 
+operations with it.
+
+[discrete]
+=== Requirements
+
+* Java 8 or later.
+* A JSON object mapping library to allow seamless integration of
+your application classes with the Elasticsearch API. The examples below
+show usage with Jackson.
+
+[discrete]
+=== Installation 
+
+[discrete]
+==== Installation in a Gradle project by using Jackson
+
+["source","groovy",subs="attributes+"]
+--------------------------------------------------
+dependencies {
+    implementation 'co.elastic.clients:elasticsearch-java:{version}'
+    implementation 'com.fasterxml.jackson.core:jackson-databind:2.12.3'
+}
+--------------------------------------------------
+
+[discrete]
+==== Installation in a Maven project by using Jackson
+
+In the `pom.xml` of your project, add the following repository definition and
+dependencies:
+
+["source","xml",subs="attributes+"]
+--------------------------------------------------
+<project>
+  <dependencies>
+
+    <dependency>
+      <groupId>co.elastic.clients</groupId>
+      <artifactId>elasticsearch-java</artifactId>
+      <version>{version}</version>
+    </dependency>
+
+    <dependency>
+      <groupId>com.fasterxml.jackson.core</groupId>
+      <artifactId>jackson-databind</artifactId>
+      <version>2.12.3</version>
+    </dependency>
+
+  </dependencies>
+</project>
+--------------------------------------------------
+
+
+Refer to the <<installation>> page to learn more.
+
+
+[discrete]
+=== Connecting
+
+You can connect to the Elastic Cloud using an API key and the Elasticsearch 
+endpoint.
+
+["source","java"]
+--------------------------------------------------
+include-tagged::{doc-tests-src}/getting_started/ConnectingTest.java[create-client]
+--------------------------------------------------
+
+Your Elasticsearch endpoint can be found on the **My deployment** page of your 
+deployment:
+
+image::images/es-endpoint.jpg[alt="Finding Elasticsearch endpoint",align="center"]
+
+You can generate an API key on the **Management** page under Security.
+
+image::images/create-api-key.png[alt="Create API key",align="center"]
+
+For other connection options, refer to the <<connecting>> section.
+
+
+[discrete]
+=== Operations
+
+Time to use Elasticsearch! This section walks you through the basic, and most 
+important, operations of Elasticsearch. For more operations and more advanced 
+examples, refer to the <<usage>> page.
+
+
+[discrete]
+==== Creating an index
+
+This is how you create the `product` index:
+
+["source","java"]
+--------------------------------------------------
+include-tagged::{doc-tests-src}/usage/IndexingTest.java[create-products-index]
+--------------------------------------------------
+
+[discrete]
+==== Indexing documents
+
+This is a simple way of indexing a document, here a `Product` application object:
+
+["source","java"]
+--------------------------------------------------
+include-tagged::{doc-tests-src}/usage/IndexingTest.java[single-doc-dsl]
+--------------------------------------------------
+
+[discrete]
+==== Getting documents
+
+You can get documents by using the following code:
+
+["source","java"]
+--------------------------------------------------
+include-tagged::{doc-tests-src}/usage/ReadingTest.java[get-by-id]
+--------------------------------------------------
+<1> The get request, with the index name and identifier.
+<2> The target class, here `Product`.
+
+
+[discrete]
+==== Searching documents
+
+This is how you can create a single match query with the Java client:
+
+["source","java"]
+--------------------------------------------------
+include-tagged::{doc-tests-src}/usage/SearchingTest.java[search-getting-started]
+--------------------------------------------------
+
+[discrete]
+==== Updating documents
+
+This is how you can update a document, for example to add a new field:
+
+["source","java"]
+--------------------------------------------------
+include-tagged::{doc-tests-src}/usage/IndexingTest.java[single-doc-update]
+--------------------------------------------------
+
+
+
+[discrete]
+==== Deleting documents
+
+["source","java"]
+--------------------------------------------------
+include-tagged::{doc-tests-src}/usage/IndexingTest.java[single-doc-delete]
+--------------------------------------------------
+
+
+[discrete]
+==== Deleting an index
+
+["source","java"]
+--------------------------------------------------
+include-tagged::{doc-tests-src}/usage/IndexingTest.java[create-products-index]
+--------------------------------------------------
+
+
+[discrete]
+== Further reading
+
+* Learn more about the <<api-conventions>> of the Java client.

docs/images/create-api-key.png

@@ -27,7 +27,8 @@ ifeval::["{release-state}"!="unreleased"]
 endif::[]
 
 include::introduction.asciidoc[]
-include::getting-started/index.asciidoc[]
+include::getting-started.asciidoc[]
+include::setup/index.asciidoc[]
 include::api-conventions/index.asciidoc[]
 
 include::usage/index.asciidoc[]

docs/images/es-endpoint.jpg

@@ -1,4 +1,4 @@
-== Getting started
+== Setup
 
 * <<installation>>
 * <<connecting>>

docs/index.asciidoc

@@ -27,10 +27,12 @@
 import co.elastic.clients.transport.ElasticsearchTransport;
 import co.elastic.clients.transport.TransportUtils;
 import co.elastic.clients.transport.rest_client.RestClientTransport;
+import org.apache.http.Header;
 import org.apache.http.HttpHost;
 import org.apache.http.auth.AuthScope;
 import org.apache.http.auth.UsernamePasswordCredentials;
 import org.apache.http.impl.client.BasicCredentialsProvider;
+import org.apache.http.message.BasicHeader;
 import org.elasticsearch.client.RestClient;
 import org.junit.jupiter.api.Disabled;
 import org.junit.jupiter.api.Test;
@@ -44,20 +46,28 @@ public class ConnectingTest {
     @Test
     public void createClient() throws Exception {
         //tag::create-client
+        // URL and API key
+        String serverUrl = "https://localhost:9200";
+        String apiKey = "VnVhQ2ZHY0JDZGJrU...";
+
         // Create the low-level client
-        RestClient restClient = RestClient.builder(
-            new HttpHost("localhost", 9200)).build();
+        RestClient restClient = RestClient
+            .builder(HttpHost.create(serverUrl))
+            .setDefaultHeaders(new Header[]{
+                new BasicHeader("Authorization", "ApiKey " + apiKey)
+            })
+            .build();
 
         // Create the transport with a Jackson mapper
         ElasticsearchTransport transport = new RestClientTransport(
             restClient, new JacksonJsonpMapper());
 
         // And create the API client
-        ElasticsearchClient client = new ElasticsearchClient(transport);
+        ElasticsearchClient esClient = new ElasticsearchClient(transport);
         //end::create-client
 
         //tag::first-request
-        SearchResponse<Product> search = client.search(s -> s
+        SearchResponse<Product> search = esClient.search(s -> s
             .index("products")
             .query(q -> q
                 .term(t -> t

docs/getting-started/connecting.asciidoc renamed to docs/setup/connecting.asciidoc

@@ -27,6 +27,7 @@
 import co.elastic.clients.elasticsearch.core.IndexResponse;
 import co.elastic.clients.elasticsearch.model.ModelTestCase;
 import co.elastic.clients.json.JsonData;
+import org.junit.jupiter.api.Disabled;
 import org.junit.jupiter.api.Test;
 import org.slf4j.Logger;
 import org.slf4j.LoggerFactory;
@@ -51,6 +52,26 @@ public class IndexingTest extends ModelTestCase {
         .shards(s -> s.total(1).successful(1).failed(0))
     );
 
+    @Test
+    @Disabled
+    public void createIndex() throws Exception {
+        //tag::create-products-index
+        esClient.indices().create(c -> c
+            .index("products")
+        );
+        //end::create-products-index
+    }
+
+    @Test
+    @Disabled
+    public void deleteIndex() throws Exception {
+        //tag::delete-products-index
+        esClient.indices().delete(d -> d
+            .index("products")
+        );
+        //end::delete-products-index
+    }
+
     @Test
     public void singleDocumentDSL() throws Exception {
 
@@ -162,4 +183,26 @@ public void singleDocumentJson() throws Exception {
             toJson(request)
         );
     }
+
+    @Test
+    public void deleteDocument() throws Exception {
+        //tag::single-doc-delete
+        esClient.delete(d -> d.index("products").id("bk-1"));
+        //end::single-doc-delete
+    }
+
+    @Test
+    @Disabled
+    public void updateDoc() throws Exception {
+        //tag::single-doc-update
+        Product product = new Product("bk-1", "City bike", 123.0);
+
+        esClient.update(u -> u
+                .index("products")
+                .id("bk-1")
+                .upsert(product),
+            Product.class
+        );
+        //end::single-doc-update
+    }
 }

docs/getting-started/index.asciidoc renamed to docs/setup/index.asciidoc

@@ -61,6 +61,25 @@ public class SearchingTest {
         )
     );
 
+    @Test
+    public void searchSimpleMatch() throws Exception {
+        transport.setResult(searchResponse);
+
+        //tag::search-getting-started
+        String searchText = "bike";
+
+        SearchResponse<Product> response = esClient.search(s -> s
+                .index("products")
+                .query(q -> q
+                    .match(t -> t
+                        .field("name")
+                        .query(searchText)
+                    )
+                ),
+            Product.class
+        );
+        //end::search-getting-started
+    }
     @Test
     public void searchMatch() throws Exception {