You can create a Java array with the make-array function:

(make-array type & dimensions)

The type argument must be a class. If you want an array of a Java primitive type, such as int or double, you can use the TYPE field of the corresponding class:

(make-array Double/TYPE 40)   ;; creates a double[40] array

If you give only one dimension to make-array, you get a normal Java array of that length. If you give multiple dimensions, you get a multidimensional array, which is implemented in Java as an array of pointers to other arrays.

In addition to make-array, there are convenience functions for creating arrays of Java primitive types: int-array, long-array, float-array, and double-array. Each can be called in several argument forms:

The Clojure function to-array takes any Clojure collection type and returns a Java Object[] array. If you have a two-dimensional matrix represented as a collection of collections, you can use the to-array-2d function to produce a 2-dimensional Java array. For example, the following code:

user=> (def matrix [[1 0 0] [0 1 0] [0 0 1]])
#'user/matrix
user=> (to-array-2d matrix)
#<Object[][] [[Ljava.lang.Object;@540984b>

If you need to convert a collection into an array of a specific type, you can use the into-array function:

(into-array collection)
(into-array type collection)

Called with one argument, a collection, into-array returns an array of the same type as the first item in the collection. Called with two arguments, the first argument is a class specifying the type of the array. For example, the following code:

user=> (into-array Comparable ["aa" "bb" "cc"])
#<Comparable[] [Ljava.lang.Comparable;@a00185>

You can retrieve a single value from an array (of any dimensionality) with the aget function:

(aget array & indices)

Setting elements in an array is complicated by the need for special functions for primitive arrays. The aset function works on any arrays of any Object type:

(aset array index value)
(aset array & indices value)

The setter functions for arrays of primitive types work the same way: aset-boolean, aset-byte, aset-char, aset-short, aset-int, aset-long, aset-float, and aset-double. Note that these functions are not very efficient; in fact, they are slower than aset on type-hinted arrays (see Chapter 14). Use them only when you need to deal with small arrays for Java interop purposes, not for performance.

You can copy an array with the aclone function, and get its length with the alength function (although count also works).

The map and reduce functions will work on Java arrays, but they work by converting the arrays to sequences. For slightly greater efficiency, you can iterate over arrays directly using array-specific macros.

(amap a idx ret expr)

The amap macro initializes ret (a symbol) as a clone of the array a, then evaluates expr repeatedly with idx bound to successive indexes of a. Whatever value is returned by expr, it will be assigned to the same index of ret. Finally, amap returns ret.

(areduce a idx ret init expr)

The areduce macro assigns ret (a symbol) the value of init, then evaluates expr repeatedly with idx bound to successive indexes of the array a. Whatever value is returned by expr becomes the new value of ret. Finally, areduce returns the last value of ret.

Note that both amap and areduce are macros implemented in terms of loop/recur, so they take expressions as arguments instead of the functions used by map and reduce.

Any Clojure namespace can be AOT-compiled. There is usually little reason to do so unless gen-class is involved. AOT-compiled Clojure code is not faster than dynamically-compiled code, and it still requires the Clojure runtime libraries (clojure.jar). However, AOT-compiled code will start up slightly faster, because the Clojure compiler does not need to compile all the source code when it is loaded, which may be beneficial for large programs.

To compile a namespace, use the compile function:

(compile name)

The name argument is a quoted symbol naming the namespace you want to compile. Clojure will load the source file for that namespace, using the same rules as require for converting namespace names to file names (see Chapter 7); compile it to Java bytecode and write the bytecode out to .class files in a target directory. One namespace will produce many .class files, one for each function.

The tricky part of AOT-compilation is getting the classpath configured correctly. The target directory where compile writes .class files is stored in the Var *compile-path*. When you call compile, both this directory and the source .clj file must be available on the Java classpath. The default *compile-path* is "classes", assumed to be a directory within the current working directory. You can change it on the Java command line by setting the Java system property "clojure.compile.path".

