JPL - Prolog API - overview

Contents

Introduction top

JPL's Prolog API is an interface which allows SWI Prolog 7.x programs to dynamically create and manipulate Java objects.

Here are some significant features of the interface and its implementation:

JPL types (Java types, as seen by Prolog) top

All Java values and object references which are passed between Prolog engines and Java VMs via JPL's Prolog API are seen as instances of types within this simplified JPL type system:

Representation of Java values and references within Prolog top

Instances of JPL types are represented within Prolog as follows:

Representation of Java types within Prolog (1): structured notation top

The Prolog API allows Prolog applications to inspect, manipulate, and reason about the types of Java values, references, methods etc., and this section describes how these types themselves are represented. Predicates which pass these type representations include (the clue is in the name):

jpl_class_to_type/2
jpl_classname_to_type/2
jpl_datum_to_type/2
jpl_is_object_type/1
jpl_is_type/1
jpl_object_to_type/2
jpl_primitive_type/1
jpl_ref_to_type/2
jpl_type_to_class/2
jpl_type_to_classname/2

The pseudo-type void is represented by this atom:

void

The pseudo-type null is represented by this atom:

null

The primitive types are represented by these atoms:

boolean
char
byte
short
int
long
float
double

class types are represented as class(package_parts,classname_parts) e.g.

class([java,util],['Date'])

array types are represented as array(type) e.g.

array(boolean)
array(class([java,lang],['String'])

This structured notation for Java types is a term-encoding, designed to be convenient for composition and decomposition by unification.

Representation of Java types within Prolog (2): descriptor notation top

The descriptor notation for Java types is one of two textual notations employed by the JVM and the Java class libraries; JPL (necessarily) supports both (and supports conversion between all three representations).

Examples of descriptor notation:

Representation of Java types within Prolog (3): classname notation top

The classname notation for Java types is the other textual notation employed by the JVM and the Java class libraries. It is a (seemingly unnecessary) variation on the descriptor notation, used by a few JNI routines. It has the slight advantage that, in the case of simple class types only, it resembles the Java source text notation for classes. This representation is supported only because certain JNI functions use it; it is used within JPL's implementation of jpl_call/4 etc. You may encounter this notation when tracing JPL activity, but otherwise you need not know about it.

Examples of classname notation:

Creating instances of Java classes top

To create an instance of a Java class from within Prolog, call jpl_new(+Class, +Params, -JRef) with a classname, a list of actual parameters for the constructor, and a variable to be bound to the new reference, e.g.

jpl_new('javax.swing.JFrame', ['frame with dialog'], JRef)

which binds JRef to a new object reference, e.g.<jref>(0x12345678).

NB for convenience, this predicate is overloaded: Class can also be a class type in structured notation, e.g. array(boolean).

Calling methods of Java objects or classes top

The object reference generated by the jpl_new/3 call (above) can be passed to other JPL API predicates such as:

jpl_call(+JRef, +Method, +Params, -Result)

e.g.

jpl_call(JRef, setVisible, [@(true)], _)

which calls the setVisible() method of the object to which JRef refers, effectively passing it the Java value true.

(This call should display the new JFrame in the top left corner of the desktop.)

Note the anonymous variable passed as the fourth argument to jpl_call/4. A variable in this position receives the result of the method call: either a value or a reference.

Since SetVisible() is a void method, the call returns the (artificial) reference @(void), which can be ignored.

Some may prefer to code this call thus:

jpl_call(F, setVisible, [@(true)], @(void))

which documents the programmer's understanding that this is a void method, and fails if it isn't.

If the JRef argument represents a class, then the named static method of that class is called.

Fetching field values of Java objects or classes top

The jpl_get/3 API predicate has the following interface:

jpl_get(+Class_or_Object, +Field, -Datum)

and can retrieve the value of an instance field e.g.

jpl_new('java.util.GregorianCalendar', [], JRef),
jpl_get(JRef, time, Ms)

or of a static field, e.g.

jpl_get('java.awt.Color', pink, Pink)

which binds the Prolog variable Pink to a reference to the predefined java.awt.Color "constant" which is held in the static final .pink field of the java.awt.Color class.

Setting field values of Java objects or classes top

Object and class fields can be set (i.e. have values or references assigned to them) by the jpl_set/3 API procedure, which has the following interface:

jpl_set(+Class_or_Object, +Field, +Datum)

where Datum must be a value or reference of a type suitable for assignment to the named field of the class or object.

A slightly longer example top

This code fragment

findall(
    Ar,
    (   current_prolog_flag(N, V),
        term_to_atom(V, Va),
        jpl_new('[Ljava.lang.String;', [N,Va], Ar)
    ),
    Ars
),
jpl_new('[[Ljava.lang.String;', Ars, Ac),
jpl_datums_to_array([name,value], Ah),
jpl_new('javax.swing.JFrame', ['current_prolog_flag'], F),
jpl_call(F, getContentPane, [], CP),
jpl_new('javax.swing.JTable', [Ac,Ah], T),
jpl_new('javax.swing.JScrollPane', [T], SP),
jpl_call(CP, add, [SP,'Center'], _),
jpl_call(F, setSize, [600,400], _),
jpl_call(F, setVisible, [@(true)], _).

builds an array of arrays of strings containing the names and values of the current SWI-Prolog "flags", and displays it in a JTable within a ScrollPane within a JFrame:

screendump of current prolog flags in a JTable within a ScrollPane within a JFrame

In addition to JPL API calls, this example calls jpl_datums_to_array/2, a utility which converts any list of valid representations of Java values (or objects) into a new Java array, whose base type is the most specialised type of which all list members are instances, and which is defined thus:

jpl_datums_to_array(Ds, A) :-
    ground(Ds),
    jpl_datums_to_most_specific_common_ancestor_type(Ds, T),
    jpl_new(array(T), Ds, A).

Having found the "most specific common ancestor type", a new array of this type is created, whose elements are initialised to the successive members of the list of datums.

This illustrates another mode of operation of jpl_new/3:

jpl_new(+ArrayType, +InitialValues, -ArrayRef)

See Prolog API - Reference for fuller details of the API procedures.

Don't overlook the possibility and advantages of writing custom Java classes to serve your Prolog applications: this interface is not designed to make Java programming redundant.

Exceptions thrown by Java top

Uncaught exceptions thrown by the JVM while handling a Prolog API call are mapped onto error(_,_) structures, e.g.

?- catch(jpl_new('java.util.Date',[yesterday],_), E, true).
E = error(java_exception((0x1026D40)), 'java.lang.IllegalArgumentException').

because, as the exception suggests, yesterday is not a valid constructor argument.

Java exceptions are always returned as Prolog exceptions with this structure:

error(java_exception(reference_to_exception_object), exception_classname)

Gotchas top

Here are a few things to watch out for.

Calling methods with no parameters

You must pass an empty parameter list when calling Java methods which take no parameters, e.g.

jpl_call('java.lang.System', gc, [], _)

There is (deliberately) no jpl_call/3 convenience predicate which defaults parameters to [] (see below).

Calling void methods

You must accept an @(void) result when calling void Java methods, e.g. either

jpl_call('java.lang.System', gc, [], @(void))

which explicitly matches the expected result, or

jpl_call('java.lang.System', gc, [], _)

which uses an anonymous variable to ignore the result.

There is (deliberately) no jpl_call/3 convenience predicate which conceals the return value of void methods (see above).

To do top

Here are a few longer-term (and tricky) aims: