doc doc doc

modules/elasticsearch/src/main/java/org/elasticsearch/action/get/GetRequest.java

@@ -27,36 +27,68 @@ import java.io.DataOutput;
 import java.io.IOException;
 
 /**
- * @author kimchy (Shay Banon)
+ * A request to get a document (its source) from an index based on its type and id. Best created using
+ * {@link org.elasticsearch.client.Requests#getRequest(String)}.
+ *
+ * <p>The operation requires the {@link #index()}, {@link #type(String)} and {@link #id(String)}
+ * to be set.
+ *
+ * @author kimchy (shay.banon)
+ * @see org.elasticsearch.action.get.GetResponse
+ * @see org.elasticsearch.client.Requests#getRequest(String)
+ * @see org.elasticsearch.client.Client#get(GetRequest)
  */
 public class GetRequest extends SingleOperationRequest {
 
     GetRequest() {
     }
 
+    /**
+     * Constructs a new get request against the specified index. The {@link #type(String)} and {@link #id(String)}
+     * must be set.
+     */
     public GetRequest(String index) {
         super(index, null, null);
     }
 
+    /**
+     * Constructs a new get request against the specified index with the type and id.
+     *
+     * @param index The index to get the document from
+     * @param type  The type of the document
+     * @param id    The id of the document
+     */
     public GetRequest(String index, String type, String id) {
         super(index, type, id);
     }
 
+    /**
+     * Sets the type of the document to fetch.
+     */
     @Required public GetRequest type(String type) {
         this.type = type;
         return this;
     }
 
+    /**
+     * Sets the id of the document to fetch.
+     */
     @Required public GetRequest id(String id) {
         this.id = id;
         return this;
     }
 
+    /**
+     * Should the listener be called on a separate thread if needed.
+     */
     @Override public GetRequest listenerThreaded(boolean threadedListener) {
         super.listenerThreaded(threadedListener);
         return this;
     }
 
+    /**
+     * Controls if the operation will be executed on a separate thread when executed locally.
+     */
     @Override public GetRequest threadedOperation(boolean threadedOperation) {
         super.threadedOperation(threadedOperation);
         return this;

modules/elasticsearch/src/main/java/org/elasticsearch/action/get/GetResponse.java

@@ -28,7 +28,11 @@ import java.io.DataOutput;
 import java.io.IOException;
 
 /**
- * @author kimchy (Shay Banon)
+ * The response of a get action.
+ *
+ * @author kimchy (shay.banon)
+ * @see GetRequest
+ * @see org.elasticsearch.client.Client#get(GetRequest)
  */
 public class GetResponse implements ActionResponse, Streamable {
 
@@ -40,36 +44,54 @@ public class GetResponse implements ActionResponse, Streamable {
 
     private byte[] source;
 
-    public GetResponse() {
+    GetResponse() {
     }
 
-    public GetResponse(String index, String type, String id, byte[] source) {
+    GetResponse(String index, String type, String id, byte[] source) {
         this.index = index;
         this.type = type;
         this.id = id;
         this.source = source;
     }
 
-    public boolean empty() {
+    /**
+     * Does the document exists.
+     */
+    public boolean exists() {
         return source == null;
     }
 
+    /**
+     * The index the document was fetched from.
+     */
     public String index() {
         return this.index;
     }
 
+    /**
+     * The type of the document.
+     */
     public String type() {
         return type;
     }
 
+    /**
+     * The id of the document.
+     */
     public String id() {
         return id;
     }
 
+    /**
+     * The source of the document if exists.
+     */
     public byte[] source() {
         return this.source;
     }
 
+    /**
+     * The source of the document (as a string).
+     */
     public String sourceAsString() {
         return Unicode.fromBytes(source);
     }

modules/elasticsearch/src/main/java/org/elasticsearch/action/get/TransportGetAction.java

@@ -31,7 +31,9 @@ import org.elasticsearch.transport.TransportService;
 import org.elasticsearch.util.settings.Settings;
 
 /**
- * @author kimchy (Shay Banon)
+ * Performs the get operation.
+ *
+ * @author kimchy (shay.banon)
  */
 public class TransportGetAction extends TransportSingleOperationAction<GetRequest, GetResponse> {
 

modules/elasticsearch/src/main/java/org/elasticsearch/action/get/package-info.java

@@ -0,0 +1,23 @@
+/*
+ * Licensed to Elastic Search and Shay Banon under one
+ * or more contributor license agreements.  See the NOTICE file
+ * distributed with this work for additional information
+ * regarding copyright ownership. Elastic Search licenses this
+ * file to you under the Apache License, Version 2.0 (the
+ * "License"); you may not use this file except in compliance
+ * with the License.  You may obtain a copy of the License at
+ *
+ *    http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing,
+ * software distributed under the License is distributed on an
+ * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+ * KIND, either express or implied.  See the License for the
+ * specific language governing permissions and limitations
+ * under the License.
+ */
+
+/**
+ * Get action.
+ */
+package org.elasticsearch.action.get;

modules/elasticsearch/src/main/java/org/elasticsearch/action/index/IndexRequest.java

@@ -34,10 +34,28 @@ import java.io.IOException;
 import static org.elasticsearch.action.Actions.*;
 
 /**
- * @author kimchy (Shay Banon)
+ * Index request to index a typed JSON document into a specific index and make it searchable. Best
+ * created using {@link org.elasticsearch.client.Requests#indexRequest(String)}.
+ *
+ * <p>The index requires the {@link #index()}, {@link #type(String)}, {@link #id(String)} and
+ * {@link #source(byte[])} to be set.
+ *
+ * <p>The source (JSON to index) can be set in its bytes form using ({@link #source(byte[])}),
+ * its string form ({@link #source(String)}) or using a {@link org.elasticsearch.util.json.JsonBuilder}
+ * ({@link #source(org.elasticsearch.util.json.JsonBuilder)}).
+ *
+ * <p>If the {@link #id(String)} is not set, it will be automatically generated.
+ *
+ * @author kimchy (shay.banon)
+ * @see IndexResponse
+ * @see org.elasticsearch.client.Requests#indexRequest(String)
+ * @see org.elasticsearch.client.Client#index(IndexRequest)
  */
 public class IndexRequest extends ShardReplicationOperationRequest {
 
+    /**
+     * Operation type controls if the type of the index operation.
+     */
     public static enum OpType {
         /**
          * Index the source. If there an existing document with the id, it will
@@ -56,10 +74,16 @@ public class IndexRequest extends ShardReplicationOperationRequest {
             this.id = id;
         }
 
+        /**
+         * The internal representation of the operation type.
+         */
         public byte id() {
             return id;
         }
 
+        /**
+         * Constructs the operation type from its internal representation.
+         */
         public static OpType fromId(byte id) {
             if (id == 0) {
                 return INDEX;
@@ -76,10 +100,22 @@ public class IndexRequest extends ShardReplicationOperationRequest {
     private byte[] source;
     private OpType opType = OpType.INDEX;
 
+    /**
+     * Constructs a new index request against the specific index. The {@link #type(String)},
+     * {@link #id(String)} and {@link #source(byte[])} must be set.
+     */
     public IndexRequest(String index) {
         this.index = index;
     }
 
+    /**
+     * Constructs a new index request against the index, type, id and using the source.
+     *
+     * @param index  The index to index into
+     * @param type   The type to index into
+     * @param id     The id of document
+     * @param source The JSON source document
+     */
     public IndexRequest(String index, String type, String id, byte[] source) {
         this.index = index;
         this.type = type;
@@ -101,43 +137,73 @@ public class IndexRequest extends ShardReplicationOperationRequest {
         return validationException;
     }
 
+    /**
+     * Should the listener be called on a separate thread if needed.
+     */
     @Override public IndexRequest listenerThreaded(boolean threadedListener) {
         super.listenerThreaded(threadedListener);
         return this;
     }
 
+    /**
+     * Controls if the operation will be executed on a separate thread when executed locally.
+     */
     @Override public IndexRequest operationThreaded(boolean threadedOperation) {
         super.operationThreaded(threadedOperation);
         return this;
     }
 
+    /**
+     * The type of the indexed document.
+     */
     String type() {
         return type;
     }
 
+    /**
+     * Sets the type of the indexed document.
+     */
     @Required public IndexRequest type(String type) {
         this.type = type;
         return this;
     }
 
+    /**
+     * The id of the indexed document. If not set, will be automatically generated.
+     */
     String id() {
         return id;
     }
 
+    /**
+     * Sets the id of the indexed document. If not set, will be automatically generated.
+     */
     public IndexRequest id(String id) {
         this.id = id;
         return this;
     }
 
+    /**
+     * The source of the JSON document to index.
+     */
     byte[] source() {
         return source;
     }
 
+    /**
+     * Sets the JSON source to index.
+     *
+     * <p>Note, its preferable to either set it using {@link #source(org.elasticsearch.util.json.JsonBuilder)}
+     * or using the {@link #source(byte[])}.
+     */
     @Required public IndexRequest source(String source) {
         this.source = Unicode.fromStringAsBytes(source);
         return this;
     }
 
+    /**
+     * Sets the JSON source to index.
+     */
     @Required public IndexRequest source(JsonBuilder jsonBuilder) {
         try {
             jsonBuilder.flush();
@@ -147,21 +213,33 @@ public class IndexRequest extends ShardReplicationOperationRequest {
         }
     }
 
+    /**
+     * Sets the JSON source to index.
+     */
     @Required public IndexRequest source(byte[] source) {
         this.source = source;
         return this;
     }
 
+    /**
+     * A timeout to wait if the index operation can't be performed immediately. Defaults to <tt>1m</tt>.
+     */
     public IndexRequest timeout(TimeValue timeout) {
         this.timeout = timeout;
         return this;
     }
 
+    /**
+     * Sets the type of operation to perform.
+     */
     public IndexRequest opType(OpType opType) {
         this.opType = opType;
         return this;
     }
 
+    /**
+     * The type of operation to perform.
+     */
     public OpType opType() {
         return this.opType;
     }
@@ -169,7 +247,9 @@ public class IndexRequest extends ShardReplicationOperationRequest {
     @Override public void readFrom(DataInput in) throws IOException, ClassNotFoundException {
         super.readFrom(in);
         type = in.readUTF();
-        id = in.readUTF();
+        if (in.readBoolean()) {
+            id = in.readUTF();
+        }
         source = new byte[in.readInt()];
         in.readFully(source, 0, source.length);
         opType = OpType.fromId(in.readByte());
@@ -178,9 +258,18 @@ public class IndexRequest extends ShardReplicationOperationRequest {
     @Override public void writeTo(DataOutput out) throws IOException {
         super.writeTo(out);
         out.writeUTF(type);
-        out.writeUTF(id);
+        if (id == null) {
+            out.writeBoolean(false);
+        } else {
+            out.writeBoolean(true);
+            out.writeUTF(id);
+        }
         out.writeInt(source.length);
         out.write(source);
         out.writeByte(opType.id());
     }
+
+    @Override public String toString() {
+        return "IndexAction [" + index + "][" + type + "][" + id + "], source [" + Unicode.fromBytes(source) + "]";
+    }
 }

modules/elasticsearch/src/main/java/org/elasticsearch/action/index/IndexResponse.java

@@ -27,7 +27,11 @@ import java.io.DataOutput;
 import java.io.IOException;
 
 /**
- * @author kimchy (Shay Banon)
+ * A response of an index operation,
+ *
+ * @author kimchy (shay.banon)
+ * @see org.elasticsearch.action.index.IndexRequest
+ * @see org.elasticsearch.client.Client#index(IndexRequest)
  */
 public class IndexResponse implements ActionResponse, Streamable {
 
@@ -37,28 +41,37 @@ public class IndexResponse implements ActionResponse, Streamable {
 
     private String type;
 
-    public IndexResponse() {
+    IndexResponse() {
 
     }
 
-    public IndexResponse(String index, String type, String id) {
+    IndexResponse(String index, String type, String id) {
         this.index = index;
         this.id = id;
         this.type = type;
     }
 
+    /**
+     * The index the document was indexed into.
+     */
     public String index() {
         return this.index;
     }
 
-    public String id() {
+    /**
-        return this.id;
+     * The type of the document indexed.
-    }
+     */
-
     public String type() {
         return this.type;
     }
 
+    /**
+     * The id of the document indexed.
+     */
+    public String id() {
+        return this.id;
+    }
+
     @Override public void readFrom(DataInput in) throws IOException, ClassNotFoundException {
         index = in.readUTF();
         id = in.readUTF();

modules/elasticsearch/src/main/java/org/elasticsearch/action/index/TransportIndexAction.java

@@ -41,7 +41,16 @@ import org.elasticsearch.util.UUID;
 import org.elasticsearch.util.settings.Settings;
 
 /**
- * @author kimchy (Shay Banon)
+ * Performs the index operation.
+ *
+ * <p>Allows for the following settings:
+ * <ul>
+ * <li><b>autoCreateIndex</b>: When set to <tt>true</tt>, will automatically create an index if one does not exists.
+ * Defaults to <tt>true</tt>.
+ * <li><b>allowIdGeneration</b>: If the id is set not, should it be generated. Defaults to <tt>true</tt>.
+ * </ul>
+ *
+ * @author kimchy (shay.banon)
  */
 public class TransportIndexAction extends TransportShardReplicationOperationAction<IndexRequest, IndexResponse> {
 

modules/elasticsearch/src/main/java/org/elasticsearch/action/index/package-info.java

@@ -0,0 +1,23 @@
+/*
+ * Licensed to Elastic Search and Shay Banon under one
+ * or more contributor license agreements.  See the NOTICE file
+ * distributed with this work for additional information
+ * regarding copyright ownership. Elastic Search licenses this
+ * file to you under the Apache License, Version 2.0 (the
+ * "License"); you may not use this file except in compliance
+ * with the License.  You may obtain a copy of the License at
+ *
+ *    http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing,
+ * software distributed under the License is distributed on an
+ * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+ * KIND, either express or implied.  See the License for the
+ * specific language governing permissions and limitations
+ * under the License.
+ */
+
+/**
+ * Index action.
+ */
+package org.elasticsearch.action.index;

modules/elasticsearch/src/main/java/org/elasticsearch/action/mlt/TransportMoreLikeThisAction.java

@@ -79,7 +79,7 @@ public class TransportMoreLikeThisAction extends BaseAction<MoreLikeThisRequest,
                 .listenerThreaded(false);
         getAction.execute(getRequest, new ActionListener<GetResponse>() {
             @Override public void onResponse(GetResponse getResponse) {
-                if (getResponse.empty()) {
+                if (getResponse.exists()) {
                     listener.onFailure(new ElasticSearchException("document missing"));
                     return;
                 }

modules/elasticsearch/src/main/java/org/elasticsearch/action/support/replication/ShardReplicationOperationRequest.java

@@ -52,10 +52,16 @@ public abstract class ShardReplicationOperationRequest implements ActionRequest
         return this.index;
     }
 
+    /**
+     * Should the listener be called on a separate thread if needed.
+     */
     @Override public boolean listenerThreaded() {
         return threadedListener;
     }
 
+    /**
+     * Should the listener be called on a separate thread if needed.
+     */
     @Override public ShardReplicationOperationRequest listenerThreaded(boolean threadedListener) {
         this.threadedListener = threadedListener;
         return this;

modules/elasticsearch/src/main/java/org/elasticsearch/action/support/single/SingleOperationRequest.java

@@ -74,6 +74,9 @@ public abstract class SingleOperationRequest implements ActionRequest {
         return id;
     }
 
+    /**
+     * Should the listener be called on a separate thread if needed.
+     */
     @Override public boolean listenerThreaded() {
         return threadedListener;
     }

modules/elasticsearch/src/main/java/org/elasticsearch/client/Client.java

@@ -49,7 +49,7 @@ import org.elasticsearch.action.terms.TermsResponse;
  * <p>A client can either be retrieved from a {@link org.elasticsearch.server.Server} started, or connected remotely
  * to one or more nodes using {@link org.elasticsearch.client.transport.TransportClient}.
  *
- * @author kimchy (Shay Banon)
+ * @author kimchy (shay.banon)
  * @see org.elasticsearch.server.Server#client()
  * @see org.elasticsearch.client.transport.TransportClient
  */

modules/elasticsearch/src/main/java/org/elasticsearch/rest/action/get/RestGetAction.java

@@ -53,7 +53,7 @@ public class RestGetAction extends BaseRestHandler {
         client.execGet(getRequest, new ActionListener<GetResponse>() {
             @Override public void onResponse(GetResponse result) {
                 try {
-                    if (result.empty()) {
+                    if (result.exists()) {
                         channel.sendResponse(new JsonRestResponse(request, NOT_FOUND));
                     } else {
                         JsonBuilder builder = restJsonBuilder(request);

modules/test/integration/src/test/java/org/elasticsearch/test/integration/document/DocumentActionsTests.java

@@ -108,7 +108,7 @@ public class DocumentActionsTests extends AbstractServersTests {
         logger.info("Get [type1/2] (should be empty)");
         for (int i = 0; i < 5; i++) {
             getResult = client1.get(getRequest("test").type("type1").id("2")).actionGet();
-            assertThat(getResult.empty(), equalTo(true));
+            assertThat(getResult.exists(), equalTo(true));
         }
 
         logger.info("Delete [type1/1]");
@@ -121,7 +121,7 @@ public class DocumentActionsTests extends AbstractServersTests {
         logger.info("Get [type1/1] (should be empty)");
         for (int i = 0; i < 5; i++) {
             getResult = client1.get(getRequest("test").type("type1").id("1")).actionGet();
-            assertThat(getResult.empty(), equalTo(true));
+            assertThat(getResult.exists(), equalTo(true));
         }
 
         logger.info("Index [type1/1]");
@@ -182,7 +182,7 @@ public class DocumentActionsTests extends AbstractServersTests {
             getResult = client1.get(getRequest("test").type("type1").id("1")).actionGet();
             assertThat("cycle #" + i, getResult.sourceAsString(), equalTo(source("1", "test")));
             getResult = client1.get(getRequest("test").type("type1").id("2")).actionGet();
-            assertThat("cycle #" + i, getResult.empty(), equalTo(false));
+            assertThat("cycle #" + i, getResult.exists(), equalTo(false));
         }
     }
 

modules/test/integration/src/test/java/org/elasticsearch/test/integration/gateway/AbstractSimpleIndexGatewayTests.java

@@ -81,7 +81,7 @@ public abstract class AbstractSimpleIndexGatewayTests extends AbstractServersTes
 
         logger.info("Getting #1, should not exists");
         GetResponse getResponse = client("server1").get(getRequest("test").type("type1").id("1")).actionGet();
-        assertThat(getResponse.empty(), equalTo(true));
+        assertThat(getResponse.exists(), equalTo(true));
         logger.info("Getting #2");
         getResponse = client("server1").get(getRequest("test").type("type1").id("2")).actionGet();
         assertThat(getResponse.sourceAsString(), equalTo(source("2", "test")));
@@ -106,7 +106,7 @@ public abstract class AbstractSimpleIndexGatewayTests extends AbstractServersTes
 
         logger.info("Getting #1, should not exists");
         getResponse = client("server1").get(getRequest("test").type("type1").id("1")).actionGet();
-        assertThat(getResponse.empty(), equalTo(true));
+        assertThat(getResponse.exists(), equalTo(true));
         logger.info("Getting #2 (not from the translog, but from the index)");
         getResponse = client("server1").get(getRequest("test").type("type1").id("2")).actionGet();
         assertThat(getResponse.sourceAsString(), equalTo(source("2", "test")));
@@ -131,7 +131,7 @@ public abstract class AbstractSimpleIndexGatewayTests extends AbstractServersTes
 
         logger.info("Getting #1, should not exists");
         getResponse = client("server1").get(getRequest("test").type("type1").id("1")).actionGet();
-        assertThat(getResponse.empty(), equalTo(true));
+        assertThat(getResponse.exists(), equalTo(true));
         logger.info("Getting #2 (not from the translog, but from the index)");
         getResponse = client("server1").get(getRequest("test").type("type1").id("2")).actionGet();
         assertThat(getResponse.sourceAsString(), equalTo(source("2", "test")));