java:reify
(java:reify "fully.qualified.Interface" "method" function ...)
(java:reify '("Interface" ...) [:value value] [:class "class"] "method" function ...)
Creates a host instance of the given interface whose methods are implemented one by one.
Each "method" names one method of the interface, and the function after it is called
with that method's arguments -- unlike java:proxy, without the method's
name. The function's value is converted to the method's return type (a void method
ignores it). Part of the JVM-only java interop package: the interpreter and JVM-compiled
classes, not the WASM backend. See the Java interop
guide.
Naming the method
A name several methods of the interface share is tagged with the parameter types, as a
java:call method name is: "append(char)", "append(CharSequence,int,int)". A name that
matches more than one method, or none, is an error.
toString, equals and hashCode can be named too. Otherwise equals and hashCode are
identity, and toString answers #<java-reify fully.qualified.Interface>.
Methods no name designates
An abstract method is not implemented: calling it throws UnsupportedOperationException
(java:reify: no implementation of java.util.Iterator.next()). A default method keeps the
interface's body, so combinators work:
Several interfaces
A list of interface names makes one object implementing each of them, so Java can hold it
as any of them. A name designates a method of any of the interfaces; a method two of them
declare with one parameter list is one method. Each name must be an interface, named once
(java:reify names interface I twice), and one that another listed interface extends adds
nothing. The object's toString, unless named, is #<java-reify I J>.
Standing for a value
:value right after the interfaces makes the object stand for a Lisp value, as a
java:handle does: wherever Java hands the object back -- a method's
result, an array's element, a callback's argument -- java: answers the value. :class
names the class Java's messages give the object; without it, its own.
Its equals and hashCode, unless named, are those of a handle with a nil hash: equal only
to an object standing for the very same value under the same class, its hash the value's
identity hash. Its toString, unless named, is Object's spelling of the class and that
hash, such as my.Cell@1b6d3586. An interface that declares value() or className() --
the methods through which the object answers the value and the class -- cannot be
implemented so (java:reify: :value conflicts with I.value()).
The value a function returns
It is converted as an argument is: an integer to int, a list to an array or a List,
nil to false or null, and so on. A function is not made a proxy on the way back --
return a java:reify or java:proxy object where an interface is expected. A value that
does not convert is an error, for example java:reify: cannot return "x" as int from java.util.function.IntSupplier.getAsInt.
Java's false reaches a function as nil. Ending the form in :java-false, after the last
function, hands it |false| instead (the guide's Java's false
back):
Ending it in :octets hands a function a byte[] -- an argument, or an element of one -- as
an (unsigned-byte 8) vector of its octets -- Java's own array, so what the function stores
Java reads (the guide's Octets back).
Ending it in :through and a function has Java call each function through that function,
(f function kind resolved arguments) -- resolved nil --, and answer what it answers (the guide's Calling functions
through another).
In a compiled program
A java:reify whose interface and method names are literal strings (a list of them quoted,
a :class literal too), and whose interfaces the compile can see, is a class generated at
compile time (Prog$Reify0.class beside the program). Nothing reflects, so the program
compiles under --java-static and builds into a GraalVM native image with no
configuration. The object prints as #<java Prog$Reify0> compiled and as the name of a
java.lang.reflect.Proxy class interpreted. A java:reify whose names are computed is
implemented when it runs, through the reflection bridge.