com.franz.jlinker
Class LispCall

java.lang.Object
  |
  +--com.franz.jlinker.LispCall

public class LispCall

extends java.lang.Object

The purpose of this class is to facilitate calls from Lisp to Java. The connection to Lisp is assumed to be open and ready.

Typical usage style:

LispCall x=new LispCall("cl:concatenate"); x.addSymbol("cl:string"); x.addArg("foo"); x.addArg("bar"); x.call(); String v = x.stringValue(); ... // discard arguments and values to re-use the instance x.close(); x.reset();

Components of a LispCall instance:

• Operation
  A string or remote Lisp reference that identifies the Lisp function that will be called.
  See: getOp(), setOp().
• Call Style
  An integer constant that identifies the call style. The call style determines when and how values are returned from Lisp.
  See: getStyle(), setStyle().
• State
  An integer constant that identifies the state of a LispCall instance. The state of the instance determines which operations are allowed and what data is available.
  See: getState(), setState(), query(), reset(), close().
• Retention Strategy
  The retention stategy determines how arguments and values are retained or discarded.
  When true, arguments and values are retained until explicitly discarded.
  When false, arguments are discarded as soon as the call to Lisp is made.
  The default is true.
  See: getRetain(), setRetain().
• Arguments
  The arguments that will be passed to the Lisp function.
  See: addArg(), setArg(), addSymbol(), setSymbol().
• Values
  The value or values returned by the call to Lisp.
  See: booleanValue(), intValue(), doubleValue(), stringValue, intArrayValue(), doubleArrayValue(), stringArrayValue(), getValue().

Field Summary

static int	RES_BOOLEAN Result type constant: boolean.
static int	RES_DOUBLE_ARRAY Result type constant: array of floating point numbers.
static int	RES_ERROR Result type constant: remote reference to a Lisp error.
static int	RES_INT_ARRAY Result type constant: array of integer values.
static int	RES_INTEGER Result type constant: integer.
static int	RES_JAVA_POINTER Result type constant: Java Object instance.
static int	RES_LISP_POINTER Result type constant: remote reference to a Lisp object.
static int	RES_LONG Result type constant: long integer.
static int	RES_MISSING Result type constant: missing result.
static int	RES_NULL Result type constant: null.
static int	RES_REAL Result type constant: floating point number.
static int	RES_STRING Result type constant: string.
static int	RES_STRING_ARRAY Result type constant: array of strings.
static int	RES_SYMBOL Result type constant: remote reference to a Lisp symbol.
static int	RES_UNKNOWN Result type constant: unknown type.
static int	RES_WRONG_STATE Result type constant: incorrect LispCall state..
static int	STATE_CLOSED Internal state constant: arguments and values discarded.
static int	STATE_COLLECTING Internal state constant: collecting arguments to call.
static int	STATE_DONE Internal state constant: call completed, value(s) available.
static int	STATE_NEW Internal state constant: new, uninitialized instance.
static int	STATE_READY Internal state constant: ready to make call.
static int	STATE_WAITDONE Internal state constant: call completed, but value(s) not retrieved.
static int	STATE_WAITING Internal state constant: waiting for call to complete.
static int	STYLE_ASYNC_BR Call style constant: asynchronous call.
static int	STYLE_ASYNC_GO Call style constant: asynchronous call.
static int	STYLE_COPY Call style constant: default call returning Java data values if possible.
static int	STYLE_IGNORE Call style constant: call with ignored value(s).
static int	STYLE_ONEWAY Call style constant: one-way call.
static int	STYLE_REF Call style constant: call returning remote reference(s) if possible.

Constructor Summary

LispCall()
Create a LispCall instance with default style and default retention strategy.

LispCall(boolean r)
Create a LispCall instance with default style and the specified retention strategy.

LispCall(int s)
Create a LispCall instance with the specifed call style.

LispCall(java.lang.String op)
Create a LispCall instance to call the specified Lisp function.

Method Summary

