Changes between Version 3 and Version 4 of JavaFfi


Ignore:
Timestamp:
11/03/10 19:28:11 (13 years ago)
Author:
astalla
Comment:

Better Java FFI documentation

Legend:

Unmodified
Added
Removed
Modified

  • JavaFfi

    v3 v4  
     1[[PageOutline]]
     2
    13= Java Foreign Function Interface =
    24
    3 ''(This is a very rough draft thrown together from an email by Alessio Stalla to the mailing list.)''
     5This 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.
    46
    5 A quick "cheat sheet":
     7== The basics ==
     8
     9The 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
     29Reflectively 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
     56Returns 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
     64TODO
     65
     66== High-level constructs ==
     67
     68TODO
     69
     70== CLOS integration ==
     71
     72TODO
     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.)''
    677
    778 `(jclass <class name>)`::
    … …  
    31102''(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.)''
    32103
    33 === `register-java-exception` ''exception-name condition-symbol'' => `T` or `NIL` ===
     104'''`register-java-exception` ''exception-name condition-symbol'' => `T` or `NIL`'''
    34105
    35106Registers the Java Throwable ''exception-name'' as the condition designated by ''condition-symbol''.
    36107
    37 === `unregister-java-exception` ''exception-name'' => `T` or `NIL` ===
     108'''`unregister-java-exception` ''exception-name'' => `T` or `NIL`'''
    38109
    39110Unregisters the Java Throwable ''exception-name'' previously registered by `register-java-exception`.
    40111
    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'' '''
    47114
    48115Retrieve or modify a field in a Java class or instance.
    … …  
    65132   Store ''value'' in a field of ''instance''. The class is derived from ''instance''.
    66133
    67 === `jconstructor` ''class-ref'' &rest ''parameter-class-refs'' => ''constructor-ref'' ===
     134''' `jconstructor` ''class-ref'' &rest ''parameter-class-refs'' => ''constructor-ref'' '''
    68135
    69136Returns a reference to the Java constructor of ''class-ref'' with the given ''parameter-class-refs''.
    70137
    71 === `jmethod` ''class-ref method-name'' &rest ''parameter-class-refs'' => ''method-ref'' ===
     138''' `jmethod` ''class-ref method-name'' &rest ''parameter-class-refs'' => ''method-ref'' '''
    72139
    73140Returns a reference to the Java method ''method-name'' of ''class-ref'' with the given ''parameter-class-refs''.
    74141
    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'' '''
    77144
    78 === `jnew` ''constructor'' &rest ''args'' => ''object'' ===
     145''' `jnew` ''constructor'' &rest ''args'' => ''object'' '''
    79146
    80147Invokes the Java constructor ''constructor'' with the arguments ''args''
    81148
    82 === `jnew-array` ''element-type'' &rest ''dimensions'' => ''array-object'' ===
     149''' `jnew-array` ''element-type'' &rest ''dimensions'' => ''array-object'' '''
    83150
    84151Creates a new Java array of type ''element-type'', with the given ''dimensions''.
    85152
    86 === `jarray-ref` ''java-array'' &rest ''indices'' => ''object'' ===
     153''' `jarray-ref` ''java-array'' &rest ''indices'' => ''object'' '''
    87154
    88155Dereference the Java array ''java-array'' using the given ''indices'', coercing the result into a Lisp type, if possible.
    89156
    90 === `jarray-ref-raw` ''java-array'' &rest ''indices'' => ''object'' ===
     157''' `jarray-ref-raw` ''java-array'' &rest ''indices'' => ''object'' '''
    91158
    92159Dereference the Java array ''java-array'' using the given ''indices''.  Does not attempt to coerce the result into a Lisp type.
    93160
    94 === `jarray-set` ''java-array new-value'' &rest ''indices'' => ''new-value'' ===
     161''' `jarray-set` ''java-array new-value'' &rest ''indices'' => ''new-value'' '''
    95162
    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'' '''
    98165
    99166`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.)
    100167
    101 === `make-immediate-object` ''object'' &optional ''type'' => ''object'' ===
     168''' `make-immediate-object` ''object'' &optional ''type'' => ''object'' '''
    102169
    103 === `java-object-p` ''object'' => `T` or `NIL` ===
     170''' `java-object-p` ''object'' => `T` or `NIL` '''
    104171
    105172Returns `T` if ''object'' is an instance of JavaObject (as opposed to a Lisp object).
    106173
    107 === `jobject-lisp-value` ''java-object'' => ''lisp-object'' ===
     174''' `jobject-lisp-value` ''java-object'' => ''lisp-object'' '''
    108175
    109176Returns the Lisp object corresponding to (wrapping?) the JavaObject. I.e. `return JavaObject.getInstance(arg.javaInstance(), true);`
    110177
    111 === `jcoerce` ''object'' ''intended-class'' => ''java-object'' ===
     178''' `jcoerce` ''object'' ''intended-class'' => ''java-object'' '''
    112179
    113180Attempts to coerce ''object'' into a JavaObject of class ''intended-class''.  Raises a `type-error` if no conversion is possible.
    114181
    115 === `%jget-property-value` ''java-object property-name'' ===
     182''' `%jget-property-value` ''java-object property-name'' '''
    116183
    117184Use `jproperty-value` instead.
    118185
    119 === `%jset-property-value` ''java-object property-name value'' ===
     186''' `%jset-property-value` ''java-object property-name value'' '''
    120187
    121188Use `(setf jproperty-value)` instead.
    122189
    123 === `jrun-exception-protected` ''closure'' ===
     190''' `jrun-exception-protected` ''closure'' '''