Sunday, February 19, 2012

Neo4J with Scala Play! 2.0 on Heroku (Part 5) :: Dispatch

Note

This post is a continuation of this post, which is the fourth part of a blog suite that aims the use of Neo4j and Play2.0 together on Heroku.

Intro

In this suite, we're gonna use Neo4J graph database through its HTTP REST api, which is quickly introduced in this post.
So that, we'll have to communicate with the server using HTTP, here comes the Dispatch scala library.
Neo4J uses Json as the resources representation, we've already discussed this subject in Play 2.0 in this post.
How to stick them together will be discussed in the next post.
Here we'll concentrate on some introduction to Dispatch's DSL for making HTTP requests and on a powerful abstraction of the body parser, that is, the Handlers.

Dispatch

The DSL

Dispatch is a very powerful library for communicating through the HTTP protocol, offering a DSL for making such queries, but also for using their responses.
Where we all know, that response can be of different content-type, the DSL presents easy handler for them.
Getting back to queries, an HTTP request has been given a method like GET or POST, when dealing with RESTful services, we'll see PUT and DELETE in the game.
When data must be provided we'll have to pass some arguments/parameters in the request payload (or url).
Let's see how those actors compose in the Dispatch's DSL.

URL

The url of the HTTP request is basically composed of the host and port, followed by path elements. Here is how to create an url such url http://dispatch.databinder.net/URLs+and+Paths.html

Attributes and Headers

After having build a Request (see above), you now have access to some modifier on it.
The probably best way to learn all of them will to check the source code here.
But here is some examples:

Method

The method is the quite more simple... juste append the name to the request, in order to change the method from 'GET' to another:

Payload

As for headers, you better check the code for know every tools, the library put in your hands. Here is some conventions I understood from the code:

Executors

Dispatch works with executors that execute the queries and accepts handlers for handling reponse.
Such response waiting is configurable by choosing among several implementations, the documentation is well suited on the wiki.
But in our case, what we need is synchronousity, because the RESTful service is also out backend service. So the executor comes with the `dispatch` package, this way:

Handlers (Response's Body)

Here's come the sfun... Handling responses.
Actually, this piece of code comes in the game just before we apply the request to the executor, but ok, let's takle it now.
A handler can also be called the response parser, that said, it is responsible to parse the whole content into a new form.
Some existing handlers are:
Basically, a handler defines an operator, a result type and takes a block that deals with such result type instance.
Some examples of such handlers are made on the wiki, especially for Json or html (here, here and here).
Others handlers exists by default, for redirecting to outstream, to compose or chain handlers.

In the next post, we'll see how to use Neo4J Json Rest Api with Play! framework through Dispatch.