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.


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()
          Throws an exception if the current thread is not the thread which created this instance of the SICStus object.
 void finalize()
          Deallocates memory used by native code and calls SP_deinitialize to deallocate and unload resources used by the emulator.
static SICStus getInitializedSICStus()
          Returns a pointer to the SICStus object which has been initialized in this JVM.
 boolean isLegalCaller()
          Similar to checkLegalCaller(), but returns false instead of throwing an exception.
 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)
          Open a query for obtaining multiple solutions.
 boolean query(SPPredicate pred, SPTerm[] args)
          Find the first solution to a query.
 boolean queryCutFail(SPPredicate pred, SPTerm[] args)
          Find the first solution to a query, then do a cut to remove all choicepoints and then fail, i.e.
 void restore(java.lang.String savFile)
          Interface to SP_restore().
 
Methods inherited from class java.lang.Object
clone, equals, 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

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()
                      throws IllegalCallerException
Throws an exception if the current thread is not the thread which created this instance of the SICStus object.
Throws:
IllegalCallerException -  
See Also:
isLegalCaller()

isLegalCaller

public boolean isLegalCaller()
                      throws IllegalCallerException
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,
                 IllegalCallerException
Interface to SP_load(), which in turn calls the Prolog predicate load_files/[1-2] (See the User's Manual).
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.
IllegalCallerException -  
See Also:
SPException, restore(java.lang.String)

restore

public void restore(java.lang.String savFile)
             throws SPException,
                    IllegalCallerException
Interface to SP_restore(). Restores the specified .sav-file. This is the preferred way of loading Prolog code instead of using SP_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.
Throws:
SPException - Something went wrong.
IllegalCallerException -  
See Also:
SPException, load(java.lang.String)

finalize

public void finalize()
Deallocates memory used by native code and calls SP_deinitialize to deallocate and unload resources used by the emulator.
Overrides:
finalize in class java.lang.Object

query

public boolean query(SPPredicate pred,
                     SPTerm[] args)
              throws SPException,
                     IllegalCallerException
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.
IllegalCallerException -  
See Also:
openQuery(se.sics.jasper.SPPredicate, se.sics.jasper.SPTerm[]), SPException, SPPredicate, SPTerm

queryCutFail

public boolean queryCutFail(SPPredicate pred,
                            SPTerm[] args)
                     throws SPException,
                            IllegalCallerException
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 -  
IllegalCallerException -  
See Also:
SPException, SPPredicate

openQuery

public SPQuery openQuery(SPPredicate pred,
                         SPTerm[] args)
                  throws IllegalCallerException
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 method close 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:
Returns a query-object.
Throws:
IllegalCallerException -  
See Also:
SPQuery.nextSolution(), SPException, SPPredicate, SPQuery.close()