menu
an API between SWI-Prolog and the Java Virtual Machine - hosted on GitHub
Java API - Overview

Java API - Overview

The Java API comprises public Java classes which support: * constructing Java representations of Prolog terms and queries; * calling queries within SWI-Prolog engines; and * retrieving (as Java representations of Prolog terms) any bindings created by a call.

The class hierarchy

The API consists of the following class hierarchy:

org.jpl7
 +-- fli
 |    +-- Prolog
 |    +-- engine_t
 |    +-- ... <other support classes for fli>
 +-- JPL
 +-- JPLException
 |    +-- PrologException
 +-- Query
 +-- Term
 |    +-- Atom
 |    +-- Compound
 |    +-- Float
 |    +-- Integer
 |    +-- Rational
 |    +-- Variable
 |    +-- JRef
 +-- Util
 +-- Version

Configuration, initialization and inspection for JPL framework:

  • org.jpl7.fli is the package for all the foreign language interface classes; those classes that use C Native library libc.so that links Java with the underlying SWI engine.
    • org.jpl7.Prolog only of constants (static finals) and static native methods. The constants and methods defined herein are in (almost) strict 1-1 correspondence with the functions in the Prolog FLI by the same name (except without the PL_, SQ_, etc. prefixes).
    • org.jpl7.engine_t holds a reference to a Prolog engine.
  • org.jpl7.JPL contains static methods which allow (i) inspection and alteration of the “default” initialisation arguments; (ii) explicit initialisation; (iii) discovery of whether the Prolog engine is already initialised, and if so, with what arguments.

Using JPL for embeeding Prolog into Java, and vice-versa:

  • org.jpl7.Term is an abstract class accounting for the several type of Prolog terms: only its subclasses can be instantiated.
    • Each instance of org.jpl7.Compound has a java.lang.String name and an array of Term arguments. For compatibility with SWI-Prolog version 7’s extension Compound terms with zero arguments, the argument array can be of zero length.
    • org.jpl7.Term.JRef is a has a (non-null, non-String) Object field, representing JPL 7.4’s Prolog references to Java objects, e.g. <jref>(0x01D8000). It is used to pass Java objects to Prolog from which Prolog can use the object (e.g., call methods on it), and obtain references to Java objects from Prolog.
  • org.jpl7.Query contains actual Prolog goals as a Term, and has various methods to run those goals and obtain results.
  • org.jpl7.Util provides various utilities, mostly related to management of Terms.

Initializing and terminating Prolog

Typically, this is automatic.

JPL lazily initializes the Prolog VM, if necessary, when the first query is activated, using default initialization arguments (command line options). Before initialization takes place, these default values can be read, and altered via the following two static methods in org.jpl7.JPL:

// in org.jpl7.JPL
public String[] getDefaultInitArgs();
public void setDefaultInitArgs(String[] args);

which effectively use the following native methods in org.jpl7.JPL.Prolog:

// org.jpl7.JPL.Prolog
public static native String[] get_default_init_args();
public static native boolean set_default_init_args(String argv[]);

After initialization, the parameter values which were actually used can be read with the following method in in org.jpl7.JPL:

public String[] getActualInitArgs();

which is effectively a call to native method Prolog.get_actual_init_args().

This method returns null if initialization has not occurred, and thus it can be used as a test. This allows Java library classes to employ JPL without placing any burden of initialization upon the applications which use them. It can also ensure that the Prolog VM is initialized only if and when it is needed.

Explicit initialization is supported (in org.jpl7.JPL):

public void init();     // call to Prolog.initialise()
public void init(String args[]);    // configure and init()!

Java code which requires a Prolog VM to be initialized in a particular way can check whether initialization has already occurred: if not, it can specify parameters and force it to be attempted; if so, it can retrieve and check the initialisation parameters actually used, to determine whether the initialization meets its requirements.

JPL does not support reinitialization of a Prolog VM, but some command line options merely set flags, which can be altered later by calling set\_prolog\_flag/2 via a JPL query.

