org.tm4j.tologx
Interface QueryEvaluator

public interface QueryEvaluator

This is the high-level interface to the tolog 1.0 query engine. Using this interface you can initialise the evaluator by loading one or more rules module files or by adding rules as strings. This class also supports the registration of extension predicates.

Method Summary

void	addRule(java.lang.String rule) Adds a new rule to the QueryEvaluator.
void	addRulesModule(java.io.InputStream src, java.lang.String prefix) Loads a rules module from the specified stream.
TologResultsSet	execute(java.lang.String queryString) A convenience method that parses and optimizes the specified tolog query and then executes it immediately.
TologResultsSet	execute(java.lang.String queryString, java.lang.Object[] queryParams) A convenience method that parses and optimizes the specified tolog query and then executes it immediately.
java.util.Map	getRegisteredPredicates() Returns a Map of the predicates currently registered with the QueryEvaluator.
PreparedQuery	prepareQuery(java.lang.String queryString) Parses (and possibly optimizes) the specified tolog query string.
void	registerPredicateClass(java.lang.String predicateName, java.lang.Class predicateClass) Registers an extension predicate with the QueryEvaluator.

Method Detail

addRulesModule

public void addRulesModule(java.io.InputStream src,
                           java.lang.String prefix)
                    throws java.io.IOException,
                           TologParserException

Loads a rules module from the specified stream.

Parameters:

src - the input stream to be parsed

Throws:

java.io.IOException - if the module file could not be read.

TologParserException - if the module file could be read but contained syntax errors.

addRule

public void addRule(java.lang.String rule)
             throws TologParserException

Adds a new rule to the QueryEvaluator.

Parameters:

rule - the rule string in tolog syntax

Throws:

TologParserException - if there is a syntax error in the rule string.

prepareQuery

public PreparedQuery prepareQuery(java.lang.String queryString)
                           throws TologParserException,
                                  TologProcessingException

Parses (and possibly optimizes) the specified tolog query string. The return value is the parsed query which can then be executed simply by calling {PreparedQuery#execute()}.

Parameters:

queryString - the tolog query string to be parsed.

Returns:

the PreparedQuery that represents the parsed, optimized tolog query.

Throws:

TologParserException - if a syntax error or parse-time error is found in queryString

TologProcessingException - if an error occurs during optimisation of the query.

execute

public TologResultsSet execute(java.lang.String queryString)
                        throws TologParserException,
                               TologProcessingException

A convenience method that parses and optimizes the specified tolog query and then executes it immediately.

Parameters:

queryString - the tolog query string to be evaluated

Returns:

the results of the query evaluation.

Throws:

TologParserException - if a syntax error or parse-time error is found in queryString

TologProcessingException - if an error occurrs during the optimisation or evaluation of the query.

execute

public TologResultsSet execute(java.lang.String queryString,
                               java.lang.Object[] queryParams)
                        throws TologParserException,
                               TologProcessingException

A convenience method that parses and optimizes the specified tolog query and then executes it immediately.

Parameters:

queryString - the tolog query string to be evaluated

queryParams - the replacement values for % references in the query string

Returns:

the results of the query evaluation.

Throws:

TologParserException - if a syntax error or parse-time error is found in queryString

TologProcessingException - if an error occurrs during the optimisation or evaluation of the query.

registerPredicateClass

public void registerPredicateClass(java.lang.String predicateName,
                                   java.lang.Class predicateClass)
                            throws java.lang.IllegalArgumentException

Registers an extension predicate with the QueryEvaluator. All implementation classes MUST implement the Predicate interface. If predicateName is the name of an already registered predicate, then the new registration overwrites the old one.

Parameters:

predicateName - the name to be used to reference the predicate from a tolog query.

predicateClass - the implementation class for the predicate.

Throws:

java.lang.IllegalArgumentException - if the specified implementation class does not implement the Predicate interface.

getRegisteredPredicates

public java.util.Map getRegisteredPredicates()

Returns a Map of the predicates currently registered with the QueryEvaluator. The Map key is the name of the predicate and the value is the implementation Class of the predicate.