com.haley.haleyrules
Interface KnowledgeBase

All Known Subinterfaces:

DevelopmentKnowledgeBase

public interface KnowledgeBase

The KnowledgeBase interface publishes the API for a knowledge base created from a KnowledgeBaseFactory.

Author:

The Haley Enterprise Copyright © 1998-2004, all rights reserved. Questions, comments or to report a problem contact support@haley.com

Method Summary

boolean	clear() Return the KnowledgeBase to the state after initialize.
void	defineFunction(java.lang.String name, EclipseFunction function) Extends the Inference engine with a user-defined fuinction
void	deleteKnowledgeBase() Deletes a knowledge base, causing exceptions if used again
void	deleteWorkingMemory(WorkingMemory workingMemory) Deletes a working memory, causing exceptions if used again.
boolean	echoing() Indicates whether information is being echoed to a file.
Relation	findRelation(java.lang.String name) Find the Relation with the specified name Each call to this function must be accompanied with a corresponding call to KnowledgeBaseObject.release().
Ruleset	findRuleset(java.lang.String name) Find the Ruleset with the specified name or null if no such ruleset exists.
Template	findTemplate(java.lang.String name) Find the Template with the specified name or null if no such template exists.
void	flushEcho() Flushes any echo
java.lang.String	getName() Gets the name of the knowledgebase
int	getNumberOfArguments(java.lang.String name) Get the number of arguments for the named function.
java.lang.Object	getObject() Returns the object that was associated with the knowledge base
RulesetIterator	getRulesets()
void	loadBatchFile(WorkingMemory workingMemory, java.lang.String filename) This function extecutes batch commands read from the specified file
void	loadBinary(java.io.InputStream stream) Load a binary ruleset file (which invalidates the prior ruleset object and all of its agendas and their rules.)
void	loadBinaryFile(java.lang.String filename) Load a binary ruleset file (which invalidates the prior ruleset object and all of its agendas and their rules.)
void	loadConfigurationFile(java.lang.String deploymentFilename, long updateGranularity, ConfigurationListener listener) This method causes the running knowledge base to load and optionally track Eclipse (.clp or .bin) files specified in a deployment file (e.g., Deployment.xml).
void	loadConfigurationURL(java.net.URL deploymentURL, long updateGranularity, ConfigurationListener listener) This method causes the running knowledge base to load and optionally track Eclipse (.clp or .bin) files specified in a deployment file (e.g., Deployment.xml).
void	loadFromDocumentElement(org.w3c.dom.Element documentElement) This method causes the running knowledge base to load Eclipse (.clp or .bin) files specified in a deployment file (e.g., Deployment.xml) or an HRML file.
void	loadFromStream(java.io.InputStream inputStream) This method causes the running knowledge base to load Eclipse (.clp or .bin) files specified in a deployment file (e.g., Deployment.xml) or an HRML file.
void	loadHRMLfile(java.lang.String filename) Loads a file containing HRML and builds the corresponding relations, templates, deffacts, rulesets, agendas, and rules in the knowledge base.
void	loadHRMLfromReader(java.lang.String systemId, java.io.Reader reader) Loads HRML from a reader and builds the corresponding relations, templates, deffacts, rulesets, agendas, and rules in the knowledge base.
void	loadText(java.lang.String text) Loads a string containing defrelation, deftemplate, deffacts, defruleset, and defrule constructs and builds the corresponding relations, templates, deffacts, rulesets, agendas, and rules in the knowledge base.
void	loadTextFile(java.lang.String filename) Loads a file containing defrelation, deftemplate, deffacts, defruleset, and defrule constructs and builds the corresponding relations, templates, deffacts, rulesets, agendas, and rules in the knowledge base.
WorkingMemory	newWorkingMemory() Create a new WorkingMemory in this KnowledgeBase.
WorkingMemory	newWorkingMemory(java.lang.Object object) Create a new WorkingMemory in this KnowledgeBase.
void	setClassLoader(java.lang.ClassLoader classLoader) Specifies and caches a reference to the ClassLoader on the KnowledgeBase.
void	setErrorListener(ErrorListener listener) Add a listener for warning messages
void	setExecutionListener(ExecutionListener listener) Add a listener for execute messages
void	setName(java.lang.String name) Sets the name of the knowledgebase
void	setObject(java.lang.Object object) Sets the object that was associated with the knowledge base
void	startEcho(java.lang.String fileName) Causes all stream output directed to the standard knowledge base streams to be echoed to a file.
void	startEcho(java.lang.String fileName, int nMinutes, int nKiloBytes) Causes all stream output directed to the standard knowledge base streams to be echoed to a file.
void	startEcho(java.io.Writer writer) Captures all Eclipse output, trace and error messages in the given Writer
void	stopEcho() Terminates the echoing of Eclipse output and closes the file or Writer.

