Clojure: First Steps into Compilation and Class Generation

I've never quite understood class generation in Clojure. The documentation is a little terse, and working examples seem to be hard to come by. So here's my walkthrough.

First, I'm assuming that we'll be creating Clojure objects from Java, calling methods on those Clojure objects from bog-standard Java code. This, I think, is the most likely scenario for the budding Clojure hacker who wants to write part of an existing Java system in Clojure.

Environment

First, you'll need to have obtained your clojure.jar, either from the snapshots here, or from the Subversion repository and building yourself.

Next, in whatever environment you're using, add the full path to clojure.jar to your CLASSPATH. Also add "." and "classes" (both relative paths, not absolute). You'll see why later.

The Clojure Code

In the directory you're building from, create the directory structure for your package, Java-style. I'm going to be putting my Clojure code in org/djw/sample.clj, so org/djw will have to exist beforehand.

In sample.clj, most of the magic's in the namespace declaration.

(ns org.djw.sample                      ;; 1
  (:import (javax.swing JFrame))        ;; 2
  (:gen-class                           ;; 3
   :name org.djw.DJW                    ;; 4
   :extends javax.swing.JFrame          ;; 5
   :constructors {[String] [String]}    ;; 6
   :init initialise                     ;; 7
   :implements [Runnable]               ;; 8
   :state fiddlyBits))                  ;; 9

• 1. This is your Clojure namespace. It doesn't mean much from Java-land.


• 2. You can import any classes used by your Clojure file here.


• 3. :gen-class allows the compiler to generate Java bytecode files.


• 4. This is the fully-qualified name of the Java class you want to emit. The Clojure compile directive generates quite a few class files that your Java code doesn't need to know about: the one in :name is an exception: it's what your Java code will import


• 5. If your class subclasses something other than Object, name it here, as normal


• 6. I want to have a String constructor that calls the String constructor in JFrame.


• 7. The initialiser function for new instances. I lack imagination, so have called it initialise here.


• 8. Horribly, my new class is both a GUI element (a JFrame) and a Runnable. Since you can implement many interfaces, this appears in a literal vector.


• 9. The initialise function gets to attach some Clojure-side state to the object being created (you'll see that in a bit). The :state specifier creates a final instance method to access that state from Java.

This leaves two functions to implement in the Clojure code: initialise and run (the latter required by Runnable).

(defn -initialise [message]
  [[message] (ref {:message message})])

(defn -run [instance]
  (let [message (:message @(.fiddlyBits instance))]
    (println message)))

Note the dash in front of the function names (this is the default :prefix from :gen-class). Also, note that the function specified by :init in :gen-class didn't get an instance to play with, whereas run (an instance method), does. This instance is the object that the method was invoked against, effectively this from Java.

initialise has to return a vector of two elements: the first consists of the arguments to pass to the superclass constructor. The second is the state that should be attached on a per-instance basis.

run is a Runnable.run implementation, and just prints out the message that the instance was created with. Note that the state is accessed with (.fiddlyBits instance), returning the ref-wrapped Clojure map, dereferenced with '@' as normal and with the :message key used to look up the associated value.

Compiling the Clojure Code to .class Files

Create a directory called classes/[package-name], in my case classes/org/djw. Why classes? Well, that's what Clojure's global *compile-path* variable is by default, so is the root where the compile command emits .class files. That's why you added it to your CLASSPATH above (you did do that, didn't you..?)

Since clojure.jar is on your CLASSPATH, you can start a Clojure REPL with just 'java clojure.main'. You can now compile the ./org/djw/sample.clj like this:

danny@mirror Desktop [10] % java clojure.main
Clojure 1.1.0-alpha-SNAPSHOT
user=> (compile 'org.djw.sample)
org.djw.sample
user=> 

And that's it. classes/org/djw will now contain org.djw.DJW (as per gen-class's :name field). It'll also contain a bunch of other .class files: don't delete these, they are required! Clojure creates a .class file per function (including unnamed functions), as well as another for initialisation.

The Java Code

This has been a lot of effort so far. But the good news that this allows Java to talk to Clojure-generated class files without having any idea that Clojure was the source language. The Java code in Test.java to use it might look like this:

import org.djw.DJW;

public class Test
{
  public static void main(String [] args)
  {
    DJW djw = new DJW("Hello");
    new Thread(djw).start();
  }
}

And that's it. DJW is the class name, and a new instance is obtained just as with any other class. It faithfully implements Runnable, as specified in the Clojure code, and it can be duly run from a Thread created from Java.

Compiling and Running the Java Code

The Java can be compiled just as with any other. Remember that the classes folder must be in your CLASSPATH for javac to see the definition of DJW.

With clojure.jar, '.' and classes in your CLASSPATH, you can just run as you'd expect:

danny@mirror Desktop [30] % javac Test.java
danny@mirror Desktop [31] % java Test      
Hello
danny@mirror Desktop [32] %

By now, you've defined a class definition in Clojure, prompted instance creation from Java, initialised the object in Clojure, handed it to a thread in Java, and printed out a message in Clojure. That's a fair amount of bouncing around, especially for such a trivial example, but hopefully you've found it useful for what you need.