int	addArg(boolean x) Add an argument to the call.
int	addArg(double x) Add an argument to the call.
int	addArg(int x) Add an argument to the call.
int	addArg(int[] x) Add an argument to the call.
int	addArg(long x) Add an argument to the call.
int	addArg(java.lang.Object x) Add an argument to the call.
int	addArg(java.lang.String x) Add an argument to the call.
int	addArg(java.lang.String[] x) Add an argument to the call.
int	addArg(com.franz.jlinker.TranStruct x) Add an argument to the call.
int	addSymbol(java.lang.String x) Add an argument to the call.
boolean	booleanValue() Get the first or only value returned from Lisp.
boolean	booleanValue(int i) Get the i-th value returned from Lisp.
int	call() Call a function in Lisp.
int	callAsyncBr() Call a function in Lisp.
int	callAsyncGo() Call a function in Lisp.
int	callCopy() Call a function in Lisp.
int	callIgnore() Call a function in Lisp.
int	callOneWay() Call a function in Lisp.
int	callRef() Call a function in Lisp.
void	close() Discard all arguments and results.
double[]	doubleArrayValue() Get the first or only value returned from Lisp.
double[]	doubleArrayValue(int i) Get the i-th value returned from Lisp.
double	doubleValue() Get the first or only value returned from Lisp.
double	doubleValue(int i) Get the i-th value returned from Lisp.
com.franz.jlinker.TranStruct	getOp() Get the Lisp operation.
boolean	getRetain() Get the retention strategy.
int	getState() Get the state of the LispCall instance.
int	getStyle() Get the call style of the LispCall instance.
com.franz.jlinker.TranStruct	getValue() Get the first or only raw value returned by a call to Lisp.
com.franz.jlinker.TranStruct	getValue(int i) Get the i-th raw value returned by a call to Lisp.
int[]	intArrayValue() Get the first or only value returned from Lisp.
int[]	intArrayValue(int i) Get the i-th value returned from Lisp.
int	intValue() Get the first or only value returned from Lisp.
int	intValue(int i) Get the i-th value returned from Lisp when it is expected to be of type int.
java.lang.String	lispType() Identify the Lisp type of the first or only returned value.
java.lang.String	lispType(int i) Identify the Lisp type of a returned value.
long	longValue() Get the first or only value returned from Lisp.
long	longValue(int i) Get the i-th value returned from Lisp.
static java.lang.String	nameOfType(int type) Translate an integer type code to a descriptive string.
java.lang.Object	objectValue() Get the first or only value returned from Lisp.
java.lang.Object	objectValue(int i) Get the i-th value returned from Lisp.
int	query() Query the state of a call to Lisp.
int	query(boolean doquery, boolean dofetch) Query the state of a call to Lisp.
boolean	reset() Discard the results but keep the arguments.
void	setArg(int i, boolean arg) Set or modify a specified argument position.
void	setArg(int i, double arg) Set or modify a specified argument position.
void	setArg(int i, double[] arg) Set or modify a specified argument position.
void	setArg(int i, int arg) Set or modify a specified argument position.
void	setArg(int i, int[] arg) Set or modify a specified argument position.
void	setArg(int i, long arg) Set or modify a specified argument position.
void	setArg(int i, java.lang.Object arg) Set or modify a specified argument position.
void	setArg(int i, java.lang.String arg) Set or modify a specified argument position.
void	setArg(int i, java.lang.String[] arg) Set or modify a specified argument position.
void	setArg(int i, com.franz.jlinker.TranStruct arg) Set or modify a specified argument position.
void	setOp(java.lang.String op) Specify the Lisp function that will be called.
void	setOp(com.franz.jlinker.TranStruct op) Specify the Lisp function that will be called.
void	setRetain(boolean r) Set the retention strategy.
void	setStyle(int s) Specify the call style.
void	setSymbol(int i, java.lang.String name) Set or modify a specified argument position.
java.lang.String[]	stringArrayValue() Get the first or only value returned from Lisp.
java.lang.String[]	stringArrayValue(int i) Get the i-th value returned from Lisp.
java.lang.String	stringValue() Get the first or only value returned from Lisp.
java.lang.String	stringValue(int i) Get the i-th value returned from Lisp.
java.lang.String	symbolName() Get the name of a Lisp symbol.
java.lang.String	symbolName(int i) Get the name of a Lisp symbol.
java.lang.String	symbolPackage() Get the name of the package of a Lisp symbol.
java.lang.String	symbolPackage(int i) Get the name of the package of a Lisp symbol.
int	typeOf() Query the type of the first or only value returned from Lisp.
int	typeOf(int i) Query the type of the i-th value returned from Lisp.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Detail

STYLE_ONEWAY

public static final int STYLE_ONEWAY

Call style constant: one-way call.
This style constant identifies a one-way Lisp call. A STYLE_ONEWAY call starts a call in Lisp and returns to the Java caller immediately without waiting for a result from Lisp.

