PB Java Client Interface - SICStus Prolog

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.

— Method on PrologSession: static PrologSession getPrologSession (String name)

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.

— Method on PrologSession: static PrologSession getPrologSession (String name, HTTPSession session)

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).

— Method on PrologSession: String getHost ()

returns the host of the Prolog server (exactly as registered in setHost).

— Method on PrologSession: void setHost (String prologServerHost)

sets the host of the Prolog server (default localhost). Either IP-address or host name is allowed.

— Method on PrologSession: int getPort ()

returns the port of the Prolog server.

— Method on PrologSession: void setPort (int port)

sets the port of the Prolog server (default 8066).

— Method on PrologSession: void connect ()

connects to the Prolog server. By default the executeQuery will automatically connect to the server when called.

— Method on PrologSession: void setAutoConnect (boolean autoConnect)

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

— Method on PrologSession: boolean isAutoConnecting ()

returns the state of the AutoConnect mode.

— Method on PrologSession: QueryAnswer executeQuery (String query)

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.

— Method on PrologSession: QueryAnswer executeQuery (String query, Bindings bindings)

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:

— Method on QueryAnswer: Term getValue (String variableName)

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.

— Method on QueryAnswer: boolean queryFailed ()

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).

— Method on QueryAnswer: boolean isError ()

returns true if there was an error.

— Method on QueryAnswer: String getError ()

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:

— Method on Term: boolean isAtom ()

returns true if the Term is an atom.

— Method on Term: boolean isInteger ()

returns true if the Term is an integer.

— Method on Term: boolean isFloat ()

returns true if the Term is a floating-point number.

— Method on Term: boolean isCompound ()

returns true if the Term is a compound term.

— Method on Term: boolean isList ()

returns true if and only if Term is a compound term with principal functor ./2.

— Method on Term: boolean isString ()

returns true if the Term is 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).

— Method on Term: boolean isVariable ()

returns true if the Term is a variable.

— Method on Term: int intValue ()

returns the int value of the integer.

— Method on Term: long longValue ()

returns the long value of the integer.

— Method on Term: float floatValue ()

returns the float value of the floating-point number.

— Method on Term: double doubleValue ()

returns the double value of the floating-point number.

— Method on Term: String getName ()

returns the functor name of the Term (see functor/3). If the Term represents a variable (isVariable() returns true), the variable name is returned.

— Method on Term: int getArity ()

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

— Method on Term: Term getArgument (int index)

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).

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.

— Method on Bindings: void bind (String name, int value)

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.

— Method on Bindings: void bind (String name, String value)

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.

— Method on Bindings: void bindAtom (String name, String value)

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.

44.5 Java Client Interface