jcall

Arguments: method-ref instance &rest args

This is the general form for calling Java methods. If the arguments specify a unique Java method, then the specified method is called with the given arguments. If more than one matching method is found, a continuable error is signaled to allow an appropriate method to be selected.

If the first (method-ref) argument is a class method, the second (instance) argument must be a reference to an instance of an appropriate class. The (unique) specified method is called with the given arguments.

If the method-ref argument is the name of a method, the instance argument must be a reference to an instance of an appropriate class. The methods of the class are examined to find one or more methods with the given number of arguments. If the arguments specify a unique Java method, then the specified method is called with the given arguments. If more than one matching method is found, a continuable error is signaled to allow an appropriate method to be selected.

If the method-ref argument is a reference to a static method, the instance argument is ignored. The (unique) specified method is called with the given arguments.

The args rest argument is a list of argumnents to the Java method. The arguments are converted using the rules in the section Data Types and Conversions in jlinker.htm. The last element in the list may be a result modifier; one of the following keywords that add advice about the value returned.

• :copy: return a scalar value, or Lisp vector if at all possible.
• :ref: return a remote reference if that makes sense.
• :ignore: do not return anything at all.
• :one-way: do not return anything at all and do not even wait for the answer. (Note: :oneway is also accepted for backward compatibility, but :one-way is preferred.)

If the Java code called from Lisp throws an exception, the exception is reflected in Lisp as a Lisp simple-error condition. The value of the slot excl::format-arguments is a list of the form

(string1 (string2 remote-ref-to-java-error))

It does not make sense to throw on purpose (rather than because of an exception) in code called from Lisp since the Java code is executed in a thread dedicated to the handling of calls from Lisp. When the Java code is running, there is no context of interest outside of the called method. That is why all throws are caught by jLinker and returned back to Lisp.

The compiler macro associated with the function allows compile-time collection of java class names and method signatures. This information is used to generate a file of class and method definitions that may be loaded to initialize an application, and avoid the class and method lookup overhead in the body of the application (see jlookup).

See jlinker.htm for more information on the jLinker facility.

Copyright (c) 1998-2016, Franz Inc. Oakland, CA., USA. All rights reserved.
This page was not revised from the 8.1 page.
Created 2010.1.21.