STYLE_IGNORE

public static final int STYLE_IGNORE

Call style constant: call with ignored value(s).
This style constant identifies a Lisp call where the value(s) are ignored. A STYLE_IGNORE call to Lisp waits for the result to be computed, but the computed value or values are not returned to Java. When the values are ignored, the time taken to encode, transmit, and decode the values is saved.

STYLE_REF

public static final int STYLE_REF

Call style constant: call returning remote reference(s) if possible.
This style constant identifies a Lisp call where the returned values are returned as remote references if at all possible.

STYLE_COPY

public static final int STYLE_COPY

Call style constant: default call returning Java data values if possible.
This style constant identifies a Lisp call where the returned values are returned as Java values if at all possible.

STYLE_ASYNC_BR

public static final int STYLE_ASYNC_BR

Call style constant: asynchronous call.
This style constant identifies an asynchronous Lisp call. Control returns to Java before the Lisp call is completed. The Lisp call is initiated in a separate Lisp thread and the Java program can test when the operation is completed. The query() method is used to test the progress of the operation.

An important side-effect of this style of call is that Lisp errors are handled in the Lisp thread, and are not just returned to Java.

STYLE_ASYNC_GO

public static final int STYLE_ASYNC_GO

Call style constant: asynchronous call.
This style constant identifies an asynchronous Lisp call. Control returns to Java before the Lisp call is completed. The Lisp call is initiated in a separate Lisp thread and the Java program can test when the operation is completed. The query() method is used to test the progress of the operation.

Lisp errors are cought and returned to Java.

STATE_NEW

public static final int STATE_NEW

Internal state constant: new, uninitialized instance.
This constant identifies the state of a newly created LispCall instance. The Lisp operation must be specified before arguments may be added or a call can be made.

STATE_COLLECTING

public static final int STATE_COLLECTING

Internal state constant: collecting arguments to call.
This constant identifies the state of a LispCall instance when it is collecting arguments to be passed to Lisp.

STATE_READY

public static final int STATE_READY

Internal state constant: ready to make call.
This constant identifies the state of a LispCall instance when it is ready to make a call to Lisp.

STATE_DONE

public static final int STATE_DONE

Internal state constant: call completed, value(s) available.
This constant identifies the state of a LispCall instance when the call is complete and the value or values returned from Lisp are available.

STATE_WAITING

public static final int STATE_WAITING

Internal state constant: waiting for call to complete.
This constant identifies the state of a LispCall instance when a call in the STYLE_ASYNC style is waiting for results.

STATE_WAITDONE

public static final int STATE_WAITDONE

Internal state constant: call completed, but value(s) not retrieved.
This constant identifies the state of a LispCall instance when a call in the STYLE_ASYNC style is done but the results have not been retrieved from Lisp.

STATE_CLOSED

public static final int STATE_CLOSED

Internal state constant: arguments and values discarded.
This constant identifies the state of a LispCall instance when arguments and values have been discarded.

RES_NULL

public static final int RES_NULL

Result type constant: null.
This constant represents a result data type when the result is null.

RES_BOOLEAN

public static final int RES_BOOLEAN

Result type constant: boolean.
This constant represents a result data type when the result is a boolean value.

RES_INTEGER

public static final int RES_INTEGER

Result type constant: integer.
This constant represents a result data type when the result is an integer value.

RES_LONG

public static final int RES_LONG

Result type constant: long integer.
This constant represents a result data type when the result is a long integer value.

RES_REAL

public static final int RES_REAL

Result type constant: floating point number.
This constant represents a result data type when the result is floating point number.

RES_STRING

public static final int RES_STRING

Result type constant: string.
This constant represents a result data type when the result is a string.

RES_SYMBOL

public static final int RES_SYMBOL

Result type constant: remote reference to a Lisp symbol.
This constant represents a result data type when the result is a remote reference to a Lisp symbol.

RES_LISP_POINTER

public static final int RES_LISP_POINTER

Result type constant: remote reference to a Lisp object.
This constant represents a result data type when the result is a remote reference to a Lisp object.

RES_ERROR

public static final int RES_ERROR

Result type constant: remote reference to a Lisp error.
This constant represents a result data type when the result is a remote reference to a Lisp error.

RES_INT_ARRAY

public static final int RES_INT_ARRAY

Result type constant: array of integer values.
This constant represents a result data type when the result is an array of integer values.

