user-data

The user-data is set up for each individual proxy object by make-lisp-proxy or make-lisp-proxy-with-overrides, and thus allows you to associate each individual proxy with an arbitrary Lisp object. The proxy definition determines whether to use it when calling the Lisp functions in the proxy definition. The default value of user-data is nil, so if you want to use it you need to specify it by using :with-user-data, either in the :options which would give the default value for all calls in the definition, or in individual method specifications. When user-data is passed, it is always passed to the Lisp function as the first argument. Another way to individualize proxies is to use overriding, which also allows you to use closures.

Overriding

When make-lisp-proxy or make-lisp-proxy-with-overrides make a proxy, they can specify overriding of some of the symbols in the proxy definition. Overriding here means mapping one symbol to to another symbol or a function object. When a symbol is supposed to be called and it is overridden, the target of the mapping is called rather than the symbol. Note that the overriding is specific to each individual proxy rather to the proxy definition, and therefore you can have different proxies using the same proxy definition (and hence implementing the same interface(s)), but calling different Lisp functions. An advantage of overriding is that it allows you to use closures created at runtime instead of symbols.

See the entry for make-lisp-proxy for how the overriding is created.

Calling the Lisp function

After a proxy is created from a proxy definition, any invocation of a Java method on it (except the Object methods toString, equals and hashCode) enters Lisp.

When a method is invoked on a proxy (normally from Java, but can be done from Lisp too), the steps for invoking your Lisp function are:

1. Check whether the item in the interface-and-method-descs for the interface of the method contains a method specification with the method-name of the method.
2. Convert the Java method arguments to Lisp arguments where possible. See Types and conversion between Lisp and Java.

Note that that if the first step above found a method specification, and it contains the keyword :jobject-scope, it affects the way non-primitive arguments are processed as described above.

3. Calling the user code:

(i) If a method specification was found in the first step above:

a) Take the symbol from the method specification, then

b) Check whether the symbol is overridden, and if it is use the target as a function to call. Otherwise, check whether the symbol is fbound, and if it is use it as a function to call, then

c) If as a result of (b) there is a function to call, check whether it should be called with the user-data. If :with-user-data was used in the method specification then use its value, otherwise if :with-user-data was used in :options item use this value, otherwise default to nil, then

d) Apply the function: if using user-data, apply the function to the user-data followed by the Lisp arguments, otherwise apply the function to the Lisp arguments only.

(ii) If the method-specific call in (i) did not happen (no method specification found, or the symbol is not fbound and not overridden), try to apply the default function:

a) If there is a default function, check whether it is overridden and if so use the target as the function to call. Otherwise use the default-function itself as the function to call, then

b) Check whether need to pass user-data, which is specified by the :default-function-with-user-data in the :options item, then

c) Apply the function: if user-data needs to be used, apply the function to the user-data, method-name and the Lisp arguments. Otherwise apply the function to the method-name and Lisp arguments.

(iii) If the calls in (i) and (ii) did not happen, an error is signaled. See handling of errors below.

4. Return a value: currently, if the user function returned a Java object (a jobject or an instance of standard-java-object), it is returned without checking. Otherwise, try to convert it to the appropriate Java object and return it. Otherwise, report it by calling the java-to-lisp-debugger-hook (see init-java-interface) with a cl:simple-error condition and return a default value from the Java method invocation, which is 0 for primitive types or null for other types.

Throwing out and error handling

The call to the Lisp function is wrapped dynamically such that any throw from it is blocked, and the default value as in the last step above is returned.

In addition, there is a debugger wrapper (using with-debugger-wrapper) which calls the java-to-lisp-debugger-hook (see init-java-interface) with the condition and then calls cl:abort. If this abort is not caught by your cl:abort restart, it is handled by the "throwing blocker" from the previous paragraph, that is the Java method returns 0 or null.

Verification

The verification functions verify-lisp-proxies and verify-lisp-proxy are provided to allow you to do some checking of the correctness of your proxy definition. Two things can be verified:

• That the symbols to be called in the proxy definition are fbound. In principle this check could happen at load-time, but that would enforce defining the functions before the proxy. The verification allows you to define the proxies and functions in any order, and then verify all the definitions, for example just before delivery.
• Check that all methods that are declared in the Java interfaces have a method-desc, and report those that do not. This requires running Java.

Note that neither of these issues is actually an error, because the default function can handle them. However it is useful to check them in case you did miss something.

Performance issues

There is a little overhead associated with using setup-lisp-proxy as opposed to define-lisp-proxy, both in the size of the delivered application (very small) and in runtime, but the difference is not large enough to prevent using setup-lisp-proxy when it is appropriate.

There is an overhead associated with initializing a proxy definition. It is therefore a bad idea to use setup-lisp-proxy many times.

Overrides and using multiple interfaces add a negligible overhead.

:jobject-scope with nil or :local are useful optimizations. In proxies that are invoked infrequently, say less than 10 times each second, the difference is probably insignificant, but it is useful for proxies that are called repeatedly by Java code. For example, if you implement the interface "java.io.FilenameFilter" to pass to "java.io.File.list" on large directories, using :jobject-scope :local or nil will reduce the overhead significantly.