• Class access
• Member access
  • Method values
• The Dot special form
• Support for Java in Clojure Library Functions
• Implementing Interfaces and Extending Classes
• Arrays
  • Vararg methods
• Type Hints
• Aliases
• param-tags
• Support for Java Primitives
• Coercions
  • Primitive coercions
  • Functional Interface Conversion
• Some optimization tips
• Java Stream Support
• Simple XML Support
• Calling Clojure From Java

Classname
Classname$InnerClass
Classname/N
primitive/N

Symbols representing class names are resolved to the Class instance. Inner or nested classes are separated from their outer class with a $. Fully-qualified class names are always valid. If a class is `import`ed in the namespace, it may be used without qualification. All classes in java.lang are automatically imported to every namespace.

A symbol whose ns-part names a class or a primitive, and whose name part is a single digit between 1 and 9, designates an array class of that component type and dimension. Added in 1.12.

(.instanceMember instance args*)
(.instanceMember Classname args*)
(.-instanceField instance)
(Classname/staticMethod args*)
(Classname/.instanceMethod instance args*)
Classname/staticField

The preferred idiomatic forms for accessing field or method members are given above. The instanceMember form works for both fields and methods. The instanceField form is required if both a field and a 0-argument method of the same name exist.

Since Clojure 1.12, Classname/.instanceMethod refers to an instance method. When an instance method is specified, the instance should be provided after the member and before the args. When a qualified instance method is present then the qualifying class takes precedence over any additional type information on the instance for the purpose of resolving the instance method.

The unqualified "." forms expand into calls to the dot operator (described below) at macroexpansion time. The expansions are as follows:

Method values

(. instance-expr member-symbol)
(. Classname-symbol member-symbol)
(. instance-expr -field-symbol)
(. instance-expr (method-symbol args*)) or (. instance-expr method-symbol args*)
(. Classname-symbol (method-symbol args*)) or (. Classname-symbol method-symbol args*)

Special form.

The '.' special form is the basis for access to Java. It can be considered a member-access operator, and/or read as 'in the scope of'.

If the first operand is a symbol that resolves to a class name, the access is considered to be to a static member of the named class. Note that nested classes are named EnclosingClass$NestedClass, per the JVM spec. Otherwise it is presumed to be an instance member and the first argument is evaluated to produce the target object.

For the special case of invoking an instance member on a Class instance, the first argument must be an expression that evaluates to the class instance - note that the preferred form at the top expands Classname to (identity Classname).

If the second operand is a symbol and no args are supplied it is taken to be a field access - the name of the field is the name of the symbol, and the value of the expression is the value of the field, unless there is a no argument public method of the same name, in which case it resolves to a call to the method. If the second operand is a symbol starting with -, the member-symbol will resolve only as field access (never as a 0-arity method) and should be preferred when that is the intent.

If the second operand is a list, or args are supplied, it is taken to be a method call. The first element of the list must be a simple symbol, and the name of the method is the name of the symbol. The args, if any, are evaluated from left to right, and passed to the matching method, which is called, and its value returned. If the method has a void return type, the value of the expression will be nil. Note that placing the method name in a list with any args is optional in the canonic form, but can be useful to gather args in macros built upon the form.

Note that boolean return values will be turned into Booleans, chars will become Characters, and numeric primitives will become Numbers unless they are immediately consumed by a method taking a primitive.

The member access forms given at the top of this section are preferred for use in all cases other than in macros.

(.. instance-expr member+)
(.. Classname-symbol member+)

member ⇒ fieldName-symbol or (instanceMethodName-symbol args*)

Macro. Expands into a member access (.) of the first member on the first argument, followed by the next member on the result, etc. For instance:

(.. System (getProperties) (get "os.name"))

expands to:

(. (. System (getProperties)) (get "os.name"))

but is easier to write, read, and understand. See also the -> macro which can be used similarly:

(-> (System/getProperties) (.get "os.name"))

(doto instance-expr (instanceMethodName-symbol args*)*)

Macro. Evaluates instance-expr then calls all of the methods/functions with the supplied arguments in succession on the resulting object, returning it.

(Classname. args*)
(Classname/new args*)
(new Classname args*)

Special form.

The args, if any, are evaluated from left to right, and passed to the constructor of the class named by Classname. The constructed object is returned.

As shown, in addition to the canonic special form new, Clojure supports special macroexpansion of symbols containing '.':

(new Classname args*)

can be written

(Classname. args*) ;note trailing dot

the latter expanding into (new Classname args) syntax at macro expansion time.

Since Clojure 1.12, a qualified form may also be used (it is not rewritten at macro expansion time):

(Classname/new args*)

Like methods, qualified constructors Classname/new can be used in value contexts and take :param-tags metadata.

(instance? Class expr)

Evaluates expr and tests if it is an instance of the class. Returns true or false

(set! (. instance-expr instanceFieldName-symbol) expr)
(set! (. Classname-symbol staticFieldName-symbol) expr)

Assignment special form.

When the first operand is a field member access form, the assignment is to the corresponding field. If it is an instance field, the instance expr will be evaluated, then the expr.

