FunctionPackage: net.jlinkerToCDocOverviewCGDocRelNotesFAQIndexPermutedIndex
Allegro CL version 9.0
Unrevised from 8.2 to 9.0.
8.2 version

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 support@franz.com).

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

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:

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:

Keyword argument Default value Comment
:error-p The value of *jlinker-error-p*. Note starting in version 8.0, the initial value of *jlinker-error-p* is t. In earlier releases the initial value was nil. When this argument is non-nil, errors detected by jlinker-init are signaled as Lisp errors. When this argument is nil, jlinker-init does not signal errors; if errors are detected, the value returned is a list of tokens that describe the error; if the operation succeeds, the value is the symbol :jlinker-init.
:verbose nil When this argument is non-nil, jlinker prints progress messages. The content of the messages depends on the mode argument.
:debug The default is the value of *jlinker-debug*. If this argument is non-nil, the Java VM prints progress and status messages to the java.lang.System.out stream.
:java-home The default is taken from the special variable *jlinker-java-home*. This argument specifies the directory where the Java executable may be found. Jlinker looks in the bin/ sub-directory for a Java executable. If the value is nil, then we assume that the Java executable will be found by the operating system if it is simply mentioned by name (ie, on Unix systems, it may be found on the default PATH). Otherwise, the value must be a suitable directory. If the value is :find (MS Windows only), the Windows registry is examined to find the Java location.
:classpath and :jar nil (for both) These arguments specify how the Java classpath should be modified (in those cases where a modification is relevant). See below for more information.
:port If unspecified, the system asks the OS to assign a port number, and this default is normally sufficient. This argument specifies the socket port used to communicate between Lisp and Java. The default is to ask the OS to assign a port number, and this default is normally sufficient. If a value is specified, it must be a positive number greater than zero, and the given port number must be available.

In earlier releases, two ports were used, one for Lisp and one for Java, and they were specified with arguments lisp-port and java-port. Now only one port is used. For backward compatibility, when mode is :start or :lisp-advertises the lisp-port argument is used and the java-port argument is ignored; when mode is :java-advertises, the java-port argument is used and the lisp-port argument is ignored.

Starting with Version 7.1, multiple jlinker-init invocations can listen at the same port number. This is the default behavior if port is specified as nil, zero, or a positive number. If it is necessary for several calls to jlinker-init to listen at different OS-assigned port numbers, the port argument should be specified as :new.

:local-dist The default value is "Lisp". This argument specifies an alternate label for the Lisp server in a jlinker connection. If multiple copies of jlinker are running in the same image, this may help in some debugging situations.
:preload nil This argument specifies a file that is loaded during the initalization of a socket connection. The file is generated by a call of the form (jlookup :gen-preload [filename]) (see jlookup).
:report nil This argument is in effect in modes :start-java and :lisp-advertises. If specified, this argument must be a function of one argument. The function is called as soon as a listening socket is created. The argument is the port number of the listening socket.
:end-function nil If non-nil, should be a functions object or function name. This function will be called when a jlinker connection is terminated. The function gets a single argument, the jlinker connection instance. The argument was implemented but un-documented in earlier current versions. The earlier implementations allowed the function to be called more than once but no longer.
:poll-count 3 When mode is :java-advertises, this argument specifies how many times Lisp will attempt to connect.
:poll-interval 5 When mode is :java-advertises, this argument specifies how many seconds Lisp will wait between connection attempts.
:connection-pool *jlinker-default-connection-pool* This argument specifies the connection pool parameters. When nil, no connection pool is created and jlinker functions as in earlier versions with one port from Lisp to Java and one from Java to Lisp. When the value is :delay, the connection pool will be created later when jstart-connection-pool is called. Other non-nil values specify the connection pool parameters. See the description of *jlinker-default-connection-pool* for more information.
:preserve-client-calls nil This argument specifies what happens to calls from Java in progress when jlinker-end is called. A value of nil specifies the behavior of earlier versions of jlinker. Any running synchronous client calls are killed. A positive number specifies the number of seconds to allow after jlinker-end exits. When the time runs out, the processes are killed. Any other non-nil value allows the client calls to run to completion.
nil nil This argument can be used to assist in diagnosing some Java problems. When debug is non-nil, this argument can be a string that is used to make two file names of the form javaout.log and javaoute.log. The standard output and error output from the Java VM is collected in these files, and printed to the Lisp console when jlinker-end is run.

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-2012, Franz Inc. Oakland, CA., USA. All rights reserved.
Documentation for Allegro CL version 9.0. This page was not revised from the 8.2 page.
Created 2012.5.30.

ToCDocOverviewCGDocRelNotesFAQIndexPermutedIndex
Allegro CL version 9.0
Unrevised from 8.2 to 9.0.
8.2 version