Creating an Extension

This section will demonstrate how to create an Extension for Rexster. Lets start by creating a PingExtension and then modify it over the course of the documentation. The code for the PingExtension can be found in the Extension samples within Rexster Kibbles.

The extension will depend on classes in rexster-core:

<dependency>
    <groupId>com.tinkerpop.rexster</groupId>
    <artifactId>rexster-core</artifactId>
    <version>??</version>
</dependency>

A Simple Ping Extension

@ExtensionNaming(namespace = "ex", name = "ping")
@ExtensionDescriptor(description = "Ping me.")
public class PingExtension extends AbstractRexsterExtension {

    @ExtensionDefinition(extensionPoint = ExtensionPoint.GRAPH)
    public ExtensionResponse evaluatePing(@RexsterContext RexsterResourceContext context,
                                          @RexsterContext Graph graph) {
        Map<String, String> map = new HashMap<String, String>();
        map.put("ping", "pong");
        return ExtensionResponse.ok(map);
    }
}

The extension is named using @ExtensionNaming annotation where a namespace and name is provided. The extension must implement the RexsterExtension interface (or simply extend from AbstractRexsterExtension which implements it itself). A method is provided called evaluatePing. This method is attached to the ExtensionPoint.GRAPH. Thus, when

http://localhost:8182/graphs/mygraph/ex/ping

is resolved, a JSON object is returned that has the key/value ping/pong.

{
  "ping": "pong"
  "version": "*.*"
  "queryTime": 3.765
}

Of course, you can (and probably will) interact with the graph and perform some calculation. In these simple examples, no graph manipulations are discussed.

Automatic Parameter Parsing and Self-Documenting Extensions

@ExtensionNaming(namespace = "ex", name = "ping")
@ExtensionDescriptor(description = "Ping me")
public class PingExtension extends AbstractRexsterExtension {

    @ExtensionDefinition(extensionPoint = ExtensionPoint.GRAPH)
    @ExtensionDescriptor(description = "A simple ping extension.")
    public ExtensionResponse evaluatePing(@RexsterContext RexsterResourceContext context,
                                          @RexsterContext Graph graph,
                                          @ExtensionRequestParameter(name="reply", description="a value to reply with") String reply) {
        Map<String, String> map = new HashMap<String, String>();
        map.put("ping", reply);
        return ExtensionResponse.ok(map);
    }
}

There are two new add-ons to the PingExtension.

1. @ExtensionDescriptor: An annotation to provide documentation to the user when the extension fails.
2. @ExtensionRequestParameter: An annotation to parse the JSON request object and provide value as a parameter.

Note what is returned when http://localhost:8182/graphs/mygraph/ex/ping is resolved:

{
  "message": null
  "api": {
    "description": "A simple ping extension."
    "parameters": {
      "reply": "a value to reply with"
    }
  }
  "success": false
}

By annotating the method and its parameters, an API is created. Next, resolve http://localhost:8182/graphs/mygraph/ex/ping?reply=ping-a-ling and what is returned is:

{
  "ping": "ping-a-ling"
  "version": "*.*"
  "queryTime": 4.281
}

Getting the Request Object and Returning a Result Object

In Rexster, JSON comes in and JSON goes out (see Mapping a URI to JSON). Its possible to get the values of the JSON request object using @ExtensionRequestParameter annotations. You can also get the JSON object directly with:

JSONObject requestObject = context.getRequestObject()

Next, building up the result in a JSONObject is as easy as using Java Map. When the result object has been constructed, return it with a ExtensionResponse method (e.g. ok, error). That is all there is to it.