tools.jinnide
Interface IJinniEngine

All Superinterfaces:

java.rmi.Remote

All Known Implementing Classes:

JinniEngine, JinniRmiImpl

public interface IJinniEngine
extends java.rmi.Remote

This is the interface for a Jinni Engine. Implementations provide different flavours e.g. for different types of output style.

TODO Make several interfaces of this one e.g. IJinnIdeEngine,IBasicJinniEngine,IdemJinniEngine,..

Version:

Cassandra

Author:

Wolfgang Chico Toepfer

Nested Class Summary

static class

IJinniEngine.EngineState

Method Summary

java.lang.String	consult(java.lang.String filePath) consults a file
java.lang.String	getInitializationFile() find out the name of the initialization file used to start up the Jinni engine
java.lang.String	getJinniOutput() this one is implemented by all the specialization classes because it includes getting the output (but not the direct feedback)
java.lang.String	getLibraryPath() find out the path of the current Jinni engine's system library
JinniEngineAnswer	getQuery(java.lang.String validator, java.lang.String value) asks a question to Jinni and returns a Jinni solution, which is only the first solution in foreground mode returned as a JinniEngineAnswer so focussed on true/false validation
JinniEngineAnswer	getSimpleQuery(java.lang.String validator, java.lang.String value) asks a question to Jinni and returns a Jinni solution, which is only the first solution in foreground mode returned as a JinniEngineAnswer so focussed on true/false validation
java.lang.String	getStartupFeedback() Returns and sets engine feedback as a by result of a query, usually the first consulting query to load the lib
IJinniEngine.EngineState	getState() Informs the client of this engine's state
java.lang.String	getVersion()
void	halt() this is one of a couple of reset methods for the Jinni server process (only halt affects the RMI server process ) such as reset which does an internal reset of the Jinni engine, should be used with care
boolean	isAllModeUsed() find out if the all mode is active
boolean	isBackgroundModeUsed() find out if the background mode is active
boolean	isPrologModeUsed() find out if the prolog mode is active
boolean	isTraceModeUsed() find out if the usual prolog trace mode is active
java.lang.String	jinnidoc(java.lang.String directoryPath) generates a documentation for a whole directory
java.lang.String	jinnidoc(java.lang.String filePath, java.lang.String filename) generates a documentation for a file
void	kill() kill the entire server process by force despite pending client requests
java.lang.String	listing() lists the current clauses in the current Jinni engine instance
java.lang.String	loadEngine() loads the engine with classpaths, consults etc.; is implicitly done in startupEngine
java.lang.String	more() returns the next solution if available otherwise no
JinniEngineAnswer	moreAsAnswer() returns the next solution as a JinniEngineAnswer if available otherwise no
java.lang.String	query(java.lang.String query) asks a question to Jinni and returns a Jinni solution, which is either all solutions in case of using the all mode, or otherwise just the first solution
java.lang.String	reconsult(java.lang.String filePath) reconsult a file
java.lang.String	renew(java.lang.String objectName) renew a Jinni object
java.lang.String	renewLoq4Jinni() renews Loq4Jinni's state to update to another logging level which is set otherwise
java.lang.String	reset() does an internal restart of the current Jinni engine
java.lang.String	restart() restarts the Jinni server process without affecting the RMI server process
void	setAllMode(boolean isAllModeUsed) allows switching between the usual prolog solution by solution mode and getting all solutions at once which is when isAllModeUsed must be true
void	setBackgroundMode() allows switching on and off the background mode which allows running a query on the server in a separate thread while other queries may be answered in sort-of the same time while the other query is still running; There is no server-side usage because a JinniProlog server is actually a rather different alternative with its own advantages (and drwabacks ;), thus it would not implement this method (actually we could move this declaration to an abstract method somewhere below this interface).
void	setInitializationFile(java.lang.String filename) sets the name of the file that is supposed to lie in the library set by setLibraryPath, if not set "init.pro" is assumed
void	setJinniOutput(javax.swing.JTextArea area) sets the text area that is used to insert all the output that is not the direct feedback of a query; if this method is not called, a default JTextArea is used
void	setLibraryPath(java.lang.String path) set developer library path where on the first level an initialization file resides that is consulted by loadEngine which is all loadEngine actually does; if not set, the directory relative to this class library is assumed
void	setPrologMode(boolean isPrologModeUsed) choose between a prolog mode which is the JinniPrologEngine and the pure mode which is the JinniPureEngine
void	setStartupFeedback(java.lang.String feedback)
void	setTraceMode(boolean isTraceModeUsed) allows switching on the usual prolog trace mode
java.lang.String	startupEngine() starts up the default engine (without providing setup parameters)
java.lang.String	startupEngine(java.lang.String[] params) starts up the engine
java.lang.String	stopEngine() stops the engine and thus sets the system back to its initial state including a possibly running thread that is also stopped
java.lang.String	stopThread() this one is implemented by all the specialization classes because it includes stopping the specific machine
void	terminate() kill the entire server process gently waiting for pending client requests to complete

