/*
 * Copyright (C) 1999-2004 <a href="mailto:mandarax@jbdietrich.com">Jens Dietrich</a>
 *
 * This library is free software; you can redistribute it and/or
 * modify it under the terms of the GNU Lesser General Public
 * License as published by the Free Software Foundation; either
 * version 2 of the License, or (at your option) any later version.
 *
 * This library is distributed in the hope that it will be useful,
 * but WITHOUT ANY WARRANTY; without even the implied warranty of
 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
 * Lesser General Public License for more details.
 *
 * You should have received a copy of the GNU Lesser General Public
 * License along with this library; if not, write to the Free Software
 * Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA  02111-1307  USA
 */
package org.mandarax.kernel;


/**
 * Basic interface of an inference engine. 
 * <p>From version 1.7, we are using a new API for querying.
 * There are two reasons to discard the old API (despite these methods are still available but marked 
 * as <em>deprecated </em>: 
 * <ol>
 * <li>Clause sets now may throw exceptions when an interator is requested. This is to take into account that mandarax 
 * does not have to copy all knowledge into local memory, but can integrate clause sets from remote datasources 
 * (like web services), databases and so on. With the query, an exception handling policy can be specified. There are
 * two policies avaialble right now: interrupt the derivation, or try the next clause or clause set.
 * <li>The result is represented by the new class <code>ResultSet</code> designed similar to <code>java.sql.ResultSet</code>. 
 * This is to emphasize the database aspect of mandarax ('deductive database') and to help programmers using the API (assuming that
 * most of them know JDBC). We will explore in the future to integrate more and more JDBC functionality, perhaps there could even be
 * a Mandarax JDBC driver at the end of this process. The main problem seems to be a 'pure string based' query language ala SQL. 
 * </ol>
 * <br>
 * From version 1.9, query methods expect an instance of <code>Query</code> (and not <code>Clause</code>) to represent the query. 
 * Users have normally used facts to represent queries. For compatibility, the fact reference implementation 
 * implements the query interface.
 * <br>
 * Since 2.0, some deprecated query methods have been removed.
 * @see org.mandarax.reference.FactImpl
 * @see org.mandarax.reference.Query
 * @author <A HREF="mailto:mandarax@jbdietrich.com">Jens Dietrich</A>
 * @version 3.3.1 <9 August 2004>
 * @since 1.0
 */
public interface InferenceEngine {

    public static final int ONE = 1;
    public static final int ALL = -1;
    
    // constants representing exception handling strategies:    
    // ignore all ClauseSetExceptions, just try the next clause or clause set
    public static final int TRY_NEXT = 0;
    // bubble all exceptions 
    public static final int BUBBLE_EXCEPTIONS =1;
    
    /**
     * Get the feature descriptions.
     * @return the feature descriptions
     */
    InferenceEngineFeatureDescriptions getFeatureDescriptions();
   
    /**
     * Answer a query, retrieve (multiple different) result.
     * The cardinality contraints describe how many results should be computed. It is either
     * <ol>
     * <li> <code>ONE</code> - indicating that only one answer is expected
     * <li> <code>ALL</code> - indicating that all answers should be computed
     * <li> <code>an integer value greater than 0 indicating that this number of results expected
     * </ol>
     * Note that computing many or all answers can be a very expensive task!<p>
     * Not all inference engines will support retrieving multiple answers, to find out whether this is supported use the feature descriptions.
     * If it is not supported, a runtime exception (<code>java.lang.IllegalArgumentException</code>)
     * is thrown indicating that the parameter (e.g. <code>ALL</code>) is not valid.
     * @see #ONE
     * @see #ALL
     * @return the result set of the query
     * @param query the query
     * @param kb the knowledge base used to answer the query
     * @param aCardinalityConstraint the number of results expected
     * @param exceptionHandlingPolicy one of the constants definied in this class (BUBBLE_EXCEPTIONS,TRY_NEXT)
     * @throws an InferenceException
     */
    ResultSet query(Query query, KnowledgeBase kb,int aCardinalityConstraint,int exceptionHandlingPolicy) throws InferenceException;
}
