Imported Upstream version 1.0.3upstream/1.0.3

8 files changed, 413 insertions, 0 deletions

diff --git a/docs/groovy-api/anatomy.asciidoc b/docs/groovy-api/anatomy.asciidoc
new file mode 100644
index 0000000..fe17226
--- /dev/null
+++ b/docs/groovy-api/anatomy.asciidoc
@@ -0,0 +1,102 @@
+[[anatomy]]
+== API Anatomy
+
+Once a <<client,GClient>> has been
+obtained, all of Elasticsearch APIs can be executed on it. Each Groovy
+API is exposed using three different mechanisms.
+
+
+[[closure]]
+=== Closure Request
+
+The first type is to simply provide the request as a Closure, which
+automatically gets resolved into the respective request instance (for
+the index API, its the `IndexRequest` class). The API returns a special
+future, called `GActionFuture`. This is a groovier version of
+elasticsearch Java `ActionFuture` (in turn a nicer extension to Java own
+`Future`) which allows to register listeners (closures) on it for
+success and failures, as well as blocking for the response. For example:
+
+[source,js]
+--------------------------------------------------
+def indexR = client.index {
+    index "test"
+    type "type1"
+    id "1"
+    source {
+        test = "value"
+        complex {
+            value1 = "value1"
+            value2 = "value2"
+        }
+    }
+}
+
+println "Indexed $indexR.response.id into $indexR.response.index/$indexR.response.type"
+--------------------------------------------------
+
+In the above example, calling `indexR.response` will simply block for
+the response. We can also block for the response for a specific timeout:
+
+[source,js]
+--------------------------------------------------
+IndexResponse response = indexR.response "5s" // block for 5 seconds, same as:
+response = indexR.response 5, TimeValue.SECONDS //
+--------------------------------------------------
+
+We can also register closures that will be called on success and on
+failure:
+
+[source,js]
+--------------------------------------------------
+indexR.success = {IndexResponse response ->
+    pritnln "Indexed $response.id into $response.index/$response.type"
+}
+indexR.failure = {Throwable t ->
+    println "Failed to index: $t.message"
+}
+--------------------------------------------------
+
+
+[[request]]
+=== Request
+
+This option allows to pass the actual instance of the request (instead
+of a closure) as a parameter. The rest is similar to the closure as a
+parameter option (the `GActionFuture` handling). For example:
+
+[source,js]
+--------------------------------------------------
+def indexR = client.index (new IndexRequest(
+        index: "test",
+        type: "type1",
+        id: "1",
+        source: {
+            test = "value"
+            complex {
+                value1 = "value1"
+                value2 = "value2"
+            }
+        }))
+
+println "Indexed $indexR.response.id into $indexR.response.index/$indexR.response.type"
+--------------------------------------------------
+
+
+[[java-like]]
+=== Java Like
+
+The last option is to provide an actual instance of the API request, and
+an `ActionListener` for the callback. This is exactly like the Java API
+with the added `gexecute` which returns the `GActionFuture`:
+
+[source,js]
+--------------------------------------------------
+def indexR = node.client.prepareIndex("test", "type1", "1").setSource({
+    test = "value"
+    complex {
+        value1 = "value1"
+        value2 = "value2"
+    }
+}).gexecute()
+--------------------------------------------------
diff --git a/docs/groovy-api/client.asciidoc b/docs/groovy-api/client.asciidoc
new file mode 100644
index 0000000..c0a6d68
--- /dev/null
+++ b/docs/groovy-api/client.asciidoc
@@ -0,0 +1,59 @@
+[[client]]
+== Client
+
+Obtaining an elasticsearch Groovy `GClient` (a `GClient` is a simple
+wrapper on top of the Java `Client`) is simple. The most common way to
+get a client is by starting an embedded `Node` which acts as a node
+within the cluster.
+
+
+[[node-client]]
+=== Node Client
+
+A Node based client is the simplest form to get a `GClient` to start
+executing operations against elasticsearch.
+
+[source,js]
+--------------------------------------------------
+import org.elasticsearch.groovy.client.GClient
+import org.elasticsearch.groovy.node.GNode
+import static org.elasticsearch.groovy.node.GNodeBuilder.nodeBuilder
+
+// on startup
+
+GNode node = nodeBuilder().node();
+GClient client = node.client();
+
+// on shutdown
+
+node.close();
+--------------------------------------------------
+
+Since elasticsearch allows to configure it using JSON based settings,
+the configuration itself can be done using a closure that represent the
+JSON:
+
+[source,js]
+--------------------------------------------------
+import org.elasticsearch.groovy.node.GNode
+import org.elasticsearch.groovy.node.GNodeBuilder
+import static org.elasticsearch.groovy.node.GNodeBuilder.*
+
+// on startup
+
+GNodeBuilder nodeBuilder = nodeBuilder();
+nodeBuilder.settings {
+    node {
+        client = true
+    }
+    cluster {
+        name = "test"
+    }
+}
+
+GNode node = nodeBuilder.node()
+
+// on shutdown
+
+node.stop().close()
+--------------------------------------------------
diff --git a/docs/groovy-api/count.asciidoc b/docs/groovy-api/count.asciidoc
new file mode 100644
index 0000000..48e8c18
--- /dev/null
+++ b/docs/groovy-api/count.asciidoc
@@ -0,0 +1,22 @@
+[[count]]
+== Count API
+
+The count API is very similar to the
+{java}/count.html[Java count API]. The Groovy
+extension allows to provide the query to execute as a `Closure` (similar
+to GORM criteria builder):
+
+[source,js]
+--------------------------------------------------
+def count = client.count {
+    indices "test"
+    types "type1"
+    query {
+        term {
+            test = "value"
+        }
+    }
+}
+--------------------------------------------------
+
+The query follows the same {ref}/query-dsl.html[Query DSL].
diff --git a/docs/groovy-api/delete.asciidoc b/docs/groovy-api/delete.asciidoc
new file mode 100644
index 0000000..45020df
--- /dev/null
+++ b/docs/groovy-api/delete.asciidoc
@@ -0,0 +1,15 @@
+[[delete]]
+== Delete API
+
+The delete API is very similar to the
+{java}/delete.html[Java delete API], here is an
+example:
+
+[source,js]
+--------------------------------------------------
+def deleteF = node.client.delete {
+    index "test"
+    type "type1"
+    id "1"
+}
+--------------------------------------------------
diff --git a/docs/groovy-api/get.asciidoc b/docs/groovy-api/get.asciidoc
new file mode 100644
index 0000000..f5255be
--- /dev/null
+++ b/docs/groovy-api/get.asciidoc
@@ -0,0 +1,18 @@
+[[get]]
+== Get API
+
+The get API is very similar to the
+{java}/get.html[Java get API]. The main benefit
+of using groovy is handling the source content. It can be automatically
+converted to a `Map` which means using Groovy to navigate it is simple:
+
+[source,js]
+--------------------------------------------------
+def getF = node.client.get {
+    index "test"
+    type "type1"
+    id "1"
+}
+
+println "Result of field2: $getF.response.source.complex.field2"
+--------------------------------------------------
diff --git a/docs/groovy-api/index.asciidoc b/docs/groovy-api/index.asciidoc
new file mode 100644
index 0000000..87f9a73
--- /dev/null
+++ b/docs/groovy-api/index.asciidoc
@@ -0,0 +1,51 @@
+= Groovy API
+:ref:  http://www.elasticsearch.org/guide/en/elasticsearch/reference/current
+:java: http://www.elasticsearch.org/guide/en/elasticsearch/client/java-api/current
+
+[preface]
+== Preface
+
+This section describes the http://groovy.codehaus.org/[Groovy] API
+elasticsearch provides. All elasticsearch APIs are executed using a
+<<client,GClient>>, and are completely
+asynchronous in nature (they either accept a listener, or return a
+future).
+
+The Groovy API is a wrapper on top of the
+{java}[Java API] exposing it in a groovier
+manner. The execution options for each API follow a similar manner and
+covered in <<anatomy>>.
+
+
+[[maven]]
+=== Maven Repository
+
+The Groovy API is hosted on
+http://search.maven.org/#search%7Cga%7C1%7Ca%3A%22elasticsearch-client-groovy%22[Maven
+Central].
+
+For example, you can define the latest version in your `pom.xml` file:
+
+[source,xml]
+--------------------------------------------------
+<dependency>
+    <groupId>org.elasticsearch</groupId>
+    <artifactId>elasticsearch-client-groovy</artifactId>
+    <version>${es.version}</version>
+</dependency>
+--------------------------------------------------
+
+include::anatomy.asciidoc[]
+
+include::client.asciidoc[]
+
+include::index_.asciidoc[]
+
+include::get.asciidoc[]
+
+include::delete.asciidoc[]
+
+include::search.asciidoc[]
+
+include::count.asciidoc[]
+
diff --git a/docs/groovy-api/index_.asciidoc b/docs/groovy-api/index_.asciidoc
new file mode 100644
index 0000000..0e65a11
--- /dev/null
+++ b/docs/groovy-api/index_.asciidoc
@@ -0,0 +1,31 @@
+[[index_]]
+== Index API
+
+The index API is very similar to the
+{java}/index_.html[Java index API]. The Groovy
+extension to it is the ability to provide the indexed source using a
+closure. For example:
+
+[source,js]
+--------------------------------------------------
+def indexR = client.index {
+    index "test"
+    type "type1"
+    id "1"
+    source {
+        test = "value"
+        complex {
+            value1 = "value1"
+            value2 = "value2"
+        }
+    }
+}
+--------------------------------------------------
+
+In the above example, the source closure itself gets transformed into an
+XContent (defaults to JSON). In order to change how the source closure
+is serialized, a global (static) setting can be set on the `GClient` by
+changing the `indexContentType` field.
+
+Note also that the `source` can be set using the typical Java based
+APIs, the `Closure` option is a Groovy extension.
diff --git a/docs/groovy-api/search.asciidoc b/docs/groovy-api/search.asciidoc
new file mode 100644
index 0000000..eb9b501
--- /dev/null
+++ b/docs/groovy-api/search.asciidoc
@@ -0,0 +1,115 @@
+[[search]]
+== Search API
+
+The search API is very similar to the
+{java}/search.html[Java search API]. The Groovy
+extension allows to provide the search source to execute as a `Closure`
+including the query itself (similar to GORM criteria builder):
+
+[source,js]
+--------------------------------------------------
+def search = node.client.search {
+    indices "test"
+    types "type1"
+    source {
+        query {
+            term(test: "value")
+        }
+    }
+}
+
+search.response.hits.each {SearchHit hit -> 
+    println "Got hit $hit.id from $hit.index/$hit.type"
+}
+--------------------------------------------------
+
+It can also be executed using the "Java API" while still using a closure
+for the query:
+
+[source,js]
+--------------------------------------------------
+def search = node.client.prepareSearch("test").setQuery({
+        term(test: "value")
+}).gexecute();
+
+search.response.hits.each {SearchHit hit -> 
+    println "Got hit $hit.id from $hit.index/$hit.type"
+}
+--------------------------------------------------
+
+The format of the search `Closure` follows the same JSON syntax as the
+{ref}/search-search.html[Search API] request.
+
+
+[[more-examples]]
+=== More examples
+
+Term query where multiple values are provided (see
+{ref}/query-dsl-terms-query.html[terms]):
+
+[source,js]
+--------------------------------------------------
+def search = node.client.search {
+    indices "test"
+    types "type1"
+    source {
+        query {
+            terms(test: ["value1", "value2"])
+        }
+    }
+}
+--------------------------------------------------
+
+Query string (see
+{ref}/query-dsl-query-string-query.html[query string]):
+
+[source,js]
+--------------------------------------------------
+def search = node.client.search {
+    indices "test"
+    types "type1"
+    source {
+        query {
+            query_string(
+                fields: ["test"],
+                query: "value1 value2")
+        }
+    }
+}
+--------------------------------------------------
+
+Pagination (see
+{ref}/search-request-from-size.html[from/size]):
+
+[source,js]
+--------------------------------------------------
+def search = node.client.search {
+    indices "test"
+    types "type1"
+    source {
+        from = 0
+        size = 10
+        query {
+            term(test: "value")
+        }
+    }
+}
+--------------------------------------------------
+
+Sorting (see {ref}/search-request-sort.html[sort]):
+
+[source,js]
+--------------------------------------------------
+def search = node.client.search {
+    indices "test"
+    types "type1"
+    source {
+        query {
+            term(test: "value")
+        }
+        sort = [
+            date : [ order: "desc"]
+        ]
+    }
+}
+--------------------------------------------------