Merge branch 'main' into add.documentation

Author: szabosteve

java-client/src/main/java/co/elastic/clients/base/ApiException.java

@@ -19,14 +19,15 @@
 
 package co.elastic.clients.base;
 
+import co.elastic.clients.elasticsearch._types.ErrorResponse;
 import co.elastic.clients.json.JsonpDeserializer;
 import org.apache.http.client.utils.URLEncodedUtils;
 
 import java.util.Collections;
 import java.util.Map;
 import java.util.function.Function;
 
-public class SimpleEndpoint<RequestT, ResponseT> implements Endpoint<RequestT, ResponseT, ElasticsearchError> {
+public class SimpleEndpoint<RequestT, ResponseT> implements Endpoint<RequestT, ResponseT, ErrorResponse> {
 
     private static final Function<?, Map<String, String>> EMPTY_MAP = x -> Collections.emptyMap();
 
@@ -99,8 +100,8 @@ public boolean isError(int statusCode) {
     }
 
     @Override
-    public JsonpDeserializer<ElasticsearchError> errorParser(int statusCode) {
-        return ElasticsearchError._DESERIALIZER;
+    public JsonpDeserializer<ErrorResponse> errorParser(int statusCode) {
+        return ErrorResponse._DESERIALIZER;
     }
 
     public <NewResponseT> SimpleEndpoint<RequestT, NewResponseT> withResponseDeserializer(

java-client/src/main/java/co/elastic/clients/base/SimpleEndpoint.java

@@ -19,12 +19,13 @@
 
 package co.elastic.clients.base.rest_client;
 
-import co.elastic.clients.base.ApiException;
 import co.elastic.clients.base.BooleanEndpoint;
 import co.elastic.clients.base.BooleanResponse;
 import co.elastic.clients.base.ElasticsearchCatRequest;
+import co.elastic.clients.elasticsearch.ElasticsearchException;
 import co.elastic.clients.base.Endpoint;
 import co.elastic.clients.base.Transport;
+import co.elastic.clients.elasticsearch._types.ErrorResponse;
 import co.elastic.clients.json.JsonpDeserializer;
 import co.elastic.clients.json.JsonpMapper;
 import co.elastic.clients.json.NdJsonpSerializable;
@@ -43,6 +44,7 @@
 import java.io.ByteArrayOutputStream;
 import java.io.IOException;
 import java.io.InputStream;
+import java.util.Iterator;
 import java.util.Map;
 import java.util.concurrent.CompletableFuture;
 import java.util.function.Function;
@@ -168,8 +170,8 @@ private <RequestT> org.elasticsearch.client.Request prepareLowLevelRequest(
             // Request has a body and must implement JsonpSerializable or NdJsonpSerializable
             ByteArrayOutputStream baos = new ByteArrayOutputStream();
 
-            if (request instanceof NdJsonpSerializable<?>) {
-                writeNdJson((NdJsonpSerializable<?>) request, baos);
+            if (request instanceof NdJsonpSerializable) {
+                writeNdJson((NdJsonpSerializable) request, baos);
             } else {
                 JsonGenerator generator = mapper.jsonProvider().createGenerator(baos);
                 mapper.serialize(request, generator);
@@ -184,15 +186,15 @@ private <RequestT> org.elasticsearch.client.Request prepareLowLevelRequest(
     }
 
     /**
-     * Write an nd-json value by serializing each of its items on a separate line.
-     * <p>
-     * If an item itself implements {@link NdJsonpSerializable}, it is output as nd-json. This allows flattening
-     * nested structures.
+     * Write an nd-json value by serializing each of its items on a separate line, recursing if its items themselves implement
+     * {@link NdJsonpSerializable} to flattening nested structures.
      */
-    private void writeNdJson(NdJsonpSerializable<?> value, ByteArrayOutputStream baos) {
-        for (Object item: value) {
-            if (item instanceof NdJsonpSerializable<?>) {
-                writeNdJson((NdJsonpSerializable<?>) item, baos);
+    private void writeNdJson(NdJsonpSerializable value, ByteArrayOutputStream baos) {
+        Iterator<?> values = value._serializables();
+        while(values.hasNext()) {
+            Object item = values.next();
+            if (item instanceof NdJsonpSerializable && item != value) { // do not recurse on the item itself
+                writeNdJson((NdJsonpSerializable) item, baos);
             } else {
                 JsonGenerator generator = mapper.jsonProvider().createGenerator(baos);
                 mapper.serialize(item, generator);
@@ -221,7 +223,8 @@ private <ResponseT, ErrorT> ResponseT getHighLevelResponse(
                 error = errorParser.deserialize(parser, mapper);
             }
 
-            throw new ApiException(error);
+            // TODO: have the endpoint provide the exception contructor
+            throw new ElasticsearchException((ErrorResponse) error);
 
         } else if (endpoint instanceof BooleanEndpoint) {
             BooleanEndpoint<?> bep = (BooleanEndpoint<?>)endpoint;

java-client/src/main/java/co/elastic/clients/base/rest_client/RestClientTransport.java

@@ -291,7 +291,7 @@ public ElasticsearchXpackAsyncClient xpack() {
 	 *      on elastic.co</a>
 	 */
 
-	public <TSource> CompletableFuture<BulkResponse> bulk(BulkRequest<TSource> request) throws IOException {
+	public CompletableFuture<BulkResponse> bulk(BulkRequest request) throws IOException {
 		return this.transport.performRequestAsync(request, BulkRequest.ENDPOINT);
 	}
 
@@ -308,9 +308,22 @@ public <TSource> CompletableFuture<BulkResponse> bulk(BulkRequest<TSource> reque
 	 *      on elastic.co</a>
 	 */
 
-	public final <TSource> CompletableFuture<BulkResponse> bulk(
-			Function<BulkRequest.Builder<TSource>, ObjectBuilder<BulkRequest<TSource>>> fn) throws IOException {
-		return bulk(fn.apply(new BulkRequest.Builder<TSource>()).build());
+	public final CompletableFuture<BulkResponse> bulk(Function<BulkRequest.Builder, ObjectBuilder<BulkRequest>> fn)
+			throws IOException {
+		return bulk(fn.apply(new BulkRequest.Builder()).build());
+	}
+
+	/**
+	 * Allows to perform multiple index/update/delete operations in a single
+	 * request.
+	 * 
+	 * @see <a href=
+	 *      "https://www.elastic.co/guide/en/elasticsearch/reference/master/docs-bulk.html">Documentation
+	 *      on elastic.co</a>
+	 */
+
+	public CompletableFuture<BulkResponse> bulk() throws IOException {
+		return this.transport.performRequestAsync(new BulkRequest.Builder().build(), BulkRequest.ENDPOINT);
 	}
 
 	// ----- Endpoint: clear_scroll
@@ -813,7 +826,7 @@ public final CompletableFuture<GetScriptResponse> getScript(
 	 *      "https://www.elastic.co/guide/en/elasticsearch/painless/master/painless-contexts.html">Documentation
 	 *      on elastic.co</a>
 	 */
-	public CompletableFuture<GetScriptContextResponse> getScriptContext() throws IOException {
+	public CompletableFuture<GetScriptContextResponse> getScriptContext() throws IOException, ElasticsearchException {
 		return this.transport.performRequestAsync(GetScriptContextRequest._INSTANCE, GetScriptContextRequest.ENDPOINT);
 	}
 
@@ -826,7 +839,8 @@ public CompletableFuture<GetScriptContextResponse> getScriptContext() throws IOE
 	 *      "https://www.elastic.co/guide/en/elasticsearch/reference/master/modules-scripting.html">Documentation
 	 *      on elastic.co</a>
 	 */
-	public CompletableFuture<GetScriptLanguagesResponse> getScriptLanguages() throws IOException {
+	public CompletableFuture<GetScriptLanguagesResponse> getScriptLanguages()
+			throws IOException, ElasticsearchException {
 		return this.transport.performRequestAsync(GetScriptLanguagesRequest._INSTANCE,
 				GetScriptLanguagesRequest.ENDPOINT);
 	}
@@ -905,7 +919,7 @@ public final <TDocument> CompletableFuture<IndexResponse> index(
 	 *      "https://www.elastic.co/guide/en/elasticsearch/reference/current/index.html">Documentation
 	 *      on elastic.co</a>
 	 */
-	public CompletableFuture<InfoResponse> info() throws IOException {
+	public CompletableFuture<InfoResponse> info() throws IOException, ElasticsearchException {
 		return this.transport.performRequestAsync(InfoRequest._INSTANCE, InfoRequest.ENDPOINT);
 	}
 
@@ -1096,7 +1110,7 @@ public final CompletableFuture<OpenPointInTimeResponse> openPointInTime(
 	 *      "https://www.elastic.co/guide/en/elasticsearch/reference/current/index.html">Documentation
 	 *      on elastic.co</a>
 	 */
-	public CompletableFuture<BooleanResponse> ping() throws IOException {
+	public CompletableFuture<BooleanResponse> ping() throws IOException, ElasticsearchException {
 		return this.transport.performRequestAsync(PingRequest._INSTANCE, PingRequest.ENDPOINT);
 	}
 

java-client/src/main/java/co/elastic/clients/elasticsearch/ElasticsearchAsyncClient.java

@@ -290,7 +290,7 @@ public ElasticsearchXpackClient xpack() {
 	 *      on elastic.co</a>
 	 */
 
-	public <TSource> BulkResponse bulk(BulkRequest<TSource> request) throws IOException {
+	public BulkResponse bulk(BulkRequest request) throws IOException {
 		return this.transport.performRequest(request, BulkRequest.ENDPOINT);
 	}
 
@@ -307,9 +307,21 @@ public <TSource> BulkResponse bulk(BulkRequest<TSource> request) throws IOExcept
 	 *      on elastic.co</a>
 	 */
 
-	public final <TSource> BulkResponse bulk(
-			Function<BulkRequest.Builder<TSource>, ObjectBuilder<BulkRequest<TSource>>> fn) throws IOException {
-		return bulk(fn.apply(new BulkRequest.Builder<TSource>()).build());
+	public final BulkResponse bulk(Function<BulkRequest.Builder, ObjectBuilder<BulkRequest>> fn) throws IOException {
+		return bulk(fn.apply(new BulkRequest.Builder()).build());
+	}
+
+	/**
+	 * Allows to perform multiple index/update/delete operations in a single
+	 * request.
+	 * 
+	 * @see <a href=
+	 *      "https://www.elastic.co/guide/en/elasticsearch/reference/master/docs-bulk.html">Documentation
+	 *      on elastic.co</a>
+	 */
+
+	public BulkResponse bulk() throws IOException {
+		return this.transport.performRequest(new BulkRequest.Builder().build(), BulkRequest.ENDPOINT);
 	}
 
 	// ----- Endpoint: clear_scroll
@@ -808,7 +820,7 @@ public final GetScriptResponse getScript(Function<GetScriptRequest.Builder, Obje
 	 *      "https://www.elastic.co/guide/en/elasticsearch/painless/master/painless-contexts.html">Documentation
 	 *      on elastic.co</a>
 	 */
-	public GetScriptContextResponse getScriptContext() throws IOException {
+	public GetScriptContextResponse getScriptContext() throws IOException, ElasticsearchException {
 		return this.transport.performRequest(GetScriptContextRequest._INSTANCE, GetScriptContextRequest.ENDPOINT);
 	}
 
@@ -821,7 +833,7 @@ public GetScriptContextResponse getScriptContext() throws IOException {
 	 *      "https://www.elastic.co/guide/en/elasticsearch/reference/master/modules-scripting.html">Documentation
 	 *      on elastic.co</a>
 	 */
-	public GetScriptLanguagesResponse getScriptLanguages() throws IOException {
+	public GetScriptLanguagesResponse getScriptLanguages() throws IOException, ElasticsearchException {
 		return this.transport.performRequest(GetScriptLanguagesRequest._INSTANCE, GetScriptLanguagesRequest.ENDPOINT);
 	}
 
@@ -899,7 +911,7 @@ public final <TDocument> IndexResponse index(
 	 *      "https://www.elastic.co/guide/en/elasticsearch/reference/current/index.html">Documentation
 	 *      on elastic.co</a>
 	 */
-	public InfoResponse info() throws IOException {
+	public InfoResponse info() throws IOException, ElasticsearchException {
 		return this.transport.performRequest(InfoRequest._INSTANCE, InfoRequest.ENDPOINT);
 	}
 
@@ -1086,7 +1098,7 @@ public final OpenPointInTimeResponse openPointInTime(
 	 *      "https://www.elastic.co/guide/en/elasticsearch/reference/current/index.html">Documentation
 	 *      on elastic.co</a>
 	 */
-	public BooleanResponse ping() throws IOException {
+	public BooleanResponse ping() throws IOException, ElasticsearchException {
 		return this.transport.performRequest(PingRequest._INSTANCE, PingRequest.ENDPOINT);
 	}
 

java-client/src/main/java/co/elastic/clients/elasticsearch/ElasticsearchClient.java

@@ -0,0 +1,60 @@
+/*
+ * Licensed to Elasticsearch B.V. under one or more contributor
+ * license agreements. See the NOTICE file distributed with
+ * this work for additional information regarding copyright
+ * ownership. Elasticsearch B.V. licenses this file to you 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.
+ */
+
+package co.elastic.clients.elasticsearch;
+
+import co.elastic.clients.elasticsearch._types.ErrorCause;
+import co.elastic.clients.elasticsearch._types.ErrorResponse;
+
+/**
+ * Exception thrown by API client methods when Elasticsearch could not accept or process a request.
+ * <p>
+ * The {@link #error()} contains the error's type and reason along with additional details that depend on the error type and
+ * the API endpoint that was called.
+ */
+public class ElasticsearchException extends RuntimeException {
+
+    private final ErrorResponse response;
+
+    public ElasticsearchException(ErrorResponse response) {
+        super(response.error().reason());
+        this.response = response;
+    }
+
+    /**
+     * The error response sent by Elasticsearch
+     */
+    public ErrorResponse response() {
+        return this.response;
+    }
+
+    /**
+     * The cause of the error. Shortcut for {@code response().error()}.
+     */
+    public ErrorCause error() {
+        return this.response.error();
+    }
+
+    /**
+     * Status code returned by Elasticsearch. Shortcut for {@code response().status()}.
+     */
+    public int status() {
+        return this.response.status();
+    }
+}

java-client/src/main/java/co/elastic/clients/elasticsearch/ElasticsearchException.java

@@ -41,7 +41,7 @@
 // typedef: _types.BulkIndexByScrollFailure
 @JsonpDeserializable
 public final class BulkIndexByScrollFailure implements JsonpSerializable {
-	private final MainError cause;
+	private final ErrorCause cause;
 
 	private final String id;
 
@@ -70,7 +70,7 @@ public BulkIndexByScrollFailure(Function<Builder, Builder> fn) {
 	/**
 	 * Required - API name: {@code cause}
 	 */
-	public MainError cause() {
+	public ErrorCause cause() {
 		return this.cause;
 	}
 
@@ -136,7 +136,7 @@ protected void serializeInternal(JsonGenerator generator, JsonpMapper mapper) {
 	 * Builder for {@link BulkIndexByScrollFailure}.
 	 */
 	public static class Builder implements ObjectBuilder<BulkIndexByScrollFailure> {
-		private MainError cause;
+		private ErrorCause cause;
 
 		private String id;
 
@@ -149,16 +149,16 @@ public static class Builder implements ObjectBuilder<BulkIndexByScrollFailure> {
 		/**
 		 * Required - API name: {@code cause}
 		 */
-		public Builder cause(MainError value) {
+		public Builder cause(ErrorCause value) {
 			this.cause = value;
 			return this;
 		}
 
 		/**
 		 * Required - API name: {@code cause}
 		 */
-		public Builder cause(Function<MainError.Builder, ObjectBuilder<MainError>> fn) {
-			return this.cause(fn.apply(new MainError.Builder()).build());
+		public Builder cause(Function<ErrorCause.Builder, ObjectBuilder<ErrorCause>> fn) {
+			return this.cause(fn.apply(new ErrorCause.Builder()).build());
 		}
 
 		/**
@@ -216,7 +216,7 @@ public BulkIndexByScrollFailure build() {
 	protected static void setupBulkIndexByScrollFailureDeserializer(
 			DelegatingDeserializer<BulkIndexByScrollFailure.Builder> op) {
 
-		op.add(Builder::cause, MainError._DESERIALIZER, "cause");
+		op.add(Builder::cause, ErrorCause._DESERIALIZER, "cause");
 		op.add(Builder::id, JsonpDeserializer.stringDeserializer(), "id");
 		op.add(Builder::index, JsonpDeserializer.stringDeserializer(), "index");
 		op.add(Builder::status, JsonpDeserializer.integerDeserializer(), "status");