/*
 * 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;

import java.util.Iterator;
/**
 * Knowledge Base objects are containers managing knowledge represented
 * by clauses sets (this includes facts and rules).
 * <br>
 * As from version 1.9 the knowledge base manages also a set of (named) queries.
 * This is consistent with <a href="www.ruleml.org">RuleML</a> where knowledge bases ("rule bases") also contain queries.
 * @see org.mandarax.kernel.Fact
 * @see org.mandarax.kernel.Rule
 * @see org.mandarax.kernel.ClauseSet
 * @author <A HREF="mailto:mandarax@jbdietrich.com">Jens Dietrich</A>
 * @version 3.3.1 <9 August 2004>
 * @since 1.0
 */
public interface KnowledgeBase extends KnowledgeOwner, ClauseSetChangeListener {

    /**
     * Add a clause set.
     * @param c a clause set
     */
    void add(ClauseSet c);

    /**
     * Add a knowledge base change listener.
     * @param l a listener
     */
    void addKnowledgeBaseChangeListener(KnowledgeBaseChangeListener l);

    /**
     * Get a collection containing all clause sets.
     * @return a list containing all clause sets
     */
    java.util.List getClauseSets();

    /**
     * Get a collection containing all clause sets that have the key.
     * @param the key object
     * @return a list containing all clause sets
     */
    java.util.List getClauseSets(Object key);

    /**
     * Get the feature descriptions.
     * @return the feature descriptions
     */
    KnowledgeBaseFeatureDescriptions getFeatureDescriptions();

    /**
     * Get the keys.
     * @return the list of keys
     */
    java.util.Collection getKeys();

    /**
     * Remove a clause.
     * @return true if the object has been found (true) or not (false)
     * @param c org.mandarax.kernel.ClauseSet
     */
    public boolean remove(ClauseSet c);

    /**
     * Remove all clauses.
     */
    public void removeAll();

    /**
     * Remove a knowledge base change listener.
     * @param l a listener
     */
    void removeKnowledgeBaseChangeListener(KnowledgeBaseChangeListener l);
    /**
     * Add a query.
     * @param q a query
     */
    void addQuery(Query q);
    /**
     * Remove a query.
     * @param q a query
     * @return true if the object has been found (true) or not (false)
     */
    boolean removeQuery(Query q);    
    /**
     * Get a query by name or null if there is no query with this name.
     * @param queryName a query name
     * @return a query of null if there is no query registered with this name
     */
    Query getQuery(String queryName);
    /**
     * Get an iterator for the names of all queries registered.
     * @return an iterator
     */
    Iterator queryNames(); 
    /**
     * Get an iterator for all queries registered.
     * @return an iterator
     */
    Iterator queries(); 
    /**
     * Get an iterator for all predicates contained (in any clause set with-) in the kb.
     * @return an iterator
     */
    Iterator predicates();

	/**
	 * Get a predicate by name.
	 * Note that there might by more than one predicate in the kb with the same name.
	 * In some cases, this makes sense (e.g. polymorphic predicates such as &lt for different
	 * types), but should be avoided for "custom" predicates (such as SimplePredicates).
	 * In this case, this method should return one predicate. In this case, applications can still use
	 * predicates() in order to find all predicates with a particular name.
	 * @return a predicate or null indicating that the kb does not contain a predicate with this name
	 * @param name a predicate name
	 */
	Predicate getPredicate(String name);

}