Method Detail

getVersion

java.lang.String getVersion()
                            throws java.rmi.RemoteException

Returns:

current version of Jinni used

Throws:

java.rmi.RemoteException

query

java.lang.String query(java.lang.String query)
                       throws JinniEngineException,
                              java.rmi.RemoteException

asks a question to Jinni and returns a Jinni solution, which is either all solutions in case of using the all mode, or otherwise just the first solution

Parameters:

query - the query to be asked

Returns:

Jinni's query response

Throws:

JinniEngineException

java.rmi.RemoteException

getSimpleQuery

JinniEngineAnswer getSimpleQuery(java.lang.String validator,
                                 java.lang.String value)
                                 throws JinniEngineException,
                                        java.rmi.RemoteException

asks a question to Jinni and returns a Jinni solution, which is only the first solution in foreground mode returned as a JinniEngineAnswer so focussed on true/false validation

Parameters:

value - the value to be validated e.g. a number (passed as a String)

validator - the validator to be used which is an indication of the desired validation predicate e.g. "validate" or "askItSomething"

Returns:

Jinni's response wrapped up in a JinniEngineAnswer instance

Throws:

JinniEngineException

java.rmi.RemoteException

getQuery

JinniEngineAnswer getQuery(java.lang.String validator,
                           java.lang.String value)
                           throws JinniEngineException,
                                  java.rmi.RemoteException

asks a question to Jinni and returns a Jinni solution, which is only the first solution in foreground mode returned as a JinniEngineAnswer so focussed on true/false validation

Parameters:

value - the value to be validated

validator - the validator to be used which is an indication of the validation module and the desired validation predicate e.g. "validator:validate" or "validator:askMeSomething"; its syntax is idential with Jinni's module predicate call syntax so always uses a colon to separate the module from the predicate

Returns:

Jinni's response wrapped up in a JinniEngineAnswer instance

Throws:

JinniEngineException

java.rmi.RemoteException

more

java.lang.String more()
                      throws JinniEngineException,
                             java.rmi.RemoteException

returns the next solution if available otherwise no

Returns:

Jinni's query response when being asked for a further solution

Throws:

JinniEngineException

java.rmi.RemoteException

moreAsAnswer

JinniEngineAnswer moreAsAnswer()
                               throws JinniEngineException,
                                      java.rmi.RemoteException

returns the next solution as a JinniEngineAnswer if available otherwise no

Returns:

Jinni's query response wrapped up as a JinniEngineAnswer instance when being asked for a further solution

Throws:

JinniEngineException

java.rmi.RemoteException

consult

java.lang.String consult(java.lang.String filePath)
                         throws JinniEngineException,
                                java.rmi.RemoteException

consults a file

Parameters:

filePath - path to the file/directory to be consulted

Returns:

consult the given file, returns jinni's answer on this query; note that a '/' or '\' suffix indicates that a whole directory is going to be consulted

Throws:

JinniEngineException

java.rmi.RemoteException

reconsult

java.lang.String reconsult(java.lang.String filePath)
                           throws JinniEngineException,
                                  java.rmi.RemoteException

reconsult a file

Parameters:

filePath - path to the file/directory to be reconsulted

Returns:

reconsult the given file, returns jinni's answer on this query; note that a '/' or '\' suffix indicates that a whole directory is going to be reconsulted

Throws:

JinniEngineException

java.rmi.RemoteException

jinnidoc

java.lang.String jinnidoc(java.lang.String filePath,
                          java.lang.String filename)
                          throws JinniEngineException,
                                 java.rmi.RemoteException

generates a documentation for a file

Parameters:

filePath - path to the file to be documented

filename - name of the file to be documented

Returns:

generates a documentation for the given file, returns the query response

Throws:

JinniEngineException

java.rmi.RemoteException

jinnidoc

java.lang.String jinnidoc(java.lang.String directoryPath)
                          throws JinniEngineException,
                                 java.rmi.RemoteException

generates a documentation for a whole directory

Parameters:

directoryPath - path to the directory to be documented

Returns:

generates a documentation for a whole directory, returns the query response

Throws:

JinniEngineException

java.rmi.RemoteException

listing

java.lang.String listing()
                         throws JinniEngineException,
                                java.rmi.RemoteException

lists the current clauses in the current Jinni engine instance

