package prefuse.data.tuple;

import java.beans.PropertyChangeListener;
import java.util.Iterator;

import prefuse.data.Schema;
import prefuse.data.Tuple;
import prefuse.data.event.TupleSetListener;
import prefuse.data.expression.Expression;
import prefuse.data.expression.Predicate;

/**
 * A collection of data tuples. This is the top level interface for all
 * data collections in the prefuse framework.
 * 
 * @author <a href="http://jheer.org">jeffrey heer</a>
 * @see prefuse.data.Tuple
 */
public interface TupleSet {

    /**
     * An empty, zero-length array of tuples.
     */
    public static final Tuple[] EMPTY_ARRAY = new Tuple[0];
    
    /**
     * Add a Tuple to this TupleSet. This method is optional, and may result
     * in an UnsupportedOperationException on some TupleSet implementations.
     * @param t the Tuple add
     * @return the actual Tuple instance stored in the TupleSet. This may be
     * null to signify that the add failed, may be a new Tuple with
     * values copied from the input tuple, or may be the input Tuple itself.
     */
    public Tuple addTuple(Tuple t);
    
    /**
     * Set the TupleSet contents to be a single Tuple. This method is
     * optional, and may result in an UnsupportedOperationException on some
     * TupleSet implementations.
     * @param t the Tuple to set as the content of this TupleSet
     * @return the actual Tuple instance stored in the TupleSet. This may be
     * null to signify that the add failed, may be a new Tuple with
     * values copied from the input tuple, or may be the input Tuple itself.
     */
    public Tuple setTuple(Tuple t);
    
    /**
     * Remove a Tuple from this TupleSet.
     * @param t the Tuple to remove
     * @return true if the Tuple was found and removed, false otherwise
     */
    public boolean removeTuple(Tuple t);
    
    /**
     * Clear this TupleSet, removing all contained Tuples.
     */
    public void clear();
    
    /**
     * Indicates if a given Tuple is contained within this TupleSet.
     * @param t the tuple to check for containment
     * @return true if the Tuple is in this TupleSet, false otherwise
     */
    public boolean containsTuple(Tuple t);
    
    /**
     * Get the number of tuples in this set.
     * @return the tuple count
     */
    public int getTupleCount();
    
    /**
     * Indicates if this TupleSet supports the addition of data columns to
     * its contained Tuple instances.
     * @return true is add column operations are supported, false otherwise
     */
    public boolean isAddColumnSupported();
    
    /**
     * Add the data fields of the given Schema to the Tuples in this TupleSet.
     * If this TupleSet contains heterogeneous Tuples (i.e., those from
     * different source tables), all backing tables involved will be updated.
     * @param s the Schema of data columns to add to this TupleSet
     */
    public void addColumns(Schema s);
    
    /**
     * Add a data field / column to this TupleSet's members.
     * @param name the name of the data field
     * @param type the type of the data field
     */
    public void addColumn(String name, Class type);
    
    /**
     * Add a data field / column to this TupleSet's members.
     * @param name the name of the data field
     * @param type the type of the data field
     * @param defaultValue the defaultValue of the data field
     */
    public void addColumn(String name, Class type, Object defaultValue);
    
    /**
     * Add a data field / column to this TupleSet's members.
     * @param name the name of the data field
     * @param expr an uncompiled expression in the prefuse expression
     * language. This will be compiled to a valid expression, and the
     * results of applying the expression to a Tuple will become the
     * data field value for that Tuple.
     * @see prefuse.data.expression
     * @see prefuse.data.expression.parser.ExpressionParser
     */
    public void addColumn(String name, String expr);
    
    /**
     * Add a data field / column to this TupleSet's members.
     * @param name the name of the data field
     * @param expr a compiled expression in the prefuse expression
     * language. The results of applying the expression to a Tuple will
     * become the data field value for that Tuple.
     * @see prefuse.data.expression
     */
    public void addColumn(String name, Expression expr);
    
    /**
     * Return an iterator over the tuples in this tuple set.
     * @return an iterator over this set's tuples
     */
    public Iterator tuples();
    
    /**
     * Return an iterator over the tuples in this tuple set, filtered by
     * the given predicate.
     * @param filter predicate to apply to tuples in this set, only tuples
     * for which the predicate evaluates to true are included in the iteration
     * @return a filtered iterator over this set's tuples
     */
    public Iterator tuples(Predicate filter);
    
    
    // -- Listeners -----------------------------------------------------------
    
    /**
     * Add a listener to this tuple set that will be notified when tuples
     * are added and removed from the set.
     * @param tsl the TupleSetListener to add
     */
    public void addTupleSetListener(TupleSetListener tsl);
    
    /**
     * Remove a listener from this tuple set.
     * @param tsl the TupleSetListener to remove
     */
    public void removeTupleSetListener(TupleSetListener tsl);
    
    
    // -- Client Properties ---------------------------------------------------
    
    /**
     * Add a PropertyChangeListener to be notified of changes to the properties
     * bounds to this TupleSet.
     * @param lstnr the PropertyChangeListener to add
     */
    public void addPropertyChangeListener(PropertyChangeListener lstnr);

    /**
     * Add a PropertyChangeListener to be notified of changes to a
     * specific property bound to this TupleSet.
     * @param key the specific key for which to listen to properties changes
     * @param lstnr the PropertyChangeListener to add
     */
    public void addPropertyChangeListener(String key, 
                                          PropertyChangeListener lstnr);

    /**
     * Remove a PropertyChangeListener from this TupleSet.
     * @param lstnr the PropertyChangeListener to remove
     */
    public void removePropertyChangeListener(PropertyChangeListener lstnr);
    
    /**
     * Remove a PropertyChangeListener from this TupleSet for a specific
     * bound property.
     * @param key the specific key for which to remove the listener
     * @param lstnr the PropertyChangeListener to remove
     */
    public void removePropertyChangeListener(String key,
                                             PropertyChangeListener lstnr);
    
    /**
     * Set an arbitrary client property with this TupleSet
     * @param key the name of the property to set
     * @param value the value of the property to use
     */
    public void putClientProperty(String key, Object value);
    
    /**
     * Get an client property bound to this TupleSet
     * @param key the name of the property to retrieve
     * @return the client property value, or null if no value was
     * found for the given key.
     */
    public Object getClientProperty(String key);
    
} // end of interface TupleSet