Method Detail

getObject

public java.lang.Object getObject()
                           throws EclipseException

Returns the object that was associated with the knowledge base

Returns:

the object to be associated with the knowledge base

Throws:

EclipseException

setObject

public void setObject(java.lang.Object object)
               throws EclipseException

Sets the object that was associated with the knowledge base

Parameters:

object - the object to be associated with the knowledge base

Throws:

EclipseException

clear

public boolean clear()
              throws EclipseException

Return the KnowledgeBase to the state after initialize. This removes all agendas, rules, and facts. WorkingMemory objects are cleared, but not removed. LoadConfiguration settings get cleared.

Returns:

true, if successful.

Throws:

EclipseException

echoing

public boolean echoing()
                throws EclipseException

Indicates whether information is being echoed to a file.

Returns:

true id echoing was initiated

Throws:

EclipseException

findRelation

public Relation findRelation(java.lang.String name)
                      throws EclipseException

Find the Relation with the specified name Each call to this function must be accompanied with a corresponding call to KnowledgeBaseObject.release().

Parameters:

name - the name of the relation to find

Returns:

the relation or null if the relation could not be found

Throws:

EclipseException - if there is an internal error

See Also:

KnowledgeBaseObject.release()

getRulesets

public RulesetIterator getRulesets()
                            throws EclipseException

Throws:

EclipseException

findRuleset

public Ruleset findRuleset(java.lang.String name)
                    throws EclipseException

Find the Ruleset with the specified name or null if no such ruleset exists. Each call to this function must be accompanied with a corresponding call to KnowledgeBaseObject.release() or Ruleset.excise()

Parameters:

name - the name of the ruleset to find

Returns:

the ruleset or null if the relation could not be found

Throws:

EclipseException - if there is an internal error

See Also:

KnowledgeBaseObject.release(), Ruleset.excise()

findTemplate

public Template findTemplate(java.lang.String name)
                      throws EclipseException

Find the Template with the specified name or null if no such template exists. Each call to this function must be accompanied with a corresponding call to KnowledgeBaseObject.release().

Parameters:

name - the name of the template to find

Returns:

the template or null if the template could not be found

Throws:

EclipseException - if there is an internal error

See Also:

KnowledgeBaseObject.release()

getNumberOfArguments

public int getNumberOfArguments(java.lang.String name)
                         throws EclipseException

Get the number of arguments for the named function.

Parameters:

name - the name of the function to get the number of arguments for

Returns:

the number of arguments, or -1 if the number is variable, or -2 if the function could not be found

Throws:

EclipseException - if there is an internal error

loadBatchFile

public void loadBatchFile(WorkingMemory workingMemory,
                          java.lang.String filename)
                   throws EclipseException

This function extecutes batch commands read from the specified file

Parameters:

workingMemory - the working memroy to use to process the batch commands

filename - the filename to load

Throws:

EclipseException - if this method is not supported

EclipseException - if unable to open the file