For details about the legal parameter values, see 2.4 Command Line Options in the SWI Prolog Reference Manual.

If you want or need (e.g., to use a non-standard install of SWIPL&JPL) to explicitly initialize the Prolog engine, you may want to check the following initialization template code explicitly the Prolog engine.

Creating terms

The Term-based classes in the org.jpl7 package are a structured concrete syntax for Prolog terms: they are not references to actual terms within the Prolog engine; rather, they are a means for constructing queries which can be called within Prolog, and they are also a means for representing (and exploring) the results of such calls. In particular, instances of org.jpl7.Variable are never bound nor shared; they are merely tokens.

Term instances are never changed by any activity within the Prolog engine: indeed; it doesn’t know of their existence.

The Term class is abstract, so it cannot be directly instantiated; to create a Term, one can create an instance of one of its subclasses, which are the ones accounting for the various data types in SWI-Prolog.

Below, we explain how to create Terms of different specific types. However, a convenient way to create a Term is to build one from its actual textual representation, as done in Prolog. This is done via static method:

public static Term textToTerm(String text)

For example, the following creates a Compound Term that has includes many other types as (sub)Terms:

Term t = Term.textToTerm("X = age_of(aristotle, 33)");

Here Term t is a Compound with functor = and two Terms args: a Variable Term with name “X” and a Compound Term representing Term age_of(aristotle, 33) which itself contains an Atom sub Term for “aristotle” and one Integer sub Term for 33.

Atoms

An org.jpl7.Atom instance represents a SWI Prolog text atom. To create an Atom, pass a (String) name to its constructor:

Atom a1 = new Atom("aristotle");
Atom a2 = new Atom("alexander");

As with Java strings, SWI Prolog text atoms represent arbitrarily long sequences of Unicode characters (including ASCII’s nul).

Two Atom instances with the same name are effectively identical. Feel free to reuse atoms when constructing compound terms.

The name of an atom need not be lower case: it can be any UCS string.

An atom’s name is retrieved with its name() method, e.g.

a1.name()

See org.jpl7.Atom JavaDoc for details of how SWI Prolog version 7’s strings and blobs (including reserved symbols) are accommodated.

Integers

A org.jpl7.Integer is a specialized org.jpl7.Term which holds a Java long value or a java.math.BigInteger object. This class corresponds to the Prolog integer arithmethic type.

org.jpl7.Integer i = new org.jpl7.Integer(5);

Be careful to avoid confusion with java.lang.Integer, e.g. by qualifying the class name as in the example above.

The org.jpl7.Integer class has an intValue() accessor to obtain the int value of an instance, and also longValue(), floatValue() and doubleValue() (just like java.lang.Integer has).

If isBig() returns true, then the value is outside the range of a Java long, and is retrieved by bigValue().

Rational

A org.jpl7.Rational is a specialized org.jpl7.Term which holds two Java long values for numerator and denominator. This class corresponds to the Prolog rational arithmetic type.

org.jpl7.Integer i = new org.jpl7.Rational(5, 2);

or from a String with the <number>r<number format:

org.jpl7.Integer i = new org.jpl7.Rational("5r2");

The org.jpl7.Rational class has an floatValue() and doubleValue() methods, as well as intValue() that will perform Integer division (thus dropping the decimal part). It also provides getters getNumerator() and getDenominator().

Floats

A org.jpl7.Float is a specialized org.jpl7.Term which holds a Java double value. This class corresponds to the Prolog float arithmethic type (64-bit ISO/IEC in SWI Prolog).

org.jpl7.Float f = new org.jpl7.Float(3.14159265);

As with integers, take care to avoid confusion between org.jpl7.Float and java.lang.Float.

The org.jpl7.Float class has a doubleValue() accessor to obtain the double value of an instance, and also a floatValue() accessor.

Variables

org.jpl7.Variable instances have identifying names, which must comply with conventional Prolog source text syntax.

Variable v1 = new Variable("X"); // a regular variable

Variable v2 = new Variable("_"); // an "anonymous" variable

Variable v3 = new Variable("_Y"); // a "dont-tell-me" variable, whose bindings we don't want to know

