Adds point in time APIs

Signed-off-by: Harsha Vamsi Kalluri <[email protected]>

CHANGELOG.md

@@ -5,6 +5,7 @@ Inspired from [Keep a Changelog](https://keepachangelog.com/en/1.0.0/)
 
 ### Added
 - Document HTTP/2 support ([#330](https://github.com/opensearch-project/opensearch-java/pull/330))
+- Added Point-In-Time APIs ([#461](https://github.com/opensearch-project/opensearch-java/pull/461))
 
 ### Dependencies
 

USER_GUIDE.md

@@ -266,6 +266,42 @@ DeleteDataStreamRequest deleteDataStreamRequest = new DeleteDataStreamRequest.Bu
 DeleteDataStreamResponse deleteDataStreamResponse = javaClient().indices().deleteDataStream(deleteDataStreamRequest);
 ```
 
+## Point-In-Time API
+
+### Creating a point in time
+
+Creates a PIT. The keep_alive query parameter is required; it specifies how long to keep a PIT.
+
+```java
+CreatePointInTimeRequest createPointInTimeRequest = new CreatePointInTimeRequest.Builder()
+                .targetIndexes(Collections.singletonList(index))
+                .keepAlive(new Time.Builder().time("100m").build()).build();
+
+CreatePointInTimeResponse createPointInTimeResponse = javaClient()
+                .createPointInTime(createPointInTimeRequest);                
+```
+
+### List all point in time
+
+Returns all PITs in the OpenSearch cluster.
+
+```java
+ListAllPointInTimeResponse listAllPointInTimeResponse = javaClient().listAllPointInTime();
+```
+
+### Delete point in time
+
+Deletes one, several, or all PITs. PITs are automatically deleted when the keep_alive time period elapses. However, to deallocate resources, you can delete a PIT using the Delete PIT API. The Delete PIT API supports deleting a list of PITs by ID or deleting all PITs at once.
+
+```java
+DeletePointInTimeRequest deletePointInTimeRequest = new DeletePointInTimeRequest.Builder()
+                .pitId(Collections.singletonList("pit_id")).build();
+
+DeletePointInTimeResponse deletePointInTimeResponse = javaClient()
+                .deletePointInTime(deletePointInTimeRequest);
+```
+
+
 ## Cat API
 
 ### Cat Indices
@@ -291,6 +327,13 @@ The following sample code cat nodes sorted by cpu
 NodesResponse nodesResponse = javaClient().cat().nodes(r -> r.sort("cpu"));
 ```
 
+### Cat point in time segments
+Similarly to the CAT Segments API, the PIT Segments API provides low-level information about the disk utilization of a PIT by describing its Lucene segments. 
+```java
+SegmentsResponse pointInTimeSegmentsResponse = javaClient().cat()
+                .pointInTimeSegments(r -> r.headers("index,shard,id,segment,size"));
+```
+
 # Using different transport options
 
 ## Amazon OpenSearch Service

java-client/src/main/java/org/opensearch/client/opensearch/OpenSearchAsyncClient.java

@@ -116,6 +116,12 @@
 import org.opensearch.client.opensearch.core.UpdateByQueryRethrottleResponse;
 import org.opensearch.client.opensearch.core.UpdateRequest;
 import org.opensearch.client.opensearch.core.UpdateResponse;
+import org.opensearch.client.opensearch.core.point_in_time.CreatePointInTimeRequest;
+import org.opensearch.client.opensearch.core.point_in_time.CreatePointInTimeResponse;
+import org.opensearch.client.opensearch.core.point_in_time.DeletePointInTimeRequest;
+import org.opensearch.client.opensearch.core.point_in_time.DeletePointInTimeResponse;
+import org.opensearch.client.opensearch.core.point_in_time.ListAllPointInTimeRequest;
+import org.opensearch.client.opensearch.core.point_in_time.ListAllPointInTimeResponse;
 import org.opensearch.client.opensearch.dangling_indices.OpenSearchDanglingIndicesAsyncClient;
 import org.opensearch.client.opensearch.features.OpenSearchFeaturesAsyncClient;
 import org.opensearch.client.opensearch.indices.OpenSearchIndicesAsyncClient;
@@ -362,6 +368,39 @@ public final <TDocument> CompletableFuture<CreateResponse> create(
 		return create(fn.apply(new CreateRequest.Builder<TDocument>()).build());
 	}
 
+	// ----- Endpoint: create_point_in_time
+
+	/**
+	 * Provides low-level information about the disk utilization of a PIT by
+	 * describing its Lucene segments.
+	 * 
+	 *
+	 */
+
+	public CompletableFuture<CreatePointInTimeResponse> createPointInTime(CreatePointInTimeRequest request)
+			throws IOException, OpenSearchException {
+		@SuppressWarnings("unchecked")
+		JsonEndpoint<CreatePointInTimeRequest, CreatePointInTimeResponse, ErrorResponse> endpoint = (JsonEndpoint<CreatePointInTimeRequest, CreatePointInTimeResponse, ErrorResponse>) CreatePointInTimeRequest._ENDPOINT;
+
+		return this.transport.performRequestAsync(request, endpoint, this.transportOptions);
+	}
+
+	/**
+	 * Provides low-level information about the disk utilization of a PIT by
+	 * describing its Lucene segments.
+	 * 
+	 * @param fn
+	 *           a function that initializes a builder to create the
+	 *           {@link CreatePointInTimeRequest}
+	 *
+	 */
+
+	public final CompletableFuture<CreatePointInTimeResponse> createPointInTime(
+			Function<CreatePointInTimeRequest.Builder, ObjectBuilder<CreatePointInTimeRequest>> fn)
+			throws IOException, OpenSearchException {
+		return createPointInTime(fn.apply(new CreatePointInTimeRequest.Builder()).build());
+	}
+
 	// ----- Endpoint: delete
 
 	/**
@@ -393,6 +432,37 @@ public final CompletableFuture<DeleteResponse> delete(
 		return delete(fn.apply(new DeleteRequest.Builder()).build());
 	}
 
+	// ----- Endpoint: delete_point_in_time
+
+	/**
+	 * Delete Point In Time
+	 * 
+	 *
+	 */
+
+	public CompletableFuture<DeletePointInTimeResponse> DeletePointInTime(DeletePointInTimeRequest request)
+			throws IOException, OpenSearchException {
+		@SuppressWarnings("unchecked")
+		JsonEndpoint<DeletePointInTimeRequest, DeletePointInTimeResponse, ErrorResponse> endpoint = (JsonEndpoint<DeletePointInTimeRequest, DeletePointInTimeResponse, ErrorResponse>) DeletePointInTimeRequest._ENDPOINT;
+
+		return this.transport.performRequestAsync(request, endpoint, this.transportOptions);
+	}
+
+	/**
+	 * Delete Point In Time
+	 * 
+	 * @param fn
+	 *           a function that initializes a builder to create the
+	 *           {@link DeletePointInTimeRequest}
+	 *
+	 */
+
+	public final CompletableFuture<DeletePointInTimeResponse> DeletePointInTime(
+			Function<DeletePointInTimeRequest.Builder, ObjectBuilder<DeletePointInTimeRequest>> fn)
+			throws IOException, OpenSearchException {
+		return DeletePointInTime(fn.apply(new DeletePointInTimeRequest.Builder()).build());
+	}
+
 	// ----- Endpoint: delete_by_query
 
 	/**
@@ -801,6 +871,20 @@ public CompletableFuture<InfoResponse> info() throws IOException, OpenSearchExce
 		return this.transport.performRequestAsync(InfoRequest._INSTANCE, InfoRequest._ENDPOINT, this.transportOptions);
 	}
 
+	// ----- Endpoint: list_point_in_time
+
+	/**
+	 * List all Point In Time
+	 * 
+	 *
+	 */
+
+	public CompletableFuture<ListAllPointInTimeResponse> listAllPointInTime()
+			throws IOException, OpenSearchException {
+		return this.transport.performRequestAsync(ListAllPointInTimeRequest._INSTANCE, ListAllPointInTimeRequest._ENDPOINT,
+				this.transportOptions);
+	}
+
 	// ----- Endpoint: mget
 
 	/**

java-client/src/main/java/org/opensearch/client/opensearch/OpenSearchClient.java

@@ -116,6 +116,12 @@
 import org.opensearch.client.opensearch.core.UpdateByQueryRethrottleResponse;
 import org.opensearch.client.opensearch.core.UpdateRequest;
 import org.opensearch.client.opensearch.core.UpdateResponse;
+import org.opensearch.client.opensearch.core.point_in_time.CreatePointInTimeRequest;
+import org.opensearch.client.opensearch.core.point_in_time.CreatePointInTimeResponse;
+import org.opensearch.client.opensearch.core.point_in_time.DeletePointInTimeRequest;
+import org.opensearch.client.opensearch.core.point_in_time.DeletePointInTimeResponse;
+import org.opensearch.client.opensearch.core.point_in_time.ListAllPointInTimeRequest;
+import org.opensearch.client.opensearch.core.point_in_time.ListAllPointInTimeResponse;
 import org.opensearch.client.opensearch.dangling_indices.OpenSearchDanglingIndicesClient;
 import org.opensearch.client.opensearch.features.OpenSearchFeaturesClient;
 import org.opensearch.client.opensearch.indices.OpenSearchIndicesClient;
@@ -359,6 +365,39 @@ public final <TDocument> CreateResponse create(
 		return create(fn.apply(new CreateRequest.Builder<TDocument>()).build());
 	}
 
+	// ----- Endpoint: create_point_in_time
+
+	/**
+	 * Provides low-level information about the disk utilization of a PIT by
+	 * describing its Lucene segments.
+	 * 
+	 *
+	 */
+
+	public CreatePointInTimeResponse createPointInTime(CreatePointInTimeRequest request)
+			throws IOException, OpenSearchException {
+		@SuppressWarnings("unchecked")
+		JsonEndpoint<CreatePointInTimeRequest, CreatePointInTimeResponse, ErrorResponse> endpoint = (JsonEndpoint<CreatePointInTimeRequest, CreatePointInTimeResponse, ErrorResponse>) CreatePointInTimeRequest._ENDPOINT;
+
+		return this.transport.performRequest(request, endpoint, this.transportOptions);
+	}
+
+	/**
+	 * Provides low-level information about the disk utilization of a PIT by
+	 * describing its Lucene segments.
+	 * 
+	 * @param fn
+	 *           a function that initializes a builder to create the
+	 *           {@link CreatePointInTimeRequest}
+	 *
+	 */
+
+	public final CreatePointInTimeResponse createPointInTime(
+			Function<CreatePointInTimeRequest.Builder, ObjectBuilder<CreatePointInTimeRequest>> fn)
+			throws IOException, OpenSearchException {
+		return createPointInTime(fn.apply(new CreatePointInTimeRequest.Builder()).build());
+	}
+
 	// ----- Endpoint: delete
 
 	/**
@@ -389,6 +428,37 @@ public final DeleteResponse delete(Function<DeleteRequest.Builder, ObjectBuilder
 		return delete(fn.apply(new DeleteRequest.Builder()).build());
 	}
 
+	// ----- Endpoint: delete_point_in_time
+
+	/**
+	 * Delete Point In Time
+	 * 
+	 *
+	 */
+
+	public DeletePointInTimeResponse deletePointInTime(DeletePointInTimeRequest request)
+			throws IOException, OpenSearchException {
+		@SuppressWarnings("unchecked")
+		JsonEndpoint<DeletePointInTimeRequest, DeletePointInTimeResponse, ErrorResponse> endpoint = (JsonEndpoint<DeletePointInTimeRequest, DeletePointInTimeResponse, ErrorResponse>) DeletePointInTimeRequest._ENDPOINT;
+
+		return this.transport.performRequest(request, endpoint, this.transportOptions);
+	}
+
+	/**
+	 * Delete Point In Time
+	 * 
+	 * @param fn
+	 *           a function that initializes a builder to create the
+	 *           {@link DeletePointInTimeRequest}
+	 *
+	 */
+
+	public final DeletePointInTimeResponse deletePointInTime(
+			Function<DeletePointInTimeRequest.Builder, ObjectBuilder<DeletePointInTimeRequest>> fn)
+			throws IOException, OpenSearchException {
+		return deletePointInTime(fn.apply(new DeletePointInTimeRequest.Builder()).build());
+	}
+
 	// ----- Endpoint: delete_by_query
 
 	/**
@@ -790,6 +860,19 @@ public InfoResponse info() throws IOException, OpenSearchException {
 		return this.transport.performRequest(InfoRequest._INSTANCE, InfoRequest._ENDPOINT, this.transportOptions);
 	}
 
+	// ----- Endpoint: list_point_in_time
+
+	/**
+	 * List all Point In Time
+	 * 
+	 *
+	 */
+
+	public ListAllPointInTimeResponse listAllPointInTime()
+			throws IOException, OpenSearchException {
+			return this.transport.performRequest(ListAllPointInTimeRequest._INSTANCE, ListAllPointInTimeRequest._ENDPOINT, this.transportOptions);
+	}
+
 	// ----- Endpoint: mget
 
 	/**

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

@@ -426,6 +426,20 @@ public CompletableFuture<NodesResponse> nodes() throws IOException, OpenSearchEx
 				this.transportOptions);
 	}
 
+	// ----- Endpoint: cat.point_in_time_segments
+
+	/**
+	 * Provides low-level information about the disk utilization of a PIT by
+	 * describing its Lucene segments.
+	 * 
+	 *
+	 */
+	public CompletableFuture<SegmentsResponse> pointInTimeSegments() throws IOException, OpenSearchException {
+		return this.transport.performRequestAsync(new PointInTimeSegmentsRequest.Builder().build(),
+				PointInTimeSegmentsRequest._ENDPOINT,
+				this.transportOptions);
+	}
+
 	// ----- Endpoint: cat.pending_tasks
 
 	/**

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

@@ -414,6 +414,47 @@ public NodesResponse nodes() throws IOException, OpenSearchException {
 				this.transportOptions);
 	}
 
+	// ----- Endpoint: cat.point_in_time_segments
+
+	/**
+	 * Provides low-level information about the disk utilization of a PIT by
+	 * describing its Lucene segments.
+	 * 
+	 *
+	 */
+	public SegmentsResponse pointInTimeSegments(PointInTimeSegmentsRequest request)
+			throws IOException, OpenSearchException {
+		@SuppressWarnings("unchecked")
+		JsonEndpoint<PointInTimeSegmentsRequest, SegmentsResponse, ErrorResponse> endpoint = (JsonEndpoint<PointInTimeSegmentsRequest, SegmentsResponse, ErrorResponse>) PointInTimeSegmentsRequest._ENDPOINT;
+
+		return this.transport.performRequest(request, endpoint, this.transportOptions);
+	}
+
+	/**
+	 * Provides low-level information about the disk utilization of a PIT by
+	 * describing its Lucene segments.
+	 * 
+	 * * @param fn
+	 * a function that initializes a builder to create the
+	 * {@link PointInTimeSegmentsRequest}
+	 */
+
+	public final SegmentsResponse pointInTimeSegments(Function<PointInTimeSegmentsRequest.Builder, ObjectBuilder<PointInTimeSegmentsRequest>> fn)
+			throws IOException, OpenSearchException {
+		return pointInTimeSegments(fn.apply(new PointInTimeSegmentsRequest.Builder()).build());
+	}
+
+	/**
+	 * Provides low-level information about the disk utilization of a PIT by
+	 * describing its Lucene segments.
+	 * 
+	 */
+	public SegmentsResponse pointInTimeSegments() throws IOException, OpenSearchException {
+		return this.transport.performRequest(new PointInTimeSegmentsRequest.Builder().build(), 
+				PointInTimeSegmentsRequest._ENDPOINT,
+				this.transportOptions);
+	}
+
 	// ----- Endpoint: cat.pending_tasks
 
 	/**