loadBinary

public void loadBinary(java.io.InputStream stream)
                throws EclipseException

Load a binary ruleset file (which invalidates the prior ruleset object and all of its agendas and their rules.)

Parameters:

stream - a InputStream

Throws:

EclipseException - if the stream could not be loaded.

See Also:

DevelopmentKnowledgeBase.saveAsBinaryFile(Ruleset,String,boolean)

loadBinaryFile

public void loadBinaryFile(java.lang.String filename)
                    throws EclipseException

Load a binary ruleset file (which invalidates the prior ruleset object and all of its agendas and their rules.)

Parameters:

filename -

Throws:

EclipseException - if the file could not be loaded.

loadConfigurationFile

public void loadConfigurationFile(java.lang.String deploymentFilename,
                                  long updateGranularity,
                                  ConfigurationListener listener)
                           throws EclipseException

This method causes the running knowledge base to load and optionally track Eclipse (.clp or .bin) files specified in a deployment file (e.g., Deployment.xml). If the second argument (updateGranularity) is non-negative then the application will automatically check for updates during resets of working memory but no more frequently than every updateGranularity seconds. The aim is to allow the knowledgebase to track possibly newly deployed logic files without restarting the entire application.

A typical user will call loadApplication once with the second parameter equal to, say, 300 so that the configuration is automatically checked for updates during calls to newWorkingMemory, but no more often than every 5 minutes (= 300 seconds). A value of zero for the second parameter indicates that a check for updates should be performed during each call to newWorkingMemory. A negative value for the second parameter indicates that no automatic checks should be performed. (The application can still make explicit calls to loadConfigurationFile() to force a check for updates.)

Working memories must not be running when new logic files are loaded into a knowledgebase. Consequently, this method, newWorkingMemory() and WorkingMemory.reset() are all synchronized on the same kb object, so no new working memories will be created or reset during reloads. However, already existing working memories might be running before a reload. Furthermore, if model-level constructs would be modified by loading a configuration, then clear will be called, destroying any facts stored in existing working memories. To handle these possibilities, whenever (re)loading is required, the reload delays until no working memories are allocated.

The third (optional) parameter is the name of a class that implements the processUpdate method of the ConfigurationListener interface. If the third parameter (ConfigurationListener) is non-null, then before (re)loading a configuration, the processUpdate method of the listener will be called to give the application a chance to react to and possibly prevent the reload. If the processUpdate method returns false, no update is performed until possibly the next automatic check for updates. (Even if processUpdate returns true, the reload will not occur if working memories still exist; see below.) ProcessUpdate's parameter indicates whether reloading the configuration would cause Eclipse to be cleared. (See the documentation for the ConfigurationListener class for full details about the ProcessUpdate method.) The ProcessUpdate method can takes any actions that might be needed to save data in case of a clear; this might be necessary for working memories that have finished running but that contain facts that are still needed. The user's processUpdate might need to call deleteWorkingMemory(WorkingMemory) to destroy working memories.

Parameters:

deploymentFilename - The name of the XML file containing the application's deployment definition.

updateGranularity - The number of seconds since the last update after which to check for updates to the configuration during resets of working memory. A value less than zero indicates that the application should never check for updates.

listener - ConfigurationListener, or null (if reloads should just wait until working memories finish running)

Returns:

true if successful, false if error

Throws:

EclipseException - if unable to load application

See Also:

ConfigurationListener.processUpdate(int)

loadConfigurationURL

public void loadConfigurationURL(java.net.URL deploymentURL,
                                 long updateGranularity,
                                 ConfigurationListener listener)
                          throws EclipseException

This method causes the running knowledge base to load and optionally track Eclipse (.clp or .bin) files specified in a deployment file (e.g., Deployment.xml).

Parameters:

deploymentURL - The URL of the XML file containing the application's deployment definition.

