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 made with static methods in this class.

  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();

  Connection methods:

  - `connect(String, int, int)`
  - `connect(String, int, int, int)`
  - `advertise(int, int)`
  - `advertise(String, String, int, int)`
  - `disconnect()`

  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 strategy 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().

- - ### Nested Class Summary

    Nested Classes
    Modifier and Type | Class and Description
    --- | ---
    `static class` | `LispCall.JlinkerState` This enum defines the constants that identify the states of a Jlinker connection.

  - ### Field Summary

    Fields
    Modifier and Type | Field and Description
    --- | ---
    `static java.lang.Object` | `connectError` Additional information about a failed connection attempt.
    `static int` | `defaultPollCount` How many times to attempt making a connection.
    `static int` | `defaultPollInterval` How often to attempt making a connection.
    `static int` | `defaultPortTimeout` How long a client should wait for a port to be available for a call to Lisp.
    `static int` | `discardBatchSize` The batch size for discardInLisp() operations.
    `java.lang.Object` | `queryError` Additional information about a failed call to query().
    `static int` | `readTimeout` Timeout value for a read operations on a socket.
    `static int` | `replyTimeout` How long a client call should wait for a reply to begin.
    `static int` | `requestTimeout` How long the server will wait for another client request.
    `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_WRAPPER` Result type constant: wrapped result.
    `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.
    `static int` | `verifiedConnectTimeout` How long to wait for a verified connection response.

  - ### Constructor Summary

    Constructors
    Constructor and Description
    `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 specified call style.
    `LispCall(java.lang.String op)` Create a LispCall instance to call the specified Lisp function.

  - ### Method Summary

    All Methods Static Methods Instance Methods Concrete Methods Deprecated Methods
    Modifier and Type | Method and Description
    --- | ---
    `int` | `addArg(boolean x)` Add a boolean argument to the call.
    `int` | `addArg(byte x)` Add a byte argument to the call.
    `int` | `addArg(byte[] x)` Add a byte array argument to the call.
    `int` | `addArg(double x)` Add a double float argument to the call.
    `int` | `addArg(double[] x)` Add a double float array argument to the call.
    `int` | `addArg(float x)` Add an argument to the call.
    `int` | `addArg(float[] x)` Add a float array argument to the call.
    `int` | `addArg(int x)` Add an integer argument to the call.
    `int` | `addArg(int[] x)` Add an argument to the call.
    `int` | `addArg(long x)` Add a long integer argument to the call.
    `int` | `addArg(java.lang.Object x)` Add an Java Object argument to the call.
    `int` | `addArg(short x)` Add a short integer argument to the call.
    `int` | `addArg(short[] 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` | `addSymbol(java.lang.String x)` Add a Lisp symbol argument to the call.
    `int` | `addSymbol(java.lang.String x, java.lang.String pk)` Add a Lisp symbol argument to the call.
    `int` | `addSymbol(java.lang.String x, java.lang.String pk, int action)` Add a Lisp symbol or a value referenced by a Lisp symbol as an argument to the call.
    `static boolean` | `advertise(int port, int timeoutSeconds)` Allow a Lisp server to connect to the Java application.
    `static boolean` | `advertise(java.lang.String l2j, java.lang.String host, int port, int timeoutSeconds)` Advertise the Java host and port in a file.
    `boolean` | `booleanValue()` Get the first or only boolean value returned from Lisp.
    `boolean` | `booleanValue(int i)` Get the i-th value returned from Lisp when it is expected to be of type boolean.
    `int` | `call()` Call a function in Lisp.
    `int` | `callAsyncBr()` Call a function in Lisp after setting the style to STYLE_ASYNC.
    `int` | `callAsyncGo()` Call a function in Lisp after setting the style to STYLE_ASYNC_GO.
    `int` | `callCopy()` Call a function in Lisp after setting the style to STYLE_COPY.
    `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.
    `static boolean` | `connect(java.lang.String com, int pollInterval, int pollCount)` Connect to a Lisp server when the host and port are published in a file.
    `static boolean` | `connect(java.lang.String host, int port, int pollInterval, int pollCount)` Connect to a Lisp server at a known host and port.
    `static long` | `discardInLisp(java.lang.Object... x)` Discard remote references to Lisp objects.
    `static void` | `disconnect()` End the connection to a Lisp server.
    `static int` | `dispatchEvent(java.lang.String ev, java.lang.Object target, java.lang.String[] s, int[] l)` Dispatch an event to the Lisp handler.
    `static int` | `dispatchEvent(java.lang.String ev, java.lang.Object target, java.lang.String[] s, int[] l, int timeout)` Dispatch an event to the Lisp handler.
    `double[]` | `doubleArrayValue()` Get the first or only double[] value returned from Lisp.
    `double[]` | `doubleArrayValue(int i)` Get the i-th value returned from Lisp when it is expected to be of type double[].
    `double` | `doubleValue()` Get the first or only double float value returned from Lisp.
    `double` | `doubleValue(int i)` Get the i-th value returned from Lisp when it is expected to be of type float or double.
    `static int[]` | `getDefaultConnectionPool()` Return an array that describes the default connection pool parameters.
    `java.lang.Object` | `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.
    `JLWrapper.TypeCode` | `getTypeCode()` Query the type of the first or only value returned from Lisp.
    `JLWrapper.TypeCode` | `getTypeCode(int i)` Query the type of the i-th value returned from Lisp.
    `java.lang.Object` | `getValue()` Get the first or only raw value returned by a call to Lisp.
    `java.lang.Object` | `getValue(int i)` Get the i-th raw value returned by a call to Lisp.
    `static java.lang.Object` | `identity(java.lang.Object arg)` Returns the argument (or an equivalent object).
    `int[]` | `intArrayValue()` Get the first or only int[] value returned from Lisp.
    `int[]` | `intArrayValue(int i)` Get the i-th value returned from Lisp when it is expected to be of type int[].
    `int` | `intValue()` Get the first or only value returned from Lisp when it is expected to be of type int.
    `int` | `intValue(int i)` Get the i-th value returned from Lisp when it is expected to be of type int.
    `static boolean` | `isJlinkerReady()` Query the state of the Jlinker connection.
    `static boolean` | `isJlinkerState(LispCall.JlinkerState... targets)` Query the state of the Jlinker connection.
    `static boolean` | `isJlinkerState(long timeout, LispCall.JlinkerState... targets)` Query the state of the Jlinker connection.
    `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 when it is expected to be of type long.
    `int` | `mayCall()` Query if it is allowed to call Lisp in this thread.
    `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 Object value returned from Lisp.
    `java.lang.Object` | `objectValue(int i)` Get the i-th value returned from Lisp when it is expected to be of type Object.
    `int` | `query()` Query the state of a call to Lisp.
    `int` | `query(boolean doquery, boolean dofetch)` Query the state of a call to Lisp.
    `java.lang.String` | `queryAsyncName()` Query the name of the Lisp process where the call is run.
    `static java.lang.Object` | `queryConnectionPool()` Query the state of the connection pool.
    `boolean` | `reset()` Discard the results but keep the arguments.
    `void` | `setArg(int i, boolean arg)` Set or modify a specified argument position with a boolean value.
    `void` | `setArg(int i, double arg)` Set or modify a specified argument position with a double value.
    `void` | `setArg(int i, double[] arg)` Set or modify a specified argument position with a copy of an array of double values.
    `void` | `setArg(int i, int arg)` Set or modify a specified argument position with an int value.
    `void` | `setArg(int i, int[] arg)` Set or modify a specified argument position with a copy of an array of int values.
    `void` | `setArg(int i, long arg)` Set or modify a specified argument position with a long value.
    `void` | `setArg(int i, java.lang.Object arg)` Set or modify a specified argument position with a reference to a Java Object or a pre-wrapped Java or Lisp object.
    `void` | `setArg(int i, java.lang.String arg)` Set or modify a specified argument position with a String value.
    `void` | `setArg(int i, java.lang.String[] arg)` Set or modify a specified argument position with a copy of an array of String values.
    `static void` | `setDefaultConnectionPool(int lispMin, int lispMax, int lispIdle, int javaMin, int javaMax, int javaIdle)` Modify the default connection pool parameters.
    `void` | `setOp(java.lang.Object op)` Specify the Lisp function that will be called.
    `void` | `setOp(java.lang.String 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 with a reference to a Lisp symbol.
    `void` | `setSymbol(int i, java.lang.String name, java.lang.String pkg)` Set or modify a specified argument position with a reference to a Lisp symbol.
    `void` | `setSymbol(int i, java.lang.String name, java.lang.String pkg, int mode)` Set or modify a specified argument position with a reference to a Lisp symbol.
    `java.lang.String[]` | `stringArrayValue()` Get the first or only String[] value returned from Lisp.
    `java.lang.String[]` | `stringArrayValue(int i)` Get the i-th value returned from Lisp when it is expected to be of type String[].
    `java.lang.String` | `stringValue()` Get the first or only String 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 the Lisp symbol returned as the first or only value of a call.
    `java.lang.String` | `symbolName(int i)` Get the name of the Lisp symbol returned as the i-th value of a call.
    `java.lang.String` | `symbolPackage()` Get the name of the package of a Lisp symbol returned as the first or only value of a call.
    `java.lang.String` | `symbolPackage(int i)` Get the name of the package of a Lisp symbol returned as the i-th value of a call.
    `int` | `typeOf()` Deprecated. use `getTypeCode()`
    `int` | `typeOf(int i)` Deprecated. use `getTypeCode(int)`

    - ### 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.

      See Also:
        Constant Field Values

    - #### STYLE_IGNORE

          public static final int STYLE_IGNORE

      Call style constant: call with ignored value(s).

      This style constant identifies a synchronous call to Lisp 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.

      See Also:
        Constant Field Values

    - #### STYLE_REF

          public static final int STYLE_REF

      Call style constant: call returning remote reference(s) if possible.

      This style constant identifies a synchronous call to Lisp; the Lisp values are returned as remote references if at all possible.

      See Also:
        Constant Field Values

    - #### STYLE_COPY

          public static final int STYLE_COPY

      Call style constant: default call returning Java data values if possible.

      This style constant identifies a synchronous call to Lisp; the Lisp values are returned as Java values if at all possible.

      See Also:
        Constant Field Values

    - #### 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.

      See Also:
        Constant Field Values

    - #### 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 caught and returned to Java.

      See Also:
        Constant Field Values

    - #### 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.

      See Also:
        Constant Field Values

    - #### 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.

      See Also:
        Constant Field Values

    - #### 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.

      See Also:
        Constant Field Values

    - #### 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.

      See Also:
        Constant Field Values

    - #### 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.

      See Also:
        Constant Field Values

    - #### 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.

      See Also:
        Constant Field Values

    - #### 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.

      See Also:
        Constant Field Values

    - #### 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_WRAPPER

          public static final int RES_WRAPPER

      Result type constant: wrapped result.

      This constant represents a result data type when an attempt is made to extract a result that is still wrapped 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.

    - #### queryError

          public java.lang.Object queryError

      Additional information about a failed call to query(). When a call to query() fails for some unexpected reason, this field may be set to a value that may provide additional information about the failure, such as a String or an Exception instance.

    - #### defaultPollInterval

          public static int defaultPollInterval

      How often to attempt making a connection. The value of this field is the integer number of milliseconds between attempts to connect when the Lisp application is advertising.

      The initial value is 1000.

      A value of -1 specifies that only one attempt will be made.

    - #### defaultPollCount

          public static int defaultPollCount

      How many times to attempt making a connection.

      The value of this field is the number of connection attempts when the Lisp application is advertising and pollInterval is positive.

      The initial value is 300.

    - #### connectError

          public static java.lang.Object connectError

      Additional information about a failed connection attempt.

      After a failed call to connect() or advertise(), this field holds an Object instance that describes the failure, usually an instance of IllegalArgumentException.

    - #### readTimeout

          public static int readTimeout

      Timeout value for a read operations on a socket.

      This timeout prevents an indefinite hangup in the event that a network connection becomes inoperative. If the network between client and server is very slow this value may need to be larger. If a quicker response to a broken network is desired, this value can be smaller. The initial setting is 30000 milliseconds.

      In the event of a timeout as a result of the readTimeout or replyTimeout, the sequence of events on the socket has been disrupted and the socket can no longer be used. The only possible recovery action is to close the connection that caused the timeout and start a new connection.

    - #### defaultPortTimeout

          public static int defaultPortTimeout

      How long a client should wait for a port to be available for a call to Lisp.

      The initial value is -1 to denote a value a few seconds longer than replyTimeout (if a port is busy, it should be free after a normal reply delay).

    - #### replyTimeout

          public static int replyTimeout

      How long a client call should wait for a reply to begin.

      If the application can expect a call to last longer, then this value should be increased. The initial setting is 300000 milliseconds. A small value allows a Java application to detect a network problem or Lisp problem sooner but limits the amount of work a Lisp call can do. If a short timeout is used, the STYLE_ASYNC calls can be used to allow Lisp calls to run as long a necessary.

      In the event of a timeout as a result of the readTimeout or replyTimeout, the sequence of events on the socket has been disrupted and the socket can no longer be used. The only possible recovery action is to close the connection that caused the timeout and start a new connection.

    - #### requestTimeout

          public static int requestTimeout

      How long the server will wait for another client request.

      The initial setting is 0 for an indefinite wait. If a positive value is specified, the connection will be terminated if a remote call does not arrive before the timeout.

    - #### verifiedConnectTimeout

          public static int verifiedConnectTimeout

      How long to wait for a verified connection response.

      In a verified connection situation, there is an immediate exchange of information once a connection is established. A timeout can mean that the Lisp program supports an older version of the connection protocol, a version that does not support verified connections. If the Lisp program is known to be up to date and legitimate connections are rejected this timeout value may need to be increased. The default value is 15000.

      This setting can be modified when a Java VM is started by setting the system property "com.franz.jlinker.verifytimeout".

    - #### discardBatchSize

          public static int discardBatchSize

      The batch size for discardInLisp() operations.

      When discardInLisp() is called the data is collected until the batch size is reached.

      To force immediate flushing of the data, set this field to zero or call discardInLisp(0).

  - ### 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 specified 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

    - #### isJlinkerReady

          public static boolean isJlinkerReady()

      Query the state of the Jlinker connection.

      The call to connect() or advertise() can take some time in one thread. If another thread attempt to use the connection before it is ready, an IllegalStateException is thrown. To avoid the exception, a thread should query the state and make a call only in the READY state.

      Introduced in version 7001002.

      Returns:
        True if the connection is in the READY state. This is the only state in which calls can be made to Lisp.

    - #### isJlinkerState

          public static boolean isJlinkerState(LispCall.JlinkerState... targets)

      Query the state of the Jlinker connection.

      In a single-threaded application, the state of the Jlinker connection is only seen as IDLE, READY, or DISCONNECTED. The other intermediate states can only be seen in parallel threads while a connection is completed or severed.

      In multi-threaded applications, a thread should make calls to Lisp only when the connection is ready. If the connection is not ready, call() will throw `IllegalStateException`.

      Introduced in version 7001002.

      Parameters:
        `targets` - One or more of the state tokens.
      Returns:
        true if current state is any one of the states mentioned in the arguments (or if no targets are mentioned).

    - #### isJlinkerState

          public static boolean isJlinkerState(long timeout,
                                               LispCall.JlinkerState... targets)

      Query the state of the Jlinker connection.

      Introduced in version 7001002.

      Parameters:
        `timeout` - The number of milliseconds to wait until desired state is reached.
        `targets` - One or more of the state tokens.
      Returns:
        true if any one of the states mentioned in the arguments is reached before the timeout expires.

    - #### getDefaultConnectionPool

          public static int[] getDefaultConnectionPool()

      Return an array that describes the default connection pool parameters.
      Returns:
        An array of 6 integers.

               { lispMin, lispMax, lispIdle, javaMin, javaMax, javaIdle }

    - #### setDefaultConnectionPool

          public static void setDefaultConnectionPool(int lispMin,
                                                      int lispMax,
                                                      int lispIdle,
                                                      int javaMin,
                                                      int javaMax,
                                                      int javaIdle)

      Modify the default connection pool parameters. This method must be called before Jlinker is initialized, or IllegalStateException is thrown. A value less than -1 leaves that default unchanged. A value of -1 specifies that the setting from Lisp will prevail. A value of zero for lispMin or javaMin suppresses the connection pool.

      Introduced in version 7001000.

      Parameters:
        `lispMin` -
        `lispMax` -
        `lispIdle` -
        `javaMin` -
        `javaMax` -
        `javaIdle` -

    - #### queryConnectionPool

          public static java.lang.Object queryConnectionPool()

      Query the state of the connection pool.
      Returns:
        The returned value is an object that depends on the state of the pool. If the pool is not running, and the default specifies no pool, the value is null. If the pool is not running but a pool is possible, the value is an array of 6 integers:

                { lispMin lispMax lispIdle javaMin javaMax javaIdle }

        If the pool is running, the value is an array of 8 integers:

                { lispMin lispCur lispMax lispIdle javaMin javaCur javaMax javaIdle }

        Introduced in version 7001000.

    - #### getState

          public int getState()

      Get the state of the LispCall instance.
      Returns:
        One of the state constants.

    - #### getOp

          public java.lang.Object getOp()

      Get the Lisp operation.
      Returns:
        The result is always a wrapper 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(java.lang.Object 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 wrapper 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 specifies the new retention strategy.

    - #### addArg

          public int addArg(byte x)

      Add a byte argument to the call.

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

      Parameters:
        `x` - A `byte` value that will be passed to Lisp.
      Returns:
        The number of arguments collected up to this point.

    - #### addArg

          public int addArg(short x)

      Add a short integer argument to the call.

      This method wraps and adds a short 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 passed to Lisp.
      Returns:
        The number of arguments collected up to this point.

    - #### addArg

          public int addArg(int x)

      Add an integer 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` - An `int` value that will be passed to Lisp.
      Returns:
        The number of arguments collected up to this point.

    - #### addArg

          public int addArg(long x)

      Add a long integer 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 `long` value that will be passed to Lisp.
      Returns:
        The number of arguments collected up to this point.

    - #### addArg

          public int addArg(boolean x)

      Add a boolean 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` - A `boolean` value that will be passed to Lisp in a wrapper.
      Returns:
        The number of arguments collected up to this point.

    - #### addArg

          public int addArg(byte[] x)

      Add a byte array argument to the call.

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

      Parameters:
        `x` - A `byte` vector that will be passed to Lisp.
      Returns:
        The number of arguments collected up to this point.

    - #### addArg

          public int addArg(short[] x)

      Add an argument to the call. This method wraps and adds a short array argument to the list of arguments that will be passed to the Lisp function when it is called.
      Parameters:
        `x` - A `short` vector that will be passed to Lisp.
      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 passed to Lisp in a wrapper.
      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 passed to Lisp in a wrapper.
      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 passed to Lisp in a wrapper.
      Returns:
        The number of arguments collected up to this point.

    - #### addArg

          public int addArg(float x)

      Add an argument to the call. This method wraps and adds a float argument to the list of arguments that will be passed to the Lisp function when it is called.
      Parameters:
        `x` - A `float` value that will be passed to Lisp.
      Returns:
        The number of arguments collected up to this point.

    - #### addArg

          public int addArg(double x)

      Add a double float 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 passed to Lisp.
      Returns:
        The number of arguments collected up to this point.

    - #### addArg

          public int addArg(float[] x)

      Add a float array argument to the call.

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

      Parameters:
        `x` - A `float` vector that will be passed to Lisp.
      Returns:
        The number of arguments collected up to this point.

    - #### addArg

          public int addArg(double[] x)

      Add a double float array argument to the call.

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

      Parameters:
        `x` - A `double` vector that will be passed to Lisp.
      Returns:
        The number of arguments collected up to this point.

    - #### addArg

          public int addArg(java.lang.Object x)

      Add an Java Object 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 passed to Lisp.
      Returns:
        The number of arguments collected up to this point.

    - #### addSymbol

          public int addSymbol(java.lang.String x)

      Add a Lisp symbol 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. The symbol is interned with read-from-string.

      Parameters:
        `x` - A `String` value that will be passed to read-from-string to create the symbol. The string may contain a package prefix as well as a symbol name. If the entire string is not consumed to create the symbol a Lisp error is signaled. Special characters must be escaped with the Lisp escape character.
      Returns:
        The number of arguments collected up to this point.

    - #### addSymbol

          public int addSymbol(java.lang.String x,
                               java.lang.String pk)

      Add a Lisp symbol 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. The symbol is interned with read-from-string.

      Parameters:
        `x` - A `String` value that will be passed to read-from-string to create the symbol. The string may contain a package prefix as well as a symbol name.
        `pk` - A `String` value that specifies the Lisp package context for read-from-string.
        - If the pk argument is the empty string, the current package is used.
        - If the pk argument is the string ":", the keyword package is used.
        - Otherwise, the string specifies a package name. The package name is interned with read-from-string to avoid case-mode issues.
        If the entire string is not consumed to create the symbol a Lisp error is signaled. Special characters must be escaped with the Lisp escape character.
      Returns:
        The number of arguments collected up to this point.

    - #### addSymbol

          public int addSymbol(java.lang.String x,
                               java.lang.String pk,
                               int action)

      Add a Lisp symbol or a value referenced by a Lisp symbol as 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. The symbol is interned with read-from-string.

      Parameters:
        `x` - A `String` value that will be passed to read-from-string to create the symbol. The string may contain a package prefix as well as a symbol name.
        `pk` - A `String` value that specifies the Lisp package context for read-from-string.
        `action` -
        - 0 denotes a symbol reference
        - 1 denotes the symbol-value of the symbol
        - 2 denotes the symbol-function of the symbol
        - 3 denotes find-class of the symbol
      Returns:
        The number of arguments collected up to this point. If the pk argument is the empty string, the current package is used. If the pk argument is the string ":", the keyword package is used. Otherwise, the string specifies a package name. The package name is interned with read-from-string to avoid case-mode issues. If the entire string is not consumed to create the symbol a Lisp error is signaled. Special characters must be escaped with the Lisp escape character.

    - #### call

          public int call()
                   throws JLinkerLispThrow,
                          JLinkerInvokeException,
                          JLinkerLispException,
                          JLinkerPortException

      Call a function in Lisp.
      Returns:
        The returned value depends on the call style.
      Throws:
        `JLinkerLispException` - if an error is detected during the call.
        `JLinkerInvokeException` - if an error interrupts the normal sequence of events. After this exception, the connection must be re-established before it can be used again.
        `JLinkerLispThrow` - if the Lisp function call was terminated with a throw.
        `JLinkerPortException` - if a port to Lisp was not available within the default port timeout interval.
        `java.lang.IllegalStateException` - if a previous call is not complete.

    - #### callOneWay

          public int callOneWay()
                         throws JLinkerLispThrow,
                                JLinkerInvokeException,
                                JLinkerLispException,
                                JLinkerPortException

      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.
      Throws:
        `JLinkerLispException`
        `JLinkerInvokeException`
        `JLinkerLispThrow`
        `JLinkerPortException`

    - #### callIgnore

          public int callIgnore()
                         throws JLinkerLispThrow,
                                JLinkerInvokeException,
                                JLinkerLispException,
                                JLinkerPortException

      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.
      Throws:
        `JLinkerLispException`
        `JLinkerInvokeException`
        `JLinkerLispThrow`
        `JLinkerPortException`

    - #### callRef

          public int callRef()
                      throws JLinkerLispThrow,
                             JLinkerInvokeException,
                             JLinkerLispException,
                             JLinkerPortException

      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:
        `JLinkerLispException` - if there was some error in the call.
        `JLinkerInvokeException`
        `JLinkerLispThrow`
        `JLinkerPortException`

    - #### callCopy

          public int callCopy()
                       throws JLinkerLispThrow,
                              JLinkerInvokeException,
                              JLinkerLispException,
                              JLinkerPortException

      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:
        `JLinkerLispException` - if there was some error in the call.
        `JLinkerInvokeException`
        `JLinkerLispThrow`
        `JLinkerPortException`

    - #### callAsyncBr

          public int callAsyncBr()
                          throws JLinkerLispThrow,
                                 JLinkerInvokeException,
                                 JLinkerLispException,
                                 JLinkerPortException

      Call a function in Lisp after setting the style to STYLE_ASYNC.
      Returns:
        The returned value is always 1.
      Throws:
        `JLinkerLispException` - if there was some error in the call.
        `JLinkerInvokeException`
        `JLinkerLispThrow`
        `JLinkerPortException`

    - #### callAsyncGo

          public int callAsyncGo()
                          throws JLinkerLispThrow,
                                 JLinkerInvokeException,
                                 JLinkerLispException,
                                 JLinkerPortException

      Call a function in Lisp after setting the style to STYLE_ASYNC_GO.
      Returns:
        The returned value is always 1.
      Throws:
        `JLinkerLispException` - if there was some error in the call.
        `JLinkerInvokeException`
        `JLinkerLispThrow`
        `JLinkerPortException`

    - #### getValue

          public java.lang.Object getValue()

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

    - #### getValue

          public java.lang.Object getValue(int i)

      Get the i-th raw value returned by a call to Lisp. <[p> If the retention strategy is false, the value is discarded after it is retrieved.
      Parameters:
        `i` - The index of the desired value.
      Returns:
        A weapper 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.

    - #### identity

          public static java.lang.Object identity(java.lang.Object arg)

      Returns the argument (or an equivalent object).

      One use for this method is to dereference Java values that were passed to Lisp by reference but can be automatically copied by the interface.

      For example, `(jnew-array "java.lang.String" 17)` returns a remote reference to a Java array. To obtain a copy of the contents of the array, the Lisp code can call

                (jstatic "identity" "com.franz.jlinker.LispCall" ref [:copy])

      The `:copy` argument is optional since the default is to copy string arrays.
      Parameters:
        `arg` -
      Returns:

    - #### typeOf

          public int typeOf()

      Deprecated. use `getTypeCode()`
      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)

      Deprecated. use `getTypeCode(int)`
      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.

    - #### getTypeCode

          public JLWrapper.TypeCode getTypeCode()

      Query the type of the first or only value returned from Lisp.
      Returns:
        The TypeCode constant that describes the type.

    - #### getTypeCode

          public JLWrapper.TypeCode getTypeCode(int i)

      Query the type of the i-th value returned from Lisp.
      Parameters:
        `i` - The index of the value queried.
      Returns:
        The TypeCode constant that describes the type.

    - #### intValue

          public int intValue()

      Get the first or only value returned from Lisp when it is expected to be of type int.
      Returns:
        The int value.
      Throws:
        `java.lang.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:
        `java.lang.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 when it is expected to be of type long.
      Parameters:
        `i` - The index of the desired value.
      Returns:
        The long value.
      Throws:
        `java.lang.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 double float value returned from Lisp.

    - #### doubleValue

          public double doubleValue(int i)

      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:
        `java.lang.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 boolean value returned from Lisp.

    - #### booleanValue

          public boolean booleanValue(int i)

      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:
        `java.lang.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 String value returned from Lisp.

    - #### stringValue

          public java.lang.String stringValue(int i)

      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:
        `java.lang.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 int[] value returned from Lisp.

    - #### intArrayValue

          public int[] intArrayValue(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:
        `java.lang.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 String[] value returned from Lisp.

    - #### stringArrayValue

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

      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:
        `java.lang.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 double[] value returned from Lisp.

    - #### doubleArrayValue

          public double[] doubleArrayValue(int i)

      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:
        `java.lang.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 Object value returned from Lisp.

    - #### objectValue

          public java.lang.Object objectValue(int i)

      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:
        `java.lang.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 the Lisp symbol returned as the first or only value of a call.
      Returns:
        A string containing the symbol-name of the symbol.
      Throws:
        `java.lang.UnsupportedOperationException` - when the returned value is not a Lisp symbol.

    - #### symbolName

          public java.lang.String symbolName(int i)

      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:
        `java.lang.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 returned as the first or only value of a call.
      Returns:
        A string containing the package-name of the package of the symbol.
      Throws:
        `java.lang.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 returned as the i-th value of a call.
      Returns:
        A string containing the package-name of the package of the symbol.
      Throws:
        `java.lang.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.

        The following results will be returned if the call was a synchronous call, or if an asynchronous call has completed and the results have been fetched to Java:

        - If the value is zero or positive, the Call to Lisp is completed and results are available in Java. The value is the number of values returned from Lisp. If the synchronous call ended by throwing JLinkerLispException, the value returned by query() will be 3; see the two argument form of query() for details.
        - A negative value of -100 indicates that the call has not yet been made, or a synchronous call is still in progress.
        - A negative value of -99 indicates that the call was terminated by a throw or some error, and no additional information is available.

        The remaining values will only be seen if the style is set to STYLE_ASYNC and the call is still in progress. In these cases, additional information can be obtained by calling query(true,true).

        - A negative value from -1 to -10 indicates that the call is still in progress.
        - A negative value of -11 indicates that the call is done but the the values have not been retrieved.
        - A negative value of -98 indicates that the call was terminated by an error in Lisp but the error information has not been retrieved.

    - #### query

          public int query(boolean doquery,
                           boolean dofetch)
                    throws JLinkerLispThrow,
                           JLinkerInvokeException,
                           JLinkerLispException

      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 a STYLE_ASYNC call has finally completed, fetch the Lisp values.

      Parameters:
        `doquery` - When this argument is true, call Lisp to fetch a more detailed description of the state of the STYLE_ASYNC call. Once a call instance is identified as completed, this argument does not trigger a call to Lisp.
        `dofetch` - When this argument is true, and an STYLE_ASYNC call is complete in Lisp, fetch the values of the call. Once the results are fetched, this argument does not trigger a call to Lisp.
      Returns:
        An integer describing the result.

        The following results will be returned if the call was a synchronous call, or if the asynchronous call has completed and the results have been fetched to Java:

        - If the value is zero or positive, it is the number of values returned from Lisp.

          If the Lisp call was terminated by an error in Lisp, the result will be 3 and the 3 results in Java are the integer -98, a string containing a description of the Lisp error, and a remote reference to the Lisp error object.

        - A negative value of -100 indicates that the call has not yet been made, or a synchronous call is still in progress.
        - A negative value of -99 indicates that the call was terminated by a throw or some error, and no additional information is available.

        The following values will be returned by query(true, false) if the style was set to STYLE_ASYNC and the call is still in progress. In these cases, additional information can be obtained by calling query(true,true).

        - A negative value from -1 to -10 indicates that the call is still in progress.
        - A non-negative value indicates that the call is completed in Lisp; the value is the number of values generated in Lisp. These values must still be retrieved into Java.
        - A negative value of -11 indicates that the call is done but the the values have not been retrieved. This result will be seen only when query(false, false) is called after query(true, false) has returned -98 or a non-negative value.
        - A negative value of -97 indicates that an exception was thrown while fetching the call status from Lisp. It was most likely caused by a connection problem. The filed queryError may contain additional information.
        - A negative value of -98 indicates that the call was terminated by an error in Lisp but the error information has not been retrieved.
        - A negative value of -99 indicates that the call was terminated by a Lisp throw and no additional information is available.

        To monitor the completion of an asynchronous call:

                 Call query(true, false) repeatedly
                      if the result is non-negative, the call is completed
                         call query(true, true) to fetch the results
                      if the result is -98, the call was terminated
                         call query(true, true) to fetch the error information
                      if the result is -99, the call was terminated
                         there is no additional information to fetch
                      otherwise, the call is still in progress

      Throws:
        `JLinkerLispException` - If an error occurs when fetching the the state or results of a STYLE_ASYNC call.
        `JLinkerInvokeException`
        `JLinkerLispThrow`

    - #### queryAsyncName

          public java.lang.String queryAsyncName()
                                          throws JLinkerLispThrow,
                                                 JLinkerInvokeException,
                                                 JLinkerLispException

      Query the name of the Lisp process where the call is run.

      This value may be of interest in an application that may need to terminate a LispCall in STYLE_ASYNC. The name can be used to interrupt or terminate the Lisp thread by using the Lisp functions `process-name-to-process`, `process-interrupt`, or `process-kill`.

      Returns:
        The string name of a Lisp process (thread).
      Throws:
        `JLinkerLispException`
        `JLinkerInvokeException`
        `JLinkerLispThrow`

    - #### 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.

      Note that if a STYLE_ASYNC operation is in progress in Lisp, it continues but any state or result will no longer be available in Java.

    - #### 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.
      Note that if a STYLE_ASYNC operation is in progress in Lisp, it continues but any state or result will no longer be available in Java.
      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 and is not ready for another call.

    - #### setArg

          public void setArg(int i,
                             boolean arg)

      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 with an int value.

    - #### setArg

          public void setArg(int i,
                             long arg)

      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 with a double value.

    - #### setArg

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

      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 with a reference to a Java Object or a pre-wrapped Java or Lisp object.

    - #### setArg

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

      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 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 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 with a reference to a Lisp symbol.

      The symbol is interned with read-from-string.

      If the entire string is not consumed to create the symbol a Lisp error is signaled. Special characters must be escaped with the Lisp escape character

      Parameters:
        `i` - The index of the modified argument.
        `name` - A `String` value that will be passed to read-from-string to create the symbol. The string may contain a package prefix as well as a symbol name.

    - #### setSymbol

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

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

      The symbol is interned with read-from-string.

      If the pkg argument is the empty string, the current package is used. If the pkg argument is the string ":", the keyword package is used. Otherwise, the string specifies a package name. The package name is interned with read-from-string to avoid case-mode issues.

      If the entire string is not consumed to create the symbol a Lisp error is signaled. Special characters must be escaped with the Lisp escape character.

      Parameters:
        `i` - The index of the modified argument.
        `name` - A `String` value that will be passed to read-from-string to create the symbol. The string may contain a package prefix as well as a symbol name.
        `pkg` - A `String` value that specifies the Lisp package context for read-from-string.

    - #### setSymbol

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

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

      The symbol is interned with read-from-string.

      Parameters:
        `i` - The index of the modified argument.
        `name` - A `String` value that will be passed to read-from-string to create the symbol. The string may contain a package prefix as well as a symbol name.
        `pkg` - A `String` value that specifies the Lisp package context for read-from-string.
        `action` -
        - 0 denotes a symbol reference
        - 1 denotes the symbol-value of the symbol
        - 2 denotes the symbol-function of the symbol
        - 3 denotes find-class of the symbol

    - #### mayCall

          public int mayCall()

      Query if it is allowed to call Lisp in this thread.

      Some Lisp implementations allow callback only in the thread in which the Lisp application called Java in the first place.

      Returns:
        an integer that describes the situation
        - 0 - cannot call yet, interface is not fully initialized
        - -1 - cannot call from this thread, ever
        - +1 - may call from this thread, but not from any other
        - +2 - may call from this or any other thread
        These restrictions apply only in Native mode. In socket mode, there are no thread restrictions, and the result is always +2.

    - #### dispatchEvent

          public static int dispatchEvent(java.lang.String ev,
                                          java.lang.Object target,
                                          java.lang.String[] s,
                                          int[] l,
                                          int timeout)

      Dispatch an event to the Lisp handler.
      Parameters:
        `ev` - is a String that names the event. This is the name that was used in the call to register-handler on the Lisp side.
        `target` - is the Object instance associated with the event when it was registered
        `s` - is an array of String data associated with the event.
        `l` - is an array of int data associated with the event.
        `timeout` - The number of milliseconds to wait for an available port. If zero, make the call only if a port is available immediately. If negative, wait indefinitely.
      Returns:
        Zero in the native implementation. Return a sequence number in the socket implementation, or -1 if a port to Lisp could not be obtained in the time specified.

    - #### dispatchEvent

          public static int dispatchEvent(java.lang.String ev,
                                          java.lang.Object target,
                                          java.lang.String[] s,
                                          int[] l)

      Dispatch an event to the Lisp handler.
      Parameters:
        `ev` - is a String that names the event. This is the name that was used in the call to register-handler on the Lisp side.
        `target` - is the Object instance associated with the event when it was registered
        `s` - is an array of String data associated with the event.
        `l` - is an array of int data associated with the event.
      Returns:
        Zero in the native implementation. Return a sequence number in the socket implementation, or -1 if a port to Lisp could not be obtained in the time specified by defaultPortTimeout.

    - #### connect

          public static boolean connect(java.lang.String host,
                                        int port,
                                        int pollInterval,
                                        int pollCount)

      Connect to a Lisp server at a known host and port.
      Parameters:
        `host` - The name of the host, "" denotes the loopback host.
        `port` - The port number.
        `pollInterval` - A polling interval in milliseconds. If the value is negative, use the value of defaultPollInterval.
        `pollCount` - The number of times to try. If the value is negative, use the value of defaultPollCount.
      Returns:
        true if a connection was made. If the connection attempt failed, return false. An Object instance describing the failure may be available in the field connectError.

    - #### connect

          public static boolean connect(java.lang.String com,
                                        int pollInterval,
                                        int pollCount)

      Connect to a Lisp server when the host and port are published in a file.
      Parameters:
        `com` - The pathname to the host and port file.
        `pollInterval` - A polling interval in milliseconds. If the value is negative, use the value of defaultPollInterval.
        `pollCount` - The number of times to try. If the value is negative, use the value of defaultPollCount.
      Returns:
        true if a connection was made. If the connection attempt failed, return false. An Object instance describing the failure may be available in the field connectError.

    - #### advertise

          public static boolean advertise(int port,
                                          int timeoutSeconds)

      Allow a Lisp server to connect to the Java application.
      Parameters:
        `port` - The port number where Java will listen.
        `timeoutSeconds` - Listen for this many seconds.
      Returns:
        true if a connection was made.

        If the connection attempt failed, return false. An Object instance describing the failure may be available in the field connectError.

    - #### advertise

          public static boolean advertise(java.lang.String l2j,
                                          java.lang.String host,
                                          int port,
                                          int timeoutSeconds)

      Advertise the Java host and port in a file.
      Parameters:
        `l2j` - The pathname to a file.
        `host` - The host name where Lisp should connect.
        `port` - The port number where Lisp should connect. If zero, a system assigned port will be used.
        `timeoutSeconds` - Listen for this many seconds.
      Returns:
        true if a connection was made. If the connection attempt failed, return false. An Object instance describing the failure may be available in the field connectError.

    - #### disconnect

          public static void disconnect()

      End the connection to a Lisp server.

    - #### discardInLisp

          public static long discardInLisp(java.lang.Object... x)

      Discard remote references to Lisp objects. Remote references to Lisp objects in Java cause the Lisp objects to remain live in Lisp as long as the Jlinker connection remains active. If storage must be freed in Lisp, obsolete references should be discarded.

      When a remote reference to a Lisp object is abandonned in Java, the finalization for the wrapper instance makes a note of it. When enough dead references are collected (as specified by discardBatchSize), Lisp is notified.

      If this method is called with a single integer argument, the argument is treated as a temporary batch size and Lisp is notified immediately if this size is exceeded at the moment. Thus calling discardInLisp(0) clears the current list of dead references.

      Parameters:
        `x` - A wrapper instance. If the wrapper is not a Lisp reference, it is ignored.
      Returns:
        The number of known dead references left after the call.