RES_DOUBLE_ARRAY

public static final int RES_DOUBLE_ARRAY

Result type constant: array of floating point numbers.
This constant represents a result data type when the result is an array of floating point numbers.

RES_STRING_ARRAY

public static final int RES_STRING_ARRAY

Result type constant: array of strings.
This constant represents a result data type when the result is an array of strings.

RES_JAVA_POINTER

public static final int RES_JAVA_POINTER

Result type constant: Java Object instance.
This constant represents a result data type when the result is a pointer to a Java Object instance.

RES_WRONG_STATE

public static final int RES_WRONG_STATE

Result type constant: incorrect LispCall state..
This constant represents a result data type when an attempt is made to extract a result from a LispCall instance in a state where results are not available.

RES_MISSING

public static final int RES_MISSING

Result type constant: missing result.
This constant represents a result data type when an attempt is made to extract a result that is not present in a LispCall instance.

RES_UNKNOWN

public static final int RES_UNKNOWN

Result type constant: unknown type.
This constant represents a result data type when the result is of unknown type. This value should only occur if a system error is encountered.

Constructor Detail

LispCall

public LispCall()

Create a LispCall instance with default style and default retention strategy. The default constructor creates and initializes a LispCall instance with the default style of STYLE_COPY and the default retention strategy. The programmer must supply a Lisp function and any required arguments before making the call. Argument wrappers and results are retained until released with a call to close().

LispCall

public LispCall(boolean r)

Create a LispCall instance with default style and the specified retention strategy. Create and initialize a LispCall instance with the default style of STYLE_COPY and a retention strategy specified by the parameter. The programmer must supply a Lisp function and any required arguments before making the call.

Parameters:

r - A boolean value that specifies the retention strategy. A true value specifies that arguments and results are retained until released with a call to close(). A false values specifies that argument wrappers are discarded immediately after the call to Lisp is made.

LispCall

public LispCall(int s)

Create a LispCall instance with the specifed call style. Create and initialize a LispCall instance with the default retention strategy and a specified call style. The programmer must supply a Lisp function and any required arguments before making the call.

Parameters:

s - An integer that specifies the call style. It must be one of the constants STYLE_ONEWAY, STYLE_IGNORE, STYLE_REF, STYLE_COPY, STYLE_ASYNC.

LispCall

public LispCall(java.lang.String op)

Create a LispCall instance to call the specified Lisp function. Create and initialize a LispCall instance with the default retention strategy and default call style to call the specified Lisp function.

Parameters:

op - A string that specifies a Lisp function name.

Method Detail

getState

public int getState()

Get the state of the LispCall instance.

Returns:

One of the state constants.

getOp

public com.franz.jlinker.TranStruct getOp()

Get the Lisp operation.

Returns:

The result is always a TranStruct instance that wraps the string naming the Lisp function or the remote reference to the actual Lisp function.

getStyle

public int getStyle()

Get the call style of the LispCall instance.

Returns:

One of the style constants.

setOp

public void setOp(java.lang.String op)

Specify the Lisp function that will be called.

Parameters:

op - A string that specifies a Lisp function name.

setOp

public void setOp(com.franz.jlinker.TranStruct op)

Specify the Lisp function that will be called. This method is useful when the Java application is holding a pre-wrapped pointer to the Lisp function, or a function pointer that was returned by a previous call to Lisp.

Parameters:

op - A TranStuct instance that specifies a Lisp function.

setStyle

public void setStyle(int s)

Specify the call style.

Parameters:

s - An integer that specifies the call style. It must be one of the constants STYLE_ONEWAY, STYLE_IGNORE, STYLE_REF, STYLE_COPY, STYLE_ASYNC.

Throws:

java.lang.IllegalArgumentException - if the argument is not suitable.

getRetain

public boolean getRetain()

Get the retention strategy.

Returns:

A boolean value that describes the retention strategy.

setRetain

public void setRetain(boolean r)

Set the retention strategy.

Parameters:

r - A boolean value that specidies the new retention strategy.

addArg

public int addArg(com.franz.jlinker.TranStruct x)

Add an argument to the call. This method adds a pre-wrapped argument to the list of arguments that will be passed to the Lisp function when it is called.

Parameters:

x - A pre-wrapped object to be passed to Lisp.

Returns:

The number of arguments collected up to this point. The index of the added argument is one less than the returned value.

addArg

public int addArg(int x)