Variable v3 = new Variable(); // a "dont-tell-me" variable sequentially named _N (N is a unique number)

Note that they are just tokens to create queries, but do not behave like Prolog variables. In particular, instances of org.jpl7.Variable are never bound nor shared across queries.

So, it is not possible to extract, for example, the “binding” of a Variable. Also, a Variable does not “belong” to any query as the following code shows:

Variable v = new Variable("X");

Term s1 = new Query("? = 5", v).oneSolution().get("X"); // s1 an JPL Integer(5)
int n = s1.intValue();

Term s2 = new Query("? = hello", v).oneSolution().get("X"); // s2 a JPL Atom("hello")
String x = s2.toString();

Instances of org.jpl7.Variable have (textual) names (“X1” in this case), and bindings are retrieved by name. Thus, the role of v above is merely to build Prolog queries and provide name “X” to free variables in those queries in order to be able to access their bindings (via those names) in solution methods (in this case oneSolution()).

As the new Variable semantics from explains, all we care about a Variable is its textual name and hence Variable instances with the same name are interchangeable and thus treated as equal under Variable.equals(). This is analogous to the other Term subclasses, as JPL takes a purely syntactic view of org.jpl7.Term. For example, two different objects created via new Atom("fred") will be treated as equals via method .equals(), and the same goes for new Variable("X").

In the following example, even though two Variables instances are different and use in different queries, they are equal under .equals():

Variable v1 = new Variable("X");
Variable v2 = new Variable("X");

Term s1 = new Query("? = 5", v1).oneSolution().get("X");
Term s2 = new Query("? = 15", v2).oneSolution().get("X");

boolean same_var = v1.equals(s2);   // evaluates to True
boolean same_bindings = s1.equals(s2); // evaluates to False

The anonymous variable “_” is not equal to any other variable (including itself!), as it cannot be interchangeably used (every of its use is different).

Please refer to Creating queries and Querying Prolog below to understand how to use JPL Variables to build queries and how to access their bindings in solutions.

Compound terms

A org.jpl7.Compound is a specialized org.jpl7.Term which contains a name and an array of org.jpl7.Term arguments, and can be constructed e.g.

Compound t1 = new Compound(
    "teacher_of",
    new Term[] {
        new Atom("aristotle"),
        new Atom("alexander")
    }
);

Note the use of Java’s anonymous array syntax

new Term[] {..., ...}

to specify any quantity (perhaps zero) of arguments.

In this example, the Java variable t1 refers to a Compound instance, which represents the Prolog term teacher_of(aristotle, alexander).

It is also possible to create a Term directly from a String using static Term.textToTerm(String text). For example, we can achieve the same term as above as follows:

Compound t1 = (Compound) Term.textToTerm("teacher_of(aristotle, alexander)")

Variables, with the usual Prolog notation, can also be included as part of the Term building process; e.g.:

Compound t1 = (Compound) Term.textToTerm("teacher_of(aristotle, X)")

To obtain the (String) name of a Compound, use the name() accessor method.

public String name();

To obtain the arity of a Compound, use the arity() accessor method.

public int arity();

To obtain an array of a Compound’s arguments, use the args() accessor method.

public Term[] args();

To obtain the ith argument of a compound (numbered from 1), use the arg() accessor method (with an int parameter value between 1 and Arity inclusive).

public Term arg(int i);

To obtain the ith argument of a compound (numbered from 0), use the arg0() accessor method (with an int parameter value between 0 and Arity-1 inclusive).

public Term arg0(int i);

Lists

In SWI-Prolog a list is either:

  • An empty list []. In JPL, the empty list is the constant JPL.LIST_NIL and is a final object of class Atom. (Observe on the SWI side, from SWI-Prolog 7+, the empty list is not an atom but a reserved word.)

  • A Compound term with functor [|] and two arguments where the second one is itself a list. On the Prolog side:

      ?- A = [1,2,3,4], A =.. [X|Y].
  A = [1, 2, 3, 4],
  X = '[|]',
  Y = [1, [2, 3, 4]].

