com.ugos.JIProlog.engine
Class JIPEngine

java.lang.Object
  |
  +--com.ugos.JIProlog.engine.JIPEngine

All Implemented Interfaces:

java.io.Serializable

public class JIPEngine

extends java.lang.Object

implements java.io.Serializable

JIPEngine implements the JIProlog interpeter.
See the section "How to call JIProlog interpreter from Java" in the Reference Manual.

Version:

3.0

Author:

Ugo Chirico 2005
Home Page: http://www.ugosweb.com/jiprolog

See Also:

JIPQuery, Serialized Form

Constructor Summary

JIPEngine()
Constructs a new instance of JIPEngine with default values search path, input and output stream.

Method Summary

void	abolish(JIPTerm term) It is equivalent to abolish/1 predicate.
void	addEventListener(JIPEventListener listener) Adds the specified JIPEventListener object
void	addTraceListener(JIPTraceListener traceListener) Adds the specified JIPTraceListener object
void	asserta(JIPTerm term) It is equivalent to asserta/1 predicate.
void	assertz(JIPTerm term) It is equivalent to assert/1 predicate.
void	closeAllQueries() Closes all pending queries
void	closeQuery(int nQueryHandle) Closes a query.
void	compileFile(java.lang.String strFileName) Compile the specified file.
void	consultFile(java.lang.String strFileName) Consults a file.
void	consultStream(java.io.InputStream ins, java.lang.String strStreamName) Consults a Stream.
java.io.InputStream	getCurrentInputStream() Gets current InputStream
java.lang.String	getCurrentInputStreamName() Gets current InputStream Name
java.io.OutputStream	getCurrentOutputStream() Gets current OutputStream
java.lang.String	getCurrentOutputStreamName() Gets current OutputStream Name
java.lang.Object	getEnvVariable(java.lang.String varName) Gets the value of a custom environment variable.
java.util.Vector	getEventListeners() Gets the list of JIPEventListeners
static java.lang.String	getInfo() Returns JIProlog info
static java.lang.String	getLicenseInfo() Returns JIProlog license info
static java.lang.String	getLicenseType() Returns the license type or null if JIProlog is not registered
java.awt.Frame	getMainFrame() Returns the Main Frame of this instance of JIPEngine.
java.lang.String	getSearchPath() returns the search path of this instance of JIPEngine.
JIPTermParser	getTermParser() Returns the instance of JIPTermParser attached to this JIPEngine object Use JIPTermParser to parse prolog terms
boolean	getTrace() Returns the trace flag.
java.util.Vector	getTraceListeners() Gets the list of JIPTraceListener
java.io.InputStream	getUserInputStream() Gets user InputStream
java.io.OutputStream	getUserOutputStream() Gets user OutputStream
static java.lang.String	getVersion() Returns the JIProlog version
boolean	hasMoreChoicePoints(int nQueryHandle) Returns true if the query has more choice points on backtracking.
void	loadFile(java.lang.String strFileName) Loads a file.
void	loadLibrary(java.lang.String strPath) Load an extensions library.
void	loadStream(java.io.InputStream ins, java.lang.String strStreamName) Loads a stream.
void	nextSolution(int nQueryHandle) Searches for another soution.
void	notifyEvent(int nID, JIPTerm term, int nQueryHandle) Notifies a JIPEvent.
int	openQuery(JIPTerm jipquery) Opens a query.
int	openQuery(java.lang.String strQuery) Opens a query.
JIPQuery	openSynchronousQuery(JIPTerm jipquery) Returns a reference to a synchronous query.
JIPQuery	openSynchronousQuery(java.lang.String strQuery) Returns a reference to a synchronous query.
java.lang.Object	removeEnvVariable(java.lang.String varName) Removes a custom environment variable.
void	removeEventListener(JIPEventListener listener) Removes the specified JIPEventListener object
void	removeTraceListener(JIPTraceListener traceListener) Removes the specified JIPTraceListener object
void	reset() Closes all pending queries, reset the prolog interpreter and clear the database
boolean	retract(JIPTerm term) It is equivalent to retract/1 predicate.
void	setCurrentInputStream(java.io.InputStream ins, java.lang.String strStreamName) Sets current InputStream
void	setCurrentOutputStream(java.io.OutputStream outs, java.lang.String strStreamName) Sets current OutputStream
void	setEnvVariable(java.lang.String varName, java.lang.Object value) Sets the value of a custom environment variable.
void	setMainFrame(java.awt.Frame fr) Sets the Main Frame of this instance of JIPEngine The Main Frame is the frame that maybe used as parent for dialogs and windows in built-in predicates showing dialogs or windows such as winputbox/3, wmsgbox/3, etc.
void	setSearchPath(java.lang.String strSearchPath) Sets the search path of this instance of JIPEngine.
void	setTrace(boolean bTrace) Sets the trace flag.
void	setUserInputStream(java.io.InputStream ins) Sets user InputStream
void	setUserOutputStream(java.io.OutputStream outs) Sets user OutputStream
void	unconsultFile(java.lang.String strFileName) Unconsults/unloads a file.
void	unconsultStream(java.lang.String strStreamName) Unconsults/unloads a stream.