updateGranularity - The number of seconds since the last update after which to check for updates to the configuration during resets of working memory. A value less than zero indicates that the application should never check for updates.

listener - ConfigurationListener, or null (if reloads should just wait until working memories finish running)

Throws:

EclipseException - if unable to load application

See Also:

loadConfigurationFile(String,long,ConfigurationListener), ConfigurationListener.processUpdate(int)

loadFromStream

public void loadFromStream(java.io.InputStream inputStream)
                    throws EclipseException

This method causes the running knowledge base to load Eclipse (.clp or .bin) files specified in a deployment file (e.g., Deployment.xml) or an HRML file.

Parameters:

inputStream - a stream to read the deployment file or HRML file from. It it is a deployment file, it must be self-contained, and not refer to external files.

Throws:

EclipseException

loadFromDocumentElement

public void loadFromDocumentElement(org.w3c.dom.Element documentElement)
                             throws EclipseException

This method causes the running knowledge base to load Eclipse (.clp or .bin) files specified in a deployment file (e.g., Deployment.xml) or an HRML file.

Parameters:

documentElement - an org.w3c.dom.Element containing the deployment or the HRML file.

Throws:

EclipseException

loadText

public void loadText(java.lang.String text)
              throws EclipseException

Loads a string containing defrelation, deftemplate, deffacts, defruleset, and defrule constructs and builds the corresponding relations, templates, deffacts, rulesets, agendas, and rules in the knowledge base. The defrelation and deftemplate definitions require a development knowledge base.

Parameters:

text - the string containing the definition

Throws:

EclipseException - if the constructs could not be added to the knowledge base.

EclipseException - if the constructs contains defrelation or deftemplate without a development knowledge base.

loadTextFile

public void loadTextFile(java.lang.String filename)
                  throws EclipseException

Loads a file containing defrelation, deftemplate, deffacts, defruleset, and defrule constructs and builds the corresponding relations, templates, deffacts, rulesets, agendas, and rules in the knowledge base. The defrelation and deftemplate definitions require a development license.

Parameters:

filename - the file to load

Throws:

EclipseException - if the file could not be opened.

EclipseException - if the file contains errors.

EclipseException - if the file contains defrelation or deftemplate without a development knowledge base.

loadHRMLfile

public void loadHRMLfile(java.lang.String filename)
                  throws EclipseException

Loads a file containing HRML and builds the corresponding relations, templates, deffacts, rulesets, agendas, and rules in the knowledge base. Relation and template definitions require a development license.

Parameters:

filename - the file to load

Throws:

EclipseException - if the file could not be opened.

EclipseException - if the file contains errors.

EclipseException - if the file contains defrelation or deftemplate without a development knowledge base.

loadHRMLfromReader

public void loadHRMLfromReader(java.lang.String systemId,
                               java.io.Reader reader)
                        throws EclipseException

Loads HRML from a reader and builds the corresponding relations, templates, deffacts, rulesets, agendas, and rules in the knowledge base. Relation and template definitions require a development license.

Parameters:

systemId - the identifier for the XML

reader - the source for the XML

Throws:

EclipseException - if the file could not be opened.

EclipseException - if the file contains errors.

EclipseException - if the file contains defrelation or deftemplate without a development knowledge base.

newWorkingMemory

public WorkingMemory newWorkingMemory(java.lang.Object object)
                               throws EclipseException

Create a new WorkingMemory in this KnowledgeBase. This method will never return null.

Parameters:

object - the object to associate with the owkring memory, may be null

Returns:

a WorkingMemory

Throws:

EclipseException - if creation fails

See Also:

newWorkingMemory(), WorkingMemory.getObject(), WorkingMemory.setObject(Object)

newWorkingMemory

public WorkingMemory newWorkingMemory()
                               throws EclipseException

Create a new WorkingMemory in this KnowledgeBase. This method will never return null.

Returns:

a WorkingMemory

Throws:

EclipseException - if creation fails

