Clojure "DSL" programming

Question

I am designing a JAX-RS REST Server using Clojure and RESTEasy.

It is my understanding that applications written in Lisp-family languages are, more than those in "traditional" imperative languages, built up as "domain-specific languages". The application is designed from the bottom-up as more and more "refined" functions until, at the "top" level, the application becomes a series of function calls to very high-level functions.

I am trying to do this for my REST server, starting with the resource classes that service URL requests (GET, POST, PUT, DELETE).

Here is my first resource:

(ns com.example.server.resources.buildtime
  (:import [javax.ws.rs CookieParam GET Produces Path]
           [javax.ws.rs.core Context Cookie NewCookie Response UriInfo]
           [org.jboss.resteasy.annotations.providers.jaxb Formatted]))

(definterface BuildTime
  (getBuildTime [^javax.ws.rs.core.UriInfo info
                 ^javax.ws.rs.core.Cookie security-cookie]))

(deftype
  ^{Formatted true}
  BuildTimeResource []
  BuildTime
  (^{GET true
     Path "/buildtime"
     Produces ["application/json"]}
    getBuildTime
    [this info security-cookie]
    (.. (Response/ok "20111009") build)))

This resource returns the server build time as a String (enclosed in a JSON package) when called at the URL "/buildtime" with the GET http method.

I will be writing many more of the these resource classes and enclosed methods (most classes will have more than one method), each with a definterface and a deftype. This seems like a perfect use for macros.

I am soliciting suggestions for how this might be done as a DSL. How does one go about thinking in terms of DSLs?

Answer 1

If I were undertaking this, I think I would start by creating a ring adapter for RESTEasy. After this is done, Compojure will know how to handle and respond to http requests in a way that works with RESTEasy. Here's some information to help you get started.

Ring is a clojure library that represents http requests and responses in a standard way. This standard is detailed here.

It works by receiving an http request from any of a variety of libraries (ie. jetty, netty, finagle) and translating it into the standard representation. It then hands the request off to a request handler (often this is defined using Compojure). The handler then returns a response (also defined in the above spec). This response is translated by ring back into a form that jetty, netty, etc. can understand.

This translation is done by ring adapters. There are a few listed here, and ring comes with an adapter for jetty built in. Maybe you can use one of them as a template for creating a RESTEasy adapter. After you've done that you can use compojure in the standard way.

Ring and compojure are great examples of how to create a DSL. Like all good DSLs, it simplifies creating solutions in its problem domain (HTTP servers in this case). They are great examples of how to think in terms of DSLs. If you study them, you'll be well on your way towards thinking in terms of DSLs.