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?

To start with: stop thinking in terms of "classes". It is already a DSL, already a bit of potentially alien semantics which you may not want to see in the final DSL. Start with specifying the problem formally. List the entities, define an algebra over them, and it will naturally crystallise into your DSL. Only then you have to start thinking about implementation. — SK-logic
Do you know about compojure? github.com/weavejester/compojure It provides a DSL not unlike the one you seem to have in mind. I also found this article pragprog.com/magazines/2011-07/growing-a-dsl-with-clojure helpful to get into 'dsl-mode'. But coming up with a good DSL seems no easy task... — Paul
@Paul: I considered Compojure. We already have a large REST server written in RESTEasy/Java. Easing a new Clojure-based one into the organization will get less resistance if I use a framework with which we are familiar. Besides, JAX-RS has some very nice features. — Ralph
Watch this: blip.tv/clojure/christophe-grand-not-dsl-macros-4540700 — Alex Taggart

Brian Brian · Accepted Answer · 2012-03-21T03:55:50

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.

Clojure "DSL" programming

1 Answers