jlinker-init

Arguments: &optional mode &key port host file local-dist timeout java-args preload debug verbose error-p library java-home classpath jar report end-function poll-count poll-interval connection-pool preserve-client-calls jave-out

There are significant changes to jLinker in 9.0. Further, a patch released in May, 2013 added the end-function and another released in late July, 2013, upgraded jlinker to version 7.1 and added the new keyword arguments connection-pool, preserve-client-calls, and java-out. This page assume you are using version 7.1 and have all jlinker patches loaded. See jlinker.htm for more information on the july 2013 patch and version 7.1.

The differences between jlinker in 9.0 as originally released and the version in 8.2 include the following. The lisp-host, lisp-port, lisp-file, java-host, java-port, and java-file keyword arguments are replaced by host, port, and file keyword arguments. For backward compatibility, the old arguments are accepted but some are ignored depending on the mode. Now only one host, port, and file is used for communicating between Lisp and Java. If old and new arguments are both present, the old arguments are ignored and a warning is signalled. See jlinker.htm for more information on the patch.

Each call to jlinker-init establishes one connection between Lisp and and Java. In socket mode, one Lisp image can connect to multiple Java VMs. In that case, the connections must be isolated in separate bindings of *jlinker-connection* (the function jlinker-listen manages this separation automatically).

Starting in Version 7.1, there are no restrictions on the number of Java connection attempts or on the order in which connection attempts are made from Java VMs running with a Version 7.1 jar file. When only one call to jlinker-init is in effect, exactly one Java connection will succeed, any others will be either refused or rejected with a timeout.

Jlinker versions before 7.1 are not designed to handle competing simultaneous attempts to connect from several Java VMs - in such a situation all or all but one attempt will fail with unpredictable behavior. Java applications can serialize access using java.nio.channels.FileChannel.tryLock() in some situations; Franz support can supply sample Java code that does this (contact [email protected]).

In mixed version situations, the older version behavior will prevail.

This function initializes a connection between Lisp and Java. The argument list supplied is combined with the value of *jlinker-init* in order to form the actual initialization arguments. Supplied arguments override any items in the value of *jlinker-init*.

The mode argument

The optional mode argument may be one of the following keywords (keywords in a single bullet are synonyms).

• :start or :start-java (the default)
• :lisp-advertises
• :java-advertises
• :native or :jni

The mode argument specifies the way in which Lisp and Java will communicate. If the mode is not specified or is nil, the default :start-java mode is used. You must specify a mode if you wish to supply values for any keyword argument.

When mode is :start (or the synonym :start-java), the Lisp process starts a new Java VM in a separate operating system process. See here below for more details.

When mode is :lisp-advertises, the Lisp process waits for a separate Java application to make contact. See here below for more details.

When mode is :java-advertises, the Lisp process attempts to connect to a separate Java process. See here below for more details.

In all the above cases, the Lisp and Java parts of the application reside in separate address spaces, and communication takes place through sockets.

When mode is :native (or the synonym :jni), the Java VM is loaded into the address space of the Lisp process. The Lisp and Java parts of the application share one address space and one operating system process. Communication takes place through foreign calls. See here below for more details.

At the application level, there is no difference between the socket (all except :native/:jni) and foreign call (:native/:jni) modes. The mode selection only affects how the interface is initialized.

jlinker-init return value

If jlinker is not initialized and the call to jlinker-init succeeds, the return value is the keyword :jlinker-init.

If jlinker is not initialized and the call to jlinker-init, the result (returning a value or signaling an error) depends on the error-p argument, as describes in the discussion of arguments below.

It is not an error to call jlinker-init when jlinker is already initialized. In that case the function ignores any arguments supplied and simply returns a keyword indicating the type of connection, based on the mode in which it was started:

• if the socket implementation is running (jlinker was started with mode is anything other than :native or :jni), then the return value is :socket.
• if the native implementation is running (jlinker was started with mode is :native or :jni), then the return value is :native.

jlinker-init keyword arguments

The meaning of many keyword arguments to jlinker-init is determined by the mode but the following keyword arguments have a common meaning:

The classpath and jar keyword arguments

Logical pathnames may be specified as values in place of regular pathnames. If either argument is specified, then the Java classpath value is the concatenation of the following three values:

1. The classpath argument: A string is used verbatim; A list (of strings) is concatenated into a string where the list elements are separated by the classpath separator; nil or no value specified means use the string ".".
2. The current value of the CLASSPATH environment variable.
3. The resolved jar file path. This file must be visible to the Java VM for the correct operation of the jlinker interface.

If a jar argument was specified, it is used as the resolved jar file path. Otherwise a default resolved jar file path is determined in 2 steps:

1. If a file "jlinker.jar" exists in the current directory, it is the default.
2. If the file with logical pathname "sys:jlinker;jlinker.jar" exists, it is the default.