While one can build non-empty lists by creating Compound terms, it can become really cumbersome, as the second argument always has to be another lits.

So, class Term provides several static methods to conveniently build non-empty lists, namely:

public static Term textToTerm(String text)
public static Term termArrayToList(Term[] terms) 
public static Term stringArrayToList(String[] a)
public static Term intArrayToList(int[] a) 
public static Term intArrayArrayToList(int[][] a)

Method textToTerm(String text) can actually build any term form its String representation, including list terms:

Term list = Util.textToTerm("[1, B, [p(g), g(1)], c]");

A second tool is termArrayToList(Term[]), which builds a list from an Array of Terms (Term[]) (the corresponding functors [|] are added automatically). For example:

Term list = Term.termArrayToList(new Term[]     // list [1, B, hello]
        { new Integer(1), new Variable("B"), new Atom("hello") });

Finally, one can build specific data-type lists using:

  • stringArrayToList(String[] a): builds a list of atoms from an Array of Strings;
  • intArrayToList(int[] a): builds a list of integers;
  • intArrayArrayToList(int[][] a): builds a list of lists of integers.

On the other direction, the following methods in Term class transform a list Term into another Java type:

public static String toString(Term t)       
public static Term[] listToTermArray(Term t) 
public static String[] atomListToStringArray(Term t)

When it comes to non-empty, compound, list terms, the behavior of toString() will depend on boolean JPL.LIST_TOSTRING_TEXTUAL:

  • If True, lists will be represented as String in the usual Prolog textual representation [e1, e2, e3, ...., en]. Note a space wil be added after each comma always.
  • If False, lists will be represented in infix notation with the list pair functor [|], e.g., [|](1, [|](2, [|](3, '[]'))) for list [1, 2, 3].

Dictionaries

A org.jpl7.Dict is a specialized org.jpl7.Term encoding a structure with named arguments, that is, dictionaries. A Dict has a tag name as a Term and a Java Map from Atom to Term. Its String representation is of the form Tag{Key1:Value1, ...,Keyn:Valuen}.

Map<Atom, Term> map = new HashMap<Atom, Term>();

map.put(new Atom("x"), new org.jpl7.Integer(12));
map.put(new Atom("y"), new org.jpl7.Integer(23));
map.put(new Atom("z"), new Integer(312));

Dict dict = new Dict(new Atom("location"), map);

One can also create a dictionary from its String representation:

Dict d = (Dict) Term.textToTerm("location{home:loc(12,3), work:loc(32,3), school:loc(3,33)}");

To get the dictionary tag and map:

public final Term getTag();
public final Map<Atom, Term> getMap();

Java objects

From JPL 7.4, Java’s objects are not represented with Compound terms anymore, but with Blobs (see here).

A JVM object is either a Compound, Atom, or JRef:

  • Java null is represented as a Compound term @(null) and a constant JPL.JNULL is defined for that structure.
  • Java Strings are represented in Prolog by text atoms, so they should be treated as Atom instances.
  • Any other JVM objects is a JRef term which stores the object in question.

The important thing is that all three cases can be passed to Prolog, so Prolog can have access to the reference to the JVM object.

To create a JPL terms for JVM object:

  • JPL.newJRef(object) yields JPL.JNULL (if the object is null) or a JRef (if the object is not null or a String).
  • JRef(object) constructor.

To retrive the actual JVM object encoded in a JPL term, we can use Term.object():

  1. If it is indeed a term JPL.JNULL, then Java null is returned.
  2. If it is a reference to a JVM non-null object, that is the term is an instnce of JRef , then the actual object being represented is returned.
  3. Otherwise, the term does not represent an object and an eception is given.

If you don’t know what this all means, don’t worry: it only affects those writing hybrid Java+Prolog programs which call each other nestedly.

To check if a term is a JVM null, we can use Term.isNull(), which succeeds only if it is equal to the Compound @(null) term represented by JPL.JNULL.

Creating queries

A Query contains a Term, representing a Prolog goal:

