This document is a reference for the Prolog API. The overall documentation is maintained on the GitHub Wiki
The library(jpl) provides a bidirectional interface to a
Java Virtual Machine.
'java.lang.String''[I' or 'Ljava.lang.String;'class(_,_) or array(_),
e.g. class([java,util],['Date'])If X is an object (non-array) type or descriptor and Params is a list of values or references, then V is the result of an invocation of that type's most specifically-typed constructor to whose respective formal parameters the actual Params are assignable (and assigned).
If X is an array type or descriptor and Params is a list of values or references, each of which is (independently) assignable to the array element type, then V is a new array of as many elements as Params has members, initialised with the respective members of Params.
If X is an array type or descriptor and Params is a non-negative integer N, then V is a new array of that type, with N elements, each initialised to Java's appropriate default value for the type.
If V is literally {Term} then we attempt to
convert a
new org.jpl7.Term instance to a corresponding term; this is
of little obvious use here, but is consistent with jpl_call/4
and jpl_get/3.
<jref>(1552320) (for
static or instance methods)'java.util.Date' (for static
methods only)'Ljava.util.Date;' (for static
methods only)class([java,util],['Date']) (for static
methods only)MethodName should be a method name (as an atom) (may involve dynamic overload resolution based on inferred types of params)
Params should be a proper list (perhaps empty) of suitable actual parameters for the named method.
The class or object may have several methods with the given name; JPL will resolve (per call) to the most appropriate method based on the quantity and inferred types of Params. This resolution mimics the corresponding static resolution performed by Java compilers.
Finally, an attempt will be made to unify Result with the
method's returned value, or with @(void) (the compound term
with name @ and argument void) if it has none.
Fspec can be
Finally, an attempt will be made to unify V with the retrieved value or object reference.
Examples
jpl_get('java.awt.Cursor', 'NE_RESIZE_CURSOR', Q).
Q = 7.
jpl_new(array(class([java,lang],['String'])), [for,while,do,if,then,else,try,catch,finally], A),
jpl_get(A, 3-5, B).
B = [if, then, else].
X can be
class(_,_) or array(_)
type (for static fields)Fspec can be
V must be a suitable value or object.
['-Xrs']Fails silently if a JVM has not yet been started, and can thus be used to test for this.
jpl.pl) of JPL.
It should exactly match the version identifiers of JPL's C (jpl.c) and Java (jpl.jar) components.
Example
?- jpl_pl_lib_version(V). V = '7.6.1'.
It should exactly match the version identifiers of JPL's Prolog (jpl.pl)
and Java (jpl.jar) components.
Example
?- jpl_c_lib_version(V). V = '7.4.0-alpha'.
ClassName is its canonical (?) source-syntax (dotted)
name, e.g. 'java.util.Date'
NB not used outside jni_junk and jpl_test (is this (still) true?)
NB oughta use the available caches (but their indexing doesn't suit)
TODO This shouldn't exist as we have jpl_class_to_entityname/2
???
The implementation actually just calls Class.getName()
to get the entity name (dotted name)
java.lang.Class.
The Type is the (Prolog Universe) JPL type term denoting the
same type as does the instance of Class.
NB should ensure that, if not found in cache, then cache is updated.
Intriguingly, getParameterTypes returns class objects (undocumented AFAIK) with names’boolean',’byte' etc. and even’void' (?!)
Class is a (canonical) reference to the corresponding class object.
NB uses caches where the class has already been mapped once before.
java.lang.Class.getName().
Type is the JPL type (a ground term) denoting the same Java type as EntityName does.
The Java type in question may be a reference type (class, abstract class, interface), and array type or a primitive, including "void".
Examples:
int int integer class([],[integer]) void void char char double double [D array(double) [[I array(array(int)) java.lang.String class([java,lang],['String']) [Ljava.lang.String; array(class([java,lang],['String'])) [[Ljava.lang.String; array(array(class([java, lang], ['String']))) [[[Ljava.util.Calendar; array(array(array(class([java,util],['Calendar'])))) foo.bar.Bling$Blong class([foo,bar],['Bling','Blong'])
NB uses caches where the class has already been mapped once before.
Use jpl_entityname_to_type/2 in preference.
Use jpl_type_to_entityname/2 in preference.
Type is the unique most specialised type of which Datum denotes an instance;
NB 3 is an instance of byte, char, short, int and long, of which byte and char are the joint, overlapping most specialised types, so this relates 3 to the pseudo subtype’char_byte';
Class is a (canonical) reference to the (canonical) class object which represents the class of Object
NB what's the point of caching the type if we don't look there first?
Type is the JPL type of that object.
void is not included.
?- setof(Type, jpl_primitive_type(Type), Types). Types = [boolean, byte, char, double, float, int, long, short].
Type is its type.
Incomplete types are now never cached (or otherwise passed around).
jFindClass throws an exception if FCN can't be found.
java.lang.Class.@(false), the JPL representation
of the Java boolean value’false'.@(null), the JPL representation
of Java's’null' reference.NB this checks only syntax, not whether the object exists.
@(true), the JPL representation
of the Java boolean value’true'.@(void), the JPL representation
of the pseudo Java value’void' (which is returned by jpl_call/4
when invoked on void methods).
NB you can try passing’void' back to Java, but it won't ever be interested.
@(false), the JPL representation of the
Java boolean value’false'.
@(null), the JPL representation of Java's’null'
reference.
@(true), the JPL representation of the Java
boolean value’true'.
@(void), the JPL representation of the
pseudo Java value’void'.
Length is the length of that array. This is a utility predicate, defined thus:
jpl_array_to_length(A, N) :-
( jpl_ref_to_type(A, array(_))
-> jGetArrayLength(A, N)
).
Elements is a Prolog list of JPL representations of the array's elements (values or references, as appropriate). This is a utility predicate, defined thus:
jpl_array_to_list(A, Es) :-
jpl_array_to_length(A, Len),
( Len > 0
-> LoBound is 0,
HiBound is Len-1,
jpl_get(A, LoBound-HiBound, Es)
; Es = []
).
NB this fails silently if
Enumeration interface.
Elements is a Prolog list of JPL references to the enumerated objects. This is a utility predicate, defined thus:
jpl_enumeration_to_list(Enumeration, Es) :-
( jpl_call(Enumeration, hasMoreElements, [], @(true))
-> jpl_call(Enumeration, nextElement, [], E),
Es = [E|Es1],
jpl_enumeration_to_list(Enumeration, Es1)
; Es = []
).
NB String is converted to atom but Integer is presumably returned as an object ref (i.e. as elsewhere, no auto unboxing);
NB this is anachronistic: the Map interface is preferred.
java.util.Iterator interface.
Element is the JPL representation of the next element in the iteration. This is a utility predicate, defined thus:
jpl_iterator_element(I, E) :-
( jpl_call(I, hasNext, [], @(true))
-> ( jpl_call(I, next, [], E)
; jpl_iterator_element(I, E)
)
).
If Datums have a most specific common supertype, then Array is a JPL reference to a new Java array, whose base type is that common supertype, and whose respective elements are the Java values or objects represented by Datums.
Array is a JPL reference to a new Java array of org.jpl7.Term,
whose elements represent the respective members of the list.
java.util.Map interface
This generates each Key-Value pair from the Map, e.g.
?- jpl_call('java.lang.System', getProperties, [], Map), jpl_map_element(Map, E).
Map = @<jref>(0x20b5c38),
E = 'java.runtime.name'-'Java(TM) SE Runtime Environment' ;
Map = @<jref>(0x20b5c38),
E = 'sun.boot.library.path'-'C:\\Program Files\\Java\\jre7\\bin'
etc.
This is a utility predicate, defined thus:
jpl_map_element(Map, K-V) :-
jpl_call(Map, entrySet, [], ES),
jpl_set_element(ES, E),
jpl_call(E, getKey, [], K),
jpl_call(E, getValue, [], V).
java.util.Set interface.
On backtracking, Element is bound to a JPL representation of each element of Set. This is a utility predicate, defined thus:
jpl_set_element(S, E) :-
jpl_call(S, iterator, [], I),
jpl_iterator_element(I, E).