Add an argument to the call. This method wraps and adds an int argument to the list of arguments that will be passed to the Lisp function when it is called.

Parameters:

x - A short value that will be wrapped in a TranStruct instance.

Returns:

The number of arguments collected up to this point.

addArg

public int addArg(long x)

Add an argument to the call. This method wraps and adds a long argument to the list of arguments that will be passed to the Lisp function when it is called.

Parameters:

x - A short value that will be wrapped in a TranStruct instance.

Returns:

The number of arguments collected up to this point.

addArg

public int addArg(boolean x)

Add an argument to the call. This method wraps and adds a boolean argument to the list of arguments that will be passed to the Lisp function when it is called.

Parameters:

x - An int value that will be wrapped in a TranStruct instance.

Returns:

The number of arguments collected up to this point.

addArg

public int addArg(int[] x)

Add an argument to the call. This method wraps and adds an int array argument to the list of arguments that will be passed to the Lisp function when it is called.

Parameters:

x - An int vector that will be wrapped in a TranStruct instance.

Returns:

The number of arguments collected up to this point.

addArg

public int addArg(java.lang.String x)

Add an argument to the call. This method wraps and adds a String argument to the list of arguments that will be passed to the Lisp function when it is called.

Parameters:

x - A String value that will be wrapped in a TranStruct instance.

Returns:

The number of arguments collected up to this point.

addArg

public int addArg(java.lang.String[] x)

Add an argument to the call. This method wraps and adds a String array argument to the list of arguments that will be passed to the Lisp function when it is called.

Parameters:

x - A String vector that will be wrapped in a TranStruct instance.

Returns:

The number of arguments collected up to this point.

addArg

public int addArg(double x)

Add an argument to the call. This method wraps and adds a double argument to the list of arguments that will be passed to the Lisp function when it is called.

Parameters:

x - A double value that will be wrapped in a TranStruct instance.

Returns:

The number of arguments collected up to this point.

addArg

public int addArg(java.lang.Object x)

Add an argument to the call. This method wraps and adds a pointer argument to the list of arguments that will be passed to the Lisp function when it is called.

Parameters:

x - An Object value that will be wrapped in a TranStruct instance.

Returns:

The number of arguments collected up to this point.

addSymbol

public int addSymbol(java.lang.String x)

Add an argument to the call. This method wraps and adds a Lisp symbol reference to the list of arguments that will be passed to the Lisp function when it is called.

Parameters:

x - A String value that will be wrapped in a TranStruct instance that regferences the desired symbol.

Returns:

The number of arguments collected up to this point.

call

public int call()
         throws com.franz.jlinker.JavaLinkDist.JLinkerException

Call a function in Lisp.

Returns:

The returned value depends on the call style.

Throws:

IllegalStateException - if a previous call is not complete.

com.franz.jlinker.JavaLinkDist.JLinkerException - or a subclass if an error is detected during the call.

callOneWay

public int callOneWay()
               throws com.franz.jlinker.JavaLinkDist.JLinkerException

Call a function in Lisp. Call a function in Lisp after setting the style to STYLE_ONEWAY. This call returns immediately without waiting for a result from Lisp.

Returns:

The returned value is always zero.

callIgnore

public int callIgnore()
               throws com.franz.jlinker.JavaLinkDist.JLinkerException

Call a function in Lisp. Call a function in Lisp after setting the style to STYLE_IGNORE. This call returns only after the Lisp call runs to completion but the Lisp value is not returned.

Returns:

The returned value is always zero.

callRef

public int callRef()
            throws com.franz.jlinker.JavaLinkDist.JLinkerException

Call a function in Lisp. Call a function in Lisp after setting the style to STYLE_REF.

Returns:

The returned value is the number of values returned from Lisp.

Throws:

com.franz.jlinker.JavaLinkDist.JLinkerException - or a subclass if there was some error in the call.

callCopy

public int callCopy()
             throws com.franz.jlinker.JavaLinkDist.JLinkerException

Call a function in Lisp. Call a function in Lisp after setting the style to STYLE_COPY.

Returns:

The returned value is the number of values returned from Lisp.

Throws:

com.franz.jlinker.JavaLinkDist.JLinkerException - or a subclass if there was some error in the call.

callAsyncBr

public int callAsyncBr()
                throws com.franz.jlinker.JavaLinkDist.JLinkerException

Call a function in Lisp. Call a function in Lisp after setting the style to STYLE_ASYNC.

