001 package com.hammurapi.reasoning;
002
003 import java.util.Collection;
004 import java.util.List;
005 import java.util.Map;
006 import java.util.Set;
007
008 /**
009 * Marker base interface for forward reasoning sessions.
010 * @author Pavel
011 * @param <F> Base class for facts.
012 */
013 public interface ForwardReasoningSession<F> extends ReasoningSession {
014
015 /**
016 * Puts object to knowledge base. If the same object (equals() based comparison)
017 * is put to the knowledge base several times, each time shall return the same
018 * handle. onAdd() listener method shall fire only the first time.
019 * @param fact
020 * @return Object handle.
021 * @throws ReasoningException
022 */
023 Handle<F> put(F fact) throws ReasoningException;
024
025 /**
026 * Puts objects in the list to the knowledge base and returns their handles.
027 * @param facts
028 * @return
029 * @throws ReasoningException
030 */
031 List<Handle<F>> putAll(List<? extends F> facts) throws ReasoningException;
032
033 /**
034 * Puts facts to the knowledge base and returns array of their handles.
035 * @param facts
036 * @return
037 * @throws ReasoningException
038 */
039 Handle<F>[] putAll(F... facts) throws ReasoningException;
040
041 /**
042 * @param fact Fact.
043 * @return True if knowledge base contains given fact.
044 * @throws ReasoningException
045 */
046 boolean contains(Object fact) throws ReasoningException;
047
048 /**
049 * @param handle Handle.
050 * @return True if knowledge base contains fact identified by given handle.
051 * @throws ReasoningException
052 */
053 boolean contains(Handle<F> handle) throws ReasoningException;
054
055 /**
056 * Retrieves object by its handle.
057 * @param handle
058 * @return
059 * @throws ReasoningException
060 */
061 F get(Handle<F> handle) throws ReasoningException;
062
063 /**
064 * Retrieves object handle.
065 * @param fact
066 * @return Object handle or null if object is not present in the knowledge base.
067 */
068 Handle<F> getHandle(Object fact);
069
070 /**
071 * Removes fact from the knowledge base.
072 * @param fact Fact to be removed.
073 * @param strict True means that the fact is known to be false
074 * and the fact and all derivations shall be removed from the knowledge base.
075 * False means that it is not known that the fact is true, but it
076 * is not known that the fact is false either. As such, the fact
077 * shall be removed (and all derivations) only if it wasn't derived
078 * from other facts.
079 */
080 void remove(F fact, boolean strict) throws ReasoningException;
081
082 /**
083 * Removes fact from the knowledge base.
084 * @param handle Fact represented by this handle to be removed.
085 * @param strict True means that the fact is known to be false
086 * and the fact and all derivations shall be removed from the knowledge base.
087 * False means that it is not known that the fact is true, but it
088 * is not known that the fact is false either. As such, the fact
089 * shall be removed (and all derivations) only if it wasn't derived
090 * from other facts.
091 */
092 void remove(Handle<F> handle, boolean strict) throws ReasoningException;
093
094 /**
095 * @return Collection of all objects in the knowledge base.
096 * @throws ReasoningException
097 */
098 Collection<? extends F> getObjects() throws ReasoningException;
099
100 /**
101 * @return Collection of handles to all objects in the knowledge base.
102 * @throws ReasoningException
103 */
104 Collection<Handle<F>> getHandles() throws ReasoningException;
105
106 /**
107 * Returns information on how given object was derived.
108 * @param obj Conclusion.
109 * @return List of derivation trees which lead to given conclusion.
110 * @throws ReasoningException
111 */
112 Collection<Derivation<F>> getDerivations(F obj) throws ReasoningException;
113
114 /**
115 * Returns information on how given object was derived.
116 * @param handle Conclusion handle.
117 * @return List of derivation trees which lead to given conclusion.
118 * @throws ReasoningException
119 */
120 Collection<Derivation<F>> getDerivations(Handle<F> handle) throws ReasoningException;
121
122 /**
123 * Fires rules execution. All rules shall finish execution before this
124 * method returns.
125 * @throws ReasoningException
126 */
127 void executeRules() throws ReasoningException;
128
129 /**
130 * Sets reasoning listener for the session.
131 * @param listener
132 * @throws ReasoningException
133 */
134 void setInferenceListener(InferenceListener<F> listener) throws ReasoningException;
135
136 /**
137 * @return Session's inference listener.
138 * @throws ReasoningException
139 */
140 InferenceListener<F> getInferenceListener() throws ReasoningException;
141
142 /**
143 * Updates fact. This operation is equivalent to strict removal and subsequent addition
144 * of the fact to the knowledge base.
145 * @param handle Fact handle.
146 * @param obj New fact value.
147 * @throws InvalidReasoningSessionException
148 * @throws InvalidHandleException
149 */
150 void updateObject(Handle<F> handle, F obj) throws ReasoningException;
151
152 /**
153 * Retrieves mapping of conclusion types to fact types
154 * from which given conclusion type can be inferred.
155 * This is an optional operation to support wrapping forward reasoning
156 * sessions into backward reasoning sessions.
157 * @return Mapping Conclusion type -> Collection of fact types to support conclusion.
158 */
159 Map<Class<F>, Set<Class<F>>> getConclusionMap();
160
161 }