docs and wrap the rest bulk request in an array

modules/elasticsearch/src/main/java/org/elasticsearch/action/bulk/BulkItemResponse.java

@@ -29,10 +29,16 @@ import org.elasticsearch.common.io.stream.Streamable;
 import java.io.IOException;
 
 /**
+ * Represents a single item response for an action executed as part of the bulk API. Holds the index/type/id
+ * of the relevant action, and if it has failed or not (with the failure message incase it failed).
+ *
  * @author kimchy (shay.banon)
  */
 public class BulkItemResponse implements Streamable {
 
+    /**
+     * Represents a failure.
+     */
     public static class Failure {
         private final String index;
         private final String type;
@@ -46,37 +52,61 @@ public class BulkItemResponse implements Streamable {
             this.message = message;
         }
 
+        /**
+         * The index name of the action.
+         */
         public String index() {
             return this.index;
         }
 
+        /**
+         * The index name of the action.
+         */
         public String getIndex() {
             return index();
         }
 
-        public String message() {
-            return this.message;
-        }
-
-        public String getMessage() {
-            return message();
-        }
-
+        /**
+         * The type of the action.
+         */
         public String type() {
             return type;
         }
 
+        /**
+         * The type of the action.
+         */
         public String getType() {
             return type();
         }
 
+        /**
+         * The id of the action.
+         */
         public String id() {
             return id;
         }
 
+        /**
+         * The id of the action.
+         */
         public String getId() {
             return this.id;
         }
+
+        /**
+         * The failure message.
+         */
+        public String message() {
+            return this.message;
+        }
+
+        /**
+         * The failure message.
+         */
+        public String getMessage() {
+            return message();
+        }
     }
 
     private int id;
@@ -103,14 +133,23 @@ public class BulkItemResponse implements Streamable {
         this.failure = failure;
     }
 
+    /**
+     * The numeric order of the item matching the same request order in the bulk request.
+     */
     public int itemId() {
         return id;
     }
 
+    /**
+     * The operation type ("index", "create" or "delete").
+     */
     public String opType() {
         return this.opType;
     }
 
+    /**
+     * The index name of the action.
+     */
     public String index() {
         if (failure != null) {
             return failure.index();
@@ -123,10 +162,16 @@ public class BulkItemResponse implements Streamable {
         return null;
     }
 
+    /**
+     * The index name of the action.
+     */
     public String getIndex() {
         return index();
     }
 
+    /**
+     * The type of the action.
+     */
     public String type() {
         if (failure != null) {
             return failure.type();
@@ -139,10 +184,16 @@ public class BulkItemResponse implements Streamable {
         return null;
     }
 
+    /**
+     * The type of the action.
+     */
     public String getType() {
         return this.type();
     }
 
+    /**
+     * The id of the action.
+     */
     public String id() {
         if (failure != null) {
             return failure.id();
@@ -155,26 +206,62 @@ public class BulkItemResponse implements Streamable {
         return null;
     }
 
+    /**
+     * The id of the action.
+     */
     public String getId() {
         return id();
     }
 
+    /**
+     * The actual response ({@link IndexResponse} or {@link DeleteResponse}). <tt>null</tt> in
+     * case of failure.
+     */
     public ActionResponse response() {
         return response;
     }
 
+    /**
+     * Is this a failed execution of an operation.
+     */
     public boolean failed() {
         return failure != null;
     }
 
+    /**
+     * Is this a failed execution of an operation.
+     */
     public boolean isFailed() {
         return failed();
     }
 
+    /**
+     * The failure message, <tt>null</tt> if it did not fail.
+     */
+    public String failureMessage() {
+        if (failure != null) {
+            return failure.message();
+        }
+        return null;
+    }
+
+    /**
+     * The failure message, <tt>null</tt> if it did not fail.
+     */
+    public String getFailureMessage() {
+        return failureMessage();
+    }
+
+    /**
+     * The actual failure object if there was a failure.
+     */
     public Failure failure() {
         return this.failure;
     }
 
+    /**
+     * The actual failure object if there was a failure.
+     */
     public Failure getFailure() {
         return failure();
     }

modules/elasticsearch/src/main/java/org/elasticsearch/action/bulk/BulkRequest.java

@@ -33,7 +33,11 @@ import java.util.List;
 import static org.elasticsearch.action.Actions.*;
 
 /**
+ * A bulk request holds an ordered {@link IndexRequest}s and {@link DeleteRequest}s and allows to executes
+ * it in a single batch.
+ *
  * @author kimchy (shay.banon)
+ * @see org.elasticsearch.client.Client#bulk(BulkRequest)
  */
 public class BulkRequest implements ActionRequest {
 
@@ -41,6 +45,10 @@ public class BulkRequest implements ActionRequest {
 
     private boolean listenerThreaded = false;
 
+    /**
+     * Adds an {@link IndexRequest} to the list of actions to execute. Follows the same behavior of {@link IndexRequest}
+     * (for example, if no id is provided, one will be generated, or usage of the create flag).
+     */
     public BulkRequest add(IndexRequest request) {
         // if the source is from a builder, we need to copy it over before adding the next one, which can come from a builder as well...
         if (request.sourceFromBuilder()) {
@@ -50,6 +58,9 @@ public class BulkRequest implements ActionRequest {
         return this;
     }
 
+    /**
+     * Adds an {@link DeleteRequest} to the list of actions to execute.
+     */
     public BulkRequest add(DeleteRequest request) {
         requests.add(request);
         return this;

modules/elasticsearch/src/main/java/org/elasticsearch/action/bulk/BulkResponse.java

@@ -29,7 +29,8 @@ import java.util.Iterator;
 
 /**
  * A response of a bulk execution. Holding a response for each item responding (in order) of the
- * bulk requests.
+ * bulk requests. Each item holds the index/type/id is operated on, and if it failed or not (with the
+ * failure message).
  *
  * @author kimchy (shay.banon)
  */
@@ -44,6 +45,9 @@ public class BulkResponse implements ActionResponse, Iterable<BulkItemResponse>
         this.responses = responses;
     }
 
+    /**
+     * Has anything failed with the execution.
+     */
     public boolean hasFailures() {
         for (BulkItemResponse response : responses) {
             if (response.failed()) {
@@ -53,6 +57,9 @@ public class BulkResponse implements ActionResponse, Iterable<BulkItemResponse>
         return false;
     }
 
+    /**
+     * The items representing each action performed in the bulk operation (in the same order!).
+     */
     public BulkItemResponse[] items() {
         return responses;
     }

modules/elasticsearch/src/main/java/org/elasticsearch/rest/action/bulk/RestBulkAction.java

@@ -146,6 +146,7 @@ public class RestBulkAction extends BaseRestHandler {
                     XContentBuilder builder = restContentBuilder(request);
                     builder.startObject();
 
+                    builder.startArray("items");
                     for (BulkItemResponse itemResponse : response) {
                         builder.startObject(itemResponse.opType());
                         builder.field("index", itemResponse.index());
@@ -156,6 +157,7 @@ public class RestBulkAction extends BaseRestHandler {
                         }
                         builder.endObject();
                     }
+                    builder.endArray();
 
                     builder.endObject();
                     channel.sendResponse(new XContentRestResponse(request, OK, builder));