|
Allegro CL version 11.0 | ||||||||
Function, net.jlinker package
Arguments: name &rest classes
This function defines a named set of Java classes. The names are used in the classes argument to scan-java-api.
The following are predefined Names and their associated classes:
:java-data
"java.lang.Character" "java.lang.Boolean" "java.lang.Byte"
"java.lang.Short" "java.lang.Integer" "java.lang.Long"
"java.lang.Float" "java.lang.Number" "java.lang.Double"
"java.lang.String" "java.lang.StringBuffer"
:java-meta
"java.lang.Class" "java.lang.Thread" "java.lang.System"
"java.lang.Math" "java.lang.Throwable" "java.lang.Exception"
:jlinker-gui
"com.franz.jlinker.JLActionListener" "com.franz.jlinker.JLItemListener"
"com.franz.jlinker.JLKeyAdapter" "com.franz.jlinker.JLMouseAdapter"
"com.franz.jlinker.JLMouseMotionAdapter" "com.franz.jlinker.JLWindowAdapter"
"com.franz.jlinker.JLComponentAdapter"
:jlinker-call "com.franz.jlinker.LispCall"See jlinker.html for more information on the jLinker facility.
Macro, net.jlinker package
Arguments: name supers statics fields slots &rest options
This macro defines a Lisp class that represents a Java class. Once a Lisp class is defined to represent a Java class, remote references to instances of the Java class will be instances of the corresponding Lisp class. As a result, Lisp methods may be defined.
If the name is a string or symbol, it is the name of the Java class and the corresponding symbol is the name of the Lisp class. If the name is a list, the first element is a symbol for the name of the Lisp class and the second element is a string or symbol that identifies a Java class. The name may also be a list of three or more elements; in this case, the first element is the name of the Lisp class, the second element is the name of the base Java class or interface, and the remaining elements are the names of derived Java classes. The derived Java classes must all inherit from the base Java class or interface. Any instances of the derived or base Java classes will be mapped to the Lisp class.
The second argument is a list of Lisp superclasses. This list will be augmented by adding the class net.jlinker::java-class at the end.
The third and fourth arguments are lists of static and class fields in the Java class. Each item is of the form
(name [:accessor aname] [:reader rname] [:writer wname])where name is again like the class name - a single string or symbol or a list of two. If the accessor, reader and writer components are omitted, the Lisp name of the field is defined as an accessor to the Java field. If any of the accessor, reader and writer components are specified, then those are the only accessors defined for the field.
The fifth argument is additional Lisp slots that are added to the class with no inspection of any kind. The final optional arguments are appended to the class definition.
(def-java-class (gcal "java.util.GregorianCalendar") ()
(((gcal-friday "FRIDAY") :reader gcal-friday)
((gcal-ad "AD") :reader gcal-ad))
()
())This form defines a Lisp class gcal that will be used to represent any remote references to instances of the Java class java.util.GregorianCalendar. The Lisp functions gcal-friday and gcal-ad (both of zero arguments) are accessors for the static fields FRIDAY and AD in the Java class.
(defclass application-buffer () ((source :initform "Lisp")))
(def-java-class (string-buffer "java.lang.StringBuffer")
(application-buffer)
()
()
((source :initform "Java")))This form defines a Lisp class string-buffer that will be used to represent any remote references to instances of the Java class java.lang.StringBuffer. The slot named source does not exist in the Java object, but is present on every remote reference to a Java object of that class. This example also shows how a remote reference may inherit from other Lisp classes.
See jlinker.html for more information on the jLinker facility.
Macro, net.jlinker package
Arguments: lisp-name (lisp-class &rest argtypes)
This macro defines a Lisp function that calls a Java constructor. The first argument is the name of the new Lisp function. The second argument is an argument list where the first item is the Lisp name of a class previously defined with def-java-class.
The Lisp name is defined as a function of n arguments, where n is the number of argtypes specified. Each argtype is a string or symbol that denotes a Java class. The Lisp class must be defined to represent exactly one Java class. If the Lisp class was defined to represent more than one Java class, an error is signaled when the macro is expanded.
(def-java-class (string-buffer "java.lang.StringBuffer")
(application-buffer)
()
()
((source :initform "Java")))
(def-java-constructor new-string-buffer-int (string-buffer "int"))This form defines a Lisp function new-string-buffer-int that calls Java to create an instance of the Java class java.lang.StringBuffer, and returns a remote reference to the instance. The remote reference will be a Lisp instance of the class string-buffer.
The constructor is called as an ordinary Lisp function:
(new-string-buffer-int 17)is an example of such a call.
(def-java-constructor new-string-buffer-str
(string-buffer "java.lang.String"))This form defines another Lisp function (new-string-buffer-str that calls a different constructor of the java.lang.StringBuffer class. The Lisp function must have a different name because the constructors are ordinary functions, not generic functions, and thus cannot be overloaded in any way.
The constructor is also called as an ordinary Lisp function:
(new-string-buffer-str "abc")See jlinker.html for more information on the jLinker facility.
Macro, net.jlinker package
Arguments: name (lisp-class &rest argtypes) &optional retmod
This macro defines a Lisp method where the first argument is specialized on a class defined with def-java-class. The first argument determines the name of the Lisp function and of the corresponding Java method.
If the argument is a single symbol, it is used as the name of the Lisp method and the symbol-name is used as the name of the Java method.
If the first argument is a list, the first element in the list is a symbol, the name of the Lisp function, and the second element is a symbol or a string, the name of the Java method.
If symbols are used to name Java methods, the symbol-name is used without any case conversion. In modern mode, this is likely to be correct and useful, but in ANSI mode it will usually be in the wrong case unless escape characters are used as needed.
The first item in the second argument is the name of a class previously defined with def-java-class. The remaining items in the second argument are strings or symbols that denote Java classes.
If the third argument is specified, it is a call modifier that is appended to every call on the Java method. If the call has an explicit modifier, the modifier in this definition is ignored.
The defined Lisp method expects as its first argument an instance of the Lisp class. Only the first argument is used to dispatch the method, the remaining arguments are bound to an &rest argument. Therefore, if two Java methods with the same name and in the same class are defined with def-java-method, they must have distinct Lisp names.
(def-java-class (string-buffer "java.lang.StringBuffer")
(application-buffer)
()
()
((source :initform "Java")))
(def-java-method
(append-str "append")
(string-buffer "java.lang.String"))
(def-java-method
(append-chr "append")
(string-buffer "char")) The above forms define Lisp methods that call the corresponding Java methods. Although these are generic functions, they still must have distinct names because we only dispatch on the first (instance) argument. If another Java class has similarly named methods, lisp methods named append-str and append-chr could be defined for that class without causing any conflicts.
The Lisp methods are called with forms such as:
(setf x (new-string-buffer-int 17))
(append-str x "abc")
(append-chr x #\d)See jlinker.html for more information on the jLinker facility.
Macro, net.jlinker package
Arguments: name (lisp-class &rest argtypes) &optional retmod
Like def-java-method, but to call a static method.
The Lisp function defined has as many arguments as argtypes; there is no leading instance (dispatch) argument.
(def-java-class (strict-math "java.lang.StrictMath") () () () ())
(def-java-static (strict-abs "abs") (strict-math "int"))This form defines an ordinary Lisp function strict-abs that calls the static method abs in the Java class java.lang.StrictMath.
(strict-abs 17)See jlinker.html for more information on the jLinker facility.
Macro, net.jlinker package
Arguments: class-name (&key lisp-supers static-slots java-slots lisp-slots java-file if-exists verbose connector) &rest java-methods
Evaluate (require :jlinkent) to load this functionality.
This macro generates an output file with Java code that defines a Java class. This macro also generates Lisp code corresponding to the Java class. See examples/jlinker/javabean/bean1gen.cl.
The arguments are:
class-name: a symbol or a list:
name
(name name () :public)
(lisp-name java-name
(java-super java-interface ... )
java-flag ... )lisp-supers: (lisp-superclass ... )
static-slots: a symbol or a list:
name
((name name :type :int :flags (:public :static)))
(slot-name accessor ... )
java-slots: a symbol or a list:
name
((name name :type :int :flags (:public)))
(slot-name accessor ... )
slot-name:(lisp-name java-name JiL-slot-def... )
lisp-slots: (clos-slot-def ... )
java-file: path-string OR T OR :none
if-exists: :supersede OR :append OR nil
connector: a JiL expression to test connection to Lisp. Default: ("LispConnector.go" |false| |null|)
java-methods: java-method .... See below.
A java-method is either a lisp-and-java-name or a list with the following elements:
(method-name
([java-arg-type] ... )
[java-return-type [java-flag] ... [result-modifier]])The elements are:
(lisp-name java-name) or a lisp-and-java-name.:public | :static | :synchronized:copy | :ref | :oneway | :ignoreThis macro defines a Java method that calls the Lisp function. The Lisp function must be separately defined by the programmer.
When a method-name is specified as a list, the lisp-name should be a symbol and the java-name may be a symbol or a string. When method-name is specified as lisp-and-java-name, and lisp-and-java-name is a symbol, then the symbol-name string is used as the Java name. This is likely to be the correct Java name only in a Modern (case-sensitive) Allegro CL images (see case.html).
When lisp-and-java-name is a string, the Lisp symbol is taken to be the result of read-from-string from a string of the form "ppp::sss" where ppp is the name of the current package and sss is the name string.
When a def-java-to-lisp-wrapper form is compiled (or evaluated) we write Java code definitions in the specified files. These definitions create Java classes where each method calls the corresponding Lisp function or method
In the Lisp environment, we create a Lisp class with def-java-class to represent the Java class.
The Lisp functions or methods must be separately defined by the programmer. See the file examples/jlinker/javabean/bean1.cl.
See jlinker.html for more information on the jLinker facility.
Generic Function, net.jlinker package
Arguments: (self net.jlinker::servlet)
This method is called from the Java servlet destroy() method. The pre-defined primary method discards any locally cached information and any remote references.
Compatibility Note: In release 6.1, the Lisp symbol naming this method was net.jlinker:destroy. In 6.2, the name is net.jlinker:destroy-servlet. The symbol net.jlinker::destroy still exists (but is not exported) and names a function that calls net.jlinker:destroy-servlet. If an existing application needs to use the unqualified symbol, it may be exported (after loading module :jlinkent) with a form such as:
(eval-when (compile load eval)
(require :jlinker)
(require :jlinkent)
(defpackage :net.jlinker (:export #:destroy))
)This function is defined when the jlinkent module is loaded. See The jLinker Servlet API for details on the jLinker Servlet API.
See jlinker.html for more information on the jLinker facility.
Generic Function, net.jlinker package
Arguments: object
If the argument is a remote reference to a Java object, the reference is discarded.
The following methods are defined:
The argument must be a list of object references.
It is considerably more efficient to discard a block of objects in one operation.
Discard all dead references to Java objects.
Discard the specified number of dead references to Java objects.
Return two values, the number of dead entries and the number of live entries in the object cache.
Discard all objects in the object cache.
See jlinker.html for more information on the jLinker facility.
Generic Function, net.jlinker package
The name of this function has been changed to wrapped-object-p. Please see the description of that function for information. The name dist-object-p is still valid (for backward compatibility) but will be removed in a later release. Please convert code to use the new name.
Generic Function, net.jlinker package
Arguments: (self http-servlet) request response
Methods are defined on http-servlet instances. The default method simply prints a message and returns to Java. The user is free to implement any desired behavior in a method defined on a subclass.
This function is defined when the jlinkent module is loaded. See The jLinker Servlet API for details on the jLinker Servlet API.
See jlinker.html for more information on the jLinker facility.
Generic Function, net.jlinker package
Arguments: (self http-servlet) request response
Methods are defined on http-servlet instances. The default method simply prints a message and returns to Java. The user is free to implement any desired behavior in a method defined on a subclass.
This function is defined when the jlinkent module is loaded. See The jLinker Servlet API for details on the jLinker Servlet API.
See jlinker.html for more information on the jLinker facility.
Generic Function, net.jlinker package
Arguments: (self http-servlet) request response
Methods are defined on http-servlet instances. The default method simply prints a message and returns to Java. The user is free to implement any desired behavior in a method defined on a subclass.
This function is defined when the jlinkent module is loaded. See The jLinker Servlet API for details on the jLinker Servlet API.
See jlinker.html for more information on the jLinker facility.
Generic Function, net.jlinker package
Arguments: (self http-servlet) request response
Methods are defined on http-servlet instances. The default method simply prints a message and returns to Java. The user is free to implement any desired behavior in a method defined on a subclass.
This function is defined when the jlinkent module is loaded. See The jLinker Servlet API for details on the jLinker Servlet API.
See jlinker.html for more information on the jLinker facility.
Generic Function, net.jlinker package
Arguments: (self http-servlet) request response
Methods are defined on http-servlet instances. The default method simply prints a message and returns to Java. The user is free to implement any desired behavior in a method defined on a subclass.
This function is defined when the jlinkent module is loaded. See The jLinker Servlet API for details on the jLinker Servlet API.
See jlinker.html for more information on the jLinker facility.
Generic Function, net.jlinker package
Arguments: (self http-servlet) request response
Methods are defined on http-servlet instances. The default method simply prints a message and returns to Java. The user is free to implement any desired behavior in a method defined on a subclass.
This function is defined when the jlinkent module is loaded. See The jLinker Servlet API for details on the jLinker Servlet API.
See jlinker.html for more information on the jLinker facility.
Generic Function, net.jlinker package
Arguments: (self http-servlet) request response
Methods are defined on http-servlet instances. The default method simply prints a message and returns to Java. The user is free to implement any desired behavior in a method defined on a subclass.
This function is defined when the jlinkent module is loaded. See The jLinker Servlet API for details on the jLinker Servlet API.
See jlinker.html for more information on the jLinker facility.
Generic Function, net.jlinker package
Arguments: string &optional (eof-error-p t) eof-value &key (start 0) end (read-error-p t) read-error-expr read-error-value (eval-error-p t) eval-error-value
This function combines the effects of read-from-string and eval in one function call. It is provided to allow a Java application to specify fairly complex behavior in a single call from Java to Lisp with arguments that can be easily manufactured in Java code.
In the most common and simplest behavior, the s-expression in the string argument is read and evaluated, and the values are returned to the caller.
The arguments string, eof-error-p, eof-value, start, and end are passed to read-from-string to control how the reeading of the string is done. The default for eof-error-p is t.
If the call to read-from-string signals an error, then the behavior is determined by the read-error-p argument (which has a default value of t). If the read-error-p argument is non-nil, then the error signaled by read-from-string is propagated to the calling context. If the read-error-p argument is nil, then the read-error-expr argument is examined. If the argument is omitted, then the value of the eval-error-value argument is used as the result of the read-from-string operation. If the read-error-expr argument is a string, then read-from-string is called on this string and the result is used as the result of the original read-from-string operation. If the read-error-expr argument is supplied, and is not a string, then it is used as the result of the original read-from-string operation.
The result of the read-from-string operation is then evaluated and the values are returned to the caller. If an error is signaled during the evaluation, the behavior is controlled by the eval-error-p argument (the default is t). If the eval-error-p argument is non-nil, then the error signaled by eval is propagated to the calling context. If the eval-error-p argument is nil, then the eval-error-value is returned to the caller.
See jlinker.html for more information on the jLinker facility.
Function, net.jlinker package
Arguments: &optional new if-exists verbose
This is a helper function used in connection with def-java-to-lisp-wrapper to set the output stream used by the macro.
The new can be:
t: means send output to *standard-output*:none: means suppress outputThe if-exists argument is used only when new is a pathname designator. In that case, its values can be:
:supersede: means delete an existing file and create a new file:append: means add to an existing file or create a new fileIf the verbose argument is non-nil, emit a message when the output stream changes.
See jlinker.html for more information on the jLinker facility.
Function, net.jlinker package
Arguments: &optional new
This is a helper function used in connection with def-java-to-lisp-wrapper to determine the language in the generated output file.
The new can be:
:java: emit Java code in output file:jil: emit JiL code in output file:none: suppress output fileThis function always returns two values: the old value and the new setting.
See jlinker.html for more information on the jLinker facility.
Generic Function, net.jlinker package
Arguments: (self net.jlinker::servlet)
Returns the ServletConfig reference saved from the call to init().
This function is defined when the jlinkent module is loaded. See The jLinker Servlet API for details on the jLinker Servlet API.
See jlinker.html for more information on the jLinker facility.
Function, net.jlinker package
Arguments: (self net.jlinker::servlet)
Retrieve from Java a reference to the ServletInfo object.
This function is defined when the jlinkent module is loaded. See The jLinker Servlet API for details on the jLinker Servlet API.
See jlinker.html for more information on the jLinker facility.
Function, net.jlinker package
Arguments: &optional tag
This function invalidates all the runtime tables and structures created by loading a set of generated Java API definitions. The Lisp functions defined by loading generated code are still defined but will signal error if called. The API definitions must be evaluated again in order to be effective.
If the generated code is loaded more than once or if several different generated files are loaded into the same Lisp, the resulting tables and structures are an accumulation of all the definitions. This function resets all this data for a fresh start.
The tag argument can be used to synchronize the loading of several generated files when they are loaded independently or in multiple threads. If several calls with non-nil and #'equal tag arguments take place in a Lisp image, only the first one will reset the tables; the subsequent ones will be ignored and will return nil. Each tag value can only be used once. If it needs to be used again for a full reset, a different tag value must be used in between.
If dynamically dispatched calls take place while definitions are reset and loaded, the results are unpredictable.
This function returns an integer that increases with each call.
See jlinker.html for more information on the jLinker facility.
Function, net.jlinker package
Arguments: object &rest index-values
Extracts the specified array element. Note that if the list of index values has fewer entries than required by the rank of the array, the result is a reference to a Java array.
This function may be used in a setf form to store a value into a Java array (analogously with using aref and setf to store a value in a Lisp array).
See jlinker.html for more information on the jLinker facility.
Function, net.jlinker package
Arguments: object value &rest index-values
Use of this operator is deprecated. This operator will be removed in the next major release of Allegro CL.
A warning is signaled at compile time when this operator is encountered unless the variable *jlinker-deprecated-warnings* is set to nil.
Store the value in the specified array element. Use of this function is deprecated in favor of a setf form using jarray-ref.
See jlinker.html for more information on the jLinker facility.
Function, net.jlinker package
Arguments: object &optional modifier
With only one argument, this function is a predicate that returns nil if the object is not a remote reference to a Java array. When the result is true, the value is the rank of the array.
If the optional argument is the keyword :dim, the value returned is nil or a list of the dimensions of the array.
If the optional argument is an integer smaller than the rank of the array, then the value returned is the maximum index in the specified dimension.
See jlinker.html for more information on the jLinker facility.
Function, net.jlinker package
Arguments: method-ref instance &rest args
This is the general form for calling Java methods. If the arguments specify a unique Java method, then the specified method is called with the given arguments. If more than one matching method is found, a continuable error is signaled to allow an appropriate method to be selected.
If the first (method-ref) argument is a class method, the second (instance) argument must be a reference to an instance of an appropriate class. The (unique) specified method is called with the given arguments.
If the method-ref argument is the name of a method, the instance argument must be a reference to an instance of an appropriate class. The methods of the class are examined to find one or more methods with the given number of arguments. If the arguments specify a unique Java method, then the specified method is called with the given arguments. If more than one matching method is found, a continuable error is signaled to allow an appropriate method to be selected.
If the method-ref argument is a reference to a static method, the instance argument is ignored. The (unique) specified method is called with the given arguments.
The args rest argument is a list of argumnents to the Java method. The arguments are converted using the rules in the section Data Types and Conversions in jlinker.html. The last element in the list may be a result modifier; one of the following keywords that add advice about the value returned.
:copy: return a scalar value, or Lisp vector if at all possible.:ref: return a remote reference if that makes sense.:ignore: do not return anything at all.:one-way: do not return anything at all and do not even wait for the answer. (Note: :oneway is also accepted for backward compatibility, but :one-way is preferred.)If the Java code called from Lisp throws an exception, the exception is reflected in Lisp as a Lisp simple-error condition. The value of the slot excl::format-arguments is a list of the form
(string1 (string2 remote-ref-to-java-error))It does not make sense to throw on purpose (rather than because of an exception) in code called from Lisp since the Java code is executed in a thread dedicated to the handling of calls from Lisp. When the Java code is running, there is no context of interest outside of the called method. That is why all throws are caught by jLinker and returned back to Lisp.
The compiler macro associated with the function allows compile-time collection of java class names and method signatures. This information is used to generate a file of class and method definitions that may be loaded to initialize an application, and avoid the class and method lookup overhead in the body of the application (see jlookup).
See jlinker.html for more information on the jLinker facility.
Function, net.jlinker package
Arguments: name-class-ref
If the argument is a string or symbol, this function returns a reference to the Java class with that name. If the class lookup triggers a Java error, a Lisp error is signaled. When caching is enabled, a new class reference is added to a local cache hashtable. If the argument is a class reference, it is returned with no further processing.
The strings "int", "short", ... are used to denote the classes that represent primitive, non-reference, values in Java.
Strings of the form "[class-or-type" are used to denote classes that represent array types.
All other classes must be specified with a fully qualified class name.
There is also a compiler macro associated with this function. It allows compile-time collection of Java class names and method signatures. This information is used to generate a file of class and method definitions that may be loaded to initialize an application, and avoid the class and method lookup overhead in the body of the application (see jlookup).
See jlinker.html for more information on the jLinker facility.
Function, net.jlinker package
Arguments: class-ref &optional name
The first argument must be a class name or a class reference. If the second argument is omitted, the value is the name of the class. If the second argument is specified, this function is a predicate that tests for the specified class name.
See jlinker.html for more information on the jLinker facility.
Function, net.jlinker package
Arguments: x y
Return t if x and y are strings that name the same Java class. Periods or slashes are permitted between class name components.
See jlinker.html for more information on the jLinker facility.
Function, net.jlinker package
Arguments: object &optional name
This function returns the name of the Java class or verifies that a remote reference is to an instance of a specified class. This operation does not require a round-trip to Java.
The first argument should be a remote reference to a Java class instance. If the second argument is omitted, the value returned is a string that names the class of the Java object. If the second argument is specified, it must be coercible to a string; the value returned is the result of comparing the class name to the second argument.
If the first argument is a Lisp string, it is treated as an instance of the Java class "java.lang.String".
If the first argument is neither a string nor a remote reference, then the function returns nil.
A second value is always returned, the name of the class or nil.
In the following example (taken from the jLinker servlet sample)
(let (out println)
(setf out (jcall "getWriter" response))
(setf println (jmeth (jclass-of out) "println" "java.lang.String"))
...)we are retrieving the "println" method of some arbitrary Java class. This code will not work if the Java VM security profile does not allow access by name to the class of the object referenced by out.
The code below appears to work in these cases
(let (out println)
(setf out (jcall "getWriter" response))
(setf println (jmeth (jcall "getClass" out)
"println" "java.lang.String"))
...)because the method is retrieved from the class object itself.
See jlinker.html for more information on the jLinker facility.
Function, net.jlinker package
Arguments: pp
Return an alternating list of keys and values describing some useful class path value in the Java VM.
If the pp argument is non-nil, pretty-print the data on *standard-output* and return nil.
See jlinker.html for more information on the jLinker facility.
Function, net.jlinker package
Arguments: class-ref &rest arg-class-refs
This is a deprecated (maintained for now for backward compatibility) name of the function jconstructor. Please use jconstructor instead of jcons. See jconstructor for details.
A warning is signaled at compile time when this operator is encountered unless the variable *jlinker-deprecated-warnings* is set to nil.
See jlinker.html for more information on the jLinker facility.
Function, net.jlinker package
Arguments: class-ref &rest arg-class-refs
This function retrieves a remote reference to a Java constructor.
The first (class-ref) argument must be a class name or a class reference.
If the arg-class-refs rest argument is a positive integer, the integer specifies the number of arguments expected by the constructor. If the class has a unique constructor for the specified number of arguments, then that constructor is returned. Otherwise a continuable error is signaled to allow an appropriate constructor to be selected.
If the arg-class-refs arguments are not a single positive integer, then each argument must be a class name or a class reference that describes an argument type. The constructor with the matching signature is retrieved from Java.
The compiler macro associated with the function allows compile-time collection of java class names and method signatures. This information is used to generate a file of class and method definitions that may be loaded to initialize an application, and avoid the class and method lookup overhead in the body of the application (see jlookup).
The symbol jcons also names this function (for backward compatibility), but please use jconstructor instead of jcons.
See jlinker.html for more information on the jLinker facility.
Function, net.jlinker package
Arguments: object
Returns a description if the argument is a remote reference.
See jlinker.html for more information on the jLinker facility.
Function, net.jlinker package
Arguments: method-ref instance &rest args
Use of this operator is deprecated. This operator will be removed in the next major release of Allegro CL.
A warning is signaled at compile time when this operator is encountered unless the variable *jlinker-deprecated-warnings* is set to nil.
This function has been replaced with jcall. Please use jcall instead or jdo-call, and modify existing code to do the same.
See jlinker.html for more information on the jLinker facility.
Function, net.jlinker package
Arguments: method class &rest args
This function has been replaced with jstatic. Please use jstatic instead or jdo-static, and modify existing code to do the same.
See jlinker.html for more information on the jLinker facility.
Function, net.jlinker package
Arguments: class-ref-or-field field-or-instance* &optional instance value
This function retrieves or modifies a field in a Java class or instance.
The valid argument patterns for this operation are:
nil value: to store value in a static field (when value may be confused with an instance-ref).See jlinker.html for more information on the jLinker facility.
Function, net.jlinker package
Arguments: name-class-ref
Use of this function is deprecated. Please use jclass instead. This function is kept for backward compatibility and will likely be removed in a later release.
See jlinker.html for more information on the jLinker facility.
Function, net.jlinker package
Arguments: class-ref &rest arg-class-refs
Use of this operator is deprecated. This operator will be removed in the next major release of Allegro CL.
A warning is signaled at compile time when this operator is encountered unless the variable *jlinker-deprecated-warnings* is set to nil.
Please use jconstructor instead of this function.
See jlinker.html for more information on the jLinker facility.
Function, net.jlinker package
Arguments: class-ref-or-field field-or-instance &optional instance value
Use of this function is deprecated. Please use jfield. This function is kept for backward compatibility and will likely be removed in a later release.
See jlinker.html for more information on the jLinker facility.
Function, net.jlinker package
Arguments: class-ref name &rest arg-class-refs
Use of this operator is deprecated. This operator will be removed in the next major release of Allegro CL.
A warning is signaled at compile time when this operator is encountered unless the variable *jlinker-deprecated-warnings* is set to nil.
Please use jmethod instead of this function.
See jlinker.html for more information on the jLinker facility.
Function, net.jlinker package
Arguments: &optional pp
Return a list of the names of all the properties present in the Java System object.
If the pp argument is non-nil, pretty-print the list on *standard-input* and return nil.
See jlinker.html for more information on the jLinker facility.
Function, net.jlinker package
Arguments: name-string
Extract the named property from the Java System object.
See jlinker.html for more information on the jLinker facility.
Function, net.jlinker package
Arguments: &optional size
This function is used to query or to set the buffer size used to transmit data from Lisp to Java.
If the size argument is omitted or is any value other than an integer, then the two values returned are eql to the current buffer size in use (and to each other). If the size argument is an integer then the two values returned are the new buffer size and the previous buffer size. The new buffer size is always adjusted to be no less than 128 and to be even.
The default buffer size of 512 is normally adequate and sufficient. Changing the value of the buffer size affects the current Lisp/Java connection and all subsequent connections. A new value takes effect as soon as any active transfer ends.
Under some circumstances in Windows 2000, the default size of 512 bytes seems to introduce unexplained delays. The effect is most clearly visible when transmitting a very long (more than 100,000 byte) string from Lisp to Java. With some buffer sizes, the operation takes a long time and the Windows Task Manager reports low cpu utilization during the transfer. With other buffer sizes, the Task Manager reports almost 100% cpu utilization and the transfer is correspondingly much faster. If transmitting large blocks of data from Lisp to Java is a significant component of an application, it may be worthwhile to experiment with the buffer size to optimize the rate of transfer.
If transfer delays seem to be occurring, reducing the buffer size often eliminates the delays, even though this strategy is at odds with the greater efficiency of larger buffer for large data transfers.
See jlinker.html for more information on the jLinker facility.
Function, net.jlinker package
Arguments: &key verbose errorp to config jar
This function copies (if necessary) the two files normally needed to use jLinker, jl-config.cl and jlinker.jar. The config and jar arguments are directory pathnames for the above files respectively; both default to "./".
The to argument is the destination directory and must be specified.
If the errorp argument is non-nil, an error is signaled if one of the files is missing.
The verbose argument controls the printing of progress messages.
See jlinker.html for more information on the jLinker facility.
Function, net.jlinker package
Arguments: &key wait server lisp-file lisp-port verbose error-p preserve-client-calls
This function ends a connection.
If lisp-port is non-nil, the lisp-file argument is ignored; the function attempts to stop advertising at the given port. If port is nil but lisp-file is non-nil, then the function attempts to stop advertising at the port specified in the file. If the wait argument is nil, the function returns before the attempts are completed but the attempts continue.
If the wait argument is non-nil (the default) or if the lisp-port or lisp-file arguments are omitted, then this function attempts to close down a connection between Lisp and Java. If a graceful disconnect fails, the connection is aborted unilaterally. If the wait argument is nil, return while attempted disconnects are going on, otherwise return only when the connection is shut down completely.
It is important to call jlinker-end before calling jlinker-init again even if the connection appears to be broken already.
The following keyword arguments alter the behavior jlinker-end:
verbose: When t, emit status and warning messages. The default is the value of *jlinker-verbose*.error-p: this argument determines the behavior ofnil, no error is signaled. This argument defaults to the value of *jlinker-error-p*.:preserve-client-calls: this argument, if specified, overrides any setting of the same argument that was specified in the call to jlinker-init. Allowable values are nil (use pre-version 7.1 behavior -- any running client calls are killed), a positive integer (wait that number of seconds before killing remaining client calls), any other non-nil value (allow client calls to run to completion). See jlinker-init for more details.jlinker-end returns one of the following values:
*:jlinker-end: jlinker connection is properly shut down in response to this call
:wait: jlinker connection was shutdown in another process; this call was waiting for it to finish because wait is true:busy: jlinker shutdown is in progress already in another process, return immediately because wait is nilnil: immediate return because there is no jlinker connection at allnil but wait is nilnil and error-p is nil and an error occurred. The list contains information about the error. The value of wait does not affect this case.nil and error-p is true and an error occurred. The value of wait does not affect this case.See jlinker.html for more information on the jLinker facility.
Generic Function, net.jlinker package
Arguments: jlinker-error
This generic function is the accessor of the action slot of jlinker-error. The action slot holds a symbol or keyword describing the high-level activity that triggered the error.
See jlinker.html for more information on the jLinker facility.
Generic Function, net.jlinker package
Arguments: jlinker-error
This generic function is the accessor of the data slot of jlinker-error. The data slot contains additional data of interest.
See jlinker.html for more information on the jLinker facility.
Generic Function, net.jlinker package
Arguments: jlinker-error
This generic function is the accessor of the dentifier slot of jlinker-error. The identifier slot holds a keyword or a string describing the error.
See jlinker.html for more information on the jLinker facility.
Function, net.jlinker package
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
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 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.
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:
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*.
The initial value of
*jlinker-error-p*
is t.
|
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
Multiple jlinker-init
invocations can listen at
the same port number. This is the default behavior
if port is specified
as |
: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
|
:java-out
|
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.
|
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:
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 ".".
The current value of the CLASSPATH environment variable.
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:
If a file "jlinker.jar" exists in the current directory, it is the default.
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.
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"))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.
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.
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.html for more information on the jLinker facility.
Function, net.jlinker package
Arguments: &key process-function end-function init-args max-servers total-timeout stop
This function starts a process that continuously restarts the Lisp jLinker server so that one is (almost) always available for a Java connection.
The Java connection attempts must be separated in time, i.e. a new connection attempt should be made only after a previous one is completely initialized. See the note about competing connections in the description of jlinker-init.
The returned value depends on the arguments. When a new listener is started, then the returned value is the name of the listening process in Lisp. When the stop argument is passed, the returned value is the stop argument. A returned value of nil indicates that no listeners were active, so the call was ignored. A returned value of :stopping indicates that a previous :stop request is not yet completed; in some cases, it may be necessary to manually kill the remaining jlinker processes. Normally, the returned value is the stop argument.
When the stop argument is the keyword :abort, any attempt to stop the listeners is terminated. This option is very likely to leave processes that must be killed manually.
The process-function argument is a function of one argument. It is called when jlinker-init returns after a new server creation. The argument is the value returned by jlinker-init. If this function returns nil, the jlinker-listen process exits and no more servers will be created. If this argument is not specified, then jlinker-listen will exit if jlinker-init fails for any reason.
The stop argument is t to stop advertising after the next connection is made. A value of :stop stops advertising immediately but leaves active connections running. A value of :all stops advertising immediately and forces all the active connections to be killed.
The end-function is called with two arguments when the listener process exits for any reason. The first argument is a reason keyword and the second is a list of currently active connections.
The init-args argument is a list of keyword-value pairs passed in a call to (jlinker-init :lisp-advertises ...).
The max-servers argument is the maximum number of simultaneous active server connections. When this number is reached, the advertised socket is disabled until one or more servers terminate.
The total-timeout argument may be a number of seconds for how long the advertised connection is made available.
See jlinker.html for more information on the jLinker facility.
Function, net.jlinker package
Arguments: &optional verify
Query the jLinker interface. Two values are returned. The first is t, nil, or :verified. The second returned value indicates the jlinker mode as follows:
nil, the second value is the keyword :socket or the keyword :native.nil, the second value is the first element of *jlinker-init*.If the interface is not running, the result is nil. If the interface is running and the verify argument is nil, return t. If the interface is running and the verify argument is non-nil, send a round-trip message to verify the connection (and return :verified if all is okay). If the interface appears to be malfunctioning, jlinker-end is called to shut down the connection completely.
See jlinker.html for more information on the jLinker facility.
Function, net.jlinker package
Arguments: key &optional value
The purpose of this function is to extract and modify data specific to one particular Lisp-Java connection. The first (required) argument, key, is a keyword that specifies the information accessed. If the second (optional) argument, value, is omitted or nil, the current value is returned; if the second argument is non-nil, it is stored.
The possible values of the key argument are:
:data: this value is reserved for the application programmer. The purpose is to provide a place for application-specific data associated with a particular connection. There is an example of its use in examples/jlinker/applet/many-applets.cl.
:notifier: this value causes jlinker-slot to return a Lisp process object when a connection is active or nil when there is no connection.
:lisp-call-error-p: if a non-nil value for value is supplied, then subsequent calls from Java are affected: if a Lisp error occurs in a call from Java an error break will be taken; one of the restarts in that case is to return alternate values to Java. Since the error break ties up the Java/Lisp interface, this option should be used sparingly.
One use for this object is to pass it as an argument to jnotify-lisp. Another use is to detect a new jlinker connection. The data structure in *jlinker-connection* is re-used from one connection to the next, hence an eq test against a saved value will always return t.
The value in the :notifier slot is newly created for each connection and can therefore be compared with eq to a saved value to detect a new connection. Note and warning: calling jlinker-slot with a second non-nil argument will modify the value of the slot and will probably damage the current jlinker connection beyond repair.
The other values of the key argument are reserved for internal uses at this time.
See jlinker.html for more information on the jLinker facility.
Function, net.jlinker package
Arguments: &optional stream-or-key prefix t1 t2
The behavior of this function depends on the type of the stream-or-key. That argument can be a string or symbol string-equal to "<" or ">", or it can be a value suitable as the first argument to format (such as a stream, t, or nil)
In this case, jlinker-version works as a boolean, testing whether the current version is earlier than or later than the version specified by the prefix, t1, and t2 arguments. prefix, t1, and t2 should all be non-negative integers. Thus, (jlinker-version :> 2) returns true for versions later than 2.0.0. (The current version in list format is the value of *jlinker-version*.)
This function generates a nice version message from the jLinker version variables. If the stream-or-key argument is nil or omitted, the message is returned as a string; otherwise, the message is written to the stream-or-key argument. The prefix argument is text inserted at the beginning of each of the 3 lines in the message.
Example:
;;; *jlinker-version* = 3.0.8
;;; *jlinker-comptime* = 2000-9-29 16:16:31
;;; JDK/Orb: c:\mmWork\java\jdk1.2 Direct link.See jlinker.html for more information on the jLinker facility.
Generic Function, net.jlinker package
Arguments: name &optional arg
This generic function has methods dispatching on the value of the name argument.
Arguments: (name (eql :version)) &optional error-p
This method returns a number that represents the version of the jLinker Java code. The number is of the form mnnnsss where the digits m are the major version, nnn the minor version, and sss the sub-minor version. A second returned value is a string containing the Java JDK version. If the error-p argument is non-nil, signal an error if not connected to Java; otherwise return nil values.
Arguments: (name (eql :query-lookup)) &optional action
This method returns t if caching is in effect.
Arguments: (name (eql :query)) &optional pprint-p
Returns a list of object statistics if the second argument is nil or omitted. If the second argument is non-nil, the value is pretty-printed to standard-output and no value is returned.
(:LOOKUP
(:NEW-ENTRIES 0 :OBJECTS 1 :NAMES 0)
:DIST-OB-CACHE
(:LIVE 9 :DEAD 0)
:JAVA-SERVER
(:LIVE 9 :FREE 0)
:LISP-SERVER
(:COUNT 0)) :NEW-ENTRIES is the number of named objects added to the cache since the last call to (jlookup :preloaded).
:OBJECTS is the number of named objects in the object cache.
:NAMES is the number of names in the object cache.
:DIST-OB-CACHE :LIVE is the number of live Lisp references to Java objects.
:DIST-OB-CACHE :DEAD is the number of dead Lisp references to Java objects.
:JAVA-SERVER :LIVE is the number of live references in the Java server.
:JAVA-SERVER :FREE is the number of free entries in the Java server table.
:LISP-SERVER :COUNT is the number of references to Lisp objects in the Lisp server table.
When pprint-p is non-nil, the result is printed to standard-output and no values are returned; otherwise the value is an alist of the above items.
Arguments: (name (eql :table)) &optional pprint-p
This method returns a list of the names of the objects in the cache. When pprint-p is non-nil, the table is pretty-printed to standard-output and no values are returned.
Arguments: (name (eql :compile-time-lookup))
Initiate compile-time lookup of Java methods.
When this facility is enabled, all j* macro expansions trigger a lookup of any class and method constants. If a class or method can only be determined at run time, a warning is printed. After compiling an application with compile-time lookup enabled, a (partial) pre-load table may be generated. For the application, a file should have the following contents:
(in-package ...)
(eval-when (compile) (jlookup :compile-time-lookup)
(eval-when (load) (jlookup :preload))
... application code definitions ...
(eval-when (compile) (jlookup :gen-preload))Arguments: (name (eql :preload)) &optional infile
Initialize the object cache with empty hashtables and load the file specified by infile, which defaults to jpreload.cl.
Arguments: (name (eql :preloaded))
Reset the new entry count in the object cache to zero.
Arguments: (name (eql :gen-preload)) &optional outfile
Write out the object cache into the file specified by outfile, which defaults to jpreload.cl.
Arguments: (name (eql :new)) &optional action
Clears the cache and starts a new one.
Arguments: (name (eql :none))
Disables caching.
See jlinker.html for more information on the jLinker facility.
Function, net.jlinker package
Arguments: class-ref &REST args
Use of this operator is deprecated. This operator will be removed in the a future release of Allegro CL.
A warning is signaled at compile time when this operator is encountered unless the variable *jlinker-deprecated-warnings* is set to nil.
This function has been replaced with jnew (which is now a function rather than a macro). Please use jnew instead of jmake-new, and modify existing code to do the same.
See jlinker.html for more information on the jLinker facility.
Function, net.jlinker package
Arguments: class-ref name &rest arg-class-refs
Use of this operator is deprecated. It is an alternate (maintained for now for backward compatibility) name of the function jmethod. Please use jmethod instead of jmeth. See jmethod for details.
A warning is signaled at compile time when this operator is encountered unless the variable *jlinker-deprecated-warnings* is set to nil.
See jlinker.html for more information on the jLinker facility.
Function, net.jlinker package
Arguments: class-ref name &rest arg-class-refs
This function retrieves a remote reference to a Java method.
The first (class-ref) argument must be a class name or a class reference. The second (name) argument must be a string or symbol that names a method.
The arg-class-refs rest argument may be a single positive integer. In this case, if the class has a unique method for the specified number of arguments, then that method is returned. Otherwise a continuable error is signaled to allow an appropriate method to be selected.
If the arg-class-refs arguments are not a single positive integer, then each argument must be a class name or a class reference that describes an argument type.
The compiler macro associated with the function allows compile-time collection of java class names and method signatures. This information is used to generate a file of class and method definitions that may be loaded to initialize an application, and avoid the class and method lookup overhead in the body of the application (see jlookup).
The symbol jmeth also names this function (for backward compatibility), but please use jmethod instead of jmeth.
See jlinker.html for more information on the jLinker facility.
Function, net.jlinker package
Arguments: class-ref &rest args
This function calls a Java constructor with the given arguments.
If the first (class-ref) argument is a string, a symbol or a class reference, we look for a constructor with the number of arguments given. If a unique constructor can be selected, then that constructor is called. Otherwise a continuable error is signaled to allow an appropriate constructor to be selected.
Otherwise, the class-ref argument is assumed to be a constructor reference. The constructor is called with the given arguments.
The value returned by calling any constructor is always a remote reference. This is the case even for java.lang.String instances which are normally represented by their Lisp equivalent. The following call may be used to extract the string representation of a String instance:
(jcall "concat" x "")The compiler macro associated with the function allows compile-time collection of java class names and method signatures. This information is used to generate a file of class and method definitions that may be loaded to initialize an application, and avoid the class and method lookup overhead in the body of the application (see jlookup).
See jlinker.html for more information on the jLinker facility.
Function, net.jlinker package
Arguments: element-type &rest dimensions
Returns a remote reference to a Java array of the specified type. The element-type argument must be string or symbol that names a Java class or a remote reference to a Java Class instance.
See jlinker.html for more information on the jLinker facility.
Generic Function, net.jlinker package
Arguments: notifier handle event longs strings
This method simulates an event arriving as if from the LispCall.dispatchEvent() notifier method in Java lightweight event handlers. The effect is to schedule a call to a handler registered with jregister-handler.
the arguments are:
(jlinker-slot :notifier) (see jlinker-slot).The timecard example in examples/jlinker/timecard/main.cl uses this method to insure that display updates from Lisp are properly serialized with updates triggered by Java code.
See jlinker.html for more information on the jLinker facility.
Function, net.jlinker package
Arguments: slot &optional pool
This function returns information about the current connection pool.
The pool argument is reserved for internal use and must not be specified.
The value returned depends on the slot argument:
:state: returns a keyword describing the state: :ready - the connection pool is ready and operational; :delayed - :delay was specified in the call to jlinker-init and jstart-connection-pool has not yet been called; :initializing - the connection pool is under construction; :jlinker-init - jlinker-init is still running and in a partial state.:dynamic: returns t if the connection pool is dynamic, i.e. the minimum and maximum port specifications are different. A connection pool manager thread is running in Lisp. Ports and server threads may come and go. Returns nil is the pool is static.:pool-ports-to-java: returns the number of Lisp ports to Java in the connection pool. Does not include the initial port to Java.:pool-ports-to-lisp: returns the number of Java ports to Lisp in the connection pool. Does not include the initial port to Lisp.:lisp-ports-to-java: returns the total number of Lisp ports to Java.:java-ports-to-lisp: returns the total number of Java portd to Lisp.:min-ports-to-java: returns the minimum number of Lisp ports to Java in the effective connection pool specification.:max-ports-to-java: returns the maximum number of Lisp ports to Java in the effective connection pool specification.:min-ports-to-lisp: returns the minimum number of Java ports to Lisp in the effective connection pool specification.:lisp-port-idle-time: returns the idle time for Lisp ports to Java in the effective connection pool specification.:java-port-idle-time: returns the idle time for Java ports to Lisp in the effective connection pool specification.See jlinker.html for more information on the jLinker facility.
Function, net.jlinker package
Arguments: &key new sum error-p slot pool
This function accesses or manages statistics maintained by jlinker about the behavior and performance of the connection pool.
If the sum argument is specified, it must be a pool statistics instance obtained in a previous call to jpool-statistics.
If the slot argument is non-nil, it must be one of the following keywords to retrieve the corresponding value from a statistics instance. When slot is non-nil, the new argument is ignored. If sum is specified (as a statistics instance), the value returned comes from that instance. If sum is nil or unspecified, the value comes from the current pool.
:active: number of Lisp ports to Java in use at some moment.:max: maximum number of Lisp ports to Java in use.:wait: number of seconds spent waiting for a Lisp port to Java.:free: number of times a port was obtained for a call.:busy: number of times a caller was told all ports are busy.The following slots refer to non-pool and pool ports combined:
:idle-wait: number of times a port was available after waiting.:idle-free: number of times a port was available without waiting.:idle-busy: number of times a port was not available.If the slot argument is omitted or nil, the return value is always a new pool statistics instance in which the values are copied atomically from the current pool. When sum is specified, it is updated from the current value as a side-effect. The :max slot is the maximum of two, the other slots are sums. (To be clear: when slot is nil, the return value is always a new statistics instance. When sum is also a statistics instance, that instance is updated but not returned.)
If the new argument is non-nil, the current pool statistics are reset to zero.
The pool argument is reserved for internal use and must not be specified.
See jlinker.html for more information on the jLinker facility.
Function, net.jlinker package
Arguments: &optional key
A call to this function is included in every preload file generated with (jlookup :gen-preload) (see jlookup). The effect of the call is to fetch all the Java classes and methods normally needed by the jLinker internals.
When called with the optional argument specified, this function is a predicate that returns true if key is the name of one of these objects.
See jlinker.html for more information on the jLinker facility.
Function, net.jlinker package
Arguments: &key lisp-ports java-ports wait
This function allows you to query the state of connection pool intitialization, perhaps waiting until some state is reached. Since the connection pool is created in parallel with the application running after jlinker-init has returned, all the features and benefits of the pool will be available only after some time has passed. If the application requires these features before it can operate correctly, the application should wait until the desired state is reached.
Connection pools are created if the connection-pool argument to jlinker-init is non-nil. That argument (or, if the value of that argument is :delay, the value of the similar argument to jstart-connection-pool) specifies, among other things, the number of Lisp ports to Java and the number of Java ports to Lisp. The state information returned (as two mustiple values described below) provides information on the state of the connection pool and the various ports.
If the wait argument is nil or 0, return immediately. If the wait argument is a positive number, wait at most that many seconds. Otherwise (wait is some non-nil value other than 0 or a positive number), wait until the specified state is reached.
The state is specified by the lisp-ports and java-ports arguments. A positive integer value for either says the specified state is when that number of ports are available (Java to Lisp ports for java-ports, Lisp to Java ports for lisp-ports).
Here are some examples of possible arguments and their meanings:
(jquery-connection-pool :wait nil) ;; return information immediately
;; the first return value will be T
;; since lisp-ports and java-ports
;; both default to NIL
(jquery-connection-pool :wait nil :lisp-ports 5)
;; return immediately. First value T if 5 (or more) Lisp to Java
;; ports are available, NIL if less than 5 are available.
(jquery-connection-pool :wait nil :lisp-ports 5 :java-ports 4)
;; return immediately. First value T if 5 (or more) Lisp to Java
;; ports are available and 4 (or more) Java to Lisp ports
;; are available NIL if either less than 5 Lisp to Java or
;; less than 4 Java to Lisp ports are available.
(jquery-connection-pool :wait t :lisp-ports 5 :java-ports 4)
;; wait until at least 5 Lisp to Java ports are available and
;; at least 4 Java to Lisp ports are available.
(jquery-connection-pool :wait 20 :lisp-ports 5 :java-ports 4)
;; wait up to 20 seconds until at least 5 Lisp to Java ports
;; are available and at least 4 Java to Lisp ports are available.
;; After 20 seconds, act as if :wait were NIL.lisp-ports and java-ports can be nil (the default in both cases) or a positive integer, which must be less than or equal to the number of such ports specified to jlinker-init (or jstart-connection-pool if the connection-pool argument to jlinker-init is :delayed). A larger number will never be available.
The function returns two values:
The first is t if the specified state has been reached, or nil.
The second value describes the state of the connection pool:
nil if there is no connection pool.:initializing if the pool is still under construction.:terminated if jlinker-end is in progress.When an integer is returned as the second value, its meaning depends on the values of the lisp-ports and java-ports arguments:
nil or omitted, an integer returned is the number of Lisp ports created to date.nil (and thus a positive integer less than or equal to the number of Lisp ports called for), wait until that many Lisp ports to Java are created and return the number of Lisp ports (or return the number of Lisp ports before that if wait is nil or a positive number).nil, wait until that many Java ports to Lisp are created; in this case, the second value is the number of Java ports to Lisp (or return the number of Java ports before that if wait is nil or a positive number).nil, wait until both numbers are reached (or return the number of Lisp ports before that if wait is nil or a positive number); in this case the second value is only the number of Lisp ports to Java.Note that since the pool creation is taking place in parallel threads, whatever state results are returned may only be true for a moment.
See jlinker.html for more information on the jLinker facility.
Function, net.jlinker package
Arguments: object event
This function returns nil or the handler associated with the object and event. It may be used to concatenate handlers. (In earlier releases, the name of this operator was query-handler. The name was changed so it follows the jLinker naming style.)
See jlinker.html for more information on the jLinker facility.
Function, net.jlinker package
Arguments: object event handler &key data count
object, the first argument, may be a remote Java reference object used to specialize the Lisp method. object may be nil to denote an event not associated with an object.
The value of the handler argument should be a function which will be the handler for the event. The form of the function is given below. handler may be nil to delete a handler.
The data argument is any Lisp value. It is passed to the handler function as the first argument in each call.
The count argument may be an integer that specifies the lifetime of the handler or nil. A nil value specifies a handler that will persist until deleted. A positive integer is decremented after each call. When the value reaches zero, the handler is deleted. For example, a count of 1 defines a handler that will handle one event and then will disappear.
Note that only one handler may be specified for each event and object combination. A new handler definition simply overrides an existing one.
A handler function should have an argument list:
Arguments data object longs strings event seqnum
The arguments to the event handler are the data and object that were used in the call to jregister-handler. The third argument is a sequence of integer values representing the numeric data associated with the event. The fourth argument is a sequence of strings representing the string data associated with the event. The event name is passed so that several events could share the same handler. The seqnum argument is the sequence number assigned to the event by the Java event handler. It may be used to identify events or detect lost events.
The handler functions are called sequentially in a dedicated Lisp process; any Lisp errors during a call are ignored. If *jlinker-verbose* is non-nil (or if jlinker-init was called with a non-nil value for the verbose keyword argument) then a message is printed to the Lisp console when a handler function signals an error.
See jlinker.html for more information on the jLinker facility.
Function, net.jlinker package
Arguments: &key lisp-min lisp-max lisp-idle java-min java-max java-idle (error-p t) wait
This function start a connection pool when delayed start was specified in the call to jlinker-init. If the pool is already started, then no action is taken. The values returned are as if (jquery-connection-pool :wait wait) were called (see jquery-connection-pool).
If no pool was specified in the call to jlinker-init, the behavior depends on the error-p argument. If non-nil, signal an error; otherwise return nil.
This function can be safely called repeatedly or from multiple threads; only the earliest call will have any effect, the others will wait or return a state.
When a pool is created, the effective parameters are obtained by combining the arguments with the value of *jlinker-default-connection-pool*.
See *jlinker-default-connection-pool* for information on the various arguments.
See jlinker.html for more information on the jLinker facility.
Function, net.jlinker package
Arguments: method class &rest args
This function calls a static Java method with the given arguments.
If the first (method) argument is a string or symbol, it names a method and the second (class) argument must be a class name or a class reference. We look for a method with the number of arguments given. If a unique method can be selected, then that method is called. Otherwise a continuable error is signaled to allow an appropriate method to be selected.
If the method argument is neither a string nor a symbol, it is assumed to be a method reference. The class argument is ignored, and the method is called with the remaining arguments.
The compiler macro associated with the function allows compile-time collection of java class names and method signatures. This information is used to generate a file of class and method definitions that may be loaded to initialize an application, and avoid the class and method lookup overhead in the body of the application (see jlookup).
See jlinker.html for more information on the jLinker facility.
Function, net.jlinker package
Arguments: class &rest argsig
Like jcons but always returns a list of constructors.
See jlinker.html for more information on the jLinker facility.
Function, net.jlinker package
Arguments: class name &rest argsig
Like jmeth but always returns a list of methods.
See jlinker.html for more information on the jLinker facility.
Generic Function, net.jlinker package
Arguments: object
If the argument is a remote reference, the reference is marked as discarded when it is passed to a callee.
See jlinker.html for more information on the jLinker facility.
Generic Function, net.jlinker package
The name of this function has been changed to wrap-object. Please see the description of that function for more information. The name make-dist-object is still valid (for backward compatibility) but will be removed in a later release. Please convert code to use the new name.
Function, net.jlinker package
Arguments: x &optional type (symcase :read) (pkcase symcase)
The purpose of this function is to create a transfer object that will transmit the value of the Lisp arguement to Java. If the Lisp object cannot be transmitted by value, the function returns nil. The function wrap-object always creates a transfer object - when the Lisp object cannot be transmitted by value, wrap-object creates a remote reference.
If the second (type) argument to make-immediate-object is omitted or nil, the conversion is done following the default conversion rules described in the Data Types and Conversions section of jlinker.html. If the type argument is not nil, then it must be a keyword that constrains how the Lisp value should be transmitted to Java. The table below shows how the Lisp type of the first argument, x, and the second argument, type, combine to control the resulting Java type:
| Lisp Type of x | type is :ref | type is :boolean | type is :byte | type is :short | type is :int |
bignum |
See Note 1 | boolean |
byte |
short |
int |
integer |
int |
boolean |
byte |
short |
int |
real |
See Note 1 | boolean |
double |
double |
double |
string |
See Note 1 | boolean |
String |
String |
String |
character |
char |
boolean |
char |
char |
char |
(array (signed-byte 32) (*)) |
See Note 1 | boolean |
byte[] |
short[] |
int[] |
(array double-float (*)) |
See Note 1 | boolean |
double[] |
double[] |
double[] |
null |
null |
boolean |
byte[] |
short[] |
int[] |
symbol
See Note 3 |
See Note 1 | boolean |
See Note 1 | See Note 1 | See Note 1 |
cons
See Note 2 |
See Note 1 | boolean |
byte[] |
short[] |
int[] |
| Lisp Type of x | type is :long | type is :single | type is :double | type is :string |
bignum |
long |
int |
int |
int |
integer |
long |
int |
int |
int |
real |
double |
float |
double |
double |
string |
String |
String |
String |
String |
character |
char |
char |
char |
char |
(array (signed-byte 32) (*)) |
int[] |
int[] |
int[] |
int[] |
(array double-float (*)) |
double[] |
float[] |
double[] |
double[] |
null |
null |
float[] |
double[] |
String[] |
symbol
See Note 3 |
See Note 1 | See Note 1 | See Note 1 | See Note 1 |
cons
See Note 2 |
See Note 1 | float[] |
double[] |
String[] |
In this case, make-immediate-object returns nil because the Lisp object may not be passed by value in this way and a remote reference must be created.
When a type is specified and the argument x is a cons, we attempt to make a Java array of the specified type. If an unsuitable value is found in the list, an error is signaled. Integer values must be in the Java int range and get truncated to byte or short if appropriate.
The Lisp list (1 2 3) is passed to Java as a remote reference in the default conversion case.
The form (make-immediate-object '(1 2 3) :int) will pass to Java an array of int values.
When the argument x is a symbol, the type argument may be one of the Lisp symbols symbol-value, symbol-function, or class to transmit a remote reference to the corresponding Lisp value.
It may seem less than useful to transmit Lisp symbols to a Java program since symbols are not a useful Java data type. Symbol references are useful to the Java program as values that may be passed back to the Lisp application. Once the symbol reference has been passed to Java it may be returned to Lisp many times with little overhead and yields the same eq symbol in Lisp every time. It is also possible for the Java program to create symbol references with LispCall.addSymbol() or LispCall.setSymbol() methods.
The symcase and pkcase arguments are ignored. It is an error to specify values for them other than the defauls shown. See jlinker.html for more information on the jLinker facility.
Function, net.jlinker package
Arguments: lisp-class-name servlet-ref config-ref
This function is called from the Java servlet init() method. The lisp-class-name argument must be a string containing a fully qualified class name and the class must be a sub-class of http-servlet.
This function is defined when the jlinkent module is loaded. See The jLinker Servlet API for details on the jLinker Servlet API.
See jlinker.html for more information on the jLinker facility.
Function, net.jlinker package
The symbol naming this function is no longer exported. The new name of this function is jquery-handler. That name should be used instead of this one.
See jlinker.html for more information on the jLinker facility.
Function, net.jlinker package
Arguments: &key jar init-args classpath keep classes mode out package names exclude rename
This function analyzes a collection of Java libraries and classes to generate Lisp functions that call Java methods and constructors through a Jlinker connection.
Each Java instance method name is mapped to a Lisp function with a corresponding Lisp name. Overloading is handled by dynamic dispatch in Lisp. More details on this later.
Each Java static method name is mapped to a Lisp name composed from the class name and method name.
Java constructors are mapped to a Lisp name derived from the class name.
Each static final field is mapped to a Lisp name derived from the class name and field name. The Lisp function caches the value in Lisp so that repeated uses of the field do not require round-trips to Java.
The scan and analysis is done by calling Java reflection API methods. Therefore, Java and the required jar files must be available during the scan and code generation.
The generated code is sensitive to the case-mode of both the generating and running Lisp. In most cases code generated in :break mode in mlisp will run equally well in alisp or mlisp. Code generated in :keep mode in mlisp is most likely to cause problems when run in alisp. (mlisp is the case-sensitive modern Common Lisp version. alisp is the case-insensitive Common Lisp. See case.html for details of case sensitivity in Allegro Common Lisp.
jar: A jar file entry or a list of jar file entries:
jar-file-entry -> path-string | (path-string filter... )
filter -> :include reg-exp-string
-> :exclude reg-exp-stringEach filter is applied in turn to each name in the jar file manifest.
Very often, a jar file contains many entries above and beyond the documented public api in a library. There is little benefit in generating Lisp names for all the internal names of the library.
init-args: A list of initial arguments to jlinker-init.
classpath: A list of additional classpath components.
If Jlinker is already running when scan-java-api is called, then both init-args and classpath are ignored.
If Jlinker is not running, jlinker-init is called with the specified arguments. A classpath argument is added to this list by combining the classpath argument with the list of jar files.
The remaining keyword arguments are:
keep: When non-nil (default is nil), scan-java-api saves the collected class and method data as the value of user::*jscan-java-api-data*. This information may be of some value in reporting a problem in API generation.
*classes: A Java class name or a list of class names. The classes mentioned in this argument are included in the analysis and code generation. This argument may also include the names of lists of classes defined with def-japi-classes.
mode: Specifies the result of the call. The choices are:
:gen (the default) - Analyze and generate Lisp code.:walk - Analyze the class tree and return a list of all methods and fields.:flat - Analyze and return a flat list of methods.out: A pathname for the output file. If mode is :gen and out is nil, then mode switches to :walk. Two output files are generated:
package: A name for the Lisp package where the generated functions will reside. If mode is :gen and package is nil, then mode switches to :walk.
A new package is created, using no other packages. All the generated function names are exported from this package.
If several jar files are involved, there may be Lisp name conflicts. In that case, the code generation may need to be split among two or more packages and the code generated into separate output files. The functions in each Lisp package must be generated with separate calls to the generator function.
If the generator is called twice for different libraries but the same output package, conflicts between the two sets of functions will not be detected when the code is generated; the conflicts may be detected when the generated code is loaded.
names: Specifies the method used to generate Lisp names. The default is :break. The choices are:
:keep - generate the Lisp name from the exact spelling of the Java name, but remain sensitive to Lisp input case mode by interning symbols with read-from-string. This style is likely to cause problems in ANS Lisp (alisp) and thus is recommended only in mlisp (Modern) mode. Here are some examples when using :keep:Instance method addItem maps to Lisp function jpk:addItem
Static method close in class com.foo.SomeClass
maps to Lisp function jpk:SomeClass.close
Constructor for class com.foo.SomeClass
maps to Lisp function jpk:new-SomeClass
Accessor for static final field foo in com.foo.SomeClass
is Lisp function jpk:SomeClass.foo:break - generate a Lisp name similar to the Java name and avoid any case issues. This style may generate name conflicts in some cases (see the exclude arg below). Here are some examples using :break:
Instance method addItem maps to Lisp function jpk:add-item
Static method close in class com.foo.SomeClass
maps to Lisp function jpk:some-class-close
Constructor for class com.foo.SomeClass
maps to Lisp function jpk:new-some-class
Accessor for static final field foo in com.foo.SomeClass
is Lisp function jpk:some-class-foo:keep-case - generate the Lisp name from the exact spelling of the Java name and bypass Lisp input case conversion by using intern explicitly. This method is the same as :keep in Modern mode (mlisp). When used in ANS mode (alisp), the code must be generated and compiled in ANS mode and can only run in ANS Lisp. Most Java names will need to be escaped in any application code.
See the table below for all the possible case-mode and names variations.
exclude*: A list of method or class names for which Lisp functions should not be generated. Each entry in the list may be a name regexp or a list of the form
class-or-method-regexp -- skip code generation for any Java member if the class name or member name contains this regexp
({ :method | :static } [method-regexp [class-regexp [(signature-regexp...)]]]) -- skip code generation for for the specified method or methods. If the class and signature regexps are omitted, skip code generation for any method with a matching name. If the class-regexp is present, skip only methods in matching classes. If the signature regexps are specified, skip only methods with that many arguments where the arguments match. A nil or an empty string will match anything.
(:constructor \[class-regexp \[(signature-regexp...)\]\])
(:final class-regexp field-regexp)
rename: A list of entries that specify alternate Lisp names for Java members. Each entry is of the form
( Java-spec Lisp-name-spec )where Lisp-name-spec may be a string or a symbol. A string denotes a symbol in the generated code package. A symbol is used as specified. If the symbol is not in the generated code package, the generated output file will assume that the needed package exists.
Java-spec: All the strings in the Java-spec must match the Java class or method name exactly. The Java-specs can be:
(:static name [class [signature]])
(:method name [class [signature]]) -- If class and signature
are omitted, the Lisp name is used for all methods
with the given name. If class is specified, only
methods in that class are affected. If signature
is specified, the Lisp name is used for exactly
one method.
(:final class name) -- The specified final static field will
have the specified Lisp accessor function.
(:constructor class [signature])Here is a table of consequences of the various values for the names argument:
| :names argument | ACL general | ACL compile | ACL run | Notes |
:break |
ANSI | ANSI | ANSI only | |
:break |
Modern | Modern | ANSI and Modern | |
:keep |
ANSI | ANSI | ANSI only | |
:keep |
Modern | Modern | Modern | |
:keep |
Modern | Modern | ANSI | Conflicts likely |
:keep |
ANSI | ANSI | ANSI | |
:keep |
Modern | Modern | Modern |
All other case-mode combinations are likely to produce conflicts and errors at code generation, compile or load time, and likely garbled results at run time.
Lisp name conflicts occur when two or more Java names map to the same generated Lisp name. When a conflict is detected, a message is printed to the console; the first definition detected for this name is emitted, but any subsequent code is suppressed for that Lisp name. A summary of all the conflicts is inserted at the end of the generated code file.
When Java names cause conflicts in Lisp, there are several actions possible:
The generated Lisp functions attempt to dispatch overloaded Java methods by analyzing the Java classes of the instance and other arguments. An available method is a potential match if the instance and argument classes are subclasses of the declaring method and declared signature parts. If this results in more than one match, then declaring classes are compared and any methods declared on a superclass are discarded. If there are still more than one method remaining, and error is signaled. No attempt is made to order the methods by their signatures.
This strategy is similar to but not identical to the way methods are dispatched by the Java compiler. In some cases, the Lisp code identifies more than one method; in some cases it may be unable to match the Lisp arguments to the declared method signatures; in these case an error is signaled.
Java classes Fine extends Narrow; Narrow extends Broad
Java methods on class Foo convert(Narrow x) convert(Broad x)
Lisp call (convert instance-of-Foo, instance-of-Fine)
Dispatcher will find two convert methods.It is also possible to call the wrong method when the intent is to call a method more general than the most specific. In Java the situation is handled by casting the argument, but there is no way to cast the argument in Lisp. These situations must be recognized by the programmer.
In some of these cases, the solution is to call the desired method explicitly with jcall, jstatic, or jnew. In some, there is no way to call the method with jlinker.
See jlinker.html for more information on the jLinker facility.
Generic Function, net.jlinker package
Arguments: (self async-http-servlet) work request response gate
This method on async-http-servlet instances is called from all the methods of the Java class LispAsyncHttpServlet. The work argument is the name of one of the work methods do-delete, do-get, do-head, do-options, do-post, do-put, and do-trace.
The request and response arguments are remote references to the request and response arguments of the Java method. The gate argument is a remote reference to an array Object[2] used by the Java method as a gate to determine when the work for a particular request is completed.
This method queues the work into a common queue where all requests from servlets are saved. The queue is emptied by a single Lisp process.
Arguments (self multi-async-http-servlet) work request response gate
This method on multi-async-http-servlet instances starts a new Lisp process for each request that arrives. The process is discarded when the request is completed.
This function is defined when the jlinkent module is loaded. See The jLinker Servlet API for details on the jLinker Servlet API.
See jlinker.html for more information on the jLinker facility.
Macro, net.jlinker package
Arguments: &body body
All calls to Java must be made with a current Java environment.
A Java environment is available by default
(LispCall style -1 0 1 2)A LispCall made with style 3 or 4 (STYLE_ASYNC_BR or STYLE_ASYNC_GO) does not provide a default Java environment. Any calls to Java from such a Lisp function must be within an explicit with-java-environment form.
Since the creation of the environment may involve some overhead when running in native mode, it is best to place calls to this macro in the outermost context where calls to Java are expected.
If the socket implementation is used exclusively, then this macro may be omitted.
See jlinker.html for more information on the jLinker facility.
Generic Function, net.jlinker package
Arguments: object-registry lisp-object &optional type-or-style
Transform a Lisp object into a representation that can be passed to Java. If the Lisp value has an equivalent representation in Java, it is passed by value; otherwise a remote reference to the Lisp object is created.
The first argument must be nil. The second argument is the Lisp object. The optional argument is used to specify the type that Java will see or to override passing by value. If the optional argument is :ref then a remote reference is always created. The other possible values of the optional argument are shown in the description of make-immediate-object.
See jlinker.html for more information on the jLinker facility.
Generic Function, net.jlinker package
Arguments: x
A predicate that identifies remote reference objects.
See jlinker.html for more information on the jLinker facility.
Copyright (c) 2023, Franz Inc. Lafayette, CA., USA. All rights reserved.
|
Allegro CL version 11.0 | ||||||||