001: package org.ofbiz.rules.engine;
002:
003: /**
004: * <p><b>Title:</b> Term
005: * <p><b>Description:</b> None
006: * <p>Copyright (c) 1999 Steven J. Metsker.
007: * <p>Copyright (c) 2001 The Open For Business Project - www.ofbiz.org
008: *
009: * <p>Permission is hereby granted, free of charge, to any person obtaining a
010: * copy of this software and associated documentation files (the "Software"),
011: * to deal in the Software without restriction, including without limitation
012: * the rights to use, copy, modify, merge, publish, distribute, sublicense,
013: * and/or sell copies of the Software, and to permit persons to whom the
014: * Software is furnished to do so, subject to the following conditions:
015: *
016: * <p>The above copyright notice and this permission notice shall be included
017: * in all copies or substantial portions of the Software.
018: *
019: * <p>THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS
020: * OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
021: * MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.
022: * IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY
023: * CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT
024: * OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR
025: * THE USE OR OTHER DEALINGS IN THE SOFTWARE.
026: *
027: * <br>
028: * <p>The Term interface defines the core elements of the logic
029: * engine.
030: *
031: * <p> Terms are the central objects in the logic programming
032: * data model, which is basically as follows:
033: *
034: * <ul>
035: * <li>A Program is a collection of Rules.
036: * <li>A Rule is a series of Structures.
037: * <li>A Structure is an Object associated with a collection of
038: * Terms.
039: * <li>Structures and Variables are Terms.
040: * </ul>
041: *
042: * <p> The statement that "Structures and Variables are Terms"
043: * has both a loose meaning and a literal meaning. Loosely, the
044: * statement means that the contents of a structure are other
045: * structures and variables. For example, the terms of
046: * <code>plays(jim, Game)</code> are the structure
047: * <code>jim</code> and the variable <code>Game</code>. The
048: * literal meaning is that class <code>Structure</code> and
049: * class <code>Variable</code> implement the interface
050: * <code>Term</code>.
051: *
052: * <p> In addition to residing at the core of the data model,
053: * the Term interface also defines unification. Unification is
054: * a kind of matching, and is the basic step in the execution
055: * of a logic program. Roughly speaking, two structures can
056: * unify if their variables can take on values to make the
057: * structures equal. To prove itself against a program, a
058: * Structure:
059: *
060: * <ul>
061: * <li>Unifies with the head of a Rule.
062: * <li>Asks the Rule to prove its remaining structures.
063: * </ul>
064: *
065: * This simple algorithm is the execution model of a logic
066: * engine. A structure can unify with another structure if
067: * their functors are equal, and if their terms can unify. An
068: * uninstantiated variable unifies with a term by instantiating
069: * to it. An instantiated variable can unify with another term
070: * if its instantiation can unify with the term.
071: *
072: * <p> The other methods declared by the Term interface define
073: * behavior that must exist in all terms, whether they are
074: * structures or variables. This behavior includes a method for
075: * creating provable version of a term, and a method for
076: * returning the value of term in a function.
077: *
078: * @author Steven J. Metsker
079: * @version 1.0
080: */
081: public interface Term {
082:
083: /**
084: * Returns a copy of the term for use in a proof.
085: * <p>
086: * When a structure proves itself against a program, it
087: * unifies with the head of a rule in the program, and then
088: * asks the remaining structures in that rule to prove
089: * themselves. For this to work, the rule has to provide
090: * a proving copy, which has a new Scope. To provide a
091: * proving copy, a rule needs proving copies of its structures,
092: * and ultimately every term needs to be able to produce
093: * such a copy.
094: *
095: * @param PosultateSource where the term can look for rules
096: *
097: * @param Scope variables for the provable rule copy
098: *
099: * @return a provable copy of this Term, that will use the
100: * supplied axiom source and scope
101: */
102: Term copyForProof(AxiomSource as, Scope scope);
103:
104: /**
105: * The value that this term should present to an evaluating
106: * function.
107: *
108: * @return the value that this term should present to an
109: * evaluating function, such as an ArithmeticOperator.
110: */
111: Object eval();
112:
113: /**
114: * Return true, if this term is a list
115: *
116: * @return true, if this term is a list
117: */
118: boolean isList();
119:
120: /**
121: * Returns a string representation of this listTailTerm.
122: *
123: * That is, return a string representation of this term,
124: * given that it is the tail of a list.
125: *
126: * @return a string representation of this listTailTerm
127: */
128: String listTailString();
129:
130: /**
131: * Returns a collection of variables that allow this term to
132: * unify with a structure.
133: *
134: * @param Structure the structure to unify with
135: *
136: * @return a collection of variables that allow this term
137: * to unify with a structure
138: */
139: Unification unify(Structure s);
140:
141: /**
142: * Returns a set of variable instantiations that allow two
143: * terms to unify.
144: * <p>
145: * When a term unifies with another term, the necessary
146: * behavior can be different depending on whether the objects
147: * involved are structures or variables. To allow the right
148: * behavior to occur, the Term interface defines two
149: * <code>unify</code> methods. This allows an implementing
150: * class to use a "double dispatching" scheme to get the right
151: * behavior for unification.
152: * <p>
153: * <code>Structure.unify(Term t)</code> employs double
154: * dispatching by returning <code>t.unify(this)</code>. This is
155: * a call to an implementation of <code>unify(Structure
156: * s)</code>, which is a different method from than
157: * <code>unify(Term t)</code>. The receiver thus knows it is
158: * unifying with a Structure and can act accordingly.
159: * <p>
160: * Structure implements <code>unify(Structure s)</code> to
161: * provide the unification of two structures. That is, it
162: * returns the combined unification of its terms with the other
163: * structure's terms, provided both have the same functor.
164: * <p>
165: * Variable implements both its <code>unify()</code>
166: * methods the same way. If the variable is uninstantiated, is
167: * instantiates to the supplied term. If the variable is
168: * already instantiated, it returns the unification of its
169: * instantiation with the supplied term.
170: * <p>
171: * Unification of an uninstantiated variable always
172: * succeeds. If a variable is instantiated, its success at
173: * unification depends on its instantiation. Unification of two
174: * structures succeeds if the structures have equal functors, the
175: * same number of terms, and if all their terms unify
176: * successfully. When unification fails, the <code>unify</code>
177: * methods return <code>null</code>.
178: *
179: * @param Term a term to unify with
180: *
181: * @return Unification a collection of variable assignments
182: * that allow the unification to succeed
183: */
184: Unification unify(Term t);
185:
186: /**
187: * Returns a collection of variables that allow this term to
188: * unify with a variable.
189: *
190: * @param Variable the variable to unify with
191: *
192: * @return a collection of variables that allow this term to
193: * unify with a variable
194: */
195: Unification unify(Variable v);
196:
197: /**
198: * Returns the variables associated with this term.
199: * <p>
200: * For a variable, this method returns a unification that contains
201: * just the variable itself. For a structure, this method returns a
202: * collection of the variables from each of its terms. For example,
203: * the variables in
204: * <blockquote><pre>
205: * address(street(Street), city(City), state(State))
206: * </pre></blockquote>
207: * are <code>Street, City, State</code>.
208: *
209: * @return the variables associated with this term
210: */
211: Unification variables();
212: }
|