Returns:

returns all the current clauses in the current jinni engine

Throws:

JinniEngineException

java.rmi.RemoteException

renew

java.lang.String renew(java.lang.String objectName)
                       throws JinniEngineException,
                              java.rmi.RemoteException

renew a Jinni object

Parameters:

objectName - name of the object to be renewed

Returns:

renew a Jinni object i.e. updates the class object information and so allows creating new instances with an updated version of the Jinni object, returns Jinni's response

Throws:

JinniEngineException

java.rmi.RemoteException

renewLoq4Jinni

java.lang.String renewLoq4Jinni()
                                throws JinniEngineException,
                                       java.rmi.RemoteException

renews Loq4Jinni's state to update to another logging level which is set otherwise

Returns:

allows switching the logging level of Loq4Jinni, returns Jinni's response

Throws:

JinniEngineException

java.rmi.RemoteException

setAllMode

void setAllMode(boolean isAllModeUsed)
                throws java.rmi.RemoteException

allows switching between the usual prolog solution by solution mode and getting all solutions at once which is when isAllModeUsed must be true

Parameters:

isAllModeUsed - actual switch value to be set

Throws:

java.rmi.RemoteException

setTraceMode

void setTraceMode(boolean isTraceModeUsed)
                  throws java.rmi.RemoteException,
                         JinniEngineException

allows switching on the usual prolog trace mode

Parameters:

isTraceModeUsed - actual switch value to be set

Throws:

java.rmi.RemoteException

JinniEngineException

isTraceModeUsed

boolean isTraceModeUsed()
                        throws java.rmi.RemoteException

find out if the usual prolog trace mode is active

Returns:

true iff the trace is active

Throws:

java.rmi.RemoteException

isAllModeUsed

boolean isAllModeUsed()
                      throws java.rmi.RemoteException

find out if the all mode is active

Returns:

true iff the all mode is active

Throws:

java.rmi.RemoteException

setBackgroundMode

void setBackgroundMode()
                       throws java.rmi.RemoteException,
                              JinniEngineException

allows switching on and off the background mode which allows running a query on the server in a separate thread while other queries may be answered in sort-of the same time while the other query is still running; There is no server-side usage because a JinniProlog server is actually a rather different alternative with its own advantages (and drwabacks ;), thus it would not implement this method (actually we could move this declaration to an abstract method somewhere below this interface).

Throws:

java.rmi.RemoteException

JinniEngineException

isBackgroundModeUsed

boolean isBackgroundModeUsed()
                             throws java.rmi.RemoteException

find out if the background mode is active

Returns:

true iff the background mode is active

Throws:

java.rmi.RemoteException

setPrologMode

void setPrologMode(boolean isPrologModeUsed)
                   throws java.rmi.RemoteException,
                          JinniEngineException

choose between a prolog mode which is the JinniPrologEngine and the pure mode which is the JinniPureEngine

Parameters:

isPrologModeUsed - actual switch value to be set

Throws:

java.rmi.RemoteException

JinniEngineException

isPrologModeUsed

boolean isPrologModeUsed()
                         throws java.rmi.RemoteException,
                                JinniEngineException

find out if the prolog mode is active

Returns:

true iff the prolog mode is active

Throws:

java.rmi.RemoteException

JinniEngineException

halt

void halt()
          throws JinniEngineException,
                 java.rmi.RemoteException,
                 java.net.MalformedURLException,
                 java.rmi.NotBoundException

this is one of a couple of reset methods for the Jinni server process (only halt affects the RMI server process ) such as reset which does an internal reset of the Jinni engine, should be used with care

Throws:

JinniEngineException

java.rmi.NotBoundException

java.net.MalformedURLException

java.rmi.RemoteException

reset

java.lang.String reset()
                       throws JinniEngineException,
                              java.rmi.RemoteException

does an internal restart of the current Jinni engine

Returns:

the query response regarding the success or failure of the mode switch

Throws:

JinniEngineException

java.rmi.RemoteException

restart

java.lang.String restart()
                         throws JinniEngineException,
                                java.rmi.RemoteException

restarts the Jinni server process without affecting the RMI server process

Returns:

the query response regarding the success or failure of the mode switch

Throws:

JinniEngineException

java.rmi.RemoteException

stopEngine

java.lang.String stopEngine()
                            throws JinniEngineException,
                                   java.rmi.RemoteException

stops the engine and thus sets the system back to its initial state including a possibly running thread that is also stopped

Returns:

the query response regarding the success or failure of the mode switch

Throws:

JinniEngineException

java.rmi.RemoteException

startupEngine

java.lang.String startupEngine()
                               throws JinniEngineException,
                                      java.rmi.RemoteException

