se.sics.jasper
Class SICStus

java.lang.Object
  se.sics.jasper.SICStus

All Implemented Interfaces:

Prolog

public class SICStus
extends java.lang.Object
implements Prolog

This class encapsulates the SICStus emulator and provides the basic functionality for interacting with Prolog. The User's Manual documents in more detail how to use this class. Refer to that document for more information.

This class uses native methods to interface with the C-Prolog interface of SICStus Prolog. Hence, this class cannot be used from within an applet.

You should not inherit from SICStus.

Constructor Summary

SICStus()
Creates a SICStus object.

SICStus(java.lang.String bootPath)
Creates a SICStus object.

SICStus(java.lang.String[] argv, java.lang.String bootPath)
Creates a SICStus object.

Method Summary

Term	consFunctor(java.lang.String functor, Term[] args) Creates a term initialized to a compound term.
Term	consList(Term head, Term tail) Creates a term initialized to a list with given head and tail.
int	debugLevel() Currently Unsupported; see the Release Notes.
static SICStus	getCaller() Returns the SICStus object corresponding to the SICStus runtime that called us.
static SICStus	getInitializedSICStus() Deprecated, do not use.
se.sics.jasper.Server	getServer() For internal use by Jasper.
void	init() Does nothing.
Term	listFromString(java.lang.String str) Creates a term initialized to a list of character codes from a Java String.
void	load(java.lang.String file) Interface to SP_load(), which in turn calls the Prolog predicate load_files/[1,2] (See the User's Manual).
static void	main(java.lang.String[] argv) This main-function is just a small test function.
Term	newObjectTerm(java.lang.Object obj) Creates a term initialized to a *global* reference to a Java object.
Prolog	newProlog() Returns the Prolog interface for this SICStus object.
Term	newTerm() Creates a null-term (i.e. the empty list, '[]').
Term	newTerm(double d) Creates a term initialized to a Prolog float.
Term	newTerm(java.lang.Double d)
Term	newTerm(float f) Creates a term initialized to a Prolog float.
Term	newTerm(java.lang.Float f)
Term	newTerm(int i) Creates a term initialized to a Prolog integer from a Java int.
Term	newTerm(java.lang.Integer i)
Term	newTerm(long j) Creates a term initialized to a Prolog integer from a Java long.
Term	newTerm(java.lang.Long j)
Term	newTerm(java.lang.String a) Creates a term initialized to a Prolog atom.
Term	newTerm(java.lang.String functor, Term[] args) Creates a term initialized to a Prolog compound term.
Term	newTerm(Term t) Creates a term initialized to an existing term.
Term	newVariable() Creates a term initialized to an unbound variable.
Term	numberFromString(java.lang.String str) Creates a term initialized to a Prolog number from a string.
Query	openPrologQuery(java.lang.String string, java.util.Map varMap) Opens a query, specified as a string, for obtaining multiple solutions.
SPQuery	openQuery(SPPredicate pred, SPTerm[] args) Deprecated Use module and predicate name directly instead.
SPQuery	openQuery(java.lang.String string, java.util.Map varMap) Opens a query, specified as a string, for obtaining multiple solutions.
SPQuery	openQuery(java.lang.String module, java.lang.String name, SPTerm[] args) Opens a query for obtaining multiple solutions.
Term	prologReadFromString(java.lang.String string, java.util.Map varMap) Creates a term by reading from a string.
boolean	query(SPPredicate pred, SPTerm[] args) Deprecated Use module and predicate name directly instead.
boolean	query(java.lang.String string, java.util.Map varMap) Finds the first solution to a query specified as a string.
boolean	query(java.lang.String module, java.lang.String name, SPTerm[] args) Finds the first solution to a query.
boolean	queryCutFail(SPPredicate pred, SPTerm[] args) Deprecated Use module and predicate name directly instead.
boolean	queryCutFail(java.lang.String string, java.util.Map varMap) Finds the first solution to a query specified as a string, then cuts away any choicepoints and fails, i.e. ignores everything but the side-effects during the first solution.
boolean	queryCutFail(java.lang.String module, java.lang.String name, SPTerm[] args) Finds the first solution to a query, then cuts away any choicepoints and fails, i.e. ignores everything but the side-effects during the first solution.
SPTerm	readFromString(java.lang.String string) Equivalent to readFromString(string, null);
SPTerm	readFromString(java.lang.String string, java.util.Map varMap) Creates a term by reading from a string.
void	restore(java.lang.String savFile) Interface to SP_restore().
boolean	reuseTermRefs() Unsupported.
int	setDebugLevel(int level) Currently Unsupported.
int	setPrintDepth(int level) Currently Unsupported.
boolean	setReuseTermRefs(boolean newVal) Unsupported; see the release notes for details.
void	setServer(se.sics.jasper.Server s) For internal use by Jasper.
boolean	setShouldCheckAge(boolean newVal) Currently Unsupported; see the release notes for details.
boolean	shouldCheckAge() Currently Unsupported; see the release notes for details.
void	startServer() Starts serving requests from a Prolog client.
void	stopServer() Stops the server.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

SICStus

public SICStus()
        throws SPException

Creates a SICStus object. Equivalent to SICStus(null,null).

Throws:

SPException - Something went wrong during startup.

See Also:

SPException

SICStus

public SICStus(java.lang.String bootPath)
        throws SPException

Creates a SICStus object. Equivalent to SICStus(null,bootPath).

Parameters:

bootPath - The path where SICStus should look for its start-up files. Currently ignored.

Throws:

SPException - Something went wrong during startup.

See Also:

SPException, SICStus(String[],String)

SICStus

public SICStus(java.lang.String[] argv,
               java.lang.String bootPath)
        throws SPException

Creates a SICStus object. This corresponds roughly to the C-Prolog interface function SP_initialize(argc, argv, options). It initializes the emulator's memory manager, allocates WAM memory areas, etc. It also loads the SICStus Runtime Library (sprt.sav), also known as the bootfile. If the bootfile cannot be found, you may specify the exact location of it by using the system property sicstus.path. If you need to set sicstus.path, it should be set to the parent directory of the directory where the Runtime Library is located.

Any (Java) system property se.sics.sicstus.property.NAME will be passed to the created SICStus instance as the (Prolog) system property NAME (since 4.1.2).

This object can only be initialized once.

Parameters:

argv - Argument vector to the emulator.

bootPath - The path where SICStus should look for its start-up files. The value should be a path such that <bootPath>/bin contains sprt.sav. Currently ignored.

Throws:

SPException - Something went wrong during startup.

See Also:

SPException, getInitializedSICStus()

Method Detail

shouldCheckAge

public final boolean shouldCheckAge()

Currently Unsupported; see the release notes for details.

See Also:

setShouldCheckAge(boolean)

setShouldCheckAge

public final boolean setShouldCheckAge(boolean newVal)

Currently Unsupported; see the release notes for details. If the argument is true then the methods on SPTerm will throw exceptions when used in a way that may potentially create dangling pointers in the Prolog heap. Returns the old value of the flag.

Off by default in the interest of backward compatibility since it will throw exception for some legal code. It is probably a good idea to turn this on for new code (and for existing non-production code). This flag will probably be on by default in the future, please try it and report good or bad experiences to sicstus-support@sics.se

Can be set with the se.sics.jasper.SICStus.checkSPTermAge system property.

reuseTermRefs

public final boolean reuseTermRefs()

Unsupported.

See Also:

setReuseTermRefs(boolean)

setReuseTermRefs

public final boolean setReuseTermRefs(boolean newVal)

Unsupported; see the release notes for details. If the argument is false then SPTerm.delete() will not make the SP_term_ref associated with the deleted SPTerm object available for re-use. Returns the old value of the flag.

This flag is currently on by default, there should be no reason to turn it off. Can be set with the se.sics.jasper.SICStus.reuseTermRefs system property.

debugLevel

public final int debugLevel()

Currently Unsupported; see the Release Notes. This method may disappear in future versions Get the current debug level.

See Also:

setDebugLevel(int)

setDebugLevel

public int setDebugLevel(int level)

Currently Unsupported. This method may disappear in future versions. Enable run-time debug checks. A value of zero disables debug checks. Returns the old debugging level. The initial debug level can be set with the se.sics.jasper.SICStus.debugLevel system propery.

main

public static void main(java.lang.String[] argv)

This main-function is just a small test function. It will try to load SICStus by creating a SICStus object and prints a message if it succeeded.

See Also:

SICStus()

getInitializedSICStus

public static SICStus getInitializedSICStus()

Deprecated, do not use. This documentation is not up-to-date!. Returns a pointer to the SICStus object which has been initialized in this JVM. Normally this reference is obtained by calling new SICStus(), but if Java has been invoked from within SICStus, it is not possible to call new SICStus() (since SICStus has already been initialized). Instead, this method can be used.

Returns:

A reference to an initialized SICStus object, or null if no SICStus object has been created. Deprecated, avoid use. This method tries to do something sensible if there are multiple sicstus objects and will work as expected if each SICStus is created in its own thread.. Some other mechanism will be introduced in the final 3.9.

load

public void load(java.lang.String file)
          throws SPException

Interface to SP_load(), which in turn calls the Prolog predicate load_files/[1,2] (See the User's Manual). Note: The preferred way to load Prolog code is through restore.

Parameters:

file - The Prolog code to load. This can be a .pl-file, or a .po-file.

Throws:

SPException - A Prolog exception was thrown.

See Also:

restore(java.lang.String)

restore

public void restore(java.lang.String savFile)
             throws SPException

Interface to SP_restore(). Restores the specified .sav-file. This is the preferred way of loading Prolog code instead of using load. This method must be called before any other SICStus method is called, and may only be used if the SICStus object has been created with new. Note that calling this method will unload all foreign resources.

Example:

 % sicstus
 SICStus 3.7 beta3: Tue Jun 02 12:29:02 MET DST 1998
 | ?- compile(bench),save_program('bench.sav').
 {compiling /home/jojo/sicstus/sicstus3/bench.pl...}
 {/home/jojo/sicstus/sicstus3/bench.pl compiled, 90 msec 6384 bytes}
 {SICStus state saved in /home/jojo/sicstus/sicstus3/bench.sav}

 yes
 | ?- halt.
 

and then restore bench.sav from Java by calling SICStus.restore().

 restore("bench.sav");
 

Parameters:

savFile - The .sav-file to restore.

Throws:

SPException

See Also:

load(java.lang.String)

setPrintDepth

public int setPrintDepth(int level)

Currently Unsupported. This method may disappear in future versions. Set the maximum print depth for the string representation of exception terms (this is what the toString method of the class SPException returns).

Parameters:

level - The new maximum print depth for exception terms.

Returns:

The old maximum print depth value. The initial maximum print depth can be set with the se.sics.jasper.SICStus.printDepth system property. The default value is 5.

query

public boolean query(java.lang.String module,
                     java.lang.String name,
                     SPTerm[] args)
              throws SPException,
                     IllegalTermException

Finds the first solution to a query. If you need more than one solution, use openQuery.

Parameters:

module - The module used for the query.

name - The predicate name used for the query.

args - The arguments to the predicate. The number of arguments must match the functor of the predicate.

Returns:

true/false corresponding to success/failure of the query.

Throws:

SPException - If a Prolog exception was thrown.

IllegalTermException

See Also:

openQuery(java.lang.String, java.lang.String, se.sics.jasper.SPTerm[]), SPException, SPTerm

query

public boolean query(java.lang.String string,
                     java.util.Map varMap)
              throws SPException

Finds the first solution to a query specified as a string. If you need more than one solution, use openQuery.

Specified by:

query in interface Prolog

Parameters:

string - The goal to use for the query, with terminating period.

varMap - The arguments to the predicate as a map from variable names to SPTerm objects. On success varMap will get entries added for all variables (with names not starting with underscore) in the goal that were not already present as input. May be null. Allocates one SPTerm for each entry added to the map (and, possibly, a small number of SPTerm objects for internal use). If varMap is null then this method behaves as if no SPTerm objects were created.

Returns:

True/false corresponding to success/failure of the query.

Throws:

SPException - If a Prolog exception was thrown.

See Also:

openQuery(java.lang.String, java.lang.String, se.sics.jasper.SPTerm[]), queryCutFail(java.lang.String, java.lang.String, se.sics.jasper.SPTerm[]), SPTerm

query

public boolean query(SPPredicate pred,
                     SPTerm[] args)
              throws SPException,
                     IllegalTermException

Deprecated Use module and predicate name directly instead. Finds the first solution to a query. If you need more than one solution, use openQuery.

Parameters:

pred - The predicate object to use for the query.

args - The arguments to the predicate. The number of arguments must match the functor of the predicate.

Returns:

True/false corresponding to success/failure of the query.

Throws:

SPException - If a Prolog exception was thrown.

IllegalTermException

See Also:

openQuery(java.lang.String, java.lang.String, se.sics.jasper.SPTerm[]), SPException, SPPredicate, SPTerm

queryCutFail

public boolean queryCutFail(java.lang.String module,
                            java.lang.String name,
                            SPTerm[] args)
                     throws SPException

Finds the first solution to a query, then cuts away any choicepoints and fails, i.e. ignores everything but the side-effects during the first solution.

Parameters:

module - The module used for the query.

name - The predicate name used for the query.

args - The arguments to the predicate.

Returns:

True/false corresponding to success/failure of the query.

Throws:

SPException

See Also:

SPException

queryCutFail

public boolean queryCutFail(java.lang.String string,
                            java.util.Map varMap)
                     throws SPException

Finds the first solution to a query specified as a string, then cuts away any choicepoints and fails, i.e. ignores everything but the side-effects during the first solution.

Specified by:

queryCutFail in interface Prolog

Parameters:

string - The goal to use for the query, with terminating period.

varMap - The arguments to the predicate as a map from variable names to SPTerm objects. May be null. No bindings are added.

Returns:

True/false corresponding to success/failure of the query.

Throws:

SPException

See Also:

query(java.lang.String, java.lang.String, se.sics.jasper.SPTerm[])

queryCutFail

public boolean queryCutFail(SPPredicate pred,
                            SPTerm[] args)
                     throws SPException

Deprecated Use module and predicate name directly instead. Finds the first solution to a query, then cuts away any choicepoints and fails, i.e. ignores everything but the side-effects during the first solution.

Parameters:

pred - The predicate object used for the query.

args - The arguments to the predicate. The number of arguments must match the functor of the predicate.

Returns:

True/false corresponding to success/failure of the query.

Throws:

SPException

See Also:

SPException, SPPredicate

openQuery

public SPQuery openQuery(java.lang.String module,
                         java.lang.String name,
                         SPTerm[] args)
                  throws IllegalTermException,
                         SPException

Opens a query for obtaining multiple solutions. The method itself does not find any solutions; use the method nextSolution to do that. When no more solutions are needed, the query must be closed using methods close or cut on the query-object.

Multiple queries can be open at the same time. See nextSolution for details and restrictions.

Parameters:

module - The module used for the query.

name - The predicate name used for the query.

args - The arguments to the predicate. The number of arguments must match the functor of the predicate.

Returns:

The openened query object.

Throws:

IllegalTermException

SPException

See Also:

SPQuery.nextSolution(), SPQuery.close(), SPQuery.cut()

openQuery

public SPQuery openQuery(java.lang.String string,
                         java.util.Map varMap)
                  throws SPException

Opens a query, specified as a string, for obtaining multiple solutions. The method itself does not find any solutions; use the method nextSolution to do that. When no more solutions are needed, the query must be closed using methods close or cut on the query-object.

Multiple queries can be open at the same time. See nextSolution for details and restrictions.

Allocates one SPTerm for each entry added to the map (and, possibly, a small number of SPTerm objects for internal use). If varMap is null then this method behaves as if no SPTerm objects were created. When the query is closed (or cut) then all SPTerm objects are reclaimed.

Parameters:

string - The goal to use for the query, with terminating period.

varMap - The arguments to the predicate as a map from variable names to SPTerm objects. The map will get entries added for all variables (with names not starting with underscore) in the goal that were not already present as input. May be null.

Returns:

The openened query object.

Throws:

SPException

See Also:

SPQuery.nextSolution(), SPQuery.close(), SPQuery.cut()

openQuery

public SPQuery openQuery(SPPredicate pred,
                         SPTerm[] args)
                  throws IllegalTermException,
                         SPException

Deprecated Use module and predicate name directly instead. Opens a query for obtaining multiple solutions. The method itself does not find any solutions; use the method nextSolution to do that. When no more solutions are needed, the query must be closed using methods close or cut on the query-object.

Multiple queries can be open at the same time. See nextSolution for details and restrictions.

Parameters:

pred - The predicate-object to open a query on.

args - The arguments to the predicate. The number of arguments must match the functor of the predicate.

Returns:

The openened query object.

Throws:

IllegalTermException

SPException

See Also:

SPQuery.nextSolution(), SPQuery.close(), SPQuery.cut(), SPPredicate

readFromString

public SPTerm readFromString(java.lang.String string,
                             java.util.Map varMap)
                      throws SPException

Creates a term by reading from a string.

Parameters:

string - The printed representation of the term, with terminating period.

varMap - Bindings for any variables occurring in the term, as a map from variable names to SPTerm objects. The map will get entries added for all variables (with names not starting with underscore) in the term that were not already present as input. May be null. Allocates one SPTerm for each entry added to the map (and, possibly, a small number of SPTerm objects for internal use). If varMap is null then this method behaves as if only the returned SPTerm object were created.

Throws:

SPException

readFromString

public SPTerm readFromString(java.lang.String string)
                      throws SPException

Equivalent to readFromString(string, null);

Throws:

SPException

openPrologQuery

public Query openPrologQuery(java.lang.String string,
                             java.util.Map varMap)
                      throws SPException

Description copied from interface: Prolog

Opens a query, specified as a string, for obtaining multiple solutions. The method itself does not find any solutions; use the method nextSolution to do that. When no more solutions are needed, the query must be closed using methods close or cut on the query-object.

Multiple queries can be open at the same time. See nextSolution for details and restrictions.

Specified by:

openPrologQuery in interface Prolog

Parameters:

string - The goal to use for the query, with terminating period.

varMap - The arguments to the predicate as a map from variable names to Term objects. The map will get entries added for all variables (with names not starting with underscore) in the goal that were not already present as input. May be null.

Returns:

The openened query object.

Throws:

SPException

See Also:

Query.nextSolution(), Query.close(), Query.cut()

prologReadFromString

public Term prologReadFromString(java.lang.String string,
                                 java.util.Map varMap)
                          throws SPException

Description copied from interface: Prolog

Creates a term by reading from a string.

Specified by:

prologReadFromString in interface Prolog

Parameters:

string - The printed representation of the term, with terminating period.

varMap - Bindings for any variables occurring in the term, as a map from variable names to Term objects. The map will get entries added for all variables (with names not starting with underscore) in the term that were not already present as input. May be null.

Throws:

SPException

newTerm

public Term newTerm()

Description copied from interface: Prolog

Creates a null-term (i.e. the empty list, '[]').

Specified by:

newTerm in interface Prolog

newTerm

public Term newTerm(Term t)
             throws IllegalTermException,
                    ConversionFailedException

Description copied from interface: Prolog

Creates a term initialized to an existing term. Modifications to the created Term does not affect the input Term.

Specified by:

newTerm in interface Prolog

Parameters:

t - The Term object whose term to use

Throws:

IllegalTermException

ConversionFailedException

newTerm

public Term newTerm(java.lang.Integer i)

newTerm

public Term newTerm(int i)

Description copied from interface: Prolog

Creates a term initialized to a Prolog integer from a Java int.

Specified by:

newTerm in interface Prolog

Parameters:

i - Initial value of the integer.

newTerm

public Term newTerm(java.lang.Long j)
             throws IllegalTermException,
                    ConversionFailedException

Throws:

IllegalTermException

ConversionFailedException

newTerm

public Term newTerm(long j)
             throws IllegalTermException,
                    ConversionFailedException

Description copied from interface: Prolog

Creates a term initialized to a Prolog integer from a Java long.

Specified by:

newTerm in interface Prolog

Parameters:

j - Initial value of the integer (long).

Throws:

IllegalTermException

ConversionFailedException

newTerm

public Term newTerm(java.lang.Double d)

newTerm

public Term newTerm(double d)

Description copied from interface: Prolog

Creates a term initialized to a Prolog float.

Specified by:

newTerm in interface Prolog

Parameters:

d - Initial value of the float.

newTerm

public Term newTerm(java.lang.Float f)

newTerm

public Term newTerm(float f)

Description copied from interface: Prolog

Creates a term initialized to a Prolog float.

Specified by:

newTerm in interface Prolog

Parameters:

f - Initial value of the float.

newTerm

public Term newTerm(java.lang.String a)
             throws ConversionFailedException

Description copied from interface: Prolog

Creates a term initialized to a Prolog atom.

Specified by:

newTerm in interface Prolog

Parameters:

a - String describing the initial value of the atom.

Throws:

ConversionFailedException

newTerm

public Term newTerm(java.lang.String functor,
                    Term[] args)
             throws ConversionFailedException,
                    IllegalTermException

Description copied from interface: Prolog

Creates a term initialized to a Prolog compound term.

Specified by:

newTerm in interface Prolog

Parameters:

functor - The functor of the compound term as a string

args - The arguments as an array of Terms

Throws:

ConversionFailedException

IllegalTermException

newVariable

public Term newVariable()
                 throws ConversionFailedException,
                        IllegalTermException

Description copied from interface: Prolog

Creates a term initialized to an unbound variable.

Specified by:

newVariable in interface Prolog

Throws:

ConversionFailedException

IllegalTermException

consFunctor

public Term consFunctor(java.lang.String functor,
                        Term[] args)
                 throws ConversionFailedException,
                        IllegalTermException

Description copied from interface: Prolog

Creates a term initialized to a compound term.

Specified by:

consFunctor in interface Prolog

Parameters:

functor - The term's functor as a Java String

args - The arguments of the term

Throws:

ConversionFailedException

IllegalTermException

consList

public Term consList(Term head,
                     Term tail)
              throws ConversionFailedException,
                     IllegalTermException

Description copied from interface: Prolog

Creates a term initialized to a list with given head and tail.

Specified by:

consList in interface Prolog

Parameters:

head - The head of the list

tail - The tail of the list

Throws:

ConversionFailedException

IllegalTermException

newObjectTerm

public Term newObjectTerm(java.lang.Object obj)
                   throws IllegalTermException,
                          ConversionFailedException

Description copied from interface: Prolog

Creates a term initialized to a *global* reference to a Java object.

Specified by:

newObjectTerm in interface Prolog

Parameters:

obj - A reference to a Java object.

Throws:

IllegalTermException

ConversionFailedException

numberFromString

public Term numberFromString(java.lang.String str)
                      throws ConversionFailedException,
                             IllegalTermException

Description copied from interface: Prolog

Creates a term initialized to a Prolog number from a string.

Specified by:

numberFromString in interface Prolog

Parameters:

str - The string containing the printed representation of the number.

Throws:

ConversionFailedException

IllegalTermException

listFromString

public Term listFromString(java.lang.String str)
                    throws ConversionFailedException,
                           IllegalTermException

Description copied from interface: Prolog

Creates a term initialized to a list of character codes from a Java String.

Specified by:

listFromString in interface Prolog

Parameters:

str - The string of characters.

Throws:

ConversionFailedException

IllegalTermException

newProlog

public Prolog newProlog()
                 throws java.lang.InterruptedException

Returns the Prolog interface for this SICStus object. If a client object already exists, return that object, else create a server and a client (Prolog) interface for this SICStus object, and return the new client. The server may be started by calling startServer()

Throws:

java.lang.InterruptedException

getCaller

public static SICStus getCaller()

Returns the SICStus object corresponding to the SICStus runtime that called us.

startServer

public void startServer()

Starts serving requests from a Prolog client. This method does not return until another thread calls stopServer(). Before calling this method you should call newProlog() and hand the result over to another Thread.

stopServer

public void stopServer()

Stops the server. Calling this method causes the Thread running in the startServer() method to return.

getServer

public se.sics.jasper.Server getServer()

Description copied from interface: Prolog

For internal use by Jasper.

Specified by:

getServer in interface Prolog

setServer

public void setServer(se.sics.jasper.Server s)

For internal use by Jasper.

init

public void init()

Does nothing.