Returns:

The returned value is always 1.

Throws:

com.franz.jlinker.JavaLinkDist.JLinkerException - or a subclass if there was some error in the call.

callAsyncGo

public int callAsyncGo()
                throws com.franz.jlinker.JavaLinkDist.JLinkerException

Call a function in Lisp. Call a function in Lisp after setting the style to STYLE_ASYNC_GO.

Returns:

The returned value is always 1.

Throws:

com.franz.jlinker.JavaLinkDist.JLinkerException - or a subclass if there was some error in the call.

getValue

public com.franz.jlinker.TranStruct getValue()

Get the first or only raw value returned by a call to Lisp.

getValue

public com.franz.jlinker.TranStruct getValue(int i)

Get the i-th raw value returned by a call to Lisp. If the retention strategy is false, the value is discarded after it is retrieved.

Parameters:

i - The index of the desired value.

Returns:

A TransTruct instance that represents a wrapped value returned from Lisp.

Throws:

WrongStateException - if

• the results are not yet available
• for some reason the Lisp call returned null
• the value was fetched before and getRetain()==false

nameOfType

public static java.lang.String nameOfType(int type)

Translate an integer type code to a descriptive string. The returned value is one of the strings:

Integer type code	String name
RES_NULL	"Null"
RES_BOOLEAN	"Boolean"
RES_INTEGER	"Integer"
RES_LONG	"Long"
RES_REAL	"Real"
RES_STRING	"String"
RES_ERROR	"Error"
RES_SYMBOL	"Symbol"
RES_LISP_POINTER	"Lisp-Pointer"
RES_INT_ARRAY	"Int-Array"
RES_DOUBLE_ARRAY	"Double-Array"
RES_STRING_ARRAY	"String-Array"
RES_UNKNOWN	"Unknown"
RES_JAVA_POINTER	"Java-Pointer"
RES_WRONG_STATE	"Wrong-State"
RES_MISSING	"Missing"
	"Unknown-nn" where nn is the integer type code

Returns:

A string describing the value.

typeOf

public int typeOf()

Query the type of the first or only value returned from Lisp.

Returns:

The integer constant that describes the type.

typeOf

public int typeOf(int i)

Query the type of the i-th value returned from Lisp.

Parameters:

i - The index of the value queried.

Returns:

The integer constant that describes the type.

intValue

public int intValue()

Get the first or only value returned from Lisp. Get the first or only value returned from Lisp when it is expected to be of type int.

Returns:

The int value.

Throws:

UnsupportedOperationException - when the value returned from Lisp is not convertible to int.

ArrayOutOfBoundsException - when the i-th value is not there.

intValue

public int intValue(int i)

Get the i-th value returned from Lisp when it is expected to be of type int.

Parameters:

i - The index of the desired value.

Returns:

The int value.

Throws:

UnsupportedOperationException - when the i-th value returned from Lisp is not convertible to int.

ArrayOutOfBoundsException - when the i-th value is not there.

longValue

public long longValue()

Get the first or only value returned from Lisp.

longValue

public long longValue(int i)

Get the i-th value returned from Lisp. Get the i-th value returned from Lisp when it is expected to be of type long.

Parameters:

i - The index of the desired value.

Returns:

The long value.

Throws:

UnsupportedOperationException - when the i-th value returned from Lisp is not convertible to long.

ArrayOutOfBoundsException - when the i-th value is not there.

doubleValue

public double doubleValue()

Get the first or only value returned from Lisp.

doubleValue

public double doubleValue(int i)

Get the i-th value returned from Lisp. Get the i-th value returned from Lisp when it is expected to be of type float or double.

Parameters:

i - The index of the desired value.

Returns:

The double value.

Throws:

UnsupportedOperationException - when the i-th value returned from Lisp is not convertible to double.

ArrayOutOfBoundsException - when the i-th value is not there.

booleanValue

public boolean booleanValue()

Get the first or only value returned from Lisp.

booleanValue

public boolean booleanValue(int i)

Get the i-th value returned from Lisp. Get the i-th value returned from Lisp when it is expected to be of type boolean.

Parameters:

i - The index of the desired value.

Returns:

The boolean value.

Throws:

UnsupportedOperationException - when the i-th value returned from Lisp is not boolean.

ArrayOutOfBoundsException - when the i-th value is not there.

stringValue

public java.lang.String stringValue()

Get the first or only value returned from Lisp.