Term goal = new Compound("teacher_of", new Term[] {new Atom("aristotle"), new Atom("alexander")});
Query q = new Query(goal);

The Query q in this example represents the Prolog query

?- teacher_of(aristotle, alexander).

The above Query is a ground one. To create queries with free variables we resort to JPL Variable term:

Term goal = new Compound("teacher_of", new Term[] {new Atom("aristotle"), new Variable("X")});
Query q = new Query(goal);

The Query q in this example represents the Prolog query

?- teacher_of(aristotle, X).

org.jpl7.Query implements java.util.Iterator, allowing a query’s solutions to be retrieved one at a time, each yielding a Map<String, Term> to access the solution binding for each free non-anonymous variable via their textual name (in the above example, just “X”).

As a Query is constructor from a Term, as explained above in Creating terms section, we can also build a Query directly from a String. The above Query can be built as follows:

Query q = new Query("teacher_of(aristotle, X)");

Querying Prolog

To ask the Prolog engine a query, one first constructs a Query instance, as in the above example, and then uses the java.util.Iterator interface, which the Query class implements, to obtain solutions (where a “solution” is what is known in logic programming jargon as a substitution, which is a collection of bindings represented via a Map<String, Term> object, each of which relates one of the variables within the query’s goal to a Term representation of the Prolog term to which the corresponding Prolog variable was bound by the proof).

public interface Iterator {
    public boolean hasNext();
    public Object next();
}

The hasNext() method can be used to determine whether a query has any (or any further) solutions. In the above example, the method call

q.hasNext()

returns true if the Prolog query teaches(aristotle, alexander) is provable, and false otherwise. In this example, the Prolog query is a ground term, so the “solution” to the query is merely a truth value, and is given by the hasNext() method.

Where a query contains variables, on the other hand, its execution yields a sequence of bindings of the variables’ names to Term instances. JPL uses a java.util.Map<String, Term> (implemented as a java.util.HashMap) to represent these bindings; the objects in the map are org.jpl7.Term instances, keyed (uniquely) by the String names of their associated variables.

For example, to print all of Aristotle’s pupils, i.e. all the bindings of X which satisfy teaches(aristotle,X), one could write

Query q = new Query("teaches", new Term[] {new Atom("aristotle"), new Variable("X")});
while (q.hasNext()) {
    Map<String, Term> binding = q.next();
    Term t = (Term) binding.get("X");
    System.out.println(t);
}

or, more concisely

for (Map m : new Query("teaches", new Term[] {new Atom("aristotle"), new Variable("X")})) {
    System.out.println(m.get("X"));
}

or, using a convenience constructor which builds the term from Prolog source text

for (Map m : new Query("teaches(aristotle,X)")) {
    System.out.println(m.get("X"));
}

If a query’s goal contains no variables (i.e. it is ground), the Query.next()method will return an emnpty map for each solution.

If a query’s goal contains more than one occurrence of some (named) variable, then each solution will have only one binding for that name.

Obtaining one solution

Often, you’ll want just the first solution to a query; org.jpl7.Query has a method for this:

public final Map<String, Term> oneSolution();

If the query has no solutions, this method returns null; otherwise, a non-null return indicates success. If the query is ground (i.e. contains no variables), the returned map will be empty (i.e. will contain no bindings).

If the query is non-ground (i.e., it includes variables), then bindings are retrieved by name, e.g.:

Map m = org.jpl7.Query.oneSolution("statistics(heap, X)");
long heapsize = m.get("X");

Obtaining all solutions

You may want all solutions to a query; org.jpl7.Query has a method for this:

public final Map<String, Term>[] allSolutions();

The returned array will contain all the query’s solutions, in the order they were obtained (as with Prolog’s findall/3, duplicates are not removed). If the query has no solutions, this method returns an empty array.

Ground queries

Sometimes an application is interested only in whether a query is provable, but not in any details of its possible solutions; org.jpl7.Query has a method for this common special case:

public final boolean hasSolution();

This method is equivalent to calling oneSolution and asking whether the return value is non-null (i.e. whether the query succeeded).

