Module org.apache.jena.core
Package org.apache.jena.reasoner.rulesys

Class Rule

java.lang.Object
org.apache.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 ':'.

  • Constructor Details

    • 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 Details

    • 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, using the default BuiltinRegistry to resolve functor names
      Throws:
      Rule.ParserException - if there is a problem

    • parseRule

      public static Rule parseRule(String source, BuiltinRegistry registry) throws Rule.ParserException
      Parse a string as a rule using a specified BuiltinRegistry to resolve functor names
      Parameters:
      source - the source string for the rule
      registry - the BuiltinRegistry used to resolve functor names
      Throws:
      Rule.ParserException - if there is a problem

    • rulesFromURL

      public static List<Rule> rulesFromURL(String uri, BuiltinRegistry registry)
      Answer the list of rules parsed from the given URL.
      Throws:
      RulesetNotFoundException

    • 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, BuiltinRegistry registry)
      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.

    • 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, BuiltinRegistry registry) throws Rule.ParserException
      Parse a string as a list a 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