package prolog.model;

import java.util.*;
import java.io.*;
import prolog.*;
import prolog.util.ParameterMatchingError;

/**
 * <p>This class represent the complete fact database. in this class,
 * facts are stored as relations in factlists. this factlists are ordered
 * by the fact's name. A fact database can be used to prove facts a unsafe fact.</p>
 */
public interface IFactDb
{
	/**
	 * clears the fact database
	 */
	public void clear();

	/**
	 * returns the factlist for the given name
	 * @param key the name of the fact to search for
	 * @return the factlist matching the given key
	 */
	public IFactList getFactList( int key );

	/**
	 * adds the given fact to the fact database.
	 * first the database is queries for a factlist with the name of
	 * the given fact. if one was found, the relation of the given
	 * fact is stored. if no one was found, a new factlist is created in
	 * which the relation is stored.
	 * @param f is the fact to be added
	 */
	public void add( IFact f );

	/**
	 * adds a new relation to the fact database under the given name.
	 * first the database is queries for a factlist matching name.
	 * if one was found, the relation is stored in. If no one was found,
	 * a new factlist is created in which the relation is stored.
	 * @param relation is the relation to be added
	 * @param name is the name of the relation
	 */
	public void add( IRelation relation, int name );

	/**
	 * queries the database for a fact.
	 * it returns true, if a fact in database is found matching the given one.
	 * first, the database is queried for a factlist with the given name.
	 * if on was found, this list is iterated finding a fact matching the
	 * given facts. If one was found, this method returns true, in all other
	 * cases false. If it returns true, the given fact is proven.
	 * @param f is the fact to test
	 * @return true if the given fact is true
	 */
	public boolean isFact( IFact f )
		throws ParameterMatchingError;

	/**
	 * generates a xml representation of this fact database
	 * @param out is the writer where to append the xml
	 * @param table
	 * @throws IOException
	 */
	public void genXml( Writer out, ISymbolTable table )
		throws IOException;

	/**
	 * returns a string representation with decoded symbols
	 * @param table is the symboltable to decode
	 * @return a string representation ;-)
	 */
	public String toString( ISymbolTable table );

	/**
	 * @return a iterator over all stored factlists
	 */
	public Iterator getFactLists();
}