Methods inherited from class java.lang.Object

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

Constructor Detail

JIPEngine

public JIPEngine()

Constructs a new instance of JIPEngine with default values search path, input and output stream. Search path is the path where this instance of JIPEngine searches for files. The default value is the value of the environment variable user.dir
Input and Output stream are the streams where this instance of JIPEngine reads and writes. The default values are respectively System.in and System.out.

Method Detail

getVersion

public static final java.lang.String getVersion()

Returns the JIProlog version

getLicenseInfo

public static final java.lang.String getLicenseInfo()

Returns JIProlog license info

getInfo

public static final java.lang.String getInfo()

Returns JIProlog info

getLicenseType

public static final java.lang.String getLicenseType()

Returns the license type or null if JIProlog is not registered

loadLibrary

public final void loadLibrary(java.lang.String strPath)
                       throws java.io.IOException

Load an extensions library.
The library should be a valid .jar file containing a set of extension classes.
If in the .jar there is a file named init.pl it is consulted as any other prolog file. For more information see the section "Load an extension library" in the Reference Manual.

java.io.IOException

addEventListener

public void addEventListener(JIPEventListener listener)

Adds the specified JIPEventListener object

Parameters:

listener - JIPEventListener object to add

See Also:

JIPEventListener

removeEventListener

public void removeEventListener(JIPEventListener listener)

Removes the specified JIPEventListener object

Parameters:

listener - JIPEventListener object to remove

See Also:

JIPEventListener

getEventListeners

public java.util.Vector getEventListeners()

Gets the list of JIPEventListeners

Returns:

Vector containing the registered JIPEventListener objects

See Also:

JIPEventListener

addTraceListener

public void addTraceListener(JIPTraceListener traceListener)

Adds the specified JIPTraceListener object

Parameters:

traceListener - JIPTraceListener object to add

See Also:

JIPTraceListener

removeTraceListener

public void removeTraceListener(JIPTraceListener traceListener)

Removes the specified JIPTraceListener object

Parameters:

traceListener - JIPTraceListener object to remove

See Also:

JIPTraceListener

getTraceListeners

public java.util.Vector getTraceListeners()

Gets the list of JIPTraceListener

Returns:

Vector of listeners

See Also:

JIPTraceListener

setMainFrame

public final void setMainFrame(java.awt.Frame fr)

Sets the Main Frame of this instance of JIPEngine The Main Frame is the frame that maybe used as parent for dialogs and windows in built-in predicates showing dialogs or windows such as winputbox/3, wmsgbox/3, etc.

Parameters:

fr - Main Frame

See Also:

getMainFrame()

getMainFrame

public final java.awt.Frame getMainFrame()

Returns the Main Frame of this instance of JIPEngine. The Main Frame is the frame that maybe used as parent for dialogs and windows in built-in predicates showing dialogs or windows such as winputbox/3, wmsgbox/3, etc.

Returns:

The Main Frame of this JIPEngine object

See Also:

setMainFrame(java.awt.Frame)

setSearchPath

public final void setSearchPath(java.lang.String strSearchPath)
                         throws java.io.IOException