In all cases the value of expr is returned.

Note - you cannot assign to function params or local bindings. Only Java fields, Vars, Refs and Agents are mutable in Clojure.

(memfn method-name arg-names*)

Macro. Expands into code that creates a fn that expects to be passed an object and any args and calls the named instance method on the object passing the args. Use when you want to treat a Java method as a first-class fn.

Note it is almost always preferable to do this directly now, with syntax like:

(bean obj)

Takes a Java object and returns a read-only implementation of the map abstraction based upon its JavaBean properties.

Many of the Clojure library functions have defined semantics for objects of Java types. contains? and get work on Java Maps, arrays, Strings, the latter two with integer keys. count works on Java Strings, Collections and arrays. nth works on Java Strings, Lists and arrays. seq works on Java reference arrays, Iterables and Strings. Since much of the rest of the library is built upon these functions, there is great support for using Java objects in Clojure algorithms.

Clojure supports the dynamic creation of objects that implement one or more interfaces and/or extend a class with the proxy macro. The resulting objects are of an anonymous class. You can also generate statically-named classes and .class files with gen-class. As of Clojure 1.2, reify is also available for implementing interfaces.

Java annotations may be attached to classes, constructors, and methods via metadata on gen-class and Clojure type constructs, see the datatypes reference for an example.

(proxy [class-and-interfaces] [args] fs+)

class-and-interfaces - a vector of class names
args - a (possibly empty) vector of arguments to the superclass constructor.
f ⇒ (name [params*] body) or (name ([params*] body) ([params+] body) …​)

Macro

Expands to code which creates a instance of a proxy class that implements the named class/interface(s) by calling the supplied fns. A single class, if provided, must be first. If not provided it defaults to Object. The interfaces names must be valid interface types. If a method fn is not provided for a class method, the superclass method will be called. If a method fn is not provided for an interface method, an UnsupportedOperationException will be thrown should it be called. Method fns are closures and can capture the environment in which proxy is called. Each method fn takes an additional implicit first arg, which is bound to this. Note that while method fns can be provided to override protected methods, they have no other access to protected members, nor to super, as these capabilities cannot be proxied.

Clojure supports the creation, reading and modification of Java arrays. It is recommended that you limit use of arrays to interop with Java libraries that require them as arguments or use them as return values.

Note that many other Clojure functions work with arrays such as via the seq library. The functions listed here exist for initial creation of arrays, or to support mutation or higher performance operations on arrays.

Vararg methods

Clojure supports the use of type hints to assist the compiler in avoiding reflection in performance-critical areas of code. Normally, one should avoid the use of type hints until there is a known performance bottleneck. Type hints are metadata tags placed on symbols or expressions that are consumed by the compiler. They can be placed on function parameters, let-bound names, var names (when defined), and expressions:

Once a type hint has been placed on an identifier or expression, the compiler will try to resolve any calls to methods thereupon at compile time. In addition, the compiler will track the use of any return values and infer types for their use and so on, so very few hints are needed to get a fully compile-time resolved series of calls. Note that type hints are not needed for static fields or the return values of static methods as the compiler always has that type information.

There is a *warn-on-reflection* flag (defaults to false) which will cause the compiler to warn you when it can’t resolve to a direct call:

For function return values, the type hint can be placed before the parameter vector:

Clojure provides aliases for primitive Java types and arrays which do not have typical representations as Java class names. The types are represented according to the specification of Java Field Descriptors. For example, byte arrays (byte-array []) have a type of "[B".

• int - A primitive int

• ints - An int array

• long - A primitive long

• longs - A long array

• float - A primitive float

• floats - A float array

• double - A primitive double

• doubles - A double array

• void - A void return

• short - A primitive short

• shorts - A short array

• boolean - A primitive boolean

• booleans - A boolean array

• byte - A primitive byte

• bytes - A byte array

• char - A primitive character

• chars - A character array

• objects - An object array

Since Clojure 1.12, developers can supply :param-tags metadata on qualified methods to specify the signature of a single desired method, 'resolving' it. The :param-tags metadata is a vector of zero or more tags: […​ tag …​]. A tag is any existing valid :tag metadata value as described above. Each tag corresponds to a parameter in the desired signature (arity should match the number of tags). Parameters with non-overloaded types can use the placeholder _ in lieu of the tag. When you supply :param-tags metadata on a qualified method, the metadata must allow the compiler to resolve it to a single method at compile time.

A new metadata reader syntax ^[ …​ ] attaches :param-tags metadata to member symbols, just as ^tag attaches :tag metadata to a symbol.

Clojure has support for high-performance manipulation of, and arithmetic involving, Java primitive types in local contexts. All Java primitive types are supported: int, float, long, double, boolean, char, short, and byte.

• let/loop-bound locals can be of primitive types, having the inferred, possibly primitive type of their init-form.

• recur forms that rebind primitive locals do so without boxing, and do type-checking for same primitive type.

• Arithmetic (+,-,*,/,inc,dec,<,<=,>,>= etc) is overloaded for primitive types where semantics are same.

