CLJ file format: Java interop

Clojure is written for the Java virtual machine and uses its classes directly: no wrappers are needed. Everything on this page is JVM Clojure; ClojureScript has its own JavaScript interop.

Classes and members

Written	Means
`Classname`, `java.util.Date`	the class (symbols of classes the namespace maps; `java.lang` is mapped by default)
`Classname$InnerClass`	an inner class
`Classname/N`, `primitive/N`	an array class of N dimensions, N from 1 to 9: `String/2`, `long/1` (1.12)
`(.method instance args*)`	calls an instance method
`(.-field instance)`	reads an instance field
`(Classname/staticMethod args*)`	calls a static method
`Classname/staticField`	reads a static field (no parentheses)
`(Classname/.method instance args*)`	calls an instance method, naming the class explicitly (1.12)
`(Classname. args)`, `(Classname/new args)`, `(new Classname args*)`	calls a constructor
`(set! (. instance-expr instanceFieldName-symbol) expr)`, `(set! (. Classname-symbol staticFieldName-symbol) expr)`	assigns an instance or a static field, as the reference gives the forms; `(set! (.-field instance) expr)` is the same with the field-access macro
`(instance? Class expr)`	true if the value is an instance of the class

The forms with a leading dot, .method and .-field, are the member-access forms that the reference prefers in all code except macros; they are shorthand for the special form .. When an object's class is not known at compile time, the call is resolved by reflection (slower); type hints avoid it.

The dot special form and its macros

Form	Meaning
`(. instance-expr member-symbol)`, `(. instance-expr -field-symbol)`	with no arguments a symbol is a field access, unless a public no-argument method of the same name exists; a name that begins with `-` is always a field
`(. instance-expr (method-symbol args))` or `(. instance-expr method-symbol args)`	a method call; `Classname-symbol` in place of the instance makes it static
`(.. instance-expr member+)`	a chain: `(.. System (getProperties) (get "os.name"))` is `(. (. System (getProperties)) (get "os.name"))`
`(doto instance-expr (method args))`	calls each method on the instance and returns the instance
`(memfn method-name arg-names*)`	a function that calls the named instance method: `(map (memfn charAt i) ["fred" "ethel" "lucy"] [1 2 3])` is `(\r \h \y)`; the reference says that `#(.charAt %1 %2)` is nearly always preferable now
`(bean obj)`	a read-only map view of the object's JavaBean properties

Method values (Clojure 1.12)

A qualified method can be used as an ordinary function in a value position: Classname/method is a function that calls a static method, Classname/.method one that calls an instance method, and Classname/new one that calls a constructor. The compiler makes the wrapping function. If the method is overloaded, it is resolved by reflection unless :param-tags metadata says which signature is meant: ^[String long] Foo/bar (the vector form of ^ attaches :param-tags). A static field is a value and is written without parentheses.

Also new in 1.12: a Clojure function is converted automatically where a Java functional interface is expected (a ^java.util.function.Predicate hint makes it explicit), any IDeref (a delay, future, atom) can be used as a Supplier, and stream-seq! stream-reduce! stream-transduce! stream-into! consume a Java Stream.

Implementing interfaces and extending classes

reify, deftype, defrecord implement interfaces and protocols (see Protocols, records and multimethods); definterface and gen-interface define interfaces.
(proxy [class-and-interfaces] [args] fs+) makes an object that extends a class and implements interfaces, with each method a function in a map; proxy-super calls the superclass method.
gen-class, and the :gen-class clause of ns, generate a named Java class when compiled ahead of time (see File structure).

Arrays

Use arrays only to meet Java libraries that need them. make-array, object-array, to-array, into-array, to-array-2d and the typed constructors boolean-array byte-array char-array short-array int-array long-array float-array double-array make them; aget, aset (and aset-int and the other typed forms), alength, aclone, amap and areduce use them; the array casts booleans bytes chars shorts ints longs floats doubles cast a value to an array of that primitive type (and are also names for the array type hints). A Java varargs method takes an explicit array in place of its varargs.

Type hints and primitives

A type hint is a :tag metadata on a symbol or expression, written ^String x. It lets the compiler resolve a call at compile time and avoid reflection. For a function's return value the hint goes before the parameter vector: (defn f ^String [a] …), or before each vector in a multi-arity definition. (set! *warn-on-reflection* true) prints a warning wherever reflection is used.
Hints may also be written as aliases of primitive types: int long float double short boolean byte char void, and the array aliases ints longs floats doubles shorts booleans bytes chars objects.
let and loop locals take the inferred, possibly primitive, type of their value; recur rebinds primitives without boxing; arithmetic and the comparison operators are overloaded for primitives; num boxes a primitive; the unchecked-* operations and *unchecked-math* skip overflow checks.

Not described

Known, not yet covered

Reference: the rules of overload resolution, boxing and the numeric tower, :tag on arglists, :once and annotation support, and the whole Java FAQ are not described; the reference page on interop was read through its headings, the arrays, type hints and aliases sections and part of the member-access rules.
Reference: clojure.java.io, clojure.java.shell, clojure.java.process and clojure.java.browse are listed on the standard library page but their functions are not explained.

Unknown

Reference: no JVM was available to run any example; that (set! (.-field instance) expr) is the same as the dot form is from knowledge of the language.

.CLJ File Format – Java interop