0
# Java Interoperability
1

2
Seamless integration with Java classes, methods, and the broader JVM ecosystem. Clojure provides comprehensive interop capabilities for working with existing Java libraries.
3

4
## Capabilities
5

6
### Java Object Creation
7

8
Methods for creating and instantiating Java objects.
9

10
```clojure { .api }
11
(new ClassName args*)
12
;; Special form: creates new instance of Java class
13
;; Returns: Java object instance
14

15
(ClassName. args*)
16
;; Macro: alternative syntax for new (note the dot)
17
;; Returns: Java object instance
18

19
;; Constructor interop examples:
20
(new java.util.Date)              ; Create new Date
21
(java.util.Date.)                 ; Alternative syntax
22
(new String "hello")              ; Create String from char array
23
(String. "hello")                 ; Alternative syntax
24
```
25

26
### Method Invocation
27

28
Calling methods on Java objects and classes.
29

30
```clojure { .api }
31
(.method object args*)
32
;; Special form: calls instance method on object
33
;; Returns: method return value
34

35
(. object method args*)
36
;; Special form: alternative method call syntax
37
;; Returns: method return value
38

39
(ClassName/staticMethod args*)
40
;; Special form: calls static method on class
41
;; Returns: method return value
42

43
(. ClassName staticMethod args*)
44
;; Special form: alternative static method syntax
45
;; Returns: method return value
46

47
;; Method chaining with .. macro
48
(.. object method1 method2 method3)
49
;; Macro: chains method calls
50
;; Equivalent to (.method3 (.method2 (.method1 object)))
51
;; Returns: final method return value
52
```
53

54
### Field Access
55

56
Accessing Java object fields and class fields.
57

58
```clojure { .api }
59
(.field object)
60
;; Special form: gets instance field value
61
;; Returns: field value
62

63
(.-field object)  
64
;; Special form: alternative field access syntax
65
;; Returns: field value
66

67
(ClassName/staticField)
68
;; Special form: gets static field value
69
;; Returns: field value
70

71
(. ClassName staticField)
72
;; Special form: alternative static field syntax  
73
;; Returns: field value
74

75
(set! (.field object) value)
76
;; Special form: sets instance field (if mutable)
77
;; Returns: value
78

79
(set! (. object field) value)
80
;; Special form: alternative field setting syntax
81
;; Returns: value
82
```
83

84
### Class and Type Operations
85

86
Working with Java classes and type information.
87

88
```clojure { .api }
89
(class object)
90
;; Function: returns Class object for object
91
;; Returns: java.lang.Class
92

93
(type object)
94
;; Function: returns type of object (Class or Clojure type)
95
;; Returns: java.lang.Class or clojure type
96

97
(instance? Class object)
98
;; Function: tests if object is instance of Class
99
;; Returns: boolean
100

101
(isa? child parent)
102
;; Function: tests class/interface hierarchy relationship
103
;; Returns: boolean
104

105
(ancestors Class)
106
;; Function: returns set of all ancestor classes/interfaces
107
;; Returns: set of java.lang.Class
108

109
(descendants Class)
110
;; Function: returns set of all descendant classes
111
;; Returns: set of java.lang.Class
112

113
(supers Class)
114
;; Function: returns set of immediate superclass/interfaces
115
;; Returns: set of java.lang.Class
116
```
117

118
### Class Loading and Importing
119

120
Managing Java class imports and loading.
121

122
```clojure { .api }
123
(import & import-lists)
124
;; Special form: imports Java classes into current namespace
125
;; import-lists: ClassName or (package.name Class1 Class2 ...)
126
;; Returns: nil
127

128
;; Import examples:
129
(import 'java.util.Date)               ; Single class
130
(import '(java.util Date Calendar))    ; Multiple classes from package
131
(import 'java.util.*)                  ; Not supported - must be explicit
132

133
;; In namespace declaration:
134
(ns my.namespace
135
  (:import [java.util Date Calendar]
136
           [java.io File FileReader]))
137
```
138

139
### Array Operations
140

141
Working with Java arrays.
142

143
```clojure { .api }
144
(make-array Class dims*)
145
;; Function: creates multi-dimensional array
146
;; Returns: Java array
147

148
(object-array size-or-seq)
149
;; Function: creates Object array
150
;; Returns: Object[]
151

152
(boolean-array size-or-seq)
153
;; Function: creates boolean array  
154
;; Returns: boolean[]
155

156
(byte-array size-or-seq)
157
;; Function: creates byte array
158
;; Returns: byte[]
159

160
(char-array size-or-seq)
161
;; Function: creates char array
162
;; Returns: char[]
163

164
(short-array size-or-seq)
165
;; Function: creates short array
166
;; Returns: short[]
167

168
(int-array size-or-seq)
169
;; Function: creates int array
170
;; Returns: int[]
171

172
(long-array size-or-seq)
173
;; Function: creates long array
174
;; Returns: long[]
175

176
(float-array size-or-seq)
177
;; Function: creates float array
178
;; Returns: float[]
179

180
(double-array size-or-seq)
181
;; Function: creates double array
182
;; Returns: double[]
183

184
(aclone array)
185
;; Function: shallow clone of array
186
;; Returns: cloned array
187

188
(alength array)
189
;; Function: returns length of array
190
;; Returns: int
191

192
(aget array idx & idxs)
193
;; Function: gets array element at indices
194
;; Returns: array element
195

196
(aset array idx val)
197
(aset array idx idx2 val)
198
;; Function: sets array element at indices
199
;; Returns: val
200

201
(to-array coll)
202
;; Function: converts collection to Object array
203
;; Returns: Object[]
204

205
(to-array-2d coll)
206
;; Function: converts collection of collections to 2D array
207
;; Returns: Object[][]
208

209
(into-array type coll)
210
;; Function: converts collection to typed array
211
;; Returns: typed array
212
```
213

