javadoc client

Author: kimchy

.idea/libraries/jgroups.xml

@@ -20,12 +20,14 @@
 package org.elasticsearch;
 
 /**
- * @author kimchy (Shay Banon) (Shay Banon)
+ * A base class for all elasticsearch exceptions.
+ *
+ * @author kimchy (Shay Banon)
  */
 public class ElasticSearchException extends RuntimeException {
 
     /**
-     * Construct a <code>NestedRuntimeException</code> with the specified detail message.
+     * Construct a <code>ElasticSearchException</code> with the specified detail message.
      *
      * @param msg the detail message
      */
@@ -34,7 +36,7 @@ public ElasticSearchException(String msg) {
     }
 
     /**
-     * Construct a <code>NestedRuntimeException</code> with the specified detail message
+     * Construct a <code>ElasticSearchException</code> with the specified detail message
      * and nested exception.
      *
      * @param msg   the detail message
@@ -44,6 +46,12 @@ public ElasticSearchException(String msg, Throwable cause) {
         super(msg, cause);
     }
 
+    /**
+     * Unwraps the actual cause from the exception for cases when the exception is a
+     * {@link ElasticSearchWrapperException}.
+     *
+     * @see org.elasticsearch.ExceptionsHelper#unwrapCause(Throwable)
+     */
     public Throwable unwrapCause() {
         return ExceptionsHelper.unwrapCause(this);
     }
@@ -68,9 +76,6 @@ public String getDetailedMessage() {
 
     /**
      * Retrieve the innermost cause of this exception, if any.
-     *
-     * @return the innermost exception, or <code>null</code> if none
-     * @since 2.0
      */
     public Throwable getRootCause() {
         Throwable rootCause = null;
@@ -89,7 +94,6 @@ public Throwable getRootCause() {
      * to the present exception if there is no root cause.
      *
      * @return the most specific cause (never <code>null</code>)
-     * @since 2.0.3
      */
     public Throwable getMostSpecificCause() {
         Throwable rootCause = getRootCause();

.idea/projectCodeStyle.xml

@@ -24,6 +24,7 @@
 import org.elasticsearch.action.support.replication.ShardReplicationOperationRequest;
 import org.elasticsearch.util.Required;
 import org.elasticsearch.util.TimeValue;
+import org.elasticsearch.util.json.JsonBuilder;
 
 import java.io.DataInput;
 import java.io.DataOutput;
@@ -122,7 +123,7 @@ String id() {
         return id;
     }
 
-    @Required public IndexRequest id(String id) {
+    public IndexRequest id(String id) {
         this.id = id;
         return this;
     }
@@ -131,7 +132,15 @@ String source() {
         return source;
     }
 
-    public IndexRequest source(String source) {
+    @Required public IndexRequest source(JsonBuilder jsonBuilder) {
+        try {
+            return source(jsonBuilder.string());
+        } catch (IOException e) {
+            throw new ElasticSearchIllegalArgumentException("Failed to build json for index request", e);
+        }
+    }
+
+    @Required public IndexRequest source(String source) {
         this.source = source;
         return this;
     }

modules/elasticsearch/src/main/java/org/elasticsearch/ElasticSearchException.java

@@ -20,11 +20,20 @@
 package org.elasticsearch.client;
 
 /**
+ * Administrative actions/operations against the cluster or the indices.
+ *
  * @author kimchy (Shay Banon)
+ * @see org.elasticsearch.client.Client#admin()
  */
 public interface AdminClient {
 
+    /**
+     * A client allowing to perform actions/operations against the cluster.
+     */
     ClusterAdminClient cluster();
 
+    /**
+     * A client allowing to perform actions/operations against the indices.
+     */
     IndicesAdminClient indices();
 }

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

@@ -36,53 +36,231 @@
 import org.elasticsearch.action.search.SearchScrollRequest;
 
 /**
+ * A client provides a one stop interface for performing actions/operations against the cluster.
+ *
+ * <p>All operations performed are asynchronous by nature. There are three flavors for each operation,
+ * the simplest returns an {@link ActionFuture}, another that also accepts an {@link ActionListener},
+ * and the last (prefixed with <tt>exec</tt>) which just accepts an {@link ActionListener} without returning
+ * an {@link ActionFuture}.
+ *
+ * <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)
+ * @see org.elasticsearch.server.Server#client()
+ * @see org.elasticsearch.client.transport.TransportClient
  */
 public interface Client {
 
+    /**
+     * Closes the client.
+     */
     void close();
 
+    /**
+     * The admin client that can be used to perform administrative operations.
+     */
     AdminClient admin();
 
+    /**
+     * Index a JSON source associated with a given index and type.
+     *
+     * <p>The id is optional, if it is not provided, one will be generated automatically.
+     *
+     * @param request The index request
+     * @return The result future
+     * @see Requests#indexRequest(String)
+     */
     ActionFuture<IndexResponse> index(IndexRequest request);
 
+    /**
+     * Index a JSON source associated with a given index and type.
+     *
+     * <p>The id is optional, if it is not provided, one will be generated automatically.
+     *
+     * @param request  The index request
+     * @param listener A listener to be notified with a result
+     * @return The result future
+     * @see Requests#indexRequest(String)
+     */
     ActionFuture<IndexResponse> index(IndexRequest request, ActionListener<IndexResponse> listener);
 
+    /**
+     * Index a JSON source associated with a given index and type.
+     *
+     * <p>The id is optional, if it is not provided, one will be generated automatically.
+     *
+     * @param request  The index request
+     * @param listener A listener to be notified with a result
+     * @see Requests#indexRequest(String)
+     */
     void execIndex(IndexRequest request, ActionListener<IndexResponse> listener);
 
+    /**
+     * Deletes a document from the index based on the index, type and id.
+     *
+     * @param request The delete request
+     * @return The result future
+     * @see Requests#deleteRequest(String)
+     */
     ActionFuture<DeleteResponse> delete(DeleteRequest request);
 
+    /**
+     * Deletes a document from the index based on the index, type and id.
+     *
+     * @param request  The delete request
+     * @param listener A listener to be notified with a result
+     * @return The result future
+     * @see Requests#deleteRequest(String)
+     */
     ActionFuture<DeleteResponse> delete(DeleteRequest request, ActionListener<DeleteResponse> listener);
 
+    /**
+     * Deletes a document from the index based on the index, type and id.
+     *
+     * @param request  The delete request
+     * @param listener A listener to be notified with a result
+     * @see Requests#deleteRequest(String)
+     */
     void execDelete(DeleteRequest request, ActionListener<DeleteResponse> listener);
 
+    /**
+     * Deletes all documents from one or more indices based on a query.
+     *
+     * @param request The delete by query request
+     * @return The result future
+     * @see Requests#deleteByQueryRequest(String...)
+     */
     ActionFuture<DeleteByQueryResponse> deleteByQuery(DeleteByQueryRequest request);
 
+    /**
+     * Deletes all documents from one or more indices based on a query.
+     *
+     * @param request  The delete by query request
+     * @param listener A listener to be notified with a result
+     * @return The result future
+     * @see Requests#deleteByQueryRequest(String...)
+     */
     ActionFuture<DeleteByQueryResponse> deleteByQuery(DeleteByQueryRequest request, ActionListener<DeleteByQueryResponse> listener);
 
+    /**
+     * Deletes all documents from one or more indices based on a query.
+     *
+     * @param request  The delete by query request
+     * @param listener A listener to be notified with a result
+     * @see Requests#deleteByQueryRequest(String...)
+     */
     void execDeleteByQuery(DeleteByQueryRequest request, ActionListener<DeleteByQueryResponse> listener);
 
+    /**
+     * Gets the JSON source that was indexed from an index with a type and id.
+     *
+     * @param request The get request
+     * @return The result future
+     * @see Requests#getRequest(String)
+     */
     ActionFuture<GetResponse> get(GetRequest request);
 
+    /**
+     * Gets the JSON source that was indexed from an index with a type and id.
+     *
+     * @param request  The get request
+     * @param listener A listener to be notified with a result
+     * @return The result future
+     * @see Requests#getRequest(String)
+     */
     ActionFuture<GetResponse> get(GetRequest request, ActionListener<GetResponse> listener);
 
+    /**
+     * Gets the JSON source that was indexed from an index with a type and id.
+     *
+     * @param request  The get request
+     * @param listener A listener to be notified with a result
+     * @see Requests#getRequest(String)
+     */
     void execGet(GetRequest request, ActionListener<GetResponse> listener);
 
+    /**
+     * A count of all the documents matching a specific query.
+     *
+     * @param request The count request
+     * @return The result future
+     * @see Requests#countRequest(String...)
+     */
     ActionFuture<CountResponse> count(CountRequest request);
 
+    /**
+     * A count of all the documents matching a specific query.
+     *
+     * @param request  The count request
+     * @param listener A listener to be notified of the result
+     * @return The result future
+     * @see Requests#countRequest(String...)
+     */
     ActionFuture<CountResponse> count(CountRequest request, ActionListener<CountResponse> listener);
 
+    /**
+     * A count of all the documents matching a specific query.
+     *
+     * @param request  The count request
+     * @param listener A listener to be notified of the result
+     * @see Requests#countRequest(String...)
+     */
     void execCount(CountRequest request, ActionListener<CountResponse> listener);
 
+    /**
+     * Search across one or more indices and one or more types with a query.
+     *
+     * @param request The search request
+     * @return The result future
+     * @see Requests#searchRequest(String...)
+     */
     ActionFuture<SearchResponse> search(SearchRequest request);
 
+    /**
+     * Search across one or more indices and one or more types with a query.
+     *
+     * @param request  The search request
+     * @param listener A listener to be notified of the result
+     * @return The result future
+     * @see Requests#searchRequest(String...)
+     */
     ActionFuture<SearchResponse> search(SearchRequest request, ActionListener<SearchResponse> listener);
 
+    /**
+     * Search across one or more indices and one or more types with a query.
+     *
+     * @param request  The search request
+     * @param listener A listener to be notified of the result
+     * @see Requests#searchRequest(String...)
+     */
     void execSearch(SearchRequest request, ActionListener<SearchResponse> listener);
 
+    /**
+     * A search scroll request to continue searching a previous scrollable search request.
+     *
+     * @param request The search scroll request
+     * @return The result future
+     * @see Requests#searchScrollRequest(String)
+     */
     ActionFuture<SearchResponse> searchScroll(SearchScrollRequest request);
 
+    /**
+     * A search scroll request to continue searching a previous scrollable search request.
+     *
+     * @param request  The search scroll request
+     * @param listener A listener to be notified of the result
+     * @return The result future
+     * @see Requests#searchScrollRequest(String)
+     */
     ActionFuture<SearchResponse> searchScroll(SearchScrollRequest request, ActionListener<SearchResponse> listener);
 
+    /**
+     * A search scroll request to continue searching a previous scrollable search request.
+     *
+     * @param request  The search scroll request
+     * @param listener A listener to be notified of the result
+     * @see Requests#searchScrollRequest(String)
+     */
     void execSearchScroll(SearchScrollRequest request, ActionListener<SearchResponse> listener);
 }