stringValue

public java.lang.String stringValue(int i)

Get the i-th value returned from Lisp. Get the i-th value returned from Lisp when it is expected to be of type String.

Parameters:

i - The index of the desired value.

Returns:

The String value.

Throws:

UnsupportedOperationException - when the i-th value returned from Lisp is not String.

ArrayOutOfBoundsException - when the i-th value is not there.

intArrayValue

public int[] intArrayValue()

Get the first or only value returned from Lisp.

intArrayValue

public int[] intArrayValue(int i)

Get the i-th value returned from Lisp. Get the i-th value returned from Lisp when it is expected to be of type int[].

Parameters:

i - The index of the desired value.

Returns:

The int[] value.

Throws:

UnsupportedOperationException - when the i-th value returned from Lisp is not int[].

ArrayOutOfBoundsException - when the i-th value is not there.

stringArrayValue

public java.lang.String[] stringArrayValue()

Get the first or only value returned from Lisp.

stringArrayValue

public java.lang.String[] stringArrayValue(int i)

Get the i-th value returned from Lisp. Get the i-th value returned from Lisp when it is expected to be of type String[].

Parameters:

i - The index of the desired value.

Returns:

The String[] value.

Throws:

UnsupportedOperationException - when the i-th value returned from Lisp is not String[].

ArrayOutOfBoundsException - when the i-th value is not there.

doubleArrayValue

public double[] doubleArrayValue()

Get the first or only value returned from Lisp.

doubleArrayValue

public double[] doubleArrayValue(int i)

Get the i-th value returned from Lisp. Get the i-th value returned from Lisp when it is expected to be of type double[].

Parameters:

i - The index of the desired value.

Returns:

The double[] value.

Throws:

UnsupportedOperationException - when the i-th value returned from Lisp is not double[].

ArrayOutOfBoundsException - when the i-th value is not there.

objectValue

public java.lang.Object objectValue()

Get the first or only value returned from Lisp.

objectValue

public java.lang.Object objectValue(int i)

Get the i-th value returned from Lisp. Get the i-th value returned from Lisp when it is expected to be of type Object.

Parameters:

i - The index of the desired value.

Returns:

The Object value.

Throws:

UnsupportedOperationException - when the i-th value returned from Lisp is not Object.

ArrayOutOfBoundsException - when the i-th value is not there.

symbolName

public java.lang.String symbolName()

Get the name of a Lisp symbol. Get the name of the Lisp symbol returned as the first or only value of a call.

Returns:

A string containing the symbol-name of the symbol.

Throws:

UnsupportedOperationException - when the returned value is not a Lisp symbol.

symbolName

public java.lang.String symbolName(int i)

Get the name of a Lisp symbol. Get the name of the Lisp symbol returned as the i-th value of a call.

Returns:

A string containing the symbol-name of the symbol.

Throws:

UnsupportedOperationException - when the returned value is not a Lisp symbol.

symbolPackage

public java.lang.String symbolPackage()

Get the name of the package of a Lisp symbol. Get the name of the package of a Lisp symbol returned as the first or only value of a call.

Returns:

A string containing the package-name of the package of the symbol.

Throws:

UnsupportedOperationException - when the returned value is not a Lisp symbol.

symbolPackage

public java.lang.String symbolPackage(int i)

Get the name of the package of a Lisp symbol. Get the name of the package of a Lisp symbol returned as the i-th value of a call.

Returns:

A string containing the package-name of the package of the symbol.

Throws:

UnsupportedOperationException - when the returned value is not a Lisp symbol.

lispType

public java.lang.String lispType()

Identify the Lisp type of the first or only returned value.

Returns:

A string that describes the Lisp type of the returned Value.

lispType

public java.lang.String lispType(int i)

Identify the Lisp type of a returned value.

Returns:

a string that describes the Lisp type of the i-th returned value.

If the returned value has been converted to a Java data value or Object, the string is one of the strings returned by nameOfType().

If the returned value is a remote reference to a Lisp object, then the string is the Lisp format ~A representation of the Lisp type.

query

public int query()

Query the state of a call to Lisp.

Returns:

An integer describing the result.

• A zero or positive value is the number of values returned from Lisp.
• A negative value of -100 indicates that the call has not yet been made.

The remaining values will only be seen if the style is set to STYLE_ASYNC.

