make-immediate-object

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

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.

A reference to a symbol is composed of the symbol name and the name of the package bound to *package* at the time make-immediate-object is called. The symcase and pkcase arguments apply only to symbol references and determine how the symbol name will be transmitted in the remote reference. This will determine how the symbol will be resolved when the remote reference returns from the Java program. The values of those arguments can be:

• :intern: pass the symbol name and/or package name as a string to be interpreted literally.
• :find: pass the symbol name and/or package name as a string. A package name is resolved by searching the list of existing package names and nicknames matching with equalp. A symbol name is resolved by searching the visible symbols in the specified package.
• :read: pass the symbol name and/or package name as a string created with the ~S format directive. A package name is resolved by reading the package name string with *package* bound to the keyword package.

  A symbol name is resolved by reading the symbol name string with *package* bound to the specified package.

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

Copyright (c) 1998-2002, Franz Inc. Oakland, CA., USA. All rights reserved.
Documentation for Allegro CL version 6.2. This page has had moderate revisions compared to the 6.1 page.
Created 2002.2.26.