Sets the search path of this instance of JIPEngine. The Search path is the path where this instance of JIPEngine searches for files.
It can refer to:
- a directory on hard disk (d:\myapp, file:/user/myapp)
- an URL (http://www.mysite.com)
- a jar file (jar://user/myprologfile.jar)

Parameters:

strSearchPath - Search path

java.io.IOException

See Also:

getSearchPath()

getSearchPath

public final java.lang.String getSearchPath()

returns the search path of this instance of JIPEngine. The Search path is the path where this instance of JIPEngine searches for files.

Returns:

the search path of this JIPEngine object.

See Also:

setSearchPath(java.lang.String)

setTrace

public final void setTrace(boolean bTrace)

Sets the trace flag. If the flag is set all JIPTraceListeners are notified during execution.

Parameters:

bTrace - Trace flag

See Also:

getTrace()

getTrace

public final boolean getTrace()

Returns the trace flag.

See Also:

setTrace(boolean)

setUserOutputStream

public final void setUserOutputStream(java.io.OutputStream outs)

Sets user OutputStream

Parameters:

outs - the user output stream to set.

See Also:

getUserOutputStream()

getUserOutputStream

public final java.io.OutputStream getUserOutputStream()

Gets user OutputStream

Returns:

The user output stream.

See Also:

setUserOutputStream(java.io.OutputStream)

setUserInputStream

public final void setUserInputStream(java.io.InputStream ins)

Sets user InputStream

Parameters:

ins - the user input stream to set

See Also:

getUserInputStream()

getUserInputStream

public final java.io.InputStream getUserInputStream()

Gets user InputStream

Returns:

The user input stream

See Also:

setUserInputStream(java.io.InputStream)

getCurrentOutputStream

public final java.io.OutputStream getCurrentOutputStream()

Gets current OutputStream

Returns:

The current output stream

See Also:

setCurrentOutputStream(java.io.OutputStream, java.lang.String)

setCurrentOutputStream

public final void setCurrentOutputStream(java.io.OutputStream outs,
                                         java.lang.String strStreamName)

Sets current OutputStream

Parameters:

outs - the current output stream to set

See Also:

getUserOutputStream()

setCurrentInputStream

public final void setCurrentInputStream(java.io.InputStream ins,
                                        java.lang.String strStreamName)

Sets current InputStream

Parameters:

ins - the current input stream to set

strStreamName - the name of the input stream

See Also:

getUserInputStream()

getCurrentInputStream

public final java.io.InputStream getCurrentInputStream()

Gets current InputStream

Returns:

The current input stream

See Also:

setCurrentInputStream(java.io.InputStream, java.lang.String)

getCurrentInputStreamName

public final java.lang.String getCurrentInputStreamName()

Gets current InputStream Name

Returns:

The current input stream name.

getCurrentOutputStreamName

public final java.lang.String getCurrentOutputStreamName()

Gets current OutputStream Name

Returns:

The current output stream name.

reset

public void reset()

Closes all pending queries, reset the prolog interpreter and clear the database

consultFile

public final void consultFile(java.lang.String strFileName)
                       throws JIPSyntaxErrorException,
                              java.io.IOException

Consults a file. If in the file there are some no multifile predicates already consulted/loaded in another file file/stream the interpreter raises an exception.

Parameters:

strFileName - the name of the file to consult. It can refer to:
- a file on hard disk (d:\myapp/myfile.pl, file:/user/myapp/myfile.pl)
- an URL (http://www.mysite.com/myfile.pl)
- a file contained in a jar file (jar://user/myprologfile.jar#myfile.pl)
- a path relative to the search path.

Throws:

com.ugos.JIProlog.engine.JIPSyntaxErrorException, - java.io.IOException

JIPSyntaxErrorException

java.io.IOException

See Also:

loadFile(java.lang.String), setSearchPath(java.lang.String)

consultStream

public final void consultStream(java.io.InputStream ins,
                                java.lang.String strStreamName)
                         throws JIPSyntaxErrorException

Consults a Stream. If in the stream there are some no multifile predicates already consulted/loaded in another file/stream the interpreter raises an exception.

Parameters:

ins - is the stream to consult

strStreamName - is the symbolic name of the stream

Throws:

com.ugos.JIProlog.engine.JIPSyntaxErrorException, - java.io.IOException

JIPSyntaxErrorException

See Also:

loadStream(java.io.InputStream, java.lang.String), setSearchPath(java.lang.String)

unconsultFile

public final void unconsultFile(java.lang.String strFileName)

Unconsults/unloads a file. Deletes from the prolog database all clauses previously consulted or loaded with to the specified file. Note: If in the file consulted/loaded there was nested consult/load the predicates defined in the other files are not deleted.

Parameters:

strFileName - the name of the file to unconsult.

See Also:

loadFile(java.lang.String), consultFile(java.lang.String)

unconsultStream

public final void unconsultStream(java.lang.String strStreamName)

Unconsults/unloads a stream. Deletes from the prolog database all clauses previously consulted or loaded with to the specified stream. Note: If in the file consulted/loaded there was nested consult/load the predicates defined in the other files are not deleted.

Parameters:

strStreamName - the name of the stream to unconsult.

See Also:

loadStream(java.io.InputStream, java.lang.String), consultStream(java.io.InputStream, java.lang.String)

compileFile

public final void compileFile(java.lang.String strFileName)
                       throws JIPSyntaxErrorException

Compile the specified file. As result a file with .cpl extension is produced

Parameters:

strFileName - the name of the file to compile. It can refer to:
- a file on hard disk (d:\myapp/myfile.pl, file:/user/myapp/myfile.pl)
- a path relative to the search path.

Throws:

com.ugos.JIProlog.engine.JIPSyntaxErrorException, - java.io.IOException

JIPSyntaxErrorException

See Also:

loadFile(java.lang.String), setSearchPath(java.lang.String)

loadFile

public final void loadFile(java.lang.String strFileName)
                    throws java.io.IOException

Loads a file. The file must contain a valid JIProlog compiled code If in the file there are some no multifile predicates already consulted/loaded in another file the interpreter raises an exception.

Parameters:

strFileName - the name of the file to load. It can refer to:
- a file on hard disk (d:\myapp/myfile.pl, file:/user/myapp/myfile.pl)
- an URL (http://www.mysite.com/myfile.pl)
- a file contained in a jar file (jar://user/myprologfile.jar#myfile.pl)
- a path relative to the search path.

Throws:

java.io.IOException

See Also:

consultFile(java.lang.String), setSearchPath(java.lang.String)

loadStream

public final void loadStream(java.io.InputStream ins,
                             java.lang.String strStreamName)
                      throws java.io.IOException

Loads a stream. The stream must contain a valid JIProlog compiled code If in the stream there are some no multifile predicates already consulted/loaded in another file the interpreter raises an exception.

Parameters:

ins - the inpustream to load

strStreamName - the name of the file to load. It can refer to:
- a file on hard disk (d:\myapp/myfile.pl, file:/user/myapp/myfile.pl)
- an URL (http://www.mysite.com/myfile.pl)
- a file contained in a jar file (jar://user/myprologfile.jar#myfile.pl)
- a path relative to the search path.

Throws:

java.io.IOException

See Also:

loadFile(java.lang.String), setSearchPath(java.lang.String)

asserta

public final void asserta(JIPTerm term)

It is equivalent to asserta/1 predicate. Add a clause to the interpreter database at the beginning of the clauses associated to the given one.

Parameters:

term - the term to assert.

retract

public final boolean retract(JIPTerm term)

It is equivalent to retract/1 predicate. Retracts a fact or a clause that unifies with the given term from the interpreter database and, as side-effect, unifies the given term the the one retracted.

Parameters:

term - the term to retract.

assertz

public final void assertz(JIPTerm term)

It is equivalent to assert/1 predicate. Add a term to the interpreter database

Parameters:

term - the term to assert.

abolish

public final void abolish(JIPTerm term)

It is equivalent to abolish/1 predicate. abolish a term in the interpreter database

Parameters:

term - the term to abolish.

openSynchronousQuery

public JIPQuery openSynchronousQuery(java.lang.String strQuery)
                              throws JIPSyntaxErrorException

Returns a reference to a synchronous query.

Parameters:

strQuery - Query as a text string

Returns:

an instantiated JIPQuery object

Throws:

JIPSyntaxErrorException

See Also:

JIPQuery, openQuery(java.lang.String)

openSynchronousQuery

public JIPQuery openSynchronousQuery(JIPTerm jipquery)

Returns a reference to a synchronous query.

Parameters:

jipquery - Query to open

Returns:

an instantiated JIPQuery object

See Also:

JIPQuery, openQuery(java.lang.String)

openQuery

public int openQuery(java.lang.String strQuery)
              throws JIPSyntaxErrorException

Opens a query.
The registered JIPEventListeners will be notified in the openNotified method.
When a solution is found the JIPEventListeners will be notified in solutionNotified.
If an error occurs the JIPEventListeners will be notified in errorNotified.

Parameters:

strQuery - Query as a text string

Returns:

The handle of the opened query

Throws:

JIPSyntaxErrorException

See Also:

nextSolution(int), closeQuery(int), JIPEventListener.openNotified(com.ugos.JIProlog.engine.JIPEvent)

openQuery

public int openQuery(JIPTerm jipquery)

Opens a query.
The registered JIPEventListeners will be notified in the openNotified method.
When an event occurs in the interpreter the registered JIPEventListeners will be notified in the corresponding notified method.
If an error occurs the registered JIPEventListeners will be notified in errorNotified.

Parameters:

jipquery - Query as a JIPTerm

Returns:

The handle of the opened query

See Also:

JIPTermParser.parseTerm(java.lang.String), nextSolution(int), closeQuery(int), JIPEventListener

nextSolution

public void nextSolution(int nQueryHandle)

Searches for another soution. The registered JIPEventListeners will be notified in the openNotified method.
When an event occurs in the interpreter the registered JIPEventListeners will be notified in the corresponding notified method.
If an error occurs the registered JIPEventListeners will be notified in errorNotified.
If the query specified in the parameter is still running it raises a JIPIsRunningException If the query specified in the parameter is not found it raises a JIPInvalidHandleException

Parameters:

nQueryHandle - the handle of the query

See Also:

openQuery(java.lang.String), closeQuery(int), JIPEventListener

closeQuery

public void closeQuery(int nQueryHandle)

Closes a query. If the query is still running it is closed.
The registered JIPEventListeners will be notified in closeNotify. If the query specified in the parameter is not found it raises a JIPInvalidHandleException

Parameters:

nQueryHandle - the handle of the query to close

See Also:

nextSolution(int), closeQuery(int), JIPEventListener.closeNotified(com.ugos.JIProlog.engine.JIPEvent)

hasMoreChoicePoints

public boolean hasMoreChoicePoints(int nQueryHandle)

Returns true if the query has more choice points on backtracking.
If the query specified in nQueryHandle is not found it raised a JIPInvalidHandleException.
If the query specified in nQueryHandle is still running it raises a JIPIsRunningException.
Note: You should not call isDeterministic until the query has no reached the goal.

Parameters:

nQueryHandle - the handle of the query

Returns:

true if the query has more choice points, false otherwise.

See Also:

openQuery(java.lang.String), nextSolution(int), closeQuery(int)

closeAllQueries

public void closeAllQueries()

Closes all pending queries

See Also:

openQuery(java.lang.String), nextSolution(int), closeQuery(int)

setEnvVariable

public void setEnvVariable(java.lang.String varName,
                           java.lang.Object value)

Sets the value of a custom environment variable.
Environment variables may be useful in custom predicates.

Parameters:

varName - the name of the variable

value - the value of the variable

See Also:

getEnvVariable(java.lang.String), removeEnvVariable(java.lang.String)

getEnvVariable

public java.lang.Object getEnvVariable(java.lang.String varName)

Gets the value of a custom environment variable.
Environment variables may be useful in custom predicates

Parameters:

varName - the name of the variable

See Also:

setEnvVariable(java.lang.String, java.lang.Object), removeEnvVariable(java.lang.String)

removeEnvVariable

public final java.lang.Object removeEnvVariable(java.lang.String varName)

Removes a custom environment variable.
Environment variables may be useful in custom predicates

Parameters:

varName - the name of the variable to remove

See Also:

setEnvVariable(java.lang.String, java.lang.Object), getEnvVariable(java.lang.String)

notifyEvent

public final void notifyEvent(int nID,
                              JIPTerm term,
                              int nQueryHandle)

Notifies a JIPEvent.

Parameters:

nID - the ID of the event to notify

term - the term attached to the event

nQueryHandle - the handle of the query which notifies the event

See Also:

JIPEvent, JIPTraceEvent

getTermParser

public final JIPTermParser getTermParser()

Returns the instance of JIPTermParser attached to this JIPEngine object
Use JIPTermParser to parse prolog terms

See Also:

JIPTermParser