nnest/sparrow

Elastic Search Client of Java

Sparrow

An Elastic Search client.

Sparrow is a sub module of NEST.

Status

Slack

nest-group-buddies.slack.com

User Guide

Sparrow-Simple

A very simple client for Elastic Search.
Use Elastic Search 5.1.1, FastXML Jackson, OGNL, SnakeYaml.

The default usage, see TestYmlLoader

Template

Define Yaml files, and follow the test case.

---
name: index-dynamic
method: PUT
endpoint: /${index}/${type}/${document.id}
params:
  timeout: 5m
  refresh: true
body:
  user: ${document.user}
  post_date: ${document.postDate}
  message: ${document.message}
  topic: ${document.topic}
headers:
  Authorization: Basic Idontknowwhatthehellitis!

Support noop key. In the following sample, ${document} should be generated as a JSON body.

name: index-dyn
method: PUT
endpoint: /${index}/${type}/${document.id}
body: 
  ${@noop}: ${document}

Support bulk command. Note the key must start with @, and they are ordered by string sorting.
In current Elastic Search(5.1.1), it is a JSON object per bulk line.
" is optional for json attribute key and value.

ame: bulk
method: POST
endpoint: /_bulk
body: 
  ${@1}: {index: {_index: twitter, _type: tweet, _id: 300 }}
  ${@2}: {user: bulk-one, message: From Bulk Command}
  ${@3}: {"index": {"_index": "twitter", "_type": "tweet", "_id": "301" }}
  ${@4}: {"user": "bulk-two", "message": "From Bulk Command"}

Context, Loader and Template

There is a context CommandTemplateContext, and a loader CommandTemplateLoader.
A simple context implementation SimpleCommandTemplateContext to support loading templates from file system or class path, also supports context hierarchy.
A Yaml loader implementation YmlCommandTemplateLoader which using SnakeYaml to load templates.
Template contains:

• name, global unique key to find the template,
• method, Http Method, mostly is GET, PUT, DELETE or POST. According to the document of Elastic Seach and which endpoint used,
• endpoint, relative location. eg. /_bulk, /${index}/${type}/${document.id}.
• body, request body. Nested map.
• params, query string, One level map.
• headers, Http headers. One level map.

endpoint, body, params and headers can contains dynamic patterns. Dynamic Patterns is wrapped by ${}, eg. ${document} means get value of document property.
Both key and value of map can be defined by dynamic patterns or in mix mode.
To fetch value from given params, the OGNL library is used, which means format of dynamic pattern must follow the OGNL rules.
See test case TestYmlLoader to find more information.

Executor

To execute the command, there is a CommandExecutor, and default implementation DefaultCommandExecutor.
Executor finds values from parameter params into template, and transforms to request body, sends to Elastic Search server, and calls response listener to handle repsonse.
Executor must have its context, rest client builder and body value converter.

• Prepare templates via context,
• Configure the rest client settings via rest client builder,
• Any body value should be converted to string via BodyValueConverter, and there are
  • PrimitiveBodyValueConverter,
  • JacksonBodyValueConverter, use FastXML Jackson object mapper to serializing, is default converter,
  • BodyValueConverterChain, chain of converters.

Response Handler

To handle the response, implements the CommandExecutionHandler. No matter how the request sending, sync or async, always use execution handler to handle response. There are

• NoopCommandExecutionHandler, actually do nothing, just for quickly implementation,
• AbstractJacksonCommandExecutionHandler, using FastXML Jackson object mapper to deserializing.

Reason of no standard response handler implementation is, cannot find the standard format(s). For specified rest request, the response format is predictable, but because Elastic Search supports very complex request formats, makes response unpredicatable. eg.

• bulk request, the repsonse only depends on the request itself.
• in some case, throw exception when not found, such as update. but in some case, response returned, such as exists.

So read document of Elastic Search, implements your own response handlers to handle the response.

License

MIT

Seeking for Cooperator

If you are interested in this project, contact me via [email protected].