se.sics.jasper
Class SICStus

java.lang.Object
  |
  +--se.sics.jasper.SICStus

public class SICStus

extends java.lang.Object

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.

Since SICStus does not support multiple instances of the emulator in the same process, this class is only allowed to be initialized once.

You should not inherit from SICStus.

Field Summary

java.lang.String

bootPath This is the path where SICStus finds the Runtime Library.

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

void	checkLegalCaller() Deprecated. Do not use, as of 3.8.2 this is a no-op.
int	debugLevel() Currently Unsupported, see the Release Notes.
static SICStus	getInitializedSICStus() Returns a pointer to the SICStus object which has been initialized in this JVM.
boolean	isLegalCaller() Deprecated. Do not use, as of 3.8.2 this is always true.
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.
SPQuery	openQuery(SPPredicate pred, SPTerm[] args) Deprecated Use module and predicate name directly instead.
SPQuery	openQuery(java.lang.String string, java.util.Map varMap) Open a query, specified as a string, for obtaining multiple solutions.
SPQuery	openQuery(java.lang.String module, java.lang.String name, SPTerm[] args) Open a query for obtaining multiple solutions.
boolean	query(SPPredicate pred, SPTerm[] args) Deprecated Use module and predicate name directly instead.
boolean	query(java.lang.String string, java.util.Map varMap) Find the first solution to a query specified as a string.
boolean	query(java.lang.String module, java.lang.String name, SPTerm[] args) Find 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) Find the first solution to a query specified as a string, then do a cut to remove all choicepoints and then fail, i.e., ignore everything but the side-effects during the first solution.
boolean	queryCutFail(java.lang.String module, java.lang.String name, SPTerm[] args) Find the first solution to a query, then do a cut to remove all choicepoints and then fail, i.e., ignore 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) Create 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.
boolean	setReuseTermRefs(boolean newVal) Unsupported, see the release notes for details.
boolean	setShouldCheckAge(boolean newVal) Currently Unsupported, see the release notes for details.
boolean	shouldCheckAge() Currently Unsupported, see the release notes for details.

Methods inherited from class java.lang.Object

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

Field Detail

bootPath

public java.lang.String bootPath

This is the path where SICStus finds the Runtime Library. The field is instantiated when creating the SICStus object. This variable should not be modified by the user or undefined results will occur.

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.

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

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 Prolog side 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()

checkLegalCaller

public void checkLegalCaller()

Deprecated. Do not use, as of 3.8.2 this is a no-op.

Throws an exception if the current thread is not the thread which created this instance of the SICStus object.

See Also:

isLegalCaller()

isLegalCaller

public boolean isLegalCaller()

Deprecated. Do not use, as of 3.8.2 this is always true.

Similar to checkLegalCaller(), but returns false instead of throwing an exception.

Returns:

true if the current thread is allowed to call methods in the SICStus-Prolog interface, false otherwise.

getInitializedSICStus

public static SICStus getInitializedSICStus()

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. The following code creates a SICStus object only if SICStus has not been initialized.

 SICStus sp;
 if (null == (sp = SICStus.getInitializedSICStus()))
  sp = new SICStus();
 

Returns:

A reference to an initialized SICStus object, or null if no SICStus object has been created.

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, a .ql-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. 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.

See Also:

load(java.lang.String)

query

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

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

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

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

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

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

Find the first solution to a query, then do a cut to remove all choicepoints and then fail, i.e., ignore 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

Find the first solution to a query specified as a string, then do a cut to remove all choicepoints and then fail, i.e., ignore everything but the side-effects during the first solution.

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.

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. Find the first solution to a query, then do a cut to remove all choicepoints and then fail, i.e., ignore 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

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

See Also:

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

openQuery

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

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

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

See Also:

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

readFromString

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

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

readFromString

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

Equivalent to readFromString(string, null);