01: /*
02: * Copyright (C) 1999-2004 <A href="http://www-ist.massey.ac.nz/JBDietrich" target="_top">Jens Dietrich</a>
03: *
04: * This library is free software; you can redistribute it and/or
05: * modify it under the terms of the GNU Lesser General Public
06: * License as published by the Free Software Foundation; either
07: * version 2 of the License, or (at your option) any later version.
08: *
09: * This library is distributed in the hope that it will be useful,
10: * but WITHOUT ANY WARRANTY; without even the implied warranty of
11: * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
12: * Lesser General Public License for more details.
13: *
14: * You should have received a copy of the GNU Lesser General Public
15: * License along with this library; if not, write to the Free Software
16: * Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA
17: */
18: package org.mandarax.kernel;
19:
20: /**
21: * Basic interface of an inference engine.
22: * <p>From version 1.7, we are using a new API for querying.
23: * There are two reasons to discard the old API (despite these methods are still available but marked
24: * as <em>deprecated </em>:
25: * <ol>
26: * <li>Clause sets now may throw exceptions when an interator is requested. This is to take into account that mandarax
27: * does not have to copy all knowledge into local memory, but can integrate clause sets from remote datasources
28: * (like web services), databases and so on. With the query, an exception handling policy can be specified. There are
29: * two policies avaialble right now: interrupt the derivation, or try the next clause or clause set.
30: * <li>The result is represented by the new class <code>ResultSet</code> designed similar to <code>java.sql.ResultSet</code>.
31: * This is to emphasize the database aspect of mandarax ('deductive database') and to help programmers using the API (assuming that
32: * most of them know JDBC). We will explore in the future to integrate more and more JDBC functionality, perhaps there could even be
33: * a Mandarax JDBC driver at the end of this process. The main problem seems to be a 'pure string based' query language ala SQL.
34: * </ol>
35: * <br>
36: * From version 1.9, query methods expect an instance of <code>Query</code> (and not <code>Clause</code>) to represent the query.
37: * Users have normally used facts to represent queries. For compatibility, the fact reference implementation
38: * implements the query interface.
39: * <br>
40: * Since 2.0, some deprecated query methods have been removed.
41: * @see org.mandarax.reference.FactImpl
42: * @see org.mandarax.reference.Query
43: * @author <A href="http://www-ist.massey.ac.nz/JBDietrich" target="_top">Jens Dietrich</A>
44: * @version 3.4 <7 March 05>
45: * @since 1.0
46: */
47: public interface InferenceEngine {
48:
49: public static final int ONE = 1;
50: public static final int ALL = -1;
51:
52: // constants representing exception handling strategies:
53: // ignore all ClauseSetExceptions, just try the next clause or clause set
54: public static final int TRY_NEXT = 0;
55: // bubble all exceptions
56: public static final int BUBBLE_EXCEPTIONS = 1;
57:
58: /**
59: * Get the feature descriptions.
60: * @return the feature descriptions
61: */
62: InferenceEngineFeatureDescriptions getFeatureDescriptions();
63:
64: /**
65: * Answer a query, retrieve (multiple different) result.
66: * The cardinality contraints describe how many results should be computed. It is either
67: * <ol>
68: * <li> <code>ONE</code> - indicating that only one answer is expected
69: * <li> <code>ALL</code> - indicating that all answers should be computed
70: * <li> <code>an integer value greater than 0 indicating that this number of results expected
71: * </ol>
72: * Note that computing many or all answers can be a very expensive task!<p>
73: * Not all inference engines will support retrieving multiple answers, to find out whether this is supported use the feature descriptions.
74: * If it is not supported, a runtime exception (<code>java.lang.IllegalArgumentException</code>)
75: * is thrown indicating that the parameter (e.g. <code>ALL</code>) is not valid.
76: * @see #ONE
77: * @see #ALL
78: * @return the result set of the query
79: * @param query the query
80: * @param kb the knowledge base used to answer the query
81: * @param aCardinalityConstraint the number of results expected
82: * @param exceptionHandlingPolicy one of the constants definied in this class (BUBBLE_EXCEPTIONS,TRY_NEXT)
83: * @throws an InferenceException
84: */
85: ResultSet query(Query query, KnowledgeBase kb,
86: int aCardinalityConstraint, int exceptionHandlingPolicy)
87: throws InferenceException;
88: }
|