Changes between Version 3 and Version 4 of JavaFfi
- Timestamp:
- 11/03/10 19:28:11 (13 years ago)
Legend:
- Unmodified
- Added
- Removed
- Modified
-
JavaFfi
v3 v4 1 [[PageOutline]] 2 1 3 = Java Foreign Function Interface = 2 4 3 ''(This is a very rough draft thrown together from an email by Alessio Stalla to the mailing list.)'' 5 This page describes the API offered by ABCL to call arbitrary Java code. Unless otherwise noted, all the symbols are exported from the JAVA package, which is used by CL-USER. 4 6 5 A quick "cheat sheet": 7 == The basics == 8 9 The core API is based on Java reflection. Some operators come in two flavors: a concise one that leaves some things to be computed by ABCL at runtime, and a more efficient and verbose one, which is mostly a direct translation of the Java reflection API. 10 11 === Function JCALL, JCALL-RAW === 12 13 '''Syntax:''' 14 15 '''jcall''' ''method instance &rest args => T'' 16 17 '''jcall-raw''' ''method instance &rest args => T'' 18 19 '''Arguments and Values:''' 20 21 `method` -- a Java method designator, that is, either a Java method metaobject (an instance of java.lang.reflect.Method), or a string representing the name of the method, for example "toString". 22 23 `instance` -- the receiver object target of the method call. If the method is static, this argument is ignored and can be NIL. 24 25 `args` -- the arguments passed to the method. 26 27 '''Description:''' 28 29 Reflectively calls a method and returns the result of the call. If `method` is a string, ABCL dynamically examines the class of `instance` to search for the most specific applicable method with that name, following Java overload resolution rules. If `method` is a Java method metaobject, it is called directly. 30 31 `jcall` translates the result to a Lisp object if possible. `jcall-raw` performs no translation and always returns the original Java object. 32 33 '''Examples:''' 34 35 {{{ 36 (jcall "toString" T) => "COMMON-LISP:T" 37 (jcall-raw "toString" T) => #<java.lang.String COMMON-LISP:T {21B42F}> 38 (jcall "compareTo" 12 24) => -1 ;;Resolves the method at runtime: inefficient but concise 39 (jcall (jmethod "java.lang.Comparable" "compareTo" "java.lang.Object") 12 24) => -1 ;;Same as above, but avoiding dynamic method resolution 40 }}} 41 42 === Function JCLASS === 43 44 '''Syntax:''' 45 46 '''jclass''' ''name-or-class-ref &optional class-loader => Java class metaobject'' 47 48 '''Arguments and Values:''' 49 50 `name-or-class-ref` -- a Java class designator, that is, a Java class metaobject (an instance of java.lang.Class), or a string representing the fully qualified name of the Java class, for example "java.lang.Object". 51 52 `class-loader` -- the classloader to use to resolve the class. Refer to the section Class resolution and loading. 53 54 '''Description:''' 55 56 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. 57 58 '''Examples:''' 59 60 `(jclass "java.util.LinkedList") => #<java.lang.Class class java.util.LinkedList {11B50A1}>` 61 62 == Class resolution and loading == 63 64 TODO 65 66 == High-level constructs == 67 68 TODO 69 70 == CLOS integration == 71 72 TODO 73 74 == A quick "cheat sheet": == 75 76 ''(This is a very rough draft thrown together from an email by Alessio Stalla to the mailing list. It will be gradually superseded by the documentation above.)'' 6 77 7 78 `(jclass <class name>)`:: … … 31 102 ''(The rest of the page is taken from the symbols and comments in [http://trac.common-lisp.net/armedbear/browser/trunk/abcl/src/org/armedbear/lisp/Java.java Java.java]. Still needs a lot of work, obviously.)'' 32 103 33 === `register-java-exception` ''exception-name condition-symbol'' => `T` or `NIL` === 104 '''`register-java-exception` ''exception-name condition-symbol'' => `T` or `NIL`''' 34 105 35 106 Registers the Java Throwable ''exception-name'' as the condition designated by ''condition-symbol''. 36 107 37 === `unregister-java-exception` ''exception-name'' => `T` or `NIL` === 108 '''`unregister-java-exception` ''exception-name'' => `T` or `NIL`''' 38 109 39 110 Unregisters the Java Throwable ''exception-name'' previously registered by `register-java-exception`. 40 111 41 === `jclass` ''name-or-class-ref'' &optional ''class-loader'' => ''class-ref'' === 42 43 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. 44 45 === `jfield` ''class-ref-or-field field-or-instance'' &optional ''instance value'' === 46 === `jfield-raw` ''class-ref-or-field field-or-instance'' &optional ''instance value'' === 112 '''jfield` ''class-ref-or-field field-or-instance'' &optional ''instance value'' ''' 113 '''`jfield-raw` ''class-ref-or-field field-or-instance'' &optional ''instance value'' ''' 47 114 48 115 Retrieve or modify a field in a Java class or instance. … … 65 132 Store ''value'' in a field of ''instance''. The class is derived from ''instance''. 66 133 67 === `jconstructor` ''class-ref'' &rest ''parameter-class-refs'' => ''constructor-ref'' === 134 ''' `jconstructor` ''class-ref'' &rest ''parameter-class-refs'' => ''constructor-ref'' ''' 68 135 69 136 Returns a reference to the Java constructor of ''class-ref'' with the given ''parameter-class-refs''. 70 137 71 === `jmethod` ''class-ref method-name'' &rest ''parameter-class-refs'' => ''method-ref'' === 138 ''' `jmethod` ''class-ref method-name'' &rest ''parameter-class-refs'' => ''method-ref'' ''' 72 139 73 140 Returns a reference to the Java method ''method-name'' of ''class-ref'' with the given ''parameter-class-refs''. 74 141 75 === `jstatic` ''method-ref class-ref'' &rest ''args'' => ''result'' === 76 === `jstatic-raw` ''method-ref class-ref'' &rest ''args'' ''result'' === 142 ''' `jstatic` ''method-ref class-ref'' &rest ''args'' => ''result'' ''' 143 ''' `jstatic-raw` ''method-ref class-ref'' &rest ''args'' ''result'' ''' 77 144 78 === `jnew` ''constructor'' &rest ''args'' => ''object'' === 145 ''' `jnew` ''constructor'' &rest ''args'' => ''object'' ''' 79 146 80 147 Invokes the Java constructor ''constructor'' with the arguments ''args'' 81 148 82 === `jnew-array` ''element-type'' &rest ''dimensions'' => ''array-object'' === 149 ''' `jnew-array` ''element-type'' &rest ''dimensions'' => ''array-object'' ''' 83 150 84 151 Creates a new Java array of type ''element-type'', with the given ''dimensions''. 85 152 86 === `jarray-ref` ''java-array'' &rest ''indices'' => ''object'' === 153 ''' `jarray-ref` ''java-array'' &rest ''indices'' => ''object'' ''' 87 154 88 155 Dereference the Java array ''java-array'' using the given ''indices'', coercing the result into a Lisp type, if possible. 89 156 90 === `jarray-ref-raw` ''java-array'' &rest ''indices'' => ''object'' === 157 ''' `jarray-ref-raw` ''java-array'' &rest ''indices'' => ''object'' ''' 91 158 92 159 Dereference the Java array ''java-array'' using the given ''indices''. Does not attempt to coerce the result into a Lisp type. 93 160 94 === `jarray-set` ''java-array new-value'' &rest ''indices'' => ''new-value'' === 161 ''' `jarray-set` ''java-array new-value'' &rest ''indices'' => ''new-value'' ''' 95 162 96 === `jcall` ''method-ref instance'' &rest ''args'' => ''result'' === 97 === `jcall-raw` ''method-ref instance'' &rest ''args'' => ''result'' === 163 ''' `jcall` ''method-ref instance'' &rest ''args'' => ''result'' ''' 164 ''' `jcall-raw` ''method-ref instance'' &rest ''args'' => ''result'' ''' 98 165 99 166 `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.) 100 167 101 === `make-immediate-object` ''object'' &optional ''type'' => ''object'' === 168 ''' `make-immediate-object` ''object'' &optional ''type'' => ''object'' ''' 102 169 103 === `java-object-p` ''object'' => `T` or `NIL` === 170 ''' `java-object-p` ''object'' => `T` or `NIL` ''' 104 171 105 172 Returns `T` if ''object'' is an instance of JavaObject (as opposed to a Lisp object). 106 173 107 === `jobject-lisp-value` ''java-object'' => ''lisp-object'' === 174 ''' `jobject-lisp-value` ''java-object'' => ''lisp-object'' ''' 108 175 109 176 Returns the Lisp object corresponding to (wrapping?) the JavaObject. I.e. `return JavaObject.getInstance(arg.javaInstance(), true);` 110 177 111 === `jcoerce` ''object'' ''intended-class'' => ''java-object'' === 178 ''' `jcoerce` ''object'' ''intended-class'' => ''java-object'' ''' 112 179 113 180 Attempts to coerce ''object'' into a JavaObject of class ''intended-class''. Raises a `type-error` if no conversion is possible. 114 181 115 === `%jget-property-value` ''java-object property-name'' === 182 ''' `%jget-property-value` ''java-object property-name'' ''' 116 183 117 184 Use `jproperty-value` instead. 118 185 119 === `%jset-property-value` ''java-object property-name value'' === 186 ''' `%jset-property-value` ''java-object property-name value'' ''' 120 187 121 188 Use `(setf jproperty-value)` instead. 122 189 123 === `jrun-exception-protected` ''closure'' === 190 ''' `jrun-exception-protected` ''closure'' '''