ensure-lisp-classes-from-tree Function

Summary

Creates a Lisp class, and potentially some or all the superclasses as needed based on the tree.

Package

lw-ji

Signature

ensure-lisp-classes-from-tree lisp-name java-class-tree force-p => class

Arguments

lisp-name⇩	A symbol.
java-class-tree⇩	A tree.
force-p⇩	A generalized boolean.

Values

class

A class metaobject.

Description

The function ensure-lisp-classes-from-tree creates a class for lisp-name, and potentially some or all the superclasses as needed based on the tree. Note that all references to "class" here are to Lisp classes. ensure-lisp-classes-from-tree does not actually know anything about Java.

ensure-lisp-classes-from-tree appears the output of the importing interface functions, where it is called with the output of get-superclass-and-interfaces-tree. Users can use it as well, but normally using plain defclass is much more appropriate.

java-class-tree is a tree representing the hierarchy of the Java classes. The structure of the tree is describe in the documentation for get-superclass-and-interfaces-tree. In general it is assumed that this tree was generated by get-superclass-and-interfaces-tree, but you can generate it yourself if you find it useful, but normally simply using defclass to define the classes you want is better.

force-p controls whether to force classes to exist or not.

The processing of a node in the tree when force-p is nil is as follows (note that java-class-tree is the first node):

1. Find the symbol corresponding to the class. For the first node, this is lisp-name. For other nodes, it first checks whether record-java-class-lisp-symbol recorded the java-class-name to lisp-name mapping, and use it if it did. if not, ensure-lisp-classes-from-tree skips this node and use instead the superclass node.
2. Once the symbol is found, ensure-lisp-classes-from-tree processes the nodes of the superclass and the nodes of the interfaces, each one of which returns a class, and construct the superclasses list from the result. It remove duplicates from the list, which can happen because interfaces can be implemented by more than one route.
3. Once it got the superclasses, except for the first node, ensure-lisp-classes-from-tree checks whether the symbol has got a class definition, and if this class definition inherit from all the superclasses. If it does, it returns this class as the result. If a class is found but is not inheriting all the superclasses, ensure-lisp-classes-from-tree redefine it to inherit all the superclasses (ignoring the existing definition), and return it. If the class is not found, ensure-lisp-classes-from-tree skips this node and use instead the superclass node.

   For the first node, ensure-lisp-classes-from-tree always creates the class.

If force-p is true, then ensure-lisp-classes-from-tree never fails for any node. Instead, in step 1 when it does not find the symbol it generates a symbol in the same way that generate-java-class-definitions does by default, and in step 3 if there is no class it creates it.

Notes

1. ensure-lisp-classes-from-tree does not need running Java.
2. The main purpose of ensure-lisp-classes-from-tree is to create the needed class(es) at load-time without a need for running Java. It is not intended to be used at run time.
3. ensure-lisp-classes-from-tree uses clos:ensure-class to create or redefine classes, so requires keeping CLOS in a delivered image (as described in the Delivery User Guide).
4. When java-class-tree matches the Java hierarchy, as it is when it is the result of get-superclass-and-interfaces-tree, if force-p is true ensure-lisp-classes-from-tree generates a full hierarchy with a CLOS class matching each Java class. with force-p nil, at least standard-java-object will always be in the hierarchy, plus any classes that were define by the importing interface or recorded by the user using record-java-class-lisp-symbol.

See also

get-superclass-and-interfaces-tree
generate-java-class-definitions