From f416ed494936b5b9fd98bbdf75e8f46019346fc9 Mon Sep 17 00:00:00 2001
From: Martijn van Groningen <martijn.v.groningen@gmail.com>
Date: Fri, 29 Aug 2014 11:53:21 +0200
Subject: [PATCH] Docs: added missing jdocs for the percolate client classes.

Also made constructors were possible package protected
and removed some useless getters in percolator source builder.
---
 .../percolate/MultiPercolateRequest.java      | 43 ++++++++++
 .../MultiPercolateRequestBuilder.java         |  1 +
 .../percolate/MultiPercolateResponse.java     | 44 ++++++++--
 .../action/percolate/PercolateRequest.java    | 86 ++++++++++++++++++-
 .../percolate/PercolateRequestBuilder.java    | 56 ++++++++----
 .../action/percolate/PercolateResponse.java   | 35 ++++++--
 .../percolate/PercolateSourceBuilder.java     | 57 ++++++------
 .../cluster/NoMasterNodeTests.java            |  5 +-
 8 files changed, 263 insertions(+), 64 deletions(-)

diff --git a/src/main/java/org/elasticsearch/action/percolate/MultiPercolateRequest.java b/src/main/java/org/elasticsearch/action/percolate/MultiPercolateRequest.java
index 835f80c7512..41414bfa696 100644
--- a/src/main/java/org/elasticsearch/action/percolate/MultiPercolateRequest.java
+++ b/src/main/java/org/elasticsearch/action/percolate/MultiPercolateRequest.java
@@ -45,6 +45,7 @@ import java.util.Map;
 import static org.elasticsearch.action.ValidateActions.addValidationError;
 
 /**
+ * A multi percolate request that encapsulates multiple {@link PercolateRequest} instances in a single api call.
  */
 public class MultiPercolateRequest extends ActionRequest<MultiPercolateRequest> implements CompositeIndicesRequest {
 
@@ -53,10 +54,16 @@ public class MultiPercolateRequest extends ActionRequest<MultiPercolateRequest>
     private IndicesOptions indicesOptions = IndicesOptions.strictExpandOpenAndForbidClosed();
     private List<PercolateRequest> requests = Lists.newArrayList();
 
+    /**
+     * Embeds a percolate request to this multi percolate request
+     */
     public MultiPercolateRequest add(PercolateRequestBuilder requestBuilder) {
         return add(requestBuilder.request());
     }
 
+    /**
+     * Embeds a percolate request to this multi percolate request
+     */
     public MultiPercolateRequest add(PercolateRequest request) {
         if (request.indices() == null && indices != null) {
             request.indices(indices);
@@ -71,10 +78,16 @@ public class MultiPercolateRequest extends ActionRequest<MultiPercolateRequest>
         return this;
     }
 
+    /**
+     * Embeds a percolate request which request body is defined as raw bytes to this multi percolate request
+     */
     public MultiPercolateRequest add(byte[] data, int from, int length, boolean contentUnsafe) throws Exception {
         return add(new BytesArray(data, from, length), contentUnsafe, true);
     }
 
+    /**
+     * Embeds a percolate request which request body is defined as raw bytes to this multi percolate request
+     */
     public MultiPercolateRequest add(BytesReference data, boolean contentUnsafe, boolean allowExplicitIndex) throws Exception {
         XContent xContent = XContentFactory.xContent(data);
         int from = 0;
@@ -313,32 +326,62 @@ public class MultiPercolateRequest extends ActionRequest<MultiPercolateRequest>
         return -1;
     }
 
+    /**
+     * @return The list of already set percolate requests.
+     */
     public List<PercolateRequest> requests() {
         return this.requests;
     }
 
+    /**
+     * @return Returns the {@link IndicesOptions} that is used as default for all percolate requests.
+     */
     public IndicesOptions indicesOptions() {
         return indicesOptions;
     }
 
+    /**
+     * Sets the {@link IndicesOptions} for all percolate request that don't have this set.
+     *
+     * Warning: This should be set before adding any percolate requests. Setting this after adding percolate requests
+     * will have no effect on any percolate requests already added.
+     */
     public MultiPercolateRequest indicesOptions(IndicesOptions indicesOptions) {
         this.indicesOptions = indicesOptions;
         return this;
     }
 
+    /**
+     * @return The default indices for all percolate request.
+     */
     public String[] indices() {
         return indices;
     }
 
+    /**
+     * Sets the default indices for any percolate request that doesn't have indices defined.
+     *
+     * Warning: This should be set before adding any percolate requests. Setting this after adding percolate requests
+     * will have no effect on any percolate requests already added.
+     */
     public MultiPercolateRequest indices(String... indices) {
         this.indices = indices;
         return this;
     }
 
+    /**
+     * @return Sets the default type for all percolate requests
+     */
     public String documentType() {
         return documentType;
     }
 
+    /**
+     * Sets the default document type for any percolate request that doesn't have a document type set.
+     *
+     * Warning: This should be set before adding any percolate requests. Setting this after adding percolate requests
+     * will have no effect on any percolate requests already added.
+     */
     public MultiPercolateRequest documentType(String type) {
         this.documentType = type;
         return this;
diff --git a/src/main/java/org/elasticsearch/action/percolate/MultiPercolateRequestBuilder.java b/src/main/java/org/elasticsearch/action/percolate/MultiPercolateRequestBuilder.java
index 8ce72213d53..7cc51242fef 100644
--- a/src/main/java/org/elasticsearch/action/percolate/MultiPercolateRequestBuilder.java
+++ b/src/main/java/org/elasticsearch/action/percolate/MultiPercolateRequestBuilder.java
@@ -24,6 +24,7 @@ import org.elasticsearch.action.support.IndicesOptions;
 import org.elasticsearch.client.Client;
 
 /**
+ * A builder for to ease the use of defining a {@link MultiPercolateRequest} instance.
  */
 public class MultiPercolateRequestBuilder extends ActionRequestBuilder<MultiPercolateRequest, MultiPercolateResponse, MultiPercolateRequestBuilder, Client> {
 
diff --git a/src/main/java/org/elasticsearch/action/percolate/MultiPercolateResponse.java b/src/main/java/org/elasticsearch/action/percolate/MultiPercolateResponse.java
index 27e9ce44f65..882682de4e4 100644
--- a/src/main/java/org/elasticsearch/action/percolate/MultiPercolateResponse.java
+++ b/src/main/java/org/elasticsearch/action/percolate/MultiPercolateResponse.java
@@ -20,6 +20,7 @@ package org.elasticsearch.action.percolate;
 
 import com.google.common.collect.Iterators;
 import org.elasticsearch.action.ActionResponse;
+import org.elasticsearch.common.Nullable;
 import org.elasticsearch.common.io.stream.StreamInput;
 import org.elasticsearch.common.io.stream.StreamOutput;
 import org.elasticsearch.common.io.stream.Streamable;
@@ -31,16 +32,20 @@ import java.io.IOException;
 import java.util.Iterator;
 
 /**
+ * Represents the response of a multi percolate request.
+ *
+ * Each item represents the response of a percolator request and the order of the items is in the same order as the
+ * percolator requests were defined in the multi percolate request.
  */
 public class MultiPercolateResponse extends ActionResponse implements Iterable<MultiPercolateResponse.Item>, ToXContent {
 
     private Item[] items;
 
-    public MultiPercolateResponse(Item[] items) {
+    MultiPercolateResponse(Item[] items) {
         this.items = items;
     }
 
-    public MultiPercolateResponse() {
+    MultiPercolateResponse() {
         this.items = new Item[0];
     }
 
@@ -49,10 +54,16 @@ public class MultiPercolateResponse extends ActionResponse implements Iterable<M
         return Iterators.forArray(items);
     }
 
+    /**
+     * Same as {@link #getItems()}
+     */
     public Item[] items() {
         return items;
     }
 
+    /**
+     * @return the percolate responses as items.
+     */
     public Item[] getItems() {
         return items;
     }
@@ -95,38 +106,61 @@ public class MultiPercolateResponse extends ActionResponse implements Iterable<M
         }
     }
 
+    /**
+     * Encapsulates a single percolator response which may contain an error or the actual percolator response itself.
+     */
     public static class Item implements Streamable {
 
         private PercolateResponse response;
         private String errorMessage;
 
-        public Item(PercolateResponse response) {
+        Item(PercolateResponse response) {
             this.response = response;
         }
 
-        public Item(String errorMessage) {
+        Item(String errorMessage) {
             this.errorMessage = errorMessage;
         }
 
-        public Item() {
+        Item() {
         }
 
+        /**
+         * @return The percolator response or <code>null</code> if there was error.
+         */
+        @Nullable
         public PercolateResponse response() {
             return response;
         }
 
+        /**
+         * @return An error description if there was an error or <code>null</code> if the percolate request was successful
+         */
+        @Nullable
         public String errorMessage() {
             return errorMessage;
         }
 
+        /**
+         * @return The percolator response or <code>null</code> if there was error.
+         */
+        @Nullable
         public PercolateResponse getResponse() {
             return response;
         }
 
+        /**
+         * @return An error description if there was an error or <code>null</code> if the percolate request was successful
+         */
+        @Nullable
         public String getErrorMessage() {
             return errorMessage;
         }
 
+        /**
+         * @return <code>true</code> if the percolator request that this item represents failed otherwise
+         * <code>false</code> is returned.
+         */
         public boolean isFailure() {
             return errorMessage != null;
         }
diff --git a/src/main/java/org/elasticsearch/action/percolate/PercolateRequest.java b/src/main/java/org/elasticsearch/action/percolate/PercolateRequest.java
index 8071e8fb1ed..07ef42e90f3 100644
--- a/src/main/java/org/elasticsearch/action/percolate/PercolateRequest.java
+++ b/src/main/java/org/elasticsearch/action/percolate/PercolateRequest.java
@@ -30,9 +30,11 @@ import org.elasticsearch.common.bytes.BytesArray;
 import org.elasticsearch.common.bytes.BytesReference;
 import org.elasticsearch.common.io.stream.StreamInput;
 import org.elasticsearch.common.io.stream.StreamOutput;
+import org.elasticsearch.common.xcontent.ToXContent;
 import org.elasticsearch.common.xcontent.XContentBuilder;
 import org.elasticsearch.common.xcontent.XContentFactory;
 import org.elasticsearch.common.xcontent.XContentType;
+import org.elasticsearch.search.builder.SearchSourceBuilderException;
 
 import java.io.IOException;
 import java.util.List;
@@ -41,7 +43,7 @@ import java.util.Map;
 import static org.elasticsearch.action.ValidateActions.addValidationError;
 
 /**
- *
+ * A request to execute a percolate operation.
  */
 public class PercolateRequest extends BroadcastOperationRequest<PercolateRequest> implements CompositeIndicesRequest {
 
@@ -60,10 +62,13 @@ public class PercolateRequest extends BroadcastOperationRequest<PercolateRequest
     // to hold it temporarily in an easy way
     long startTime;
 
+    /**
+     * Constructor only for internal usage.
+     */
     public PercolateRequest() {
     }
 
-    public PercolateRequest(PercolateRequest request, BytesReference docSource) {
+    PercolateRequest(PercolateRequest request, BytesReference docSource) {
         super(request.indices());
         this.documentType = request.documentType();
         this.routing = request.routing();
@@ -84,37 +89,67 @@ public class PercolateRequest extends BroadcastOperationRequest<PercolateRequest
         return requests;
     }
 
+    /**
+     * Getter for {@link #documentType(String)}
+     */
     public String documentType() {
         return documentType;
     }
 
+    /**
+     * Sets the type of the document to percolate. This is important as it selects the mapping to be used to parse
+     * the document.
+     */
     public PercolateRequest documentType(String type) {
         this.documentType = type;
         return this;
     }
 
+    /**
+     * Getter for {@link #routing(String)}
+     */
     public String routing() {
         return routing;
     }
 
+    /**
+     * A comma separated list of routing values to control the shards the search will be executed on.
+     */
     public PercolateRequest routing(String routing) {
         this.routing = routing;
         return this;
     }
 
+    /**
+     * Getter for {@link #preference(String)}
+     */
     public String preference() {
         return preference;
     }
 
+    /**
+     * Sets the preference to execute the search. Defaults to randomize across shards. Can be set to
+     * <tt>_local</tt> to prefer local shards, <tt>_primary</tt> to execute only on primary shards, or
+     * a custom value, which guarantees that the same order will be used across different requests.
+     */
     public PercolateRequest preference(String preference) {
         this.preference = preference;
         return this;
     }
 
+    /**
+     * Getter for {@link #getRequest(GetRequest)}
+     */
     public GetRequest getRequest() {
         return getRequest;
     }
 
+    /**
+     * This defines where to fetch the document to be percolated from, which is an alternative of defining the document
+     * to percolate in the request body.
+     *
+     * If this defined than this will override the document specified in the request body.
+     */
     public PercolateRequest getRequest(GetRequest getRequest) {
         this.getRequest = getRequest;
         return this;
@@ -131,14 +166,23 @@ public class PercolateRequest extends BroadcastOperationRequest<PercolateRequest
         }
     }
 
+    /**
+     * @return The request body in its raw form.
+     */
     public BytesReference source() {
         return source;
     }
 
+    /**
+     * Raw version of {@link #source(PercolateSourceBuilder)}
+     */
     public PercolateRequest source(Map document) throws ElasticsearchGenerationException {
         return source(document, Requests.CONTENT_TYPE);
     }
 
+    /**
+     * Raw version of {@link #source(PercolateSourceBuilder)}
+     */
     @SuppressWarnings("unchecked")
     public PercolateRequest source(Map document, XContentType contentType) throws ElasticsearchGenerationException {
         try {
@@ -150,46 +194,82 @@ public class PercolateRequest extends BroadcastOperationRequest<PercolateRequest
         }
     }
 
+    /**
+     * Raw version of {@link #source(PercolateSourceBuilder)}
+     */
     public PercolateRequest source(String document) {
         this.source = new BytesArray(document);
         this.unsafe = false;
         return this;
     }
 
+    /**
+     * Raw version of {@link #source(PercolateSourceBuilder)}
+     */
     public PercolateRequest source(XContentBuilder documentBuilder) {
         source = documentBuilder.bytes();
         unsafe = false;
         return this;
     }
 
+    /**
+     * Raw version of {@link #source(PercolateSourceBuilder)}
+     */
     public PercolateRequest source(byte[] document) {
         return source(document, 0, document.length);
     }
 
+    /**
+     * Raw version of {@link #source(PercolateSourceBuilder)}
+     */
     public PercolateRequest source(byte[] source, int offset, int length) {
         return source(source, offset, length, false);
     }
 
+    /**
+     * Raw version of {@link #source(PercolateSourceBuilder)}
+     */
     public PercolateRequest source(byte[] source, int offset, int length, boolean unsafe) {
         return source(new BytesArray(source, offset, length), unsafe);
     }
 
+    /**
+     * Raw version of {@link #source(PercolateSourceBuilder)}
+     */
     public PercolateRequest source(BytesReference source, boolean unsafe) {
         this.source = source;
         this.unsafe = unsafe;
         return this;
     }
 
+    /**
+     * Sets the request body definition for this percolate request as raw bytes.
+     *
+     * This is the preferred way to set the request body.
+     */
     public PercolateRequest source(PercolateSourceBuilder sourceBuilder) {
-        this.source = sourceBuilder.buildAsBytes(Requests.CONTENT_TYPE);
+        try {
+            XContentBuilder builder = XContentFactory.contentBuilder(Requests.CONTENT_TYPE);
+            sourceBuilder.toXContent(builder, ToXContent.EMPTY_PARAMS);
+            this.source = builder.bytes();
+        } catch (Exception e) {
+            throw new SearchSourceBuilderException("Failed to build search source", e);
+        }
         this.unsafe = false;
         return this;
     }
 
+    /**
+     * Getter for {@link #onlyCount(boolean)}
+     */
     public boolean onlyCount() {
         return onlyCount;
     }
 
+    /**
+     * Sets whether this percolate request should only count the number of percolator queries that matches with
+     * the document being percolated and don't keep track of the actual queries that have matched.
+     */
     public PercolateRequest onlyCount(boolean onlyCount) {
         this.onlyCount = onlyCount;
         return this;
diff --git a/src/main/java/org/elasticsearch/action/percolate/PercolateRequestBuilder.java b/src/main/java/org/elasticsearch/action/percolate/PercolateRequestBuilder.java
index 5d6af5dd68a..e2f4e20d934 100644
--- a/src/main/java/org/elasticsearch/action/percolate/PercolateRequestBuilder.java
+++ b/src/main/java/org/elasticsearch/action/percolate/PercolateRequestBuilder.java
@@ -35,7 +35,7 @@ import org.elasticsearch.search.sort.SortBuilder;
 import java.util.Map;
 
 /**
- *
+ * A builder the easy to use of defining a percolate request.
  */
 public class PercolateRequestBuilder extends BroadcastOperationRequestBuilder<PercolateRequest, PercolateResponse, PercolateRequestBuilder, Client> {
 
@@ -46,7 +46,8 @@ public class PercolateRequestBuilder extends BroadcastOperationRequestBuilder<Pe
     }
 
     /**
-     * Sets the type of the document to percolate.
+     * Sets the type of the document to percolate. This is important as it selects the mapping to be used to parse
+     * the document.
      */
     public PercolateRequestBuilder setDocumentType(String type) {
         request.documentType(type);
@@ -97,7 +98,7 @@ public class PercolateRequestBuilder extends BroadcastOperationRequestBuilder<Pe
     }
 
     /**
-     * Limits the maximum number of percolate query matches to be returned.
+     * Delegates to {@link PercolateSourceBuilder#setSize(int)}}
      */
     public PercolateRequestBuilder setSize(int size) {
         sourceBuilder().setSize(size);
@@ -105,7 +106,7 @@ public class PercolateRequestBuilder extends BroadcastOperationRequestBuilder<Pe
     }
 
     /**
-     * Similar as {@link #setScore(boolean)}, but whether to sort by the score descending.
+     * Delegates to {@link PercolateSourceBuilder#setSort(boolean)}}
      */
     public PercolateRequestBuilder setSortByScore(boolean sort) {
         sourceBuilder().setSort(sort);
@@ -113,7 +114,7 @@ public class PercolateRequestBuilder extends BroadcastOperationRequestBuilder<Pe
     }
 
     /**
-     * Adds
+     * Delegates to {@link PercolateSourceBuilder#addSort(SortBuilder)}
      */
     public PercolateRequestBuilder addSort(SortBuilder sort) {
         sourceBuilder().addSort(sort);
@@ -121,8 +122,7 @@ public class PercolateRequestBuilder extends BroadcastOperationRequestBuilder<Pe
     }
 
     /**
-     * Whether to compute a score for each match and include it in the response. The score is based on
-     * {@link #setPercolateQuery(QueryBuilder)}}.
+     * Delegates to {@link PercolateSourceBuilder#setSort(boolean)}}
      */
     public PercolateRequestBuilder setScore(boolean score) {
         sourceBuilder().setTrackScores(score);
@@ -130,8 +130,7 @@ public class PercolateRequestBuilder extends BroadcastOperationRequestBuilder<Pe
     }
 
     /**
-     * Sets a query to reduce the number of percolate queries to be evaluated and score the queries that match based
-     * on this query.
+     * Delegates to {@link PercolateSourceBuilder#setDoc(PercolateSourceBuilder.DocBuilder)}
      */
     public PercolateRequestBuilder setPercolateDoc(PercolateSourceBuilder.DocBuilder docBuilder) {
         sourceBuilder().setDoc(docBuilder);
@@ -139,8 +138,7 @@ public class PercolateRequestBuilder extends BroadcastOperationRequestBuilder<Pe
     }
 
     /**
-     * Sets a query to reduce the number of percolate queries to be evaluated and score the queries that match based
-     * on this query.
+     * Delegates to {@link PercolateSourceBuilder#setQueryBuilder(QueryBuilder)}
      */
     public PercolateRequestBuilder setPercolateQuery(QueryBuilder queryBuilder) {
         sourceBuilder().setQueryBuilder(queryBuilder);
@@ -148,7 +146,7 @@ public class PercolateRequestBuilder extends BroadcastOperationRequestBuilder<Pe
     }
 
     /**
-     * Sets a filter to reduce the number of percolate queries to be evaluated.
+     * Delegates to {@link PercolateSourceBuilder#setFilterBuilder(FilterBuilder)}
      */
     public PercolateRequestBuilder setPercolateFilter(FilterBuilder filterBuilder) {
         sourceBuilder().setFilterBuilder(filterBuilder);
@@ -156,7 +154,7 @@ public class PercolateRequestBuilder extends BroadcastOperationRequestBuilder<Pe
     }
 
     /**
-     * Enables highlighting for the percolate document. Per matched percolate query highlight the percolate document.
+     * Delegates to {@link PercolateSourceBuilder#setHighlightBuilder(HighlightBuilder)}
      */
     public PercolateRequestBuilder setHighlightBuilder(HighlightBuilder highlightBuilder) {
         sourceBuilder().setHighlightBuilder(highlightBuilder);
@@ -164,7 +162,7 @@ public class PercolateRequestBuilder extends BroadcastOperationRequestBuilder<Pe
     }
 
     /**
-     * Add a aggregation definition.
+     * Delegates to {@link PercolateSourceBuilder#addAggregation(AggregationBuilder)}
      */
     public PercolateRequestBuilder addAggregation(AggregationBuilder aggregationBuilder) {
         sourceBuilder().addAggregation(aggregationBuilder);
@@ -172,53 +170,81 @@ public class PercolateRequestBuilder extends BroadcastOperationRequestBuilder<Pe
     }
 
     /**
-     * Sets the raw percolate request body.
+     * Sets the percolate request definition directly on the request.
+     * This will overwrite any definitions set by any of the delegate methods.
      */
     public PercolateRequestBuilder setSource(PercolateSourceBuilder source) {
         sourceBuilder = source;
         return this;
     }
 
+    /**
+     * Raw variant of {@link #setSource(PercolateSourceBuilder)}
+     */
     public PercolateRequestBuilder setSource(Map<String, Object> source) {
         request.source(source);
         return this;
     }
 
+    /**
+     * Raw variant of {@link #setSource(PercolateSourceBuilder)}
+     */
     public PercolateRequestBuilder setSource(Map<String, Object> source, XContentType contentType) {
         request.source(source, contentType);
         return this;
     }
 
+    /**
+     * Raw variant of {@link #setSource(PercolateSourceBuilder)}
+     */
     public PercolateRequestBuilder setSource(String source) {
         request.source(source);
         return this;
     }
 
+    /**
+     * Raw variant of {@link #setSource(PercolateSourceBuilder)}
+     */
     public PercolateRequestBuilder setSource(XContentBuilder sourceBuilder) {
         request.source(sourceBuilder);
         return this;
     }
 
+    /**
+     * Raw variant of {@link #setSource(PercolateSourceBuilder)}
+     */
     public PercolateRequestBuilder setSource(BytesReference source) {
         request.source(source, false);
         return this;
     }
 
+    /**
+     * Raw variant of {@link #setSource(PercolateSourceBuilder)}
+     */
     public PercolateRequestBuilder setSource(BytesReference source, boolean unsafe) {
         request.source(source, unsafe);
         return this;
     }
 
+    /**
+     * Raw variant of {@link #setSource(PercolateSourceBuilder)}
+     */
     public PercolateRequestBuilder setSource(byte[] source) {
         request.source(source);
         return this;
     }
 
+    /**
+     * Raw variant of {@link #setSource(PercolateSourceBuilder)}
+     */
     public PercolateRequestBuilder setSource(byte[] source, int offset, int length) {
         request.source(source, offset, length);
         return this;
     }
 
+    /**
+     * Raw variant of {@link #setSource(PercolateSourceBuilder)}
+     */
     public PercolateRequestBuilder setSource(byte[] source, int offset, int length, boolean unsafe) {
         request.source(source, offset, length, unsafe);
         return this;
diff --git a/src/main/java/org/elasticsearch/action/percolate/PercolateResponse.java b/src/main/java/org/elasticsearch/action/percolate/PercolateResponse.java
index 5c739696d5e..4999d88c2c9 100644
--- a/src/main/java/org/elasticsearch/action/percolate/PercolateResponse.java
+++ b/src/main/java/org/elasticsearch/action/percolate/PercolateResponse.java
@@ -20,6 +20,7 @@ package org.elasticsearch.action.percolate;
 
 import org.elasticsearch.action.ShardOperationFailedException;
 import org.elasticsearch.action.support.broadcast.BroadcastOperationResponse;
+import org.elasticsearch.common.Nullable;
 import org.elasticsearch.common.io.stream.StreamInput;
 import org.elasticsearch.common.io.stream.StreamOutput;
 import org.elasticsearch.common.io.stream.Streamable;
@@ -37,7 +38,7 @@ import java.io.IOException;
 import java.util.*;
 
 /**
- *
+ * Encapsulates the response of a percolator request.
  */
 public class PercolateResponse extends BroadcastOperationResponse implements Iterable<PercolateResponse.Match>, ToXContent {
 
@@ -48,7 +49,7 @@ public class PercolateResponse extends BroadcastOperationResponse implements Ite
     private long count;
     private InternalAggregations aggregations;
 
-    public PercolateResponse(int totalShards, int successfulShards, int failedShards, List<ShardOperationFailedException> shardFailures,
+    PercolateResponse(int totalShards, int successfulShards, int failedShards, List<ShardOperationFailedException> shardFailures,
                              Match[] matches, long count, long tookInMillis, InternalAggregations aggregations) {
         super(totalShards, successfulShards, failedShards, shardFailures);
         this.tookInMillis = tookInMillis;
@@ -57,7 +58,7 @@ public class PercolateResponse extends BroadcastOperationResponse implements Ite
         this.aggregations = aggregations;
     }
 
-    public PercolateResponse(int totalShards, int successfulShards, int failedShards, List<ShardOperationFailedException> shardFailures, long tookInMillis, Match[] matches) {
+    PercolateResponse(int totalShards, int successfulShards, int failedShards, List<ShardOperationFailedException> shardFailures, long tookInMillis, Match[] matches) {
         super(totalShards, successfulShards, failedShards, shardFailures);
         this.tookInMillis = tookInMillis;
         this.matches = matches;
@@ -66,10 +67,6 @@ public class PercolateResponse extends BroadcastOperationResponse implements Ite
     PercolateResponse() {
     }
 
-    public PercolateResponse(Match[] matches) {
-        this.matches = matches;
-    }
-
     /**
      * How long the percolate took.
      */
@@ -191,6 +188,9 @@ public class PercolateResponse extends BroadcastOperationResponse implements Ite
         out.writeOptionalStreamable(aggregations);
     }
 
+    /**
+     * Represents a query that has matched with the document that was percolated.
+     */
     public static class Match implements Streamable {
 
         private Text index;
@@ -198,6 +198,9 @@ public class PercolateResponse extends BroadcastOperationResponse implements Ite
         private float score;
         private Map<String, HighlightField> hl;
 
+        /**
+         * Constructor only for internal usage.
+         */
         public Match(Text index, Text id, float score, Map<String, HighlightField> hl) {
             this.id = id;
             this.score = score;
@@ -205,6 +208,9 @@ public class PercolateResponse extends BroadcastOperationResponse implements Ite
             this.hl = hl;
         }
 
+        /**
+         * Constructor only for internal usage.
+         */
         public Match(Text index, Text id, float score) {
             this.id = id;
             this.score = score;
@@ -214,18 +220,33 @@ public class PercolateResponse extends BroadcastOperationResponse implements Ite
         Match() {
         }
 
+        /**
+         * @return The index that the matched percolator query resides in.
+         */
         public Text getIndex() {
             return index;
         }
 
+        /**
+         * @return The id of the matched percolator query.
+         */
         public Text getId() {
             return id;
         }
 
+        /**
+         * @return If in the percolate request a query was specified this returns the score representing how well that
+         * query matched on the metadata associated with the matching query otherwise {@link Float#NaN} is returned.
+         */
         public float getScore() {
             return score;
         }
 
+        /**
+         * @return If highlighting was specified in the percolate request the this returns highlight snippets for each
+         * matching field in the document being percolated based on this query otherwise <code>null</code> is returned.
+         */
+        @Nullable
         public Map<String, HighlightField> getHighlightFields() {
             return hl;
         }
diff --git a/src/main/java/org/elasticsearch/action/percolate/PercolateSourceBuilder.java b/src/main/java/org/elasticsearch/action/percolate/PercolateSourceBuilder.java
index 5a8eefcaa15..f09e630f459 100644
--- a/src/main/java/org/elasticsearch/action/percolate/PercolateSourceBuilder.java
+++ b/src/main/java/org/elasticsearch/action/percolate/PercolateSourceBuilder.java
@@ -29,7 +29,6 @@ import org.elasticsearch.index.query.FilterBuilder;
 import org.elasticsearch.index.query.QueryBuilder;
 import org.elasticsearch.search.aggregations.AbstractAggregationBuilder;
 import org.elasticsearch.search.aggregations.AggregationBuilder;
-import org.elasticsearch.search.builder.SearchSourceBuilderException;
 import org.elasticsearch.search.highlight.HighlightBuilder;
 import org.elasticsearch.search.sort.ScoreSortBuilder;
 import org.elasticsearch.search.sort.SortBuilder;
@@ -48,23 +47,11 @@ public class PercolateSourceBuilder implements ToXContent {
     private QueryBuilder queryBuilder;
     private FilterBuilder filterBuilder;
     private Integer size;
-    private Boolean sort;
     private List<SortBuilder> sorts;
     private Boolean trackScores;
     private HighlightBuilder highlightBuilder;
     private List<AggregationBuilder> aggregations;
 
-    public DocBuilder percolateDocument() {
-        if (docBuilder == null) {
-            docBuilder = new DocBuilder();
-        }
-        return docBuilder;
-    }
-
-    public DocBuilder getDoc() {
-        return docBuilder;
-    }
-
     /**
      * Sets the document to run the percolate queries against.
      */
@@ -73,10 +60,6 @@ public class PercolateSourceBuilder implements ToXContent {
         return this;
     }
 
-    public QueryBuilder getQueryBuilder() {
-        return queryBuilder;
-    }
-
     /**
      * Sets a query to reduce the number of percolate queries to be evaluated and score the queries that match based
      * on this query.
@@ -86,10 +69,6 @@ public class PercolateSourceBuilder implements ToXContent {
         return this;
     }
 
-    public FilterBuilder getFilterBuilder() {
-        return filterBuilder;
-    }
-
     /**
      * Sets a filter to reduce the number of percolate queries to be evaluated.
      */
@@ -120,6 +99,8 @@ public class PercolateSourceBuilder implements ToXContent {
 
     /**
      * Adds a sort builder. Only sorting by score desc is supported.
+     *
+     * By default the matching percolator queries are returned in an undefined order.
      */
     public PercolateSourceBuilder addSort(SortBuilder sort) {
         if (sorts == null) {
@@ -147,7 +128,7 @@ public class PercolateSourceBuilder implements ToXContent {
     }
 
     /**
-     * Add an aggregationB definition.
+     * Add an aggregation definition.
      */
     public PercolateSourceBuilder addAggregation(AggregationBuilder aggregationBuilder) {
         if (aggregations == null) {
@@ -157,16 +138,6 @@ public class PercolateSourceBuilder implements ToXContent {
         return this;
     }
 
-    public BytesReference buildAsBytes(XContentType contentType) throws SearchSourceBuilderException {
-        try {
-            XContentBuilder builder = XContentFactory.contentBuilder(contentType);
-            toXContent(builder, ToXContent.EMPTY_PARAMS);
-            return builder.bytes();
-        } catch (Exception e) {
-            throw new SearchSourceBuilderException("Failed to build search source", e);
-        }
-    }
-
     @Override
     public XContentBuilder toXContent(XContentBuilder builder, Params params) throws IOException {
         builder.startObject();
@@ -211,19 +182,31 @@ public class PercolateSourceBuilder implements ToXContent {
         return builder;
     }
 
+    /**
+     * @return A new {@link DocBuilder} instance.
+     */
     public static DocBuilder docBuilder() {
         return new DocBuilder();
     }
 
+    /**
+     * A builder for defining the document to be percolated in various ways.
+     */
     public static class DocBuilder implements ToXContent {
 
         private BytesReference doc;
 
+        /**
+         * Sets the document to be percolated.
+         */
         public DocBuilder setDoc(BytesReference doc) {
             this.doc = doc;
             return this;
         }
 
+        /**
+         * Sets the document to be percolated.
+         */
         public DocBuilder setDoc(String field, Object value) {
             Map<String, Object> values = new HashMap<>(2);
             values.put(field, value);
@@ -231,20 +214,30 @@ public class PercolateSourceBuilder implements ToXContent {
             return this;
         }
 
+        /**
+         * Sets the document to be percolated.
+         */
         public DocBuilder setDoc(String doc) {
             this.doc = new BytesArray(doc);
             return this;
         }
 
+        /**
+         * Sets the document to be percolated.
+         */
         public DocBuilder setDoc(XContentBuilder doc) {
             this.doc = doc.bytes();
             return this;
         }
 
+        /**
+         * Sets the document to be percolated.
+         */
         public DocBuilder setDoc(Map doc) {
             return setDoc(doc, Requests.CONTENT_TYPE);
         }
 
+        @SuppressWarnings("unchecked")
         public DocBuilder setDoc(Map doc, XContentType contentType) {
             try {
                 return setDoc(XContentFactory.contentBuilder(contentType).map(doc));
diff --git a/src/test/java/org/elasticsearch/cluster/NoMasterNodeTests.java b/src/test/java/org/elasticsearch/cluster/NoMasterNodeTests.java
index 1689dc20a18..d95811b3e35 100644
--- a/src/test/java/org/elasticsearch/cluster/NoMasterNodeTests.java
+++ b/src/test/java/org/elasticsearch/cluster/NoMasterNodeTests.java
@@ -37,6 +37,7 @@ import org.junit.Test;
 
 import java.util.HashMap;
 
+import static org.elasticsearch.action.percolate.PercolateSourceBuilder.docBuilder;
 import static org.elasticsearch.common.settings.ImmutableSettings.settingsBuilder;
 import static org.elasticsearch.test.ElasticsearchIntegrationTest.Scope;
 import static org.elasticsearch.test.hamcrest.ElasticsearchAssertions.assertThrows;
@@ -95,7 +96,7 @@ public class NoMasterNodeTests extends ElasticsearchIntegrationTest {
         );
 
         PercolateSourceBuilder percolateSource = new PercolateSourceBuilder();
-        percolateSource.percolateDocument().setDoc(new HashMap());
+        percolateSource.setDoc(docBuilder().setDoc(new HashMap()));
         assertThrows(client().preparePercolate()
                         .setIndices("test").setDocumentType("type1")
                         .setSource(percolateSource),
@@ -103,7 +104,7 @@ public class NoMasterNodeTests extends ElasticsearchIntegrationTest {
         );
 
         percolateSource = new PercolateSourceBuilder();
-        percolateSource.percolateDocument().setDoc(new HashMap());
+        percolateSource.setDoc(docBuilder().setDoc(new HashMap()));
         assertThrows(client().preparePercolate()
                         .setIndices("no_index").setDocumentType("type1")
                         .setSource(percolateSource),