starts up the default engine (without providing setup parameters)

Returns:

returns some initial feedback

Throws:

JinniEngineException

java.rmi.RemoteException

startupEngine

java.lang.String startupEngine(java.lang.String[] params)
                               throws JinniEngineException,
                                      java.rmi.RemoteException

starts up the engine

Parameters:

params - Jinni initialization parameters that may be set here

Returns:

returns some initial feedback

Throws:

JinniEngineException

java.rmi.RemoteException

getInitializationFile

java.lang.String getInitializationFile()
                                       throws java.rmi.RemoteException

find out the name of the initialization file used to start up the Jinni engine

Returns:

the name of the initialization file see setInitializationFile

Throws:

java.rmi.RemoteException

setInitializationFile

void setInitializationFile(java.lang.String filename)
                           throws JinniEngineException,
                                  java.rmi.RemoteException

sets the name of the file that is supposed to lie in the library set by setLibraryPath, if not set "init.pro" is assumed

Parameters:

filename - name of the initialization file

Throws:

JinniEngineException

java.rmi.RemoteException

setLibraryPath

void setLibraryPath(java.lang.String path)
                    throws JinniEngineException,
                           java.rmi.RemoteException

set developer library path where on the first level an initialization file resides that is consulted by loadEngine which is all loadEngine actually does; if not set, the directory relative to this class library is assumed

Parameters:

path - path to the JinnIde sytem library

Throws:

JinniEngineException

java.rmi.RemoteException

getLibraryPath

java.lang.String getLibraryPath()
                                throws java.rmi.RemoteException

find out the path of the current Jinni engine's system library

Returns:

returns the current library path, see setLibraryPath

Throws:

java.rmi.RemoteException

loadEngine

java.lang.String loadEngine()
                            throws JinniEngineException,
                                   java.rmi.RemoteException

loads the engine with classpaths, consults etc.; is implicitly done in startupEngine

Returns:

Jinni's feedback message

Throws:

JinniEngineException

java.rmi.RemoteException

stopThread

java.lang.String stopThread()
                            throws JinniEngineException,
                                   java.rmi.RemoteException

this one is implemented by all the specialization classes because it includes stopping the specific machine

Returns:

the query response regarding the success or failure of the stop process

Throws:

JinniEngineException

java.rmi.RemoteException

getJinniOutput

java.lang.String getJinniOutput()
                                throws JinniEngineException,
                                       java.rmi.RemoteException

this one is implemented by all the specialization classes because it includes getting the output (but not the direct feedback)

Returns:

the part of a query response that is directed to the Jinni output stream

Throws:

JinniEngineException

java.rmi.RemoteException

setJinniOutput

void setJinniOutput(javax.swing.JTextArea area)
                    throws JinniEngineException,
                           java.rmi.RemoteException

sets the text area that is used to insert all the output that is not the direct feedback of a query; if this method is not called, a default JTextArea is used

Parameters:

area - the text area to be used to keep the output of a Jinni instance

Throws:

JinniEngineException

java.rmi.RemoteException

getState

IJinniEngine.EngineState getState()
                                  throws java.rmi.RemoteException

Informs the client of this engine's state

Throws:

java.rmi.RemoteException

getStartupFeedback

java.lang.String getStartupFeedback()
                                    throws java.rmi.RemoteException,
                                           JinniEngineException

Returns and sets engine feedback as a by result of a query, usually the first consulting query to load the lib

Returns:

feedback produced during startup of the engine most probably as a result of consulting a lib

Throws:

RemoteException, - JinniEngineException

java.rmi.RemoteException

JinniEngineException

setStartupFeedback

void setStartupFeedback(java.lang.String feedback)
                        throws java.rmi.RemoteException,
                               JinniEngineException

Throws:

java.rmi.RemoteException

JinniEngineException

kill

void kill()
          throws java.rmi.RemoteException,
                 java.rmi.NoSuchObjectException,
                 JinniEngineException,
                 java.net.MalformedURLException,
                 java.rmi.NotBoundException

kill the entire server process by force despite pending client requests

Throws:

java.rmi.RemoteException

java.rmi.NoSuchObjectException

JinniEngineException

java.rmi.NotBoundException

java.net.MalformedURLException

terminate

void terminate()
               throws java.rmi.RemoteException,
                      java.rmi.NoSuchObjectException,
                      JinniEngineException,
                      java.net.MalformedURLException,
                      java.rmi.NotBoundException

kill the entire server process gently waiting for pending client requests to complete

Throws:

java.rmi.RemoteException

java.rmi.NoSuchObjectException

JinniEngineException

java.rmi.NotBoundException

java.net.MalformedURLException