Here's an example. Suppose you have a project containing three directories: source code in "source", compiled code in "target", and libraries in "lib". Your Clojure code is in the file "source/com/example/my_library.clj", with the following namespace declaration:

(ns com.example.my-library)

To compile this namespace, you can start Clojure from the root directory of your project like this (all on one line):

java -cp lib/clojure.jar:sources:target    

  -Dclojure.compile.path=target  clojure.main

Note that the classpath contains three elements: the Clojure JAR file, the "sources" directory, and the "target" directory. (You would add JAR files for any other libraries your project uses.) In addition, the system property clojure.compile.path is set to "target". The "target" directory must exist! Then, at the Clojure REPL, you can run:

user=> (compile 'com.example.my-library)

This will load the source file from "source/com/example/my_library.clj", compile it, and write a bunch of .class files in the directory "target/com/example/".

Once this is done, you can load and use the namespace com.example.my-library without the original source files. All you need are the .class files and clojure.jar. Obviously, you shouldn't delete your source files, because you might want to change them and recompile later.

To make it easier to integrate AOT-compilation into build scripts, you can start Java with the class clojure.lang.Compile instead of clojure.main, setting up the classpath and system property as before, passing the namespaces to be compiled as arguments on the command line. In the Apache Ant build system, for example, the XML configuration would contain something like the following snippet:

<java classname="clojure.lang.Compile"
      classpath="clojure.jar:target:source">
  <sysproperty key="clojure.compile.path"
               value="target"/>
  <arg value="my.first.namespace"/>
  <arg value="my.second.namespace"/>
</java>

How does gen-class fit into this? When compile is compiling a file that calls gen-class, it generates the additional .class files described by the gen-class configuration options. At any other time, i.e., when not AOT compiling, gen-class does nothing.

Now you're ready to tackle the options to gen-class. You will usually only need the first three options, :name, :extends, and :implements, but we cover them all here. Wherever the arguments call for a class or interface name, that name may be given as either a symbol (which will not be evaluated) or a String, and must be fully-qualified with the Java package name.

The :name argument is the name of the class to be generated. Remember that this is a Java-style package + class name, so you must use underscores or CamelCase instead of hyphens.

The :extends argument is the fully-qualified name of a Java class (not an interface) as either a String or a symbol. The generated class will be a subclass of that class.

The :implements argument is a vector of Java interface names. The generated class will be declared to implement those interfaces and will include stub methods for all the methods defined in those interfaces.

As explained earlier, the class generated by gen-class will only contain stub methods. The implementations of those methods are normal Clojure functions in a namespace. Each Clojure function will have the same name as its corresponding method, with an added prefix. The prefix defaults to "-", and can be changed with the :prefix argument to gen-class. The functions will be called with the object instance as their first argument. For example, if your generated class implements a Java interface with the methods doStuff(int i) and doMoreStuff(String s), your namespace should contain the following function definitions:

(defn -doStuff [this i] ...)
(defn -doMoreStuff [this s] ...)

By default, gen-class uses the current namespace to look up method definitions; this can be changed with the :impl-ns argument to gen-class.

You may want to create a class that can be called by Java code but preserves Clojure's notions of immutable state. The :state argument names a public instance field (of type Object) that will be added to the generated class. Within your methods, you can access the value of this field just like any other Java field. Note that the :state field is declared final, so it may not be set outside of the object constructor. Typically, the value of the :state field will be one of Clojure's mutable reference types (Ref, Agent, or Atom). In this way, you can create stateful Java objects that take advantage of Clojure's transactional semantics.

If your object has :state, you must provide a way to initialize it. The :init argument names an "initialization function" that is called before the superclass constructor, with the same arguments as the constructor. The initialization function must return a vector like [[args...] state], where state is the value of the :state field and args are the arguments that will be passed back to the superclass constructor.

To do additional computation after the superclass constructor, the :post-init argument names a function that will be called immediately after the superclass constructor(s), with the newly-constructed object as its argument. The :post-init function's return value is ignored.

By default, the generated class contains stub methods for all non-private methods of the parent class and interfaces. If you want to add to this set of methods, you can do so with the :methods option to gen-class. Its argument is a vector of method signatures, each of the form [name [arg-types...] return-type]. Those methods are then implemented by Clojure functions with prefixed names just like superclass methods. To create a static method, add :static true metadata to the signature vector.

For example, suppose you want to add two methods to your class with the following Java signatures:

public int add(int a, int b);
public static String getNextID();

You would use gen-class like this:

(gen-class ...
  :methods [[add [int int] int]
            #^{:static true} [getNextID [] String]])
...
(defn -add [this a b] ...)
(defn -getNextID [] ...)

Remember that :methods is only used for adding methods that do not exist in the superclass/superinterfaces. You do not need to redefine the signatures of existing Java methods.

The generated class will automatically have public constructors with type signatures matching those of the superclass constructors. You can add additional constructors with the :constructors option to gen-class. The argument to :constructors is a map of the form {[types...] [super-types...], ...}. The keys of the map are vectors of argument types for the added constructors, which must map to an existing superclass constructor, identified by a vector of its argument types. For example, if your generated class :extends a class Foo with a constructor Foo(int, int), and you want to add a constructor that takes a single String argument, you can do so with the following gen-class form:

(gen-class ...
  :constructors {[String] [int int]} ...)

You must also supply an :init function that accepts and returns the appropriate types.

Some Java development styles encourage static factory methods instead of public constructors. You can add static factory methods to your generated class with the :factory option to gen-class. Its argument is the name of the generated factory method; this method will be overloaded to accept all the same argument types as the constructors.

Because your method implementations are Clojure functions, not true Java methods, they do not have access to protected fields of the superclass, nor can they call superclass methods. To work around this, you can add the :exposes and :exposes-methods options to gen-class.

:exposes takes a map of the form {field {:get getter, :set setter}, ...}. Each key is the name of a protected instance field of the superclass, the value specifies the names of public getter and setter methods that will be added to the generated class. You do not need to provide implementations for these methods; they are generated automatically.

:exposes-methods takes a map of the form {super exposed, ...}, where super is the name of a superclass method, and exposed is the name of a public method that will be added to the generated class. The exposed method calls the super method. You can use this feature when, for example, your implementation of a method needs to call the superclass version of the same method.

Java allows any class to be run as command-line executable, provided it has a method declared public static void main(String[] args). You can specify :main true in gen-class to add the static main method to your generated class. The function implementing this method should be called -main (unless you changed the prefix). Rather than a single array argument, it will be called with however many arguments are present on the command line. An easy way to handle this is to define the function to take a variable number of arguments:

(gen-class ...
  :main true ...)
(defn -main [& args] ...)

Once you have compiled a namespace with a :main method, you can execute it at the command line like this:

java -cp ...  your.class.name  arguments...

Remember that your compiled .class files and the Clojure JAR must be on the classpath.

By default, any class generated with gen-class will automatically load its implementing namespace from the classpath the first time it is used, just as if you had require'd the namespace. If you are using some alternative code loading mechanism and you do not want the generated class to interfere, add the :load-impl-ns false option to gen-class.

gen-class can appear as part of a namespace declaration in the ns macro. In this case, it is written as (:gen-class options...). Within ns, the :name and :impl-ns options default to the namespace being declared and :main defaults to true. Everything else is the same. However, remember that you need not limit yourself to one namespace per generated class. You could generate several classes, with different :prefix options, and put all the method implementations in the same Clojure namespace.

If all you need is a program that can be run at the command line, you only need a -main function and an ns declaration containing (:gen-class), as in this example:

(ns com.example.app
  (:gen-class))

(defn -main [& args]
  (println "Hello, World!"))

When AOT-compiled into a directory named classes, this example can be run with the command:

java -cp classes:clojure.jar com.example.app