| Version 3 (modified by , 13 years ago) (diff) |
|---|
Java Foreign Function Interface
(This is a very rough draft thrown together from an email by Alessio Stalla to the mailing list.)
A quick "cheat sheet":
(jclass <class name>)- gives you a Java class
(jmethod <java class> <method names> <&rest argument types>)- gives you a method
(jconstructor <java class> <&rest argument types>)- a constructor
(jnew <constructor> <&rest arguments>)- instantiates a new Java object
(jcall <method> <object> <&rest arguments>)- calls a method
jstatic- to access static fields and methods.
jfield- to access fields.
jproperty-valueand(setf jproperty-value)- access "properties" following the Java Bean convention (setXXX and getXXX).
That's almost all; there is some more advanced stuff (e.g. manipulating Java arrays).
You can find most or all of this stuff inside Java.java. It's not documented but quite readable.
For example code that uses the Java FFI API, see the examples.
(The rest of the page is taken from the symbols and comments in Java.java. Still needs a lot of work, obviously.)
register-java-exception exception-name condition-symbol => T or NIL
Registers the Java Throwable exception-name as the condition designated by condition-symbol.
unregister-java-exception exception-name => T or NIL
Unregisters the Java Throwable exception-name previously registered by register-java-exception.
jclass name-or-class-ref &optional class-loader => class-ref
Returns a reference to the Java class designated by name-or-class-ref. If the class-loader parameter is passed, the class is resolved with respect to the given ClassLoader?.
jfield class-ref-or-field field-or-instance &optional instance value
jfield-raw class-ref-or-field field-or-instance &optional instance value
Retrieve or modify a field in a Java class or instance.
Supported argument patterns:
- class-ref field-name
- Retrieve the value of a static field.
- class-ref field-name instance-ref
- Retrieve the value of a class field of the instance.
- class-ref field-name primitive-value
- Store primitive-value in a static field.
- class-ref field-name instance-ref value
- Store value in a class field of the instance.
- class-ref field-name nil value
- Store value in a static field (when value may be confused with an instance-ref).
- field-name instance
- Retrieve the value of a field of instance. The class is derived from instance.
- field-name instance value
- Store value in a field of instance. The class is derived from instance.
jconstructor class-ref &rest parameter-class-refs => constructor-ref
Returns a reference to the Java constructor of class-ref with the given parameter-class-refs.
jmethod class-ref method-name &rest parameter-class-refs => method-ref
Returns a reference to the Java method method-name of class-ref with the given parameter-class-refs.
jstatic method-ref class-ref &rest args => result
jstatic-raw method-ref class-ref &rest args result
jnew constructor &rest args => object
Invokes the Java constructor constructor with the arguments args
jnew-array element-type &rest dimensions => array-object
Creates a new Java array of type element-type, with the given dimensions.
jarray-ref java-array &rest indices => object
Dereference the Java array java-array using the given indices, coercing the result into a Lisp type, if possible.
jarray-ref-raw java-array &rest indices => object
Dereference the Java array java-array using the given indices. Does not attempt to coerce the result into a Lisp type.
jarray-set java-array new-value &rest indices => new-value
jcall method-ref instance &rest args => result
jcall-raw method-ref instance &rest args => result
jcall calls makeLispObject() to convert the result to an appropriate Lisp type. jcall-raw does no type conversion. The result of the call is simply wrapped in a JavaObject?. (This is true for all the -raw variants.)
make-immediate-object object &optional type => object
java-object-p object => T or NIL
Returns T if object is an instance of JavaObject? (as opposed to a Lisp object).
jobject-lisp-value java-object => lisp-object
Returns the Lisp object corresponding to (wrapping?) the JavaObject?. I.e. return JavaObject.getInstance(arg.javaInstance(), true);
jcoerce object intended-class => java-object
Attempts to coerce object into a JavaObject? of class intended-class. Raises a type-error if no conversion is possible.
%jget-property-value java-object property-name
Use jproperty-value instead.
%jset-property-value java-object property-name value
Use (setf jproperty-value) instead.