See Also:

newWorkingMemory(Object), WorkingMemory.getObject(), WorkingMemory.setObject(Object)

deleteWorkingMemory

public void deleteWorkingMemory(WorkingMemory workingMemory)
                         throws EclipseException

Deletes a working memory, causing exceptions if used again.

Parameters:

workingMemory - to be deleted

Throws:

EclipseException

startEcho

public void startEcho(java.lang.String fileName,
                      int nMinutes,
                      int nKiloBytes)
               throws EclipseException

Causes all stream output directed to the standard knowledge base streams to be echoed to a file.

If the nMinutes

If nMinutes is less than or equal to zero, then there is no time limit on the dribble file, otherwise the file is closed when the file exceeds the specified size and a new file is opened.

If a time or size limit has been imposed, then current time in CCYYMMDDhhmmss format is appended to the base of the file name before it is opened

Parameters:

fileName - the file name to which information should be echoed

nMinutes - the number of minutes to wait before closing the dribble file, where 0 means no limit

nKiloBytes - the maximim size of the dribble file in kiloBytes, where 0 means no limit

Throws:

EclipseException

startEcho

public void startEcho(java.lang.String fileName)
               throws EclipseException

Causes all stream output directed to the standard knowledge base streams to be echoed to a file.

Parameters:

fileName - the file name to which information should be echoed

Throws:

EclipseException

startEcho

public void startEcho(java.io.Writer writer)
               throws EclipseException

Captures all Eclipse output, trace and error messages in the given Writer

Parameters:

writer - the Writer to write the output to

Throws:

EclipseException

flushEcho

public void flushEcho()
               throws EclipseException

Flushes any echo

Throws:

EclipseException

stopEcho

public void stopEcho()
              throws EclipseException

Terminates the echoing of Eclipse output and closes the file or Writer. If echoing() returns false, then this method has no effect. This method throws a RuntimeException (rather than than an EclipseException) if the file is open but cannot be closed (so that catch clauses needn't catch them).

Throws:

EclispeException - if unable to stop echoing

EclipseException

setErrorListener

public void setErrorListener(ErrorListener listener)
                      throws EclipseException

Add a listener for warning messages

Parameters:

listener - an ErrorListener

Throws:

EclipseException - if the knowledge base has been deleted

setExecutionListener

public void setExecutionListener(ExecutionListener listener)
                          throws EclipseException

Add a listener for execute messages

Parameters:

listener - an ExecutionListener

Throws:

EclipseException - if teh knowledge base has been deleted

java.lang.NullPointerException - if listener is null

setClassLoader

public void setClassLoader(java.lang.ClassLoader classLoader)
                    throws EclipseException

Specifies and caches a reference to the ClassLoader on the KnowledgeBase. This ClassLoader will be used first whenever a knowledge base attempts to load a class to be invoked by rule actions..

Parameters:

classLoader - the ClassLoader to be used by the KnowledgeBase.

Throws:

EclipseException - if the KnowledgeBase has been deleted

EclipseException - if an error occurred

getName

public java.lang.String getName()
                         throws EclipseException

Gets the name of the knowledgebase

Returns:

the name of the knowledgebase

Throws:

EclipseException - if an error occured

setName

public void setName(java.lang.String name)
             throws EclipseException

Sets the name of the knowledgebase

Parameters:

name - the name to set to

Throws:

EclipseException - if an error occured

defineFunction

public void defineFunction(java.lang.String name,
                           EclipseFunction function)
                    throws EclipseException

Extends the Inference engine with a user-defined fuinction

Parameters:

name - the name of the function as it will appear in the Eclipse language

function - the Java function that implements the function

Throws:

EclipseExcpetion - if an error occurred

EclipseException

deleteKnowledgeBase

public void deleteKnowledgeBase()
                         throws EclipseException

Deletes a knowledge base, causing exceptions if used again

Throws:

EclipseException