make-immediate-object

Arguments: x &optional type (symcase :read) (pkcase symcase)

Update: a patch released in March, 2011, modified this function to ignore the symcase and pkcase optional arguments. An error will be signaled if this function is called with values for those arguments other than the defaults shown (that is, both :read).

The purpose of this function is to create a transfer object that will transmit the value of the Lisp arguement to Java. If the Lisp object cannot be transmitted by value, the function returns nil. The function make-dist-object always creates a transfer object - when the Lisp object cannot be transmitted by value, make-dist-object creates a remote reference.

If the second (type)argument to make-immediate-object is omitted or nil, the conversion is done following the default conversion rules described in the Data Types and Conversions section of jlinker.htm. If the type argument is not nil, then it must be a keyword that constrains how the Lisp value should be transmitted to Java. The table below shows how the Lisp type of the first argument, x, and the second argument, type, combine to control the resulting Java type:

Notes

1. In this case, make-immediate-object returns nil because the Lisp object may not be passed by value in this way and a remote reference must be created.
2. When a type is specified and the argument x is a cons, we attempt to make a Java array of the specified type. If an unsuitable value is found in the list, an error is signaled. Integer values must be in the Java int range and get truncated to byte or short if appropriate.

   The Lisp list (1 2 3) is passed to Java as a remote reference in the default conversion case.

   The form (make-immediate-object '(1 2 3) :int) will pass to Java an array of int values.

3. When the argument x is a symbol, the type argument may be one of the Lisp symbols symbol-value, symbol-function, or class to transmit a remote reference to the corresponding Lisp value.

It may seem less than useful to transmit Lisp symbols to a Java program since symbols are not a useful Java data type. Symbol references are useful to the Java program as values that may be passed back to the Lisp application. Once the symbol reference has been passed to Java it may be returned to Lisp many times with little overhead and yields the same eq symbol in Lisp every time. It is also possible for the Java program to create symbol references with the newDistSym() method.

The symcase and pkcase arguments are ignored. It is an error to specify values for them other than the defauls shown.

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.