If the value of jar is specified to be nil, then we assume that the jlinker.jar file is visible to the Java VM for reasons outside our control; for example, it may have been installed in the Java library directory along with the built-in Java libraries. In this case, the resolved jar file path is the empty string.

If neither jar nor classpath are given values, then the behavior is compatible with older versions of jlinker - the behavior is determined entirely by the value of the *jlinker-java-home* variable. Jlinker adds "." and "jlinker.jar" to the classpath on the assumption that the jlinker.jar file is in the current directory.

Mode :start-java

When mode is :start-java (or the synonym :start), the Lisp process starts a new Java VM in a separate operating system process.

The arguments java-home, classpath, jar, java-args, and debug determine how the Java VM is started from the Lisp process.

The port argument may be specified if the default is not sufficient (you may also use the obsolete lisp-port argument but you may not use the obsolete java-port argument). The arguments library, load, and file are ignored. The argument host should not be specified.

The debug argument: on Microsoft Windows, the debug argument also determines the Java executable. If debug is nil, we use the executable "javaw.exe"; if debug is non-nil, we use the executable "java.exe" which opens a console window where Java output may be seen.

The java-args argument: the value should be a list of string arguments passed to Java.These are added after the ones passed by jLinker. If the first item in this list is a sub-list starting with the keyword :options, then the remainder of the sub-list is passed to Java in front of any options passed by jLinker.

When jlinker starts the JVM, a command string is composed with a class name and some arguments to the jlinker startup class. An application can pass additional arguments by listing them in the java-args argument. Arguments to the JVM must be inserted before the class name in the command string. If the first item in the java-args list is itself a list beginning with :options, then the items following :options are inserted as JVM arguments. For example, to specify a large memory for the JVM, use the argument

     :java-args '((:options "-Xmx2048m"))

Mode :lisp-advertises

When mode is :lisp-advertises, the Lisp process waits for a separate Java application to make contact. The Java application uses static methods in the LispCall class to make the connection.

The file argument (you may also use the obsolete lisp-file argument): this argument specifies a file in which Lisp advertises the host and port where Java must connect. The default is "JavaToLisp.trp". If this argument is nil, Lisp simply listens at the specified port and does not advertise in a file. In that case it is necessary to specify port as a non-zero value.

The host argument (you may also use the obsolete lisp-host argument): this argument is used when the file specified by the file argument is written. The Java application needs to know the lisp-host value if it is running on a different host. The default value is "localhost".

The timeout argument: if non-nil, this argument specifies the number of seconds Lisp will wait for a connection from Java. If the timeout is a negative number -v, signal a continuable error after v seconds. If continued, wait another v seconds.

Mode :java-advertises

When mode is :java-advertises, the Lisp process attempts to connect to a separate Java process. The Java application uses static methods in the LispCall class to make the connection.

The file argument (you may also use the obsolete java-file argument): this argument specifies a file in which Java advertises the host and port where Lisp must connect. The default is "LispToJava.trp". If this argument is nil, Java is assumed to listen at the specified port and does not advertise in a file.

The host argument (you may also use the obsolete java-host argument): this argument must specifiy the host where Java is advertising when file is nil. The default value is "localhost".

The port argument (you may also use the obsolete java-port argument): this argument must specifiy the port where Java is advertising when file is nil. When file is nil, this argument must be specified as positive number greater than zero.

Lisp will attempt to connect poll-count times, with poll-interval seconds between attempts.

Mode :native

When mode is :native (or the synonym :jni), the Java VM is loaded into the address space of the Lisp process. The Lisp and Java parts of the application share one address space and one operating system process. Calls between Lisp and Java are equivalent to foreign library calls and data is transmitted in registers or in memory-to-memory copies.

The arguments java-home, library, classpath, jar, java-args, and debug determine how the Java VM is started from the Lisp process.

The port, file, host, and timeout arguments are ignored.

The library argument: this argument specifies the pathname of the shared library where the Java VM is implemented. The default value is taken from the special variable *jni-library*. On MS Windows, the initial value is :find to specify that the Windows Registry should be searched for the location of the Java Library. Otherwise, the value must be a path string. A relative path is merged with the value of the java-home argument.

The java-args argument: this argument may be a list of strings that specify additional arguments passed to the Java VM. Some of these are described in the Java documentation and in the file Xusage.txt in the Java runtime.

For example, the argument "-Xmx256m" specifies 256 megabytes for the Java heap while the argument "-Dfoo=bar" specifes the value "bar" for the Java System.property.

The load argument: this argument forces a re-load of the Java shared library.

If a Lisp image is saved with dumplisp while a jlinker native connections is running, the saved image must re-initialize the Lisp-Java connection when the saved image is re-started. This is done by calling

(jlinker-init :native :load t :library "xxx" ...)

The library argument must be specified in this case.

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

Copyright (c) 1998-2019, Franz Inc. Oakland, CA., USA. All rights reserved.
This page was not revised from the 8.2 page.
Created 2012.5.30.