For each custom REST class, Elasticsearch will pass three arguments when creating an object of such type: the Settings type object, which holds the settings; the RestController type object that we will use to bind our REST action to the REST endpoint; and the Client type object, which is an Elasticsearch client and entry point for cooperation with it. All of these arguments are also required by the super class, so we invoke the base class constructor and pass them.

There is one more thing: the @Inject annotation. It allows us to inform Elasticsearch that it should put the objects in the constructor during the object creation. For more information about it, please refer to the Javadoc of the mentioned annotation, which is available at https://github.com/elasticsearch/elasticsearch/blob/master/src/main/java/org/elasticsearch/common/inject/Inject.java.

Now, let's focus on the following code line:

controller.registerHandler(Method.GET, "/_mastering/nodes", this);

What it does is that it registers our custom REST action implementation and binds it to the endpoint of our choice. The first argument is the HTTP method type, the REST action will be able to work with. As we said earlier, we only want to respond to GET requests. If we would like to respond to multiple types of HTTP methods, we should just include multiple registerHandler method invocations with each HTTP method. The second argument specifies the actual REST endpoint our custom action will be available at; in our case, it will available under the /_mastering/nodes endpoint. The third argument tells Elasticsearch which class should be responsible for handling the defined endpoint; in our case, this is the class we are developing, thus we are passing this.

Although the handleRequest method is the longest one in our code, it is not complicated. We start by reading the request parameter with the following line of code:

String prefix = request.param("prefix", "");

We store the prefix request parameter in the variable called prefix. By default, we want an empty String object to be assigned to the prefix variable if there is no prefix parameter passed to the request (the default value is defined by the second parameter of the param method of the request object).

Next, we retrieve the NodesInfoResponse object using the Elasticsearch client object and its abilities to run administrative commands. In this case, we have used the possibility of sending queries to Elasticsearch in an asynchronous way. Instead of the call execute().actionGet() part, which waits for a response and returns it, we have used the execute() call, which takes a future object that will be informed when the query finishes. So, the rest of the method is in the buildResponse() callback of the RestBuilderListener object. The NodesInfoResponse object will contain an array of NodeInfo objects, which we will use to get node names. What we need to do is return all the node names that start with a given prefix or all if the prefix parameter was not present in the request. In order to do this, we create a new array:

List<String> nodes = new ArrayList<String>();

We iterate over the available nodes using the following for loop:

for (NodeInfo nodeInfo : response.getNodes())

We get the node name using the getName method of the DiscoveryNode object, which is returned after invoking the getNode method of NodeInfo:

String nodeName = nodeInfo.getNode().getName();

If prefix is empty or if it starts with the given prefix, we add the name of the node to the array we've created. After we iterate through all the NodeInfo objects, we call the are starting build the response and sent it through the HTTP.

The last thing regarding our CustomRestAction class is the response handling, which is the responsibility of the last part of the buildResponse() method that we created. It is simple because an appropriate response builder is already provided by Elasticsearch under the builder argument. It takes into consideration the format parameter used by the client in the call, so by default, we send the response in a proper JSON format just like Elasticsearch does and also take the YAML (http://en.wikipedia.org/wiki/YAML) format for free.

Now, we use the builder object we got to start the response object (using the startObject method) and start a nodes field (because the value of the field is a collection, it will automatically be formatted as an array). The nodes field is created inside the initial object, and we will use it to return matching nodes names. Finally, we close the object using the endObject method.

After we have our object ready to be sent as a response, we return the BytesRestResponse object. We do this in the following line:

return new BytesRestResponse(RestStatus.OK, builder);

As you can see, to create the object, we need to pass two parameters: RestStatus and the XContentBuilder, which holds our response. The RestStatus class allows us to specify the response code, which is RestStatus.OK in our case, because everything went smoothly.