001: /**
002: * Copyright 2007 Jens Dietrich Licensed under the Apache License, Version 2.0 (the "License");
003: * you may not use this file except in compliance with the License.
004: * You may obtain a copy of the License at http://www.apache.org/licenses/LICENSE-2.0
005: * Unless required by applicable law or agreed to in writing, software distributed under the
006: * License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND,
007: * either express or implied. See the License for the specific language governing permissions
008: * and limitations under the License.
009: */package nz.org.take.rt;
010:
011: import java.io.PrintStream;
012: import java.util.List;
013:
014: /**
015: * Utility class to controll the derivation process.
016: * Responsibilities:
017: * <ol>
018: * <li>record the derivation tree, and return it to the application</li>
019: * <li>interrupt derivations</li>
020: * <li>optional: progress notification</li>
021: * <li>optional: loop checking</li>
022: * <li>optional: stop derivation after a certain number of steps</li>
023: * </ol>
024: * Used to record derivation trees, and can be used to cancel the inference process.
025: * Recorded are string ids of the rules, facts etc, applications can use this strings to
026: * access artefacts in the knowledge base.
027: * @author <a href="http://www-ist.massey.ac.nz/JBDietrich/">Jens Dietrich</a>
028: * @param <T> the type of the iterated elements
029: */
030:
031: public interface DerivationController {
032: // constant signaling that no parameter has been provided
033: public static final Object NIL = new Object() {
034: public String toString() {
035: return "?";
036: }
037: };
038: // constants to be used as parameters in log
039: public static final int ANY = 0;
040: public static final int RULE = 1;
041: public static final int FACT = 2;
042: public static final int BEAN_PROPERTY = 3;
043: public static final int JAVA_METHOD = 4;
044: public static final int COMPARISON = 5;
045: public static final int EXTERNAL_FACT_SET = 6;
046: public static final int NAF = 7;
047:
048: /**
049: * Log the use of a clause set
050: * @param ruleRef a string referencing the knowledge element (id or similar)
051: * @param in kind what kind of knowledge this is (one of the constants RULE, FACT etc)
052: * @param the parameter bindings used
053: */
054: public void log(String ruleRef, int kind, Object... param);
055:
056: /**
057: * Get (a copy of) the derivation log.
058: * May throw a runtime exception (e.g., if the derivation has been cancelled).
059: * @return a list
060: */
061: public List<DerivationLogEntry> getLog();
062:
063: /**
064: * Print the log to a print stream.
065: * @param out a print stream
066: */
067: public void printLog(PrintStream out);
068:
069: /**
070: * Print the log to System.out.
071: */
072: public void printLog();
073:
074: /**
075: * Get the derivation level.
076: * @return
077: */
078: public int getDepth();
079:
080: /**
081: * Increase the derivation level.
082: * @return this
083: */
084: public DerivationController increaseDepth();
085:
086: /**
087: * Reset the derivation level.
088: * @param value
089: * @return this
090: */
091: public DerivationController reset(int value);
092:
093: /**
094: * Cancel the derivation.
095: */
096: public void cancel();
097:
098: /**
099: * Whether the derivation has been cancelled. If the derivation is cancelled, the next call to log should
100: * trigger a DerivationCancelledException.
101: * This can be used by applications to stop long running derivations.
102: * @return the cancelled status
103: */
104: public boolean isCancelled();
105:
106: /**
107: * Get the number of derivation steps performed so far.
108: * @return an int
109: */
110: public int getDerivationCount();
111: }
|