001 /**
002 * Property of Hammurapi Group
003 */
004 package com.hammurapi.reasoning.spi;
005
006 import java.lang.reflect.Method;
007 import java.util.Collection;
008 import java.util.Map;
009
010 import com.hammurapi.reasoning.ReasoningException;
011
012
013 /**
014 * Rule context
015 * @author Pavel
016 */
017 public interface InferenceContext {
018
019 /**
020 * Implementations set this constant to provide rules access
021 * to inference context in implementation-neutral way.
022 */
023 InferenceContext INSTANCE = Util.loadService(InferenceContext.class);
024
025 /**
026 * Posts conclusions to rules container. Objects placed to the knowledge base by this
027 * method are removed from the knowledge base when source facts are removed.
028 * Returning a value from inference method has the same effect.
029 * @param conclusion
030 */
031 void post(Object... conclusions);
032
033 /**
034 * Puts a fact to the knowledge base. Objects placed to the knowledge base by this method
035 * remain in it even if source facts are removed.
036 * @param fact
037 * @throws ReasoningException
038 */
039 void put(Object fact) throws ReasoningException;
040
041 /**
042 * Rules invoke this method from multi-fact (multi-parameter) inference methods
043 * to indicate that a fact passed in <code>position</code> parameter
044 * shall not participate in further joins.
045 * @param position
046 * @param local Rule may consume incoming fact to prevent it being handled to other rules
047 * or to prevent its participation in further joins in multi-fact rules. If local is true,
048 * the fact is removed from further rule joins, but it will be handled to other rules. If
049 * false, the fact will not be handled to other rules, but it will be stored in rule's collection
050 * of input facts to participate in further joins.
051 * @throws IllegalArgumentException If <code>local</code> argument is true for single-parameter
052 * rules.
053 * @return True if fact was successfully consumed. In multi-parameter joins fact may come from
054 * a rule collection, not from the engine's input. As such it might not be possible to prevent
055 * handling of the fact to other rules. In this case this method returns false.
056 */
057 boolean consumeInput(int position, boolean local);
058
059 /**
060 * When an object is removed from knowledge base, its conclusions are also removed.
061 * If a rule needs to undo an action on object removal (e.g. delete a record from
062 * database, which was inserted on object addition), the rule shall register an
063 * undo handler.
064 * @param fact Fact to which the handler shall be attached.
065 * @param undoCommand Command which is executed when any of rule inputs is removed from the knowledge base.
066 */
067 void addUndo(Runnable undoCommand);
068
069
070 /**
071 * This method shall be invoked only from accept methods.
072 * @return Parameter indices in the target method corresponding to accept method parameters.
073 */
074 int[] parameterIndices();
075
076 /**
077 * @return Signature of the target multi-parameter <code>infer()</code> method.
078 */
079 Method targetMethod();
080
081 /**
082 * @param fact Fact.
083 * @return True if knowledge base contains given fact.
084 * @throws ReasoningException
085 */
086 boolean contains(Object fact) throws ReasoningException;
087
088 /**
089 * @return Collection of all objects in the knowledge base.
090 * @throws ReasoningException
091 */
092 Collection<?> getObjects() throws ReasoningException;
093
094 /**
095 * @return Properties associated with rule session and given inference path.
096 */
097 Map<String, ?> getProperties() throws ReasoningException;
098
099 /**
100 * Removes object from the knowledge base.
101 * @param fact
102 * @throws ReasoningException
103 */
104 void remove(Object fact) throws ReasoningException;
105
106 /**
107 * Updates mutable fact. Same as invoking <code>update(fact, fact)</code>
108 * @param fact
109 * @throws ReasoningException
110 */
111 void update(Object fact) throws ReasoningException;
112
113 /**
114 * Updates immutable fact with a new value.
115 * @param originalFact Original fact.
116 * @param newFact New fact to replace the original fact.
117 * @throws ReasoningException
118 */
119 void update(Object originalFact, Object newFact) throws ReasoningException;
120
121 }