• A negative value of -10 indicates that the call is still in progress. The two argument form of query() must be used to get a more detailed response.
• A negative value of -11 indicates that the call is done but the the values have not been retrieved. The two argument form of query() must be used to get the number of values or to retrieve them.
• A negative value of -99 indicates that the call was terminated by a throw or some error.

query

public int query(boolean doquery,
                 boolean dofetch)
          throws com.franz.jlinker.JavaLinkDist.JLinkerException

Query the state of a call to Lisp. If the call was with style STYLE_ASYNC, then query the progress of the call in Lisp and fetch the results. If an STYLE_ASYNC call has finally completed, fetch the Lisp values.

Parameters:

doquery - When this argument is true, fetch a more detailed description of the state of an STYLE_ASYNC call.

dofetch - When this argument is true, and an STYLE_ASYNC call is complete in Lisp, fetch the values of the call.

Returns:

An integer describing the result.

• A zero or positive value is the number of values returned from Lisp.
• A negative value of -100 indicates that the call has not yet been made.

The remaining values will only be seen if the style is set to STYLE_ASYNC.

• A negative value between zero and -10 indicates that the call is still incomplete.
• A negative value of -10 indicates that the call is in progress but doquery was false so a more detailed response is not available.
• A negative value of -11 indicates that the call is done but the the values have not been retrieved because dofetch was false.
• A negative value of -98 indicates that the call was terminated by an error and three values will be returned if and when dofetch is true: -98, as string describing the error, and a remote reference to the error object.
• A negative value of -99 indicates that the call was terminated by an error or a throw.

Throws:

com.franz.jlinker.JavaLinkDist.JLinkerException - If an error occurs when fetching the the state or results of a STYLE_ASYNC call.

close

public void close()

Discard all arguments and results. The style, retention strategy, and Lisp operator are retained if previously set. A call to reset() is needed before new arguments may be added.

reset

public boolean reset()

Discard the results but keep the arguments. Discard results but keep arguments so that the LispCall instance may be re-used for another call. The style, retention strategy, and Lisp operator are retained if previously set.

• If the LispCall instance was in state STATE_COLLECTING arguments, it switches to STATE_READY with the current number of arguments.
• If the LispCall instance was in state STATE_DONE, STATE_WAITING, or STATE_WAITDONE the effect depends on the retention strategy.
  If arguments were retained, the instance switches to STATE_READY for another call.
  If arguments were not retained, then the instance switches to the STATE_COLLECTING state.
• If the LispCall instance was in STATE_CLOSED, then if the Lisp operation is set the instance switches to the STATE_COLLECTING state, otherwise it switches to the STATE_NEW state.

Returns:

The returned value is true if the LispCall instance is ready to make another call. The methods setOp() and setArg() may be used to modify the instance before making a call.

When the returned value is false, the LispCall instance is in the STATE_NEW or STATE_COLLECTING state ansd is not ready for another call.

setArg

public void setArg(int i,
                   com.franz.jlinker.TranStruct arg)

Set or modify a specified argument position. Set or modify a specified argument position with a pre-wrapped value.

setArg

public void setArg(int i,
                   boolean arg)

Set or modify a specified argument position. Set or modify a specified argument position with a boolean value.

setArg

public void setArg(int i,
                   int arg)

Set or modify a specified argument position. Set or modify a specified argument position with an int value.

setArg

public void setArg(int i,
                   long arg)

Set or modify a specified argument position. Set or modify a specified argument position with a long value.

setArg

public void setArg(int i,
                   double arg)

Set or modify a specified argument position. Set or modify a specified argument position with a double value.

setArg

public void setArg(int i,
                   java.lang.String arg)

Set or modify a specified argument position. Set or modify a specified argument position with a String value.

setArg

public void setArg(int i,
                   java.lang.Object arg)

Set or modify a specified argument position. Set or modify a specified argument position with a reference to a Java Object.

setArg

public void setArg(int i,
                   int[] arg)

Set or modify a specified argument position. Set or modify a specified argument position with a copy of an array of int values.

setArg

public void setArg(int i,
                   double[] arg)

Set or modify a specified argument position. Set or modify a specified argument position with a copy of an array of double values.

setArg

public void setArg(int i,
                   java.lang.String[] arg)

Set or modify a specified argument position. Set or modify a specified argument position with a copy of an array of String values.

setSymbol

public void setSymbol(int i,
                      java.lang.String name)

Set or modify a specified argument position. Set or modify a specified argument position with a reference to a Lisp symbol.