001: package org.ofbiz.rules.engine;
002:
003: /**
004: * <p><b>Title:</b> Gateway
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>A Gateway is a structure that can prove its truth at most
029: * once before failing.
030: * <p>
031: * Examples of gateways are comparisons, negations, and
032: * mathematical evaluations. For example, <code>Age >
033: * 18</code> is either true or not, it cannot prove itself in
034: * more than one way. Also, <code> not married(X)</code> is
035: * true only if the structure <code>married(X)</code> cannot
036: * prove itself at all.
037: * <p>
038: * The fact that gateways can be true only once is important
039: * in rules. For example, a rule might contain:
040: * <blockquote><pre>
041: * ..., plays(jim, Game, Rating),
042: * Rating >= 7, likes(jane, Game), ...
043: * </pre></blockquote>
044: * As this rule proves itself, if it finds a game that Jim
045: * plays with a rating of, say, 8, the rule will accept that
046: * <code>Rating >= 7</code>. The rule will then proceed to
047: * prove the structures after the comparison. The rule may
048: * succeed with the latter structures many times, but
049: * eventually these structures will run out of proofs, and the
050: * rule will fail back to the comparison structure.
051: * <p>
052: * On failing back, the rule will ask the comparison for its
053: * next proof. This amounts to asking if there is a different
054: * way to prove that 8 is greater than or equal to 7. Since
055: * the comparison has already succeeded once, which allowed
056: * the rule to check the latter structures, on failing back
057: * the comparison will fail. This will cause the rule to fail
058: * back to the preceding <code>plays</code> structure, which
059: * may be able to find other proofs.
060: * <p>
061: * If a preceding structure succeeds, the rule will move
062: * forward again, and ask a gateway to prove itself. Since the
063: * gateway has failed, it will try again to prove itself.
064: *
065: * @author Steven J. Metsker
066: *
067: * @version 1.0
068: *
069: */
070: public abstract class Gateway extends Structure {
071:
072: /**
073: * If this structure is involved in a proof, the gate is
074: * open and will shut when the rule fails back to this
075: * structure.
076: */
077: protected boolean open = false;
078:
079: /**
080: * Allows subclasses to use this form of constructor. This typically
081: * happens when the subclass object is creating an executable copy
082: * of itself.
083: *
084: * @param functor the functor for this gateway
085: *
086: * @param terms the terms of the gateway
087: *
088: * @param program the program the gateway will prove itself
089: * against
090: */
091: protected Gateway(Object functor, Term[] terms) {
092: super (functor, terms);
093: }
094:
095: /**
096: * Returns true if the gate is closed and this gateway can find a new
097: * proof.
098: * <p>
099: * A gateway is a structure that can prove itself in at most one
100: * way. After a successful proof, a gateway leaves its gate open.
101: * <p>
102: * If the gate is open when this method executes, this method will
103: * shut the gate and return false. This occurs after a gateway has
104: * proven itself true once, and a rule has failed back to the point
105: * where it is asking the gateway for another proof.
106: * <p>
107: * If the gate is not open, this gateway will try to prove itself.
108: * Then,
109: * <ul>
110: * <p><li>
111: * If the gate is not open and this gateway can prove itself, then
112: * this method will return true and leave the gate open. Returning
113: * true allows the containing rule to go on to prove whatever
114: * structures follow this one. When the rule fails back to this
115: * gateway, the gate will be open, and at that time this gateway
116: * will fail.
117: * <p><li>
118: * If the gate is not open and this gateway can not prove itself,
119: * this method returns false.
120: * </ul>
121: * <p>
122: * Upon leaving the gate closed, this method unbinds any variables
123: * that instantiated as part of this gateway's proof. This method
124: * also sets rule checking to begin again at the first program rule,
125: * upon the next request for a proof sent to this gateway.
126: *
127: * @param depth the depth at which to print tracing information
128: *
129: * @return true if the gate is closed and this gateway can find a
130: * new proof
131: */
132: public boolean canFindNextProof() {
133: if (open) {
134: open = false;
135: } else {
136: open = canProveOnce();
137: }
138: if (!open) {
139: cleanup();
140: }
141: return open;
142: }
143:
144: /**
145: * Returns true if the comparison operator holds true between each
146: * pair of terms.
147: * <p>
148: * This method recovers the comparison operator from the Token which
149: * is the functor for this Comparison. This method applies this
150: * comparison to each pair of terms. That is, this method compares
151: * term 0 with term 1, term 1 with term 2, term 2 with term 3, and
152: * so on. This method returns true if the comparison holds between
153: * each adjacent pair of terms.
154: * <p>
155: * If a term is a variable, this method uses the term's ground value
156: * in the comparison.
157: *
158: * @param depth the depth at which to print trace information
159: */
160: public boolean canProveOnce() {
161: return true;
162: }
163:
164: /**
165: * Insert the method's description here.
166: * Creation date: (12/7/99 11:09:44 AM)
167: */
168: protected void cleanup() {
169: }
170: }
|