com.hp.hpl.jena.reasoner.rulesys
Class Rule

java.lang.Object
  com.hp.hpl.jena.reasoner.rulesys.Rule

All Implemented Interfaces:

ClauseEntry

public class Rule
extends Object
implements ClauseEntry

Representation of a generic inference rule.

This represents the rule specification but most engines will compile this specification into an abstract machine or processing graph.

The rule specification comprises a list of antecendents (body) and a list of consequents (head). If there is more than one consequent then a backchainer should regard this as a shorthand for several rules, all with the same body but with a singleton head.

Each element in the head or body can be a TriplePattern, a Functor or a Rule. A TriplePattern is just a triple of Nodes but the Nodes can represent variables, wildcards and embedded functors - as well as constant uri or literal graph nodes. A functor comprises a functor name and a list of arguments. The arguments are Nodes of any type except functor nodes (there is no functor nesting). The functor name can be mapped into a registered java class that implements its semantics. Functors play three roles - in heads they represent actions (procedural attachement); in bodies they represent builtin predicates; in TriplePatterns they represent embedded structured literals that are used to cache matched subgraphs such as restriction specifications.

The equality contract for rules is that two rules are equal if each of terms (ClauseEntry objects) are equals and they have the same name, if any.

We include a trivial, recursive descent parser but this is just there to allow rules to be embedded in code. External rule syntax based on N3 and RDF could be developed. The embedded syntax supports rules such as: [ (?C rdf:type *), guard(?C, ?P) -> (?c rb:restriction some(?P, ?D)) ].
[ (?s owl:foo ?p) -> [ (?s owl:bar ?a) -> (?s ?p ?a) ] ].
[name: (?s owl:foo ?p) -> (?s ?p ?a)].
only built in namespaces are recognized as such, * is a wildcard node, ?c is a variable, name(node ... node) is a functor, (node node node) is a triple pattern, [..] is an embedded rule, commas are ignore and can be freely used as separators. Functor names may not end in ':'.

Author:

Dave Reynolds * @version $Revision: 1.2 $ on $Date: 2011-04-28 19:40:26 $

Nested Class Summary

static class	Rule.Parser Inner class which provides minimalist parsing support based on tokenisation with depth 1 lookahead.
static class	Rule.ParserException Inner class.

Constructor Summary

Rule(List<ClauseEntry> head, List<ClauseEntry> body)
Constructor

Rule(String name, ClauseEntry[] head, ClauseEntry[] body)
Constructor

Rule(String name, List<ClauseEntry> head, List<ClauseEntry> body)
Constructor

Method Summary

int	bodyLength() Return the number of body elements
Rule	cloneRule() Clone a rule, cloning any embedded variables.
boolean	equals(Object o) Equality override
ClauseEntry[]	getBody() return the entire rule body as an array of objects
ClauseEntry	getBodyElement(int n) Return the n'th body element
ClauseEntry[]	getHead() return the entire rule head as an array of objects
ClauseEntry	getHeadElement(int n) Return the n'th head element
String	getName() Get the name for the rule - can be null.
int	getNumVars() Return the number of distinct variables in the rule.
int	hashCode() hash function override
int	headLength() Return the number of head elements
Rule	instantiate(BindingEnvironment env) Instantiate a rule given a variable binding environment.
boolean	isAxiom() Returns true if the rule does not depend on any data, and so should be treated as an axiom.
boolean	isBackward() Return true if the rule was written as a backward (as opposed to forward) rule.
boolean	isMonotonic() Returns false for rules which can affect other rules non-monotonically (remove builtin or similar) or are affected non-monotonically (involve negation-as-failure).
static Rule	parseRule(String source) Parse a string as a rule.
static List<Rule>	parseRules(Rule.Parser parser) Run a pre-bound rule parser to extract it's rules
static List<Rule>	parseRules(String source) Parse a string as a list a rules.
static List<Rule>	rulesFromURL(String uri) Answer the list of rules parsed from the given URL.
static Rule.Parser	rulesParserFromReader(BufferedReader src) Processes the source reader stripping off comment lines and noting prefix definitions (@prefix) and rule inclusion commands (@include).
boolean	sameAs(Object o) Compare clause entries, taking into account variable indices.
void	setBackward(boolean flag) Set the rule to be run backwards.
void	setNumVars(int n) Set the number of distinct variables for this rule.
String	toShortString() Print a short description of the rule, just its name if it has one, otherwise the whole rule description.
String	toString() Printable string describing the rule

