Coming Up for Air

Jerkey: A Kotlin DSL for Jersey

I’m currently working on a DSLs-in-Kotlin presentation for my local JUG, so I need a good domain in which to work. HTML is a great sample domain, but it’s been done to death. After a bit of head scratching, I’ve come up with what is, I think, a somewhat novel domain: REST application building. Sure, there are libraries like Ktor, but suffers from some very serious NIH. I’m totally kidding, but the dearth of discussions regarding REST applications and DSL construction was good enough for me, so let’s see what we have so far.

What really sold me on the idea was that Jersey already offers an API for programmatically creating REST endpoints, which you can read about here. All we need to do then, is define a DSL to build the application model, then run it through this API and let Jersey do the heavy lifting, which sounds perfect for what is intended to be, primarily, a didactic project. I’ll spare you the details of how the DSL is built and skip straight to the "finished" project:

application {
    produces = "application/json"
    consumes = "application/json"
    resource {
        path = "items"
        method = "get"
        handler = ::listItems
        param {
            source = "query"
            name = "someParam"
            type = Int::class
    resource {
        path = "items/{id}"
        method = "get"
        handler = ::getItem
        param {
            source = "path"
            name = "id"
            type = Int::class

While there’s a good chance I’ll modify the structure of the DSL as I continue to work on the presentation, this represents a working DSL. Once I call build(), I can then access the REST application via a browser or curl.

A few things to call out. Notice the handler property. With that, I can specify the function in my Kotlin code that will actually handle the request. Where Jersey allows me to define a method like this:

public Response listItems(@QueryParam("someParam") Integer someParam) { ... }

I have yet to be able to figure out how to dispatch to a Kotlin method with an arbitrary number of parameters. One might think of the spread operator, but requires the receiving method specify a varargs parameter, which I’ve tried to avoid, possibly for no good reason other than tunnel vision. :) What I’ve opted to use, though, is CallContext object, which will encapsulate various things pulled from the request and presented in, in theory, ready-to-use forms. In this instance, the context would have a parameter called 'someParam' of type Int. At this point, the type coercion is pretty crude, but the whole thing is a work in progress, so cut me some slack. :)

One of the more interesting parts, I think, is the creation of the resources for Jersey to consume, and part of the fun in that is the demonstration of Kotlin’s Java interop, going both directions:

class JerkeyResourceConfig(val application: Application) : ResourceConfig() {
    init {
        val resourceBuilder = Resource.builder()

        application.resources.forEach { res ->
            val childResource = resourceBuilder.addChildResource(res.path)
            val methodBuilder = childResource.addMethod(res.method.toUpperCase())
                    .handledBy(Inflector<ContainerRequestContext, Response> {
                        val context = CallContext()
                        (it.uriInfo.queryParameters + it.uriInfo.pathParameters).forEach { qp ->
                            val name = qp.key!!
                            val value = qp.value[0]!!
                            val param = res.params[name]

                            param?.let {
                                context.processParam(param, name, value)

We iterate over the resource instances from the DSL, creating subresources of the base resource defined by the application element in the DSL.

My DSL code consumes that here:

fun build() {
    val rc = JerkeyResourceConfig(this)

    val baseUri = UriBuilder.fromUri("http://localhost$path").port(port).build()
    val server = JdkHttpServerFactory.createHttpServer(baseUri, rc);

Put all of that together with this handler method:

fun listItems(context : CallContext) : Response {
    val id : Int = context.params["param"] as Int
    return Response.ok().entity("items $id").build()

and we get this from the command-line:

$  curl -Ssk http://localhost:8080/items?param=1024
items 1024

It’s not very flashy, but for one evening’s hacking, it’s not too shabby. :) If you’d like to follow along, you can find the (meager) sources here.


Sample quote

Quote source