FunctionPackage: javatools.jlinkerToCDocOverviewCGDocRelNotesFAQIndexPermutedIndex
Allegro CL version 8.1
Unrevised from 8.0 to 8.1.
8.0 version

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:

Lisp Type of x type is :ref type is :boolean type is :byte type is :short type is :int
bignum See Note 1 boolean byte short int
integer int boolean byte short int
real See Note 1 boolean double double double
string See Note 1 boolean String String String
character char boolean char char char
(array (signed-byte 32) (*)) See Note 1 boolean byte[] short[] int[]
(array double-float (*)) See Note 1 boolean double[] double[] double[]
null null boolean byte[] short[] int[]
symbol See Note 3 See Note 1 boolean See Note 1 See Note 1 See Note 1
cons See Note 2 See Note 1 boolean byte[] short[] int[]
Lisp Type of x type is :long type is :single type is :double type is :string
bignum long int int int
integer long int int int
real double float double double
string String String String String
character char char char char
(array (signed-byte 32) (*)) int[] int[] int[] int[]
(array double-float (*)) double[] float[] double[] double[]
null null float[] double[] String[]
symbol See Note 3 See Note 1 See Note 1 See Note 1 See Note 1
cons See Note 2 See Note 1 float[] double[] String[]

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:

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


Copyright (c) 1998-2009, Franz Inc. Oakland, CA., USA. All rights reserved.
Documentation for Allegro CL version 8.1. This page was not revised from the 8.0 page.
Created 2009.7.29.

ToCDocOverviewCGDocRelNotesFAQIndexPermutedIndex
Allegro CL version 8.1
Unrevised from 8.0 to 8.1.
8.0 version