Methods inherited from class java.lang.Object

getClass, notify, notifyAll, wait, wait, wait

Constructor Detail

Rule

public Rule(List<ClauseEntry> head,
            List<ClauseEntry> body)

Constructor

Parameters:

body - a list of TriplePatterns or Functors.

head - a list of TriplePatterns, Functors or rules

Rule

public Rule(String name,
            List<ClauseEntry> head,
            List<ClauseEntry> body)

Constructor

Parameters:

name - a label for rule

body - a list of TriplePatterns or Functors.

head - a list of TriplePatterns, Functors or rules

Rule

public Rule(String name,
            ClauseEntry[] head,
            ClauseEntry[] body)

Constructor

Parameters:

name - a label for rule

body - an array of TriplePatterns or Functors.

head - an array of TriplePatterns, Functors or rules

Method Detail

bodyLength

public int bodyLength()

Return the number of body elements

getBodyElement

public ClauseEntry getBodyElement(int n)

Return the n'th body element

getBody

public ClauseEntry[] getBody()

return the entire rule body as an array of objects

headLength

public int headLength()

Return the number of head elements

getHeadElement

public ClauseEntry getHeadElement(int n)

Return the n'th head element

getHead

public ClauseEntry[] getHead()

return the entire rule head as an array of objects

isBackward

public boolean isBackward()

Return true if the rule was written as a backward (as opposed to forward) rule.

setBackward

public void setBackward(boolean flag)

Set the rule to be run backwards.

Parameters:

flag - if true the rule should run backwards.

getName

public String getName()

Get the name for the rule - can be null.

setNumVars

public void setNumVars(int n)

Set the number of distinct variables for this rule. Used internally when cloing rules, not normally required.

getNumVars

public int getNumVars()

Return the number of distinct variables in the rule. Or more precisely, the size of a binding environment needed to represent the rule.

instantiate

public Rule instantiate(BindingEnvironment env)

Instantiate a rule given a variable binding environment. This will clone any non-bound variables though that is only needed for trail implementations.

cloneRule

public Rule cloneRule()

Clone a rule, cloning any embedded variables.

isMonotonic

public boolean isMonotonic()

Returns false for rules which can affect other rules non-monotonically (remove builtin or similar) or are affected non-monotonically (involve negation-as-failure).

isAxiom

public boolean isAxiom()

Returns true if the rule does not depend on any data, and so should be treated as an axiom.

toString

public String toString()

Printable string describing the rule

Overrides:

toString in class Object

toShortString

public String toShortString()

Print a short description of the rule, just its name if it has one, otherwise the whole rule description.

parseRule

public static Rule parseRule(String source)
                      throws Rule.ParserException

Parse a string as a rule.

Throws:

Rule.ParserException - if there is a problem

rulesFromURL

public static List<Rule> rulesFromURL(String uri)

Answer the list of rules parsed from the given URL.

Throws:

RulesetNotFoundException

rulesParserFromReader

public static Rule.Parser rulesParserFromReader(BufferedReader src)

Processes the source reader stripping off comment lines and noting prefix definitions (@prefix) and rule inclusion commands (@include). Returns a parser which is bound to the stripped source text with associated prefix and rule inclusion definitions.

parseRules

public static List<Rule> parseRules(Rule.Parser parser)
                             throws Rule.ParserException

Run a pre-bound rule parser to extract it's rules

Returns:

a list of rules

Throws:

Rule.ParserException - if there is a problem

parseRules

public static List<Rule> parseRules(String source)
                             throws Rule.ParserException

Parse a string as a list a rules.

Returns:

a list of rules

Throws:

Rule.ParserException - if there is a problem

equals

public boolean equals(Object o)

Equality override

Overrides:

equals in class Object

hashCode

public int hashCode()

hash function override

Overrides:

hashCode in class Object

sameAs

public boolean sameAs(Object o)

Compare clause entries, taking into account variable indices. The equality function ignores differences between variables.

Specified by:

sameAs in interface ClauseEntry