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

	:/("dispatch.databinder.net", 80) / "URLs+and+Paths" //note that the port can be omitted
	url("http://dispatch.databinder.net/URLs+and+Paths") // pretty simple, if the root is already a path

view raw url.scala hosted with ❤ by GitHub

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:

	url(urlString)
	>\ "ISO-8859-1" //set the charset
	<:< (Map("Accept-Language" -> "fr-BE" )) //set some headers
	gzip //encode the response in archived gzip is accepted

view raw attr_headers.scala hosted with ❤ by GitHub

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:

	url(urlString) POST
	url(urlString) PUT
	url(urlString) DELETE
	url(urlString) HEAD

view raw methods.scala hosted with ❤ by GitHub

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:

	url(urlString) << (bodyAsStringOrTupleOfStrings) // Two "less than"s will POST with the body as payload
	url(urlString) <<< (bodyAsStringOrTupleOfStrings) // Three "less than"s will PUT with the body as payload
	url(urlString) <<? (tupleOfStrings) // the payload will be generated as query parameters

view raw payload.scala hosted with ❤ by GitHub

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:

	import dispatch._
	val http = new Http
	http(:/("localhost", 7474) / "db" / "data") //ok now what to do with the result... here come the Handlers

view raw executor.scala hosted with ❤ by GitHub

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:

	val h = new Html
	h(url(urlString) >| ) // the simpler, it ignores the content
	h(url(urlString) <> { xml => //do something with xml } ) // this handler converts to xml
	h(url(urlString) >- { txt => //do something with txt } ) // this handler converts to txt

view raw handlers.scala hosted with ❤ by GitHub

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.