Changes between Version 5 and Version 6 of JavaFfi/RuntimeClass

07/06/12 21:00:41 (10 years ago)



  • JavaFfi/RuntimeClass

    v5 v6  
    1717The API has been inspired by the original, but has been changed in some places.
    19 == Terminology ==
     19== Terminology and definitions ==
    2121Before digging into the API, a few terms must be defined for clarity:
    2323 * '''access flag''': a keyword understood by the Java class file writer as a modifier for a class, field, or method. Examples: :public, :private, :static.
     24 * '''Java type designator''': either a string naming a Java class, or a keyword corresponding to a primitive type such as :int, :double, :boolean etc., or (only when indicated) the keyword :void.
    2526== Main API entry points ==
    4950Arguably, the most important feature of runtime-class is to define Java methods in Lisp. Each method is implemented as a call to a pre-existing Lisp function, with the necessary conversions for arguments and return values. Contrarily to the old implementation of runtime-class, no API is specified to replace method implementations at runtime; instead, you can leverage the usual mechanism of passing a symbol as a function designator and later replacing its symbol-function.
     52A method definition is a list in the following form:
     54```(method-name return-type argument-types function &key modifiers annotations override)```
     56 * '''```method-name```''' is self-explicative.
     57 * '''```return-type```''' - the Java type designator (including :void) for the return type of the method. '''Note:''' currently many primitive types are not supported.
     58 * '''```argument-types```''' - a list of Java type designators for the argument types of the method. '''Note:''' currently many primitive types are not supported.
     59 * '''```function```''' - a Lisp function designator. The function must have ```(1+ (length argument-types))``` parameters: the first is the receiving object (what would be the ```this``` reference in Java), the others are the method arguments, opportunely converted to Lisp values. In the body of the function, you can call other methods on the same object with the usual ```jcall``` operator. '''Note:''' the calling convention for functions with > 8 arguments is currently not supported.
     60 * '''```modifiers```''' - a list of modifier keywords for the method. The default is '''(:public)'''.
     61 * '''```annotations```''' - a (possibly empty) list of annotation definitions (see the appropriate section below) to be placed on the method.
     62 * '''```override```''' - defines the override policy (see below). By default it's ```nil```.
     64==== Overriding superclass methods ====
     66There's no special action to be performed to make a method override another; if your class contains a method with a signature compatible to some other method defined in one of its superclasses, your method will override the other. However, you may want to call the overridden method (e.g. to provide a fallback case). How that happens is controlled by the '''```override```''' keyword argument.
     68 * if ```override``` is ```nil``` (the default), you cannot call the superclass method.
     69 * if ```override``` is non-```nil```, a private method called ```super$```''```<the name of your method>```'' will be defined, with the following behaviour:
     70  * if ```override``` is ```T```, then the ```super$...``` method will call a method with the exact same signature as yours and defined in the direct superclass. '''Note:''' a smarter implementation could be provided that, when possible, would search in all the superclasses for the best match, according to the rules in the JLS, but it is not implemented at the moment.
     71  * ('''not yet implemented''') else, it is assumed to be a list in the form ```(class-name argument-types)```. A call to a method with the same name, with the provided signature and defined in the specified superclass, will be generated.
     73'''Note:''' what happens with the super$name convention if you're overriding two overloads of the same method? A naming strategy must be defined, or the user must be given the possibility to specify another name instead of super$name.