Added javadoc

Author: sohaibiftikhar

client/rest-high-level/src/main/java/org/elasticsearch/client/RestHighLevelClient.java

@@ -374,7 +374,7 @@ public final void bulkAsync(BulkRequest bulkRequest, RequestOptions options, Act
     }
 
     /**
-     * Executes a bulk request using the Bulk API.
+     * Executes a reindex request.
      * See <a href="https://www.elastic.co/guide/en/elasticsearch/reference/current/docs-reindex.html">Reindex API on elastic.co</a>
      * @param reindexRequest the request
      * @param options the request options (e.g. headers), use {@link RequestOptions#DEFAULT} if nothing needs to be customized
@@ -388,7 +388,7 @@ public final BulkByScrollResponse reindex(ReindexRequest reindexRequest, Request
     }
 
     /**
-     * Asynchronously executes a bulk request using the Bulk API.
+     * Asynchronously executes a reindex request.
      * See <a href="https://www.elastic.co/guide/en/elasticsearch/reference/current/docs-reindex.html">Reindex API on elastic.co</a>
      * @param reindexRequest the request
      * @param options the request options (e.g. headers), use {@link RequestOptions#DEFAULT} if nothing needs to be customized

server/src/main/java/org/elasticsearch/index/reindex/BulkByScrollResponseBuilder.java

@@ -21,21 +21,25 @@
 
 import org.elasticsearch.common.unit.TimeValue;
 import org.elasticsearch.action.bulk.BulkItemResponse.Failure;
+import org.elasticsearch.common.xcontent.ObjectParser;
 import org.elasticsearch.index.reindex.ScrollableHitSource.SearchFailure;
 import org.elasticsearch.index.reindex.BulkByScrollTask.StatusBuilder;
 
 import java.util.ArrayList;
 import java.util.List;
 import java.util.concurrent.TimeUnit;
 
-public class BulkByScrollResponseBuilder extends StatusBuilder {
+/**
+ * Helps build a {@link BulkByScrollResponse}. Used by an instance of {@link ObjectParser} when parsing from XContent.
+ */
+class BulkByScrollResponseBuilder extends StatusBuilder {
     private TimeValue took;
     private BulkByScrollTask.Status status;
     private List<Failure> bulkFailures = new ArrayList<>();
     private List<SearchFailure> searchFailures = new ArrayList<>();
     private boolean timedOut;
 
-    public BulkByScrollResponseBuilder() {}
+    BulkByScrollResponseBuilder() {}
 
     public void setTook(long took) {
         setTook(new TimeValue(took, TimeUnit.MILLISECONDS));

server/src/main/java/org/elasticsearch/index/reindex/BulkByScrollTask.java

@@ -202,6 +202,11 @@ public boolean shouldCancelChildrenOnCancellation() {
         return true;
     }
 
+    /**
+     * This class acts as a builder for {@link Status}. Once the {@link Status} object is built by calling
+     * {@link #buildStatus()} it is immutable. Used by an instance of {@link ObjectParser} when parsing from
+     * XContent.
+     */
     public static class StatusBuilder {
         private Integer sliceId = null;
         private Long total = null;
@@ -558,6 +563,11 @@ public XContentBuilder toXContent(XContentBuilder builder, Params params) throws
             return builder.endObject();
         }
 
+        /**
+         * We need to write a manual parser for this because of {@link StatusOrException}. Since
+         * {@link StatusOrException#fromXContent(XContentParser)} tries to peek at a field first before deciding
+         * what needs to be it cannot use an {@link ObjectParser}.
+         */
         public XContentBuilder innerXContent(XContentBuilder builder, Params params)
                 throws IOException {
             if (sliceId != null) {
@@ -961,6 +971,13 @@ public XContentBuilder toXContent(XContentBuilder builder, Params params) throws
             return builder;
         }
 
+        /**
+         * Since {@link StatusOrException} can contain either an {@link Exception} or a {@link Status} we need to peek
+         * at a field first before deciding what needs to be parsed since the same object could contains either.
+         * The {@link #EXPECTED_EXCEPTION_FIELDS} contains the fields that are expected when the serialised object
+         * was an instance of exception and the {@link Status#FIELDS_SET} is the set of fields expected when the
+         * serialized object was an instance of Status.
+         */
         public static StatusOrException fromXContent(XContentParser parser) throws IOException {
             XContentParser.Token token = parser.currentToken();
             if (token == null) {

server/src/main/java/org/elasticsearch/index/reindex/ReindexRequest.java

@@ -45,7 +45,7 @@
  * to which documents are written.
  */
 public class ReindexRequest extends AbstractBulkIndexByScrollRequest<ReindexRequest>
-    implements CompositeIndicesRequest, ToXContentObject {
+                            implements CompositeIndicesRequest, ToXContentObject {
     /**
      * Prototype for index requests.
      */
@@ -128,25 +128,37 @@ private boolean routingIsValid() {
         }
     }
 
+    /**
+     * Set the indices which will act as the source for the ReindexRequest
+     */
     public ReindexRequest setSourceIndices(String... sourceIndices) {
         if (sourceIndices != null) {
             this.getSearchRequest().indices(sourceIndices);
         }
         return this;
     }
 
+    /**
+     * Set the document types which need to be copied from the source indices
+     */
     public ReindexRequest setSourceDocTypes(String... docTypes) {
         if (docTypes != null) {
             this.getSearchRequest().types(docTypes);
         }
         return this;
     }
 
+    /**
+     * Sets the scroll size for setting how many documents are to be processed in one batch during reindex
+     */
     public ReindexRequest setSourceBatchSize(int size) {
         this.getSearchRequest().source().size(size);
         return this;
     }
 
+    /**
+     * Set the query for selecting documents from the source indices
+     */
     public ReindexRequest setSourceQuery(QueryBuilder queryBuilder) {
         if (queryBuilder != null) {
             this.getSearchRequest().source().query(queryBuilder);
@@ -158,34 +170,51 @@ public ReindexRequest setSourceQuery(QueryBuilder queryBuilder) {
      * Add a sort against the given field name.
      *
      * @param name The name of the field to sort by
+     * @param order The order in which to sort
      */
     public ReindexRequest addSortField(String name, SortOrder order) {
         this.getSearchRequest().source().sort(name, order);
         return this;
     }
 
+    /**
+     * Set the target index for the ReindexRequest
+     */
     public ReindexRequest setDestIndex(String destIndex) {
         if (destIndex != null) {
             this.getDestination().index(destIndex);
         }
         return this;
     }
 
+    /**
+     * Set the document type for the destination index
+     */
     public ReindexRequest setDestDocType(String docType) {
         this.getDestination().type(docType);
         return this;
     }
 
+    /**
+     * Set the routing to decide which shard the documents need to be routed to
+     */
     public ReindexRequest setDestRouting(String routing) {
         this.getDestination().routing(routing);
         return this;
     }
 
+    /**
+     * Set the version type for the target index. A {@link VersionType#EXTERNAL} helps preserve the version
+     * if the document already existed in the target index.
+     */
     public ReindexRequest setDestVersionType(VersionType versionType) {
         this.getDestination().versionType(versionType);
         return this;
     }
 
+    /**
+     * Allows to set the ingest pipeline for the target index.
+     */
     public void setDestPipeline(String pipelineName) {
         this.getDestination().setPipeline(pipelineName);
     }
@@ -199,15 +228,24 @@ public ReindexRequest setDestOpType(String opType) {
         return this;
     }
 
-    public IndexRequest getDestination() {
-        return destination;
-    }
-
+    /**
+     * Set the {@link RemoteInfo} if the source indices are in a remote cluster.
+     */
     public ReindexRequest setRemoteInfo(RemoteInfo remoteInfo) {
         this.remoteInfo = remoteInfo;
         return this;
     }
 
+    /**
+     * Gets the target for this reindex request in the for of an {@link IndexRequest}
+     */
+    public IndexRequest getDestination() {
+        return destination;
+    }
+
+    /**
+     * Get the {@link RemoteInfo} if it was set for this request.
+     */
     public RemoteInfo getRemoteInfo() {
         return remoteInfo;
     }