Getting Started with Ring and Compojure - Clojure Web Programming

I am currently testing out different technologies to run a small web service in a windows environment at my day job. I have worked with Node.js on Linux but have not had much luck with it on windows. At the same time I am also learning Clojure so I did some checking to see what type of web development options are available in Clojure and I found Ring and Compojure. In this post I will follow the same process I did in my Getting Started with Node.js post, that is to start off with a bare bones ‘Hello World’ sample with Ring and then follow that up with a sample using Compojure to receive parameters by GET and POST.

The Setup

If you don’t already have Clojure installed you can get everything you need from the download page. While you are there go ahead and grab the clojure-contrib zip as well. Assuming you already have Java on your machine the next step is to add the Clojure and Clojure-contrib directories to your CLASSPATH.

Once you have Clojure installed the next thing to install is lein. It is a Clojure build tool that helps you manage your projects. In my short period of time in the Clojure world lein has been a great tool and I have found it has many useful plugins. The install takes no time at all, just follow the instructions on the project’s page and you will be ready for business. Now that I have Clojure and lein installed I'm ready to start the ‘Hello Clojure Web’ project.

Creating the Hello Clojure Web App

Step number one is to create the project using lein by running the command:

lein new hello-clojure-web

When lein has finished there will be a new directory named hello-clojure-web. When you cd into the directory and do dir or ls you should see a directory structure similar to this:

Lein creates a directory structure for our project separating the tests from the source code, a .gitignore file and a project.clj file. The project.clj file it handles project dependencies and sets up variables that are used to describe the project. We will just scratch the surface of the project file in this post.

The project.clj File

In the project.clj file the first line simply defines the name and version of the project. The dependencies section is used to list what libraries the project depends on. For our app we need to add the dependencies to the ring-core and ring-jetty-adapter libraries. To get the exact information I needed to add in the dependencies section I turned to the clojars.org site. The clojars site is a place where you can find open source libraries. It provides you with the exact syntax required to add the library to your project. To see what a clojars page looks like visit the ring/ring-core page. The line below adds the two ring dependencies I need for my project. Dependencies are added by using the libraries name followed by the version you wish to use.

[ring/ring-core "0.3.7"][ring/ring-jetty-adapter "0.3.7"]

After we've added to the Ring dependency our project.clj file should look like:

After adding my dependencies to the project.clj file I need to 'install' them. Lein will do it for me when I run this command:

lein deps

Lein will retrieve the necessary files and place them in the project's lib directory. If all goes well you should see something like the image to the right. If you see an error message text similar to this towards the bottom of the message:

1 required artifact is missing.

for artifact:
  org.apache.maven:super-pom:jar:2.0

It usually means that you have misspelled the name of a dependency in the project.clj file. To see it for yourself remove a letter from the dependency we just added, save the file and then re-run the lein deps command.

src/hello-clojure-web/core.clj

When I created the project lein created a core.clj file in the src/hello-clojure-web directory. The only line inside of the file is the project's namespace declaration. My first step was to add a reference to the ring.adapter.jetty library which I will us to run our HTTP service. Next, I added the handler function which handles the web requests. The last line of the file starts the web service passing the handler function to the run-jetty function. Here is the completed hello-clojure-web/core.clj file.

The handler function takes one parameter which is the web request and returns the response. It hanldes all web requests that come on on port 8080 returning the same response for a request at ‘/’ and ‘/this/is/a/long/one’.

In order to test our project out we will use the REPL. Starting the REPL session with lein makes it easier to run our code within the REPL session. To start a REPL session I need to jump back to the command prompt in the project's home directory and run:

lein repl

From within the REPL session enter the following line:

(use 'hello-clojure-web.core)

This will starts up my service which is now listening for requests on port 8080. Next, I fired up Chrome and entered http://localhost:8080. If everything works correctly I should see Hello Clojure Web! If you do not see the text then an error has occurred. Usually the REPL gives an error message that will point you in the right direction.

I want to change the text to reflect the fact I'm using Ring. I'm going to keep the REPL running and go back to the source file. I changed the Hello Clojure Web string to read Hello Ring!, saved it and refreshed the browser but I didn't see the changes. When I stop and restart the REPL. Re-enter the use statement and reload the web page I will see my changes.

In order for me to see my changes without restarting the REPL I need to add a reference to the ring-devel library. Since I do not want this library to be apart of my ‘production’ version I will only add the dependency to my dev environment by making use of the dev dependency tag. My updated project.clj file now looks like this.

After the changes make sure to run lein deps again. You will see in the output of that command it places files in the hello-clojure-web/libs/dev directory in addition to the hello-clojure-web/libs directory.

Now that I have the dependencies taken care of it is time to update the code in the core.clj file. I've wrapped the run-jetty call in a function called boot so I can make use of the wrap-reload function. What this call does is reload the namespace of our application before each request is handled. So now we can make changes to our code and refresh the browser to see them. Here's what the updated code looks like:

As you can see there wasn't much change in the code needed to be able to handle our updates. To see it in action, start up REPL and view the app in the browser. Change the response text and then reload the web page. You should see our updated message. Next I'll describe how to parse parameters from a GET and POST requests.

Retrieving Parameters

In this section I'm going to introduce Compojure, a small, open source web framework. To keep things simple I am going to add the Compojure code to our already existing core.clj file. Before I make changes to core.clj I need to update the project.clj file with the Compojure dependencies.

The Updated project.clj file

I added the compojure lib in the 'normal' dependencies section and in the dev-dependencies I added the reference to the lein-ring plugin. The ring plugin allows me to start ring by running the command: lein ring server. For the ring server command to work I need to tell ring where the handler method is which is done on the last line of the file. Ring knows that app will handle the web requests. I ran lein deps again to update the project's dependencies to include lein-ring.

Now that the project.clj file is updated I need to adjust the ns statement in the core.clj file to include the Compojure libraries:

(ns hello-clojure-web.core 
  (:use compojure.core) 
  (:require [compojure.route :as route] 
            [compojure.handler :as handler]) 
  (:use ring.middleware.reload) 
  (:use ring.adapter.jetty)) 

Nothing special going on here, just a few more libraries to include. Next I setup my routes. Using the defroutes macro I create the routes I want my app to respond to. Compojure will take the route definitions and generate a Ring handler function. The routes are processed from the top down, the first match wins. If a request comes in that doesn’t match the three routes I’ve defined the route/not-found will be called.

My last step is to bind app to the handler/site my-routes function. This binding is used to start up the application. After I have updated the file I can start the app by running:

lein ring server

The command starts up the web app and brings up a browser opening it to http://localhost:3000/. To test my app I wrote a batch script that utilizes curl. It tries my three routes plus a non-existing route to ensure they are handled properly, and it worked!

The complete core.clj file:

Summary

The Clojure web world offers frameworks at different levels. You can stay at a relatively low level buy using Ring or if you want something at a little higher level you can use Compojure. I am a Clojure noob and I was able to get a web app up and running in no time. I will be expanding on my Compojure knowledge through a project I am working on with my son. We had originally planned on using Node.js but now that I found Compojure we have decided to go with a Clojure based application. As the project progresses I am sure I will have more Clojure web related posts.

Resources

Clojure, Lein, Ring, Compojure

Code

project.clj core.clj test_clojure_web.bat