001: package org.drools;
002:
003: /*
004: * Copyright 2005 JBoss Inc
005: *
006: * Licensed under the Apache License, Version 2.0 (the "License");
007: * you may not use this file except in compliance with the License.
008: * You may obtain a copy of the License at
009: *
010: * http://www.apache.org/licenses/LICENSE-2.0
011: *
012: * Unless required by applicable law or agreed to in writing, software
013: * distributed under the License is distributed on an "AS IS" BASIS,
014: * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
015: * See the License for the specific language governing permissions and
016: * limitations under the License.
017: */
018:
019: import java.io.Serializable;
020: import java.util.Iterator;
021: import java.util.List;
022: import java.util.Map;
023:
024: import org.drools.event.AgendaEventListener;
025: import org.drools.event.RuleFlowEventListener;
026: import org.drools.event.WorkingMemoryEventListener;
027: import org.drools.rule.Rule;
028: import org.drools.ruleflow.common.instance.ProcessInstance;
029: import org.drools.spi.Activation;
030: import org.drools.spi.AgendaFilter;
031: import org.drools.spi.AgendaGroup;
032: import org.drools.spi.AsyncExceptionHandler;
033: import org.drools.spi.GlobalResolver;
034:
035: /**
036: * A knowledge session for a <code>RuleBase</code>.
037: *
038: * While this object can be serialised out, it cannot be serialised in. This is because
039: * the RuleBase reference is transient. Please see the RuleBase interface for serializing
040: * in WorkingMemories from an InputStream.
041: *
042: */
043: public interface WorkingMemory extends EventManager {
044:
045: /**
046: * Returns the Agenda for this WorkingMemory. While the WorkingMemory interface is considered public, the Agenda interface
047: * is more subject to change.
048: * @return
049: * the Agenda
050: */
051: public Agenda getAgenda();
052:
053: /**
054: * Set a specific instance as a global in this working memory. Null values will return doing nothing.
055: * The global identifier and its type must be declared in the drl.
056: *
057: * @param identifier
058: * the identifier under which to populate the data
059: * @param value
060: * the global value, cannot be null
061: */
062: void setGlobal(String identifier, Object value);
063:
064: /**
065: * Retrieve a specific instance of global data by identifier
066: *
067: * @return application data or null if nothing is set under this identifier
068: */
069: Object getGlobal(String identifier);
070:
071: /**
072: * Sets the GlobalResolver instance to be used when resolving globals, replaces the current GlobalResolver.
073: * Typcicaly a delegating GlobalResolver is created that first gets a reference to the current GlobalResolver,
074: * for delegating
075: *
076: * @param globalResolver
077: */
078: void setGlobalResolver(GlobalResolver globalResolver);
079:
080: /**
081: * Returns the current GlobalResolver
082: *
083: * @return
084: */
085: GlobalResolver getGlobalResolver();
086:
087: /**
088: * Retrieve the <code>RuleBase</code> for this working memory.
089: *
090: * @return The <code>RuleBase</code>.
091: */
092: RuleBase getRuleBase();
093:
094: /**
095: * Fire all items on the agenda until empty.
096: *
097: * @throws FactException
098: * If a RuntimeException error occurs.
099: */
100: void fireAllRules() throws FactException;
101:
102: /**
103: * Fire all items on the agenda until empty, using the given AgendaFiler
104: *
105: * @throws FactException
106: * If a RuntimeException error occurs.
107: */
108: void fireAllRules(AgendaFilter agendaFilter) throws FactException;
109:
110: /**
111: * Fire all items on the agenda until empty or at most 'fireLimit' rules have fired
112: *
113: * @throws FactException
114: * If a RuntimeException error occurs.
115: */
116: void fireAllRules(int fireLimit) throws FactException;
117:
118: /**
119: * Fire all items on the agenda using the given AgendaFiler
120: * until empty or at most 'fireLimit' rules have fired
121: *
122: * @throws FactException
123: * If a RuntimeException error occurs.
124: */
125: void fireAllRules(final AgendaFilter agendaFilter, int fireLimit)
126: throws FactException;
127:
128: /**
129: * Retrieve the object associated with a <code>FactHandle</code>.
130: *
131: *
132: * @param handle
133: * The fact handle.
134: *
135: * @return The associated object.
136: */
137: Object getObject(FactHandle handle);
138:
139: /**
140: * Retrieve the <code>FactHandle</code> associated with an Object.
141: *
142: * @param object
143: * The object.
144: *
145: * @return The associated fact handle.
146: */
147: FactHandle getFactHandle(Object object);
148:
149: /**
150: * Returns an Iterator for the Objects in the Working Memory. This Iterator is not thread safe.
151: * @return
152: * the Iterator
153: */
154: Iterator iterateObjects();
155:
156: /**
157: * Returns an Iterator for the Objects in the Working Memory. This Iterator will filter out
158: * any objects that the ObjectFilter does not accept. This Iterator is not thread safe.
159: *
160: * @param filter
161: *
162: * @return
163: * the Iterator
164: */
165: Iterator iterateObjects(ObjectFilter filter);
166:
167: /**
168: * Returns an Iterator for the FactHandles in the Working Memory. This Iterator is not thread safe.
169: * @return
170: * the Iterator
171: */
172: Iterator iterateFactHandles();
173:
174: /**
175: * Returns an Iterator for the Objects in the Working Memory. This Iterator will filter out
176: * any objects that the ObjectFilter does not accept. This Iterator is not thread safe.
177: *
178: * @param filter
179: *
180: * @return
181: * the Iterator
182: */
183: Iterator iterateFactHandles(ObjectFilter filter);
184:
185: /**
186: * Returns the AgendaGroup which has the current WorkingMemory focus. The AgendaGroup interface is subject to change.
187: * @return
188: * the AgendaGroup
189: */
190: public AgendaGroup getFocus();
191:
192: /**
193: * Set the focus to the specified AgendaGroup
194: * @param focus
195: */
196: void setFocus(String focus);
197:
198: /**
199: * Set the focus to the specified AgendaGroup
200: * @param focus
201: */
202: void setFocus(AgendaGroup focus);
203:
204: /**
205: * Assert a fact.
206: *
207: * @param object
208: * The fact object.
209: *
210: * @return The new fact-handle associated with the object.
211: *
212: * @throws FactException
213: * If a RuntimeException error occurs.
214: */
215: FactHandle insert(Object object) throws FactException;
216:
217: /**
218: * Retrieve the QueryResults of the specified query.
219: *
220: * @param query
221: * The name of the query.
222: *
223: * @return The QueryResults of the specified query.
224: * If no results match the query it is empty.
225: *
226: * @throws IllegalArgumentException
227: * if no query named "query" is found in the rulebase
228: */
229: public QueryResults getQueryResults(String query);
230:
231: /**
232: * Retrieve the QueryResults of the specified query and arguments
233: *
234: * @param query
235: * The name of the query.
236: *
237: * @param arguments
238: * The arguments used for the query
239: *
240: * @return The QueryResults of the specified query.
241: * If no results match the query it is empty.
242: *
243: * @throws IllegalArgumentException
244: * if no query named "query" is found in the rulebase
245: */
246: public QueryResults getQueryResults(String query, Object[] arguments);
247:
248: /**
249: * Insert a fact registering JavaBean <code>PropertyChangeListeners</code>
250: * on the Object to automatically trigger <code>update</code> calls
251: * if <code>dynamic</code> is <code>true</code>.
252: *
253: * @param object
254: * The fact object.
255: * @param dynamic
256: * true if Drools should add JavaBean
257: * <code>PropertyChangeListeners</code> to the object.
258: *
259: * @return The new fact-handle associated with the object.
260: *
261: * @throws FactException
262: * If a RuntimeException error occurs.
263: */
264: FactHandle insert(Object object, boolean dynamic)
265: throws FactException;
266:
267: /**
268: * Retract a fact.
269: *
270: * @param handle
271: * The fact-handle associated with the fact to retract.
272: *
273: * @throws FactException
274: * If a RuntimeException error occurs.
275: */
276: void retract(FactHandle handle) throws FactException;
277:
278: /**
279: * Inform the WorkingMemory that a Fact has been modified and that it
280: * should now update the network.
281: *
282: * @param handle
283: * The fact-handle associated with the fact to modify.
284: * @param object
285: * The new value of the fact.
286: *
287: * @throws FactException
288: * If a RuntimeException error occurs.
289: */
290: void update(FactHandle handle, Object object) throws FactException;
291:
292: /**
293: *
294: * @param factHandle
295: */
296: public void modifyRetract(final FactHandle factHandle);
297:
298: /**
299: *
300: * @param factHandle
301: * @param object
302: */
303: public void modifyInsert(final FactHandle factHandle,
304: final Object object);
305:
306: /**
307: * Sets the AsyncExceptionHandler to handle exceptions thrown by the Agenda
308: * Scheduler used for duration rules.
309: *
310: * @param handler
311: */
312: void setAsyncExceptionHandler(AsyncExceptionHandler handler);
313:
314: /**
315: * Clear the Agenda. Iterates over each AgendaGroup cancalling all Activations.
316: */
317: void clearAgenda();
318:
319: /**
320: * Clear the Agenda Group, cancelling all its Activations.
321: */
322: public void clearAgendaGroup(String group);
323:
324: /**
325: * Clears the Activation Group, cancellings all its Activations
326: * @param group
327: */
328: public void clearActivationGroup(String group);
329:
330: /**
331: * Clears the RuleFlow group, cancelling all its Activations
332: * @param group
333: */
334: public void clearRuleFlowGroup(String group);
335:
336: /**
337: * Starts a new process instance for the process with the given id.
338: */
339: ProcessInstance startProcess(String processId);
340:
341: /**
342: * Stops rule firing after the currect rule finishes executing
343: *
344: */
345: public void halt();
346:
347: }
|