package prolog.model;

import java.io.*;
import java.util.*;

/**
 * <p>The base interface of a relation between some atoms, like a row
 * in a database. This interface is used to store and get facts but
 * also to store and get parameters e.g. in a statement</p>
 * <p>prolog: myFact(joe,dan).</p>
 * <p>in this example, the relation would contain the atoms "joe" and "dan"</p>
 */
public interface IRelation
{
	/**
	 * returns the number of atoms contained in this relation
	 * @return number of atoms
	 */
	public int getValueCount();

	/**
	 * returns the atom at the specified index
	 * @param index of the atom to be returned
	 * @return atom at the specified index
	 */
	public IAtom get( int index );

	/**
	 * returns an iterator over all atoms contained in this relation
	 * @return iterator over the values in this relation
	 */
	public Iterator getValues();

	/**
	 * builds a indexmap. a indexmap contains the atom
	 * as key and the index as integer. this function is only
	 * used for parameter matching.
	 * @return the created indexmap
	 */
	public Map buildMap();

	/**
	 * generates xml describing this relation
	 * @param out the writer where o append the xml
	 * @param table the symboltable if the xml should be decoded
	 * @throws IOException if writing xml fails
	 */
	public void genXml( Writer out, ISymbolTable table )
		throws IOException;

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

	/**
	 * returns a string representation of this object with decoded symbols
	 * in prolog syntax used for query results e.g. X=a, Y=b
	 * @param table - the symboltable used to decode
	 * @param parameterNames - the names of the parameters in this relation
	 * @return the string representation
	 */
	public String toString( int[] parameterNames, ISymbolTable table );
}