Terminating queries

Queries terminate automatically when hasNext() returns false (or when next() throws an exception), and once a query has terminated, its engine is returned to the pool for reuse (by any thread).

To terminate a query before all of its solutions have been exhausted, use its close() method:

public final void close();

This method stops a query, setting it back into a state where it can be restarted. Here is an example in which the first three solutions to the query are obtained:

Query query = // obtain Query somehow
for (int i = 0; i < 3 && query.hasNext(); ++i) {
    Map<String, Term> solution = query.next();
    // process solution...
}
query.close();

You may call close() on an inactive query without ill-effect, and you should always call close if you have not exhausted all solutions to a query, otherwise the associated Prolog engine will not be released.

If you are using the allSolutions(), hasSolution(), nSolutions(), or oneSolution() methods, you need not worry about closing the query; it is done automatically for you.

See Types of Queries guide for further details and explanation on both one-shot and iterative queries that can be issued from Java.

Queries from multi-threaded applications

JPL maintains a finite pool of Prolog engines, one of which is allocated to a query when it is activated (i.e. when, one way or another, a solution is requested). A query’s engine is returned to the pool when it is closed (explicitly or automatically).

If no pool engine is available when a query is activated, the activation is blocked until an engine becomes available.

Each JVM thread can have at most one Prolog engine attached. A thread may nest (stack) two or more active queries, e.g. open and close a second query while a first is active, but it may not interleave the retrieval of solutions from two open queries.

Note that engines cannot communicate thread_local predicates or global variables. That means that you can only use these from Java within a single query. If a thread activates two consecutive queries, it may get two different engines.

Note also that, once a thread has activated a query, it cannot pass it to another thread: solutions of a query must be retrieved by the thread which activated it.

See Multi Threaded Queries guide for further details and subtle issues when potentially issuing multiple queries from various threads.

Exceptions

JPL provides crude but adequate exception handling. The base class for all exceptions is org.jpl7.JPLException, which specialises java.lang.RuntimeException and hence is unchecked. Converting the exception to a java.lang.String should provide some descriptive information about the reason for the error. JPL’s only other exception class is org.jpl7.PrologException, which extends org.jpl7.JPLException.

A org.jpl7.PrologException is thrown either during execution of a Prolog built-in predicate or by an explicit call of throw/1 by application code.

Debugging

Each Term type (together with the Query class) supports an implementation of toString() which returns a more-or-less familiar Prolog textual representation of the Term or Query.

In general, Term and Query instances are represented in the form (type data), where type is the name of the type (e.g., Atom, Compound, Tuple, etc.), and data is a representation of the contents of the Term. For example, if the Term is an Atom, the data is the Atom’s name. The arguments of Compounds are represented by comma-separated lists within square brackets (‘[’ ‘]’).

Viewing the structure of a term or query can be useful in determining whether an error lies on the Prolog or Java side of your JPL applications.

Version information

To obtain the current version of JPL you are using, you may obtain a static reference to the org.jpl7.Version class by calling the org.jpl7.JPL#version static method. This will return a org.jpl7.Version structure, which has the following final fields:

package org.jpl7;
public class Version {
    public final int major;                // e.g. 7
    public final int minor;                // e.g. 4
    public final int patch;                // e.g. 0
    public final java.lang.String status;  // e.g. "alpha"
}

You may wish to use this class instance to obtain fine-grained information about the current JPL version, e.g.

if (JPL.version().major == 7) {

You may also call the version_string() static method of the org.jpl7.JPL class. This will return a String representation of the current JPL version.

The version string can be written to the standard output stream by running the main() method of the org.jpl7.JPL class.

linux% java org.jpl7.JPL
JPL 7.4.0-alpha

Gotchas

Argument numbering

The Term[] args of a Compound are indexed (like all Java arrays) from zero, whereas in Prolog the args of a structure are conventionally numbered from one.

All solutions of a Query with no solutions

Query.allSolutions() returns an empty array of Map<String, Term> if the query has no solutions (in 1.x versions it inconsistently returned null).