make-lisp-proxy

make-lisp-proxy-with-overrides Functions

Summary

Make a Lisp proxy.

Package

lw-ji

Signatures

make-lisp-proxy name &key user-data print-name overrides overrides-plist class-loader => proxy

make-lisp-proxy-with-overrides name &rest args &key user-data print-name class-loader &allow-other-keys => proxy

Arguments

Values

Description

The functions make-lisp-proxy and make-lisp-proxy-with-overrides make a Lisp proxy, which is a Java proxy where method invocation ends up calling Lisp code. The result is a jobject proxy which represents the proxy, which can then be used in Java where an object that implements any of the interfaces that the proxy implements is required.

Note: The jobject is "local", which means that if it is generated in the scope of a call from Java it must be used (passed to Java method, return to the call from Java or pass it to jobject-ensure-global) in the scope of the call from Java. You cannot store it in Lisp and use it later (but you can do that with the result of jobject-ensure-global). If the jobject is generated not in the scope of a Java call, it must be used on the same thread that it was made.

name must be associated with a proxy definition, either by define-lisp-proxy or setup-lisp-proxy. The proxy definition determines which interfaces the proxy implements, and what happens when a method is invoked on the proxy. The processing of invocation of a method on the proxy is described in the documentation for define-lisp-proxy.

user-data is an arbitrary object. It is passed to the Lisp function if the proxy definition specifies that it should be passed (keyword :with-user-data or :default-function-with-user-data for the default function).

print-name specifies the name of the proxy, after it is converted to a string by cl:princ-to-string. If the proxy definition has a print-name too, the full print name of the proxy is formed by concatenating the definition's print-name and the proxy's print-name separated by " - ", otherwise the full print name is the proxy's print-name. The full print name is used when printing the proxy, and is also returned when the Java method toString is applied to it. If print-name is nil, a counter is used.

overrides, if supplied, must be an association list specifying overriding (see "Overrides" below), that is a list of conses where the cl:car is the symbol to override and the cl:cdr is the target. When overrides is non-nil overrides-plist is ignored.

If overrides-plist is supplied it must be a plist specifying overriding, that is a list of even length where each even element is a symbol to override and the following odd element is the target.

class-loader specifies the ClassLoader to pass as the first argument to the Java method Proxy.newProxyInstance when making the Lisp proxy. If class-loader is non-nil, it must be a jobject representing the Java ClassLoader to use. If class-loader is nil, then the internal ClassLoader is used (see the description of the class-loader-finder keyword in init-java-interface for how this is set up).

The argument args of make-lisp-proxy-with-overrides is used as a plist specifying overrides, after removing any occurrences of :print-name and :user-data from it.

Overrides

Overrides allow make-lisp-proxy and make-lisp-proxy-with-overrides to override symbols in the proxy definition, which means that instead of calling the symbol in the proxy definition the target in the overrides is called. See the documentation for define-lisp-proxy for details of the processing.

make-lisp-proxy-with-overrides is intended to make it simpler to use overrides. It is equivalent to calling make-lisp-proxy with overrides-plist, and actually calls make-lisp-proxy (so may get errors that look like they came from make-lisp-proxy).

make-lisp-proxy and make-lisp-proxy-with-overrides signal error if name is not associated with a proxy definition, and if any overrides are not of the right form or any of the functions to call is not a function designator. They may also signal an error if the proxy definition was not initialized and they failed to initialize it.

See also

define-lisp-proxy
setup-lisp-proxy
15.3.2 Using proxies