214
### Type Coercion
215

216
Converting between Clojure and Java types.
217

218
```clojure { .api }
219
(boolean x)
220
;; Function: coerces to boolean (false for nil/false, true otherwise)
221
;; Returns: boolean
222

223
(byte x)
224
;; Function: coerces to byte
225
;; Returns: byte
226

227
(char x)
228
;; Function: coerces to char
229
;; Returns: char
230

231
(short x)
232
;; Function: coerces to short
233
;; Returns: short
234

235
(int x)
236
;; Function: coerces to int
237
;; Returns: int
238

239
(long x)
240
;; Function: coerces to long
241
;; Returns: long
242

243
(float x)
244
;; Function: coerces to float
245
;; Returns: float
246

247
(double x)
248
;; Function: coerces to double
249
;; Returns: double
250

251
(bigint x)
252
;; Function: coerces to BigInteger
253
;; Returns: java.math.BigInteger
254

255
(bigdec x)
256
;; Function: coerces to BigDecimal
257
;; Returns: java.math.BigDecimal
258
```
259

260
### Proxy and Interface Implementation
261

262
Creating objects that implement Java interfaces or extend classes.
263

264
```clojure { .api }
265
(proxy [Class* interfaces*] [super-ctor-args*] 
266
  (method-name [args*] body)*)
267
;; Macro: creates object implementing interfaces/extending class
268
;; Returns: proxy object
269

270
(reify interfaces*
271
  (method-name [this args*] body)*)  
272
;; Macro: creates object implementing interfaces (more efficient than proxy)
273
;; Returns: reified object
274

275
;; Proxy example:
276
(proxy [java.io.InputStream] []
277
  (read [] -1))
278

279
;; Reify example:  
280
(reify java.util.Comparator
281
  (compare [this a b] 
282
    (Integer/compare a b)))
283
```
284

285
### Exception Handling with Java
286

287
Working with Java exceptions in Clojure.
288

289
```clojure { .api }
290
;; Standard try-catch works with Java exceptions
291
(try
292
  (java-operation-that-might-throw)
293
  (catch java.io.IOException e
294
    (handle-io-exception e))
295
  (catch Exception e
296
    (handle-general-exception e)))
297

298
;; Access exception methods
299
(.getMessage exception)
300
(.printStackTrace exception)
301
(.getCause exception)
302
```
303

304
**Usage Examples:**
305

306
```clojure
307
;; Object creation
308
(def date (new java.util.Date))
309
(def list (java.util.ArrayList.))
310

311
;; Method calls
312
(.toString date)                      ; => "Thu Sep 05 19:32:00 UTC 2025"
313
(.add list "hello")                   ; => true
314
(.size list)                          ; => 1
315

316
;; Static methods  
317
(System/currentTimeMillis)            ; => 1725564720000
318
(Math/sqrt 16)                        ; => 4.0
319

320
;; Field access
321
System/out                            ; => PrintStream
322
(.length "hello")                     ; => 5
323

324
;; Method chaining
325
(.. "hello world" 
326
    (toUpperCase)
327
    (substring 0 5))                  ; => "HELLO"
328

329
;; Arrays
330
(def arr (int-array [1 2 3 4]))
331
(alength arr)                         ; => 4
332
(aget arr 0)                          ; => 1
333
(aset arr 0 10)                       ; => 10
334

335
;; Type checking
336
(class "hello")                       ; => java.lang.String
337
(instance? String "hello")            ; => true
338
(instance? Number 42)                 ; => true
339

340
;; Interface implementation
341
(def my-comparator
342
  (reify java.util.Comparator
343
    (compare [this a b]
344
      (Integer/compare a b))))
345

346
(def sorted-list 
347
  (java.util.TreeSet. my-comparator))
348

349
;; Collections interop
350
(def java-list (java.util.ArrayList. [1 2 3]))
351
(seq java-list)                       ; => (1 2 3)
352
(vec java-list)                       ; => [1 2 3]
353

354
;; Exception handling
355
(try
356
  (Integer/parseInt "not-a-number")
357
  (catch NumberFormatException e
358
    (str "Invalid number: " (.getMessage e))))
359
```