001: /******************************************************************
002: * File: Builtin.java
003: * Created by: Dave Reynolds
004: * Created on: 11-Apr-2003
005: *
006: * (c) Copyright 2003, 2004, 2005, 2006, 2007, 2008 Hewlett-Packard Development Company, LP
007: * [See end of file]
008: * $Id: Builtin.java,v 1.13 2008/01/02 12:07:47 andy_seaborne Exp $
009: *****************************************************************/package com.hp.hpl.jena.reasoner.rulesys;
010:
011: import com.hp.hpl.jena.graph.*;
012:
013: /**
014: * Rules employ builtins to do all tests and actions other than simple triple
015: * matches and triple creation.
016: * <p>
017: * Builtins can be invoked in two contexts. In the head of forward rules they perform
018: * some action based on the variable bindings generated by the body and additional context
019: * (the graph being reasoned over, the set of triples bound by the body). In the body
020: * of rules they perform tests, and additional variable bindings.
021: * <p>
022: * The mapping from the rule definition (which uses functors to hold the parsed call)
023: * to the java implementation of the builtin is done via the
024: * {@link BuiltinRegistry BuiltinRegistry} which can
025: * be user extended.
026: *
027: * @author <a href="mailto:der@hplb.hpl.hp.com">Dave Reynolds</a>
028: * @version $Revision: 1.13 $ on $Date: 2008/01/02 12:07:47 $
029: */
030: public interface Builtin {
031:
032: /**
033: * Return a convenient name for this builtin, normally this will be the name of the
034: * functor that will be used to invoke it and will often be the final component of the
035: * URI.
036: */
037: public String getName();
038:
039: /**
040: * Return the full URI which identifies this built in.
041: */
042: public String getURI();
043:
044: /**
045: * Return the expected number of arguments for this functor or 0 if the number is flexible.
046: */
047: public int getArgLength();
048:
049: /**
050: * This method is invoked when the builtin is called in a rule body.
051: * @param args the array of argument values for the builtin, this is an array
052: * of Nodes, some of which may be Node_RuleVariables.
053: * @param length the length of the argument list, may be less than the length of the args array
054: * for some rule engines
055: * @param context an execution context giving access to other relevant data
056: * @return return true if the buildin predicate is deemed to have succeeded in
057: * the current environment
058: */
059: public boolean bodyCall(Node[] args, int length, RuleContext context);
060:
061: /**
062: * This method is invoked when the builtin is called in a rule head.
063: * Such a use is only valid in a forward rule.
064: * @param args the array of argument values for the builtin, this is an array
065: * of Nodes.
066: * @param length the length of the argument list, may be less than the length of the args array
067: * for some rule engines
068: * @param context an execution context giving access to other relevant data
069: */
070: public void headAction(Node[] args, int length, RuleContext context);
071:
072: /**
073: * Returns false if this builtin has side effects when run in a body clause,
074: * other than the binding of environment variables.
075: */
076: public boolean isSafe();
077:
078: /**
079: * Returns false if this builtin is non-monotonic. This includes non-monotonic checks like noValue
080: * and non-monotonic actions like remove/drop. A non-monotonic call in a head is assumed to
081: * be an action and makes the overall rule and ruleset non-monotonic.
082: * Most JenaRules are monotonic deductive closure rules in which this should be false.
083: */
084: public boolean isMonotonic();
085: }
086:
087: /*
088: (c) Copyright 2003, 2004, 2005, 2006, 2007, 2008 Hewlett-Packard Development Company, LP
089: All rights reserved.
090:
091: Redistribution and use in source and binary forms, with or without
092: modification, are permitted provided that the following conditions
093: are met:
094:
095: 1. Redistributions of source code must retain the above copyright
096: notice, this list of conditions and the following disclaimer.
097:
098: 2. Redistributions in binary form must reproduce the above copyright
099: notice, this list of conditions and the following disclaimer in the
100: documentation and/or other materials provided with the distribution.
101:
102: 3. The name of the author may not be used to endorse or promote products
103: derived from this software without specific prior written permission.
104:
105: THIS SOFTWARE IS PROVIDED BY THE AUTHOR ``AS IS'' AND ANY EXPRESS OR
106: IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES
107: OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED.
108: IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY DIRECT, INDIRECT,
109: INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT
110: NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
111: DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
112: THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
113: (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF
114: THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
115: */
|