• aget / aset are overloaded for arrays of primitives

• aclone, alength functions for arrays of primitives

• constructor functions for primitive arrays: float-array, int-array, etc.

• Type hints for primitive arrays - ^ints, ^floats, etc.

• Coercion ops int, float, etc. produce primitives when consumer can take primitive

• The num coercion function boxes primitives to force generic arithmetic

• Array cast functions ints longs, etc. which produce int[], long[], etc.

• A set of "unchecked" operations for utmost performing, but potentially unsafe, integer (int/long) ops: unchecked-multiply unchecked-dec unchecked-inc unchecked-negate unchecked-add unchecked-subtract unchecked-remainder unchecked-divide

• A dynamic var to automatically swap safe operations with unchecked operations: *unchecked-math*

• amap and areduce macros for functionally (i.e. non-destructively) processing one or more arrays in order to produce a new array or aggregate value respectively.

Rather than write this Java:

you can write this Clojure:

and the resulting code is exactly the same speed (when run with java -server).

The best aspect of this is that you need not do anything special in your initial coding. Quite often these optimizations are unneeded. Should a bit of code be a bottleneck, you can speed it up with minor adornment:

Functions have limited support for primitive arguments and return type: type hints for long and double (only these) generate primitive-typed overloads. Note that this capability is restricted to functions of arity no greater than 4.

Thus a function defined as

both takes and returns values of primitive type long (invocations with a boxed argument and indeed any object result in a cast and delegation to the primitive-typed overload).

Primitive coercions

Functional Interface Conversion

• All arguments are passed to Clojure fns as objects, so there’s no point to putting arbitrary primitive type hints on fn args (excepting primitive array type hints, and long and double as noted). Instead, use the let technique shown to place args in primitive locals if they need to participate in primitive arithmetic in the body.

• (let [foo (int bar)] …​) is the correct way to get a primitive local. Do not use ^Integer etc.

• Don’t rush to unchecked math unless you want truncating operations. HotSpot does a good job at optimizing the overflow check, which will yield an exception instead of silent truncation. On a typical example, that has about a 5% difference in speed - well worth it. Also, people reading your code don’t know if you are using unchecked for truncation or performance - best to reserve it for the former and comment if the latter.

• There’s usually no point in trying to optimize an outer loop, in fact it can hurt you as you’ll be representing things as primitives which just have to be re-boxed in order to become args to the inner call. The only exception is reflection warnings - you must get rid of them in any code that gets called frequently.

• Almost every time someone presents something they are trying to optimize with hints, the faster version has far fewer hints than the original. If a hint doesn’t improve things in the end - take it out.

• Many people seem to presume only the unchecked- ops do primitive arithmetic - not so. When the args are primitive locals, regular + and * etc do primitive math with an overflow check - fast and safe.

• So, the simplest route to fast math is to leave the operators alone and just make sure the source literals and locals are primitive. Arithmetic on primitives yields primitives. If you’ve got a loop (which you probably do if you need to optimize) make sure the loop locals are primitives first - then if you accidentally are producing a boxed intermediate result you’ll get an error on recur. Don’t solve that error by coercing your intermediate result, instead, figure out what argument or local is not primitive.

Clojure collections implement the Java collection interfaces, which provide Stream and Spliterator access. Clojure persistent vectors implement a custom Spliterator that supports parallel streams.

Clojure provides functions (since 1.12) to interoperate with streams in an idiomatic manner, all functions behave analogously to their Clojure counterparts:

• (stream-seq! stream) ⇒ seq

• (stream-reduce! f [init-val] stream) ⇒ val

• (stream-transduce! xf f [init-val] stream) ⇒ val

• (stream-into! to-coll [xf] stream) ⇒ to-coll

All of these operations are terminal stream operations (they consume the stream).

Included with the distribution is simple XML support, found in the src/clj/clojure/xml.clj file. All names from this file are in the clojure.xml namespace.

(parse source)

Parses and loads the source, which can be a File, InputStream or String naming a URI. Returns a tree of the clojure.xml/element struct-map, which has the keys :tag, :attrs, and :content. and accessor fns tag, attrs, and content.

The clojure.java.api package provides a minimal interface to bootstrap Clojure access from other JVM languages. It does this by providing:

1. The ability to use Clojure’s namespaces to locate an arbitrary var, returning the var’s clojure.lang.IFn interface.

2. A convenience method read for reading data using Clojure’s edn reader

IFns provide complete access to Clojure’s APIs. You can also access any other library written in Clojure, after adding either its source or compiled form to the classpath.

The public Java API for Clojure consists of the following classes and interfaces:

• clojure.java.api.Clojure

• clojure.lang.IFn

All other Java classes should be treated as implementation details, and applications should avoid relying on them.

To lookup and call a Clojure function:

Functions in clojure.core are automatically loaded. Other namespaces can be loaded via require:

IFns can be passed to higher order functions, e.g. the example below passes inc to map:

Most IFns in Clojure refer to functions. A few, however, refer to non-function data values. To access these, use deref instead of invoking the function: