[Backport 2.x] Add option to set headers and sort options in cat requests

CHANGELOG.md

@@ -12,6 +12,7 @@ Inspired from [Keep a Changelog](https://keepachangelog.com/en/1.0.0/)
 - Require two maintainers to approve release ([#383](https://github.com/opensearch-project/opensearch-java/pull/383))
 - Add support for mapping limit settings ([#382](https://github.com/opensearch-project/opensearch-java/pull/382))
 - Add buffered lookahead for Jackson ([#338](https://github.com/opensearch-project/opensearch-java/pull/338))
+- Add support for headers and sort parameters in cat requests ([#388](https://github.com/opensearch-project/opensearch-java/issues/388))
 
 ### Dependencies
 - Bumps `grgit-gradle` from 4.0.1 to 5.0.0

USER_GUIDE.md

@@ -15,6 +15,10 @@
   - [Aggregations](#aggregations)
   - [Delete the document](#delete-the-document)
   - [Delete the index](#delete-the-index)
+  - [Cat API](#cat-api)
+    - [Cat Indices](#cat-indices)
+    - [Cat Aliases](#cat-aliases)
+    - [Cat Nodes](#cat-nodes)
 - [Using different transport options](#using-different-transport-options)
   - [Amazon Managed OpenSearch](#amazon-managed-opensearch)
 
@@ -199,6 +203,31 @@ DeleteIndexRequest deleteIndexRequest = new DeleteRequest.Builder().index(index)
 DeleteIndexResponse deleteIndexResponse = client.indices().delete(deleteIndexRequest);
 ```
 
+## Cat API
+
+### Cat Indices
+The following sample code cat indices with required headers and sorted by creation date
+
+```java
+IndicesRequest indicesRequest = new IndicesRequest.Builder()
+        .headers("index,health,status,pri,rep,doc.count,creation.date,creation.date.string").sort("creation.date").build();
+IndicesResponse indicesResponse = javaClient().cat().indices(indicesRequest);
+```
+
+
+### Cat aliases
+The following sample code cat aliases with name "test-alias" and sorted by index
+```java
+AliasesRequest aliasesRequest = new AliasesRequest.Builder().name("test-alias").sort("index").build();
+AliasesResponse aliasesResponse = javaClient().cat().aliases(aliasesRequest);
+```
+
+### Cat nodes
+The following sample code cat nodes sorted by cpu
+```java
+NodesResponse nodesResponse = javaClient().cat().nodes(r -> r.sort("cpu"));
+```
+
 # Using different transport options
 
 ## Amazon Managed OpenSearch

java-client/src/main/java/org/opensearch/client/opensearch/cat/AliasesRequest.java

@@ -42,14 +42,13 @@
 import org.opensearch.client.transport.endpoints.SimpleEndpoint;
 import org.opensearch.client.util.ApiTypeHelper;
 import org.opensearch.client.util.ObjectBuilder;
-import org.opensearch.client.util.ObjectBuilderBase;
 
+import javax.annotation.Nullable;
 import java.util.HashMap;
 import java.util.List;
 import java.util.Map;
 import java.util.function.Function;
 import java.util.stream.Collectors;
-import javax.annotation.Nullable;
 
 // typedef: cat.aliases.Request
 
@@ -67,7 +66,7 @@ public class AliasesRequest extends CatRequestBase {
 	// ---------------------------------------------------------------------------------------------
 
 	private AliasesRequest(Builder builder) {
-
+		super(builder);
 		this.expandWildcards = ApiTypeHelper.unmodifiable(builder.expandWildcards);
 		this.name = ApiTypeHelper.unmodifiable(builder.name);
 
@@ -102,7 +101,7 @@ public final List<String> name() {
 	 * Builder for {@link AliasesRequest}.
 	 */
 
-	public static class Builder extends ObjectBuilderBase implements ObjectBuilder<AliasesRequest> {
+	public static class Builder extends CatRequestBaseBuilder<AliasesRequest.Builder> {
 		@Nullable
 		private List<ExpandWildcard> expandWildcards;
 
@@ -170,6 +169,11 @@ public AliasesRequest build() {
 
 			return new AliasesRequest(this);
 		}
+
+		@Override
+		protected Builder self() {
+			return this;
+		}
 	}
 
 	// ---------------------------------------------------------------------------------------------
@@ -214,8 +218,7 @@ public AliasesRequest build() {
 
 			// Request parameters
 			request -> {
-				Map<String, String> params = new HashMap<>();
-				params.put("format", "json");
+				Map<String, String> params = new HashMap<>(request.queryParameters());
 				if (ApiTypeHelper.isDefined(request.expandWildcards)) {
 					params.put("expand_wildcards",
 							request.expandWildcards.stream()

java-client/src/main/java/org/opensearch/client/opensearch/cat/AllocationRequest.java

@@ -42,14 +42,13 @@
 import org.opensearch.client.transport.endpoints.SimpleEndpoint;
 import org.opensearch.client.util.ApiTypeHelper;
 import org.opensearch.client.util.ObjectBuilder;
-import org.opensearch.client.util.ObjectBuilderBase;
 
+import javax.annotation.Nullable;
 import java.util.HashMap;
 import java.util.List;
 import java.util.Map;
 import java.util.function.Function;
 import java.util.stream.Collectors;
-import javax.annotation.Nullable;
 
 // typedef: cat.allocation.Request
 
@@ -68,7 +67,7 @@ public class AllocationRequest extends CatRequestBase {
 	// ---------------------------------------------------------------------------------------------
 
 	private AllocationRequest(Builder builder) {
-
+		super(builder);
 		this.bytes = builder.bytes;
 		this.nodeId = ApiTypeHelper.unmodifiable(builder.nodeId);
 
@@ -103,7 +102,7 @@ public final List<String> nodeId() {
 	 * Builder for {@link AllocationRequest}.
 	 */
 
-	public static class Builder extends ObjectBuilderBase implements ObjectBuilder<AllocationRequest> {
+	public static class Builder extends CatRequestBaseBuilder<AllocationRequest.Builder> {
 		@Nullable
 		private Bytes bytes;
 
@@ -155,6 +154,11 @@ public AllocationRequest build() {
 
 			return new AllocationRequest(this);
 		}
+
+		@Override
+		protected Builder self() {
+			return this;
+		}
 	}
 
 	// ---------------------------------------------------------------------------------------------
@@ -200,8 +204,7 @@ public AllocationRequest build() {
 
 			// Request parameters
 			request -> {
-				Map<String, String> params = new HashMap<>();
-				params.put("format", "json");
+				Map<String, String> params = new HashMap<>(request.queryParameters());
 				if (request.bytes != null) {
 					params.put("bytes", request.bytes.jsonValue());
 				}

java-client/src/main/java/org/opensearch/client/opensearch/cat/CatRequestBase.java

@@ -37,21 +37,99 @@
 package org.opensearch.client.opensearch.cat;
 
 import org.opensearch.client.opensearch._types.RequestBase;
+import org.opensearch.client.util.ObjectBuilder;
 import org.opensearch.client.util.ObjectBuilderBase;
 
-// typedef: cat._types.CatRequestBase
+import javax.annotation.Nullable;
+import java.util.HashMap;
+import java.util.Map;
 
+// typedef: cat._types.CatRequestBase
 
 
 public abstract class CatRequestBase extends RequestBase {
-	public CatRequestBase() {
-	}
 
-	protected abstract static class AbstractBuilder<BuilderT extends AbstractBuilder<BuilderT>>
-			extends
-				ObjectBuilderBase {
-		protected abstract BuilderT self();
+    @Nullable
+    private final String headers;
+
+    @Nullable
+    private final String sort;
+
+    public CatRequestBase() {
+        this.headers = null;
+        this.sort = null;
+    }
+
+    public CatRequestBase(CatRequestBaseBuilder<?> builder) {
+        this.headers = builder.headers;
+        this.sort = builder.sort;
+    }
+
+    protected final Map<String, String> queryParameters() {
+        Map<String, String> params = new HashMap<>();
+        if (headers != null && !headers.isBlank()) {
+            params.put("h", headers);
+        }
+        if(sort != null && !sort.isBlank()) {
+            params.put("s", sort);
+        }
+        params.put("format", "json");
+        return params;
+    }
+
+
+    /**
+     * A comma-separated list of headers to limit the returned information
+     * <p>
+     * API name: {@code h}
+     */
+    public final String headers() {
+        return this.headers;
+    }
+
+    /**
+     * A comma-separated list of headers to sort the returned information
+     * <p>
+     * API name: {@code s}
+     * <p>
+     */
+    public final String sort() {
+        return this.sort;
+    }
+
+
+    protected abstract static class CatRequestBaseBuilder<BuilderT extends CatRequestBaseBuilder> extends ObjectBuilderBase implements ObjectBuilder {
+
+        @Nullable
+        protected String headers;
+
+        @Nullable
+        protected String sort;
+
+        protected abstract BuilderT self();
+
+        /**
+         * A comma-separated list of specific headers to limits the output
+         * <p>
+         * API name: {@code h}
+         * <p>
+         */
+        public final BuilderT headers(@Nullable String headers) {
+            this.headers = headers;
+            return self();
+        }
+
+        /**
+         * A comma-separated list of headers to sort the returned information
+         * <p>
+         * API name: {@code s}
+         * <p>
+         */
+        public final BuilderT sort(@Nullable String sort) {
+            this.sort = sort;
+            return self();
+        }
 
-	}
+    }
 
 }

java-client/src/main/java/org/opensearch/client/opensearch/cat/ClusterManagerRequest.java

@@ -41,7 +41,6 @@
 import org.opensearch.client.transport.endpoints.SimpleEndpoint;
 
 import java.util.HashMap;
-import java.util.Map;
 
 // typedef: cat.cluster_manager.Request
 
@@ -79,12 +78,7 @@ public ClusterManagerRequest() {
 			},
 
 			// Request parameters
-			request -> {
-				Map<String, String> params = new HashMap<>();
-				params.put("format", "json");
-				return params;
-
-			}, SimpleEndpoint.emptyMap(), false, ClusterManagerResponse._DESERIALIZER);
+			request -> new HashMap<>(request.queryParameters()), SimpleEndpoint.emptyMap(), false, ClusterManagerResponse._DESERIALIZER);
 
 	/**
 	 * Endpoint "{@code cat.cluster_manager}".
@@ -104,10 +98,5 @@ public ClusterManagerRequest() {
 			},
 
 			// Request parameters
-			request -> {
-				Map<String, String> params = new HashMap<>();
-				params.put("format", "json");
-				return params;
-
-			}, SimpleEndpoint.emptyMap(), false, ClusterManagerResponse._DESERIALIZER);
+			request -> new HashMap<>(request.queryParameters()), SimpleEndpoint.emptyMap(), false, ClusterManagerResponse._DESERIALIZER);
 }

java-client/src/main/java/org/opensearch/client/opensearch/cat/CountRequest.java

@@ -41,14 +41,12 @@
 import org.opensearch.client.transport.endpoints.SimpleEndpoint;
 import org.opensearch.client.util.ApiTypeHelper;
 import org.opensearch.client.util.ObjectBuilder;
-import org.opensearch.client.util.ObjectBuilderBase;
 
+import javax.annotation.Nullable;
 import java.util.HashMap;
 import java.util.List;
-import java.util.Map;
 import java.util.function.Function;
 import java.util.stream.Collectors;
-import javax.annotation.Nullable;
 
 // typedef: cat.count.Request
 
@@ -64,7 +62,7 @@ public class CountRequest extends CatRequestBase {
 	// ---------------------------------------------------------------------------------------------
 
 	private CountRequest(Builder builder) {
-
+		super(builder);
 		this.index = ApiTypeHelper.unmodifiable(builder.index);
 
 	}
@@ -88,7 +86,7 @@ public final List<String> index() {
 	 * Builder for {@link CountRequest}.
 	 */
 
-	public static class Builder extends ObjectBuilderBase implements ObjectBuilder<CountRequest> {
+	public static class Builder extends CatRequestBaseBuilder<CountRequest.Builder> {
 		@Nullable
 		private List<String> index;
 
@@ -127,6 +125,11 @@ public CountRequest build() {
 
 			return new CountRequest(this);
 		}
+
+		@Override
+		protected Builder self() {
+			return this;
+		}
 	}
 
 	// ---------------------------------------------------------------------------------------------
@@ -170,10 +173,5 @@ public CountRequest build() {
 			},
 
 			// Request parameters
-			request -> {
-				Map<String, String> params = new HashMap<>();
-				params.put("format", "json");
-				return params;
-
-			}, SimpleEndpoint.emptyMap(), false, CountResponse._DESERIALIZER);
+			request -> new HashMap<>(request.queryParameters()), SimpleEndpoint.emptyMap(), false, CountResponse._DESERIALIZER);
 }