Java Interface

The Java interface is centered around the class PrologSession, which represents a connection (or session) to a Prolog server. PrologSession contains static methods for looking up named PrologSession instances using JNDI (Java Naming and Directory Interface) as well as methods for querying the Prolog server. Other important classes are: QueryAnswer, which contains the answer for a query sent to the Prolog server; Term, which represents a Prolog term; and Bindings, which supports stuffing of variable values used in queries.

General information about Java, Servlets and JNDI is available at the Java Technology site: http://java.sun.com/

A brief description of the methods in the provided Java classes are presented below. More information about the Java APIs is available in the JavaDoc files in the directory http://www.sics.se/sicstus/docs/.

The PrologSession object is the connection to the Prolog server. The constructor PrologSession() creates a PrologSession with the default settings (host = localhost, port = 8066.

PrologSession contains the following methods:

static PrologSession getPrologSession (String name) Method on PrologSession
returns the PrologSession registered in JNDI with the given name. Use this method in application servers where services are registered using JNDI. Please note: the application server must be configured to register the PrologSession with the given name for this method to work. See Tomcat configuration in PB Ex Tomcat.

static PrologSession getPrologSession (String name, HTTPSession session) Method on PrologSession
returns the PrologSession registered in JNDI with the given name. The PrologSession will make use of sessions and the session id will be the same as in the HTTPSession. Use this method in web application servers with support for servlets and HTTPSession (and when support for sessions is desired).

String getHost () Method on PrologSession
returns the host of the Prolog server (exactly as registered in setHost).

void setHost (String prologServerHost) Method on PrologSession
sets the host of the Prolog server (default localhost). Either IP-address or host name is allowed.

int getPort () Method on PrologSession
returns the port of the Prolog server.

void setPort (int port) Method on PrologSession
sets the port of the Prolog server (default 8066).

void connect () Method on PrologSession
connects to the Prolog server. By default the executeQuery will automatically connect to the server when called.

void setAutoConnect (boolean autoConnect) Method on PrologSession
sets the connection mode of this PrologSession. If set to true it will ensure that it is connected to the Prolog server as soon as a call to executeQuery or anything else causing a need for communication happens. This is by default set to true

boolean isAutoConnecting () Method on PrologSession
returns the state of the AutoConnect mode.

QueryAnswer executeQuery (String query) Method on PrologSession
sends a query to the Prolog server and waits for the answer before returning the QueryAnswer. Anonymous variables (underscore, _), will be ignored, and thus not accessible in the QueryAnswer. executeQuery throws IOException if communication problems with the server occurs. Please note: executeQuery will only return one answer.

QueryAnswer executeQuery (String query, Bindings bindings) Method on PrologSession
sends a query to the Prolog server and waits for the answer before returning the QueryAnswer. Bindings are variable bindings for the given query and will ensure that the values are stuffed correctly. An example:
          QueryAnswer answer =
             executeQuery("evaluate(In,Out)",
                          new Bindings().bind("In","4*9."));
          

The QueryAnswer contains the answer (new bindings) for a query (or the error that occurred during the query process). QueryAnswer inherits from Bindings, and extends and modifies it with the following methods:

Term getValue (String variableName) Method on QueryAnswer
returns the value of the given variable. If there is a value a Term (a parsed Prolog term) is returned, otherwise null is returned. All bindings from the query are available in the QueryAnswer.

boolean queryFailed () Method on QueryAnswer
returns true if the query failed (e.g. the Prolog returned no). In this case, there will be no answers (no new bindings, and isError will return false).

boolean isError () Method on QueryAnswer
returns true if there was an error.

String getError () Method on QueryAnswer
returns the error message (which is only set if there was an error, otherwise it will be null).

The Term object is for representing parsed Prolog terms, and has the following methods:

boolean isAtom () Method on Term
returns true if the Term is an atom.

boolean isInteger () Method on Term
returns true if the Term is an integer.

boolean isFloat () Method on Term
returns true if the Term is a floating-point number.

boolean isCompound () Method on Term
returns true if the Term is a compound term.

boolean isList () Method on Term
returns true if and only if Term is a compound term with principal functor ./2.

boolean isString () Method on Term
returns true if the Term an instance of PBString (which can be used for fast string access by a type-cast to PBString and the use of the method getString() that returns the string).

boolean isVariable () Method on Term
returns true if the Term is a variable.

int intValue () Method on Term
returns the int value of the integer.

long longValue () Method on Term
returns the long value of the integer.

float floatValue () Method on Term
returns the float value of the floating-point number.

double doubleValue () Method on Term
returns the double value of the floating-point number.

String getName () Method on Term
returns the functor name of the Term (see functor/3 in Prolog). If the Term represents a variable (isVariable() returns true), the variable name is returned.

int getArity () Method on Term
returns the number of arguments of this term (e.g. parent(A1,A2) would return 2) (see functor/3 in Prolog). If the term is not a compound term, getArity() will return 0.

Term getArgument (int index) Method on Term
returns the Term representing the argument at the position given by index. If there are no arguments, or if an argument with the specified index does not exist, IndexOutOfBoundsException will be thrown. The first argument has index one (see arg/3 in Prolog).

Bindings is used for binding variables to values in a query sent to the Prolog. The values will be automatically stuffed before they are sent to the Prolog server.

void bind (String name, int value) Method on Bindings
binds the variable with the given name to the given value. Please note: this method is also available for values of type long, float, double, and Term.

void bind (String name, String value) Method on Bindings
binds the variable with the given name to the given value. The value will be seen as a list of UNICODE character codes in Prolog.

void bindAtom (String name, String value) Method on Bindings
binds the variable with the given name to the given value. Please note: this method will encode the String as an atom when querying the Prolog server.