Package org.apache.jena.reasoner.rulesys

Class Rule

  • All Implemented Interfaces:
    ClauseEntry
    public class Rule
extends java.lang.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 ':'.

    • Nested Class Summary

      Nested Classes 
      Modifier and Type Class Description
      static class  Rule.Parser
      Inner class which provides minimalist parsing support based on tokenisation with depth 1 lookahead.
      static class  Rule.ParserException
      Inner class.

    • Method Summary

      All Methods Static Methods Instance Methods Concrete Methods 
      Modifier and Type Method Description
      int bodyLength()
      Return the number of body elements
      Rule cloneRule()
      Clone a rule, cloning any embedded variables.
      boolean equals​(java.lang.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
      java.lang.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​(java.lang.String source)
      Parse a string as a rule, using the default BuiltinRegistry to resolve functor names
      static Rule parseRule​(java.lang.String source, BuiltinRegistry registry)
      Parse a string as a rule using a specified BuiltinRegistry to resolve functor names
      static java.util.List<Rule> parseRules​(java.lang.String source)
      Parse a string as a list a rules.
      static java.util.List<Rule> parseRules​(java.lang.String source, BuiltinRegistry registry)
      Parse a string as a list a rules.
      static java.util.List<Rule> parseRules​(Rule.Parser parser)
      Run a pre-bound rule parser to extract it's rules
      static java.util.List<Rule> rulesFromURL​(java.lang.String uri)
      Answer the list of rules parsed from the given URL.
      static java.util.List<Rule> rulesFromURL​(java.lang.String uri, BuiltinRegistry registry)
      Answer the list of rules parsed from the given URL.
      static Rule.Parser rulesParserFromReader​(java.io.BufferedReader src)
      Processes the source reader stripping off comment lines and noting prefix definitions (@prefix) and rule inclusion commands (@include).
      static Rule.Parser rulesParserFromReader​(java.io.BufferedReader src, BuiltinRegistry registry)
      Processes the source reader stripping off comment lines and noting prefix definitions (@prefix) and rule inclusion commands (@include).
      boolean sameAs​(java.lang.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.
      java.lang.String toShortString()
      Print a short description of the rule, just its name if it has one, otherwise the whole rule description.
      java.lang.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​(java.util.List<ClauseEntry> head,
            java.util.List<ClauseEntry> body)
        Constructor
        Parameters:
        body - a list of TriplePatterns or Functors.
        head - a list of TriplePatterns, Functors or rules

      • Rule

        public Rule​(java.lang.String name,
            java.util.List<ClauseEntry> head,
            java.util.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​(java.lang.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 java.lang.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 java.lang.String toString()
        Printable string describing the rule
        Overrides:
        toString in class java.lang.Object

      • toShortString

        public java.lang.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​(java.lang.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​(java.lang.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 java.util.List<Rule> rulesFromURL​(java.lang.String uri)
        Answer the list of rules parsed from the given URL.
        Throws:
        RulesetNotFoundException

      • rulesParserFromReader

        public static Rule.Parser rulesParserFromReader​(java.io.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​(java.io.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 java.util.List<Rule> parseRules​(java.lang.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​(java.lang.Object o)
        Equality override
        Overrides:
        equals in class java.lang.Object

      • hashCode

        public int hashCode()
        hash function override
        Overrides:
        hashCode in class java.lang.Object

      • sameAs

        public boolean sameAs​(java.lang.Object o)
        Compare clause entries, taking into account variable indices. The equality function ignores differences between variables.
        Specified by:
        sameAs in interface ClauseEntry