001: package prefuse.data.tuple;
002:
003: import java.beans.PropertyChangeListener;
004: import java.util.Iterator;
005:
006: import prefuse.data.Schema;
007: import prefuse.data.Tuple;
008: import prefuse.data.event.TupleSetListener;
009: import prefuse.data.expression.Expression;
010: import prefuse.data.expression.Predicate;
011: import prefuse.data.util.Sort;
012:
013: /**
014: * A collection of data tuples. This is the top level interface for all
015: * data collections in the prefuse framework.
016: *
017: * @author <a href="http://jheer.org">jeffrey heer</a>
018: * @see prefuse.data.Tuple
019: */
020: public interface TupleSet {
021:
022: /**
023: * An empty, zero-length array of tuples.
024: */
025: public static final Tuple[] EMPTY_ARRAY = new Tuple[0];
026:
027: /**
028: * Add a Tuple to this TupleSet. This method is optional, and may result
029: * in an UnsupportedOperationException on some TupleSet implementations.
030: * @param t the Tuple add
031: * @return the actual Tuple instance stored in the TupleSet. This may be
032: * null to signify that the add failed, may be a new Tuple with
033: * values copied from the input tuple, or may be the input Tuple itself.
034: */
035: public Tuple addTuple(Tuple t);
036:
037: /**
038: * Set the TupleSet contents to be a single Tuple. This method is
039: * optional, and may result in an UnsupportedOperationException on some
040: * TupleSet implementations.
041: * @param t the Tuple to set as the content of this TupleSet
042: * @return the actual Tuple instance stored in the TupleSet. This may be
043: * null to signify that the add failed, may be a new Tuple with
044: * values copied from the input tuple, or may be the input Tuple itself.
045: */
046: public Tuple setTuple(Tuple t);
047:
048: /**
049: * Remove a Tuple from this TupleSet.
050: * @param t the Tuple to remove
051: * @return true if the Tuple was found and removed, false otherwise
052: */
053: public boolean removeTuple(Tuple t);
054:
055: /**
056: * Clear this TupleSet, removing all contained Tuples.
057: */
058: public void clear();
059:
060: /**
061: * Indicates if a given Tuple is contained within this TupleSet.
062: * @param t the tuple to check for containment
063: * @return true if the Tuple is in this TupleSet, false otherwise
064: */
065: public boolean containsTuple(Tuple t);
066:
067: /**
068: * Get the number of tuples in this set.
069: * @return the tuple count
070: */
071: public int getTupleCount();
072:
073: /**
074: * Indicates if this TupleSet supports the addition of data columns to
075: * its contained Tuple instances.
076: * @return true is add column operations are supported, false otherwise
077: */
078: public boolean isAddColumnSupported();
079:
080: /**
081: * Add the data fields of the given Schema to the Tuples in this TupleSet.
082: * If this TupleSet contains heterogeneous Tuples (i.e., those from
083: * different source tables), all backing tables involved will be updated.
084: * @param s the Schema of data columns to add to this TupleSet
085: */
086: public void addColumns(Schema s);
087:
088: /**
089: * Add a data field / column to this TupleSet's members.
090: * @param name the name of the data field
091: * @param type the type of the data field
092: */
093: public void addColumn(String name, Class type);
094:
095: /**
096: * Add a data field / column to this TupleSet's members.
097: * @param name the name of the data field
098: * @param type the type of the data field
099: * @param defaultValue the defaultValue of the data field
100: */
101: public void addColumn(String name, Class type, Object defaultValue);
102:
103: /**
104: * Add a data field / column to this TupleSet's members.
105: * @param name the name of the data field
106: * @param expr an uncompiled expression in the prefuse expression
107: * language. This will be compiled to a valid expression, and the
108: * results of applying the expression to a Tuple will become the
109: * data field value for that Tuple.
110: * @see prefuse.data.expression
111: * @see prefuse.data.expression.parser.ExpressionParser
112: */
113: public void addColumn(String name, String expr);
114:
115: /**
116: * Add a data field / column to this TupleSet's members.
117: * @param name the name of the data field
118: * @param expr a compiled expression in the prefuse expression
119: * language. The results of applying the expression to a Tuple will
120: * become the data field value for that Tuple.
121: * @see prefuse.data.expression
122: */
123: public void addColumn(String name, Expression expr);
124:
125: /**
126: * Return an iterator over the tuples in this tuple set.
127: * @return an iterator over this set's tuples
128: */
129: public Iterator tuples();
130:
131: /**
132: * Return an iterator over the tuples in this tuple set, filtered by
133: * the given predicate.
134: * @param filter predicate to apply to tuples in this set, only tuples
135: * for which the predicate evaluates to true are included in the iteration
136: * @return a filtered iterator over this set's tuples
137: */
138: public Iterator tuples(Predicate filter);
139:
140: /**
141: * Return an iterator over the tuples in this tuple set, filtered by
142: * the given predicate
143: * @param filter predicate to apply to tuples in this set, only tuples
144: * for which the predicate evaluates to true are included in the iteration.
145: * If this value is null, no filtering will be performed.
146: * @param sort the sorting criteria by which to order the returned tuples
147: * @return a filtered, sorted iterator over this set's tuples
148: */
149: public Iterator tuples(Predicate filter, Sort sort);
150:
151: // -- Listeners -----------------------------------------------------------
152:
153: /**
154: * Add a listener to this tuple set that will be notified when tuples
155: * are added and removed from the set.
156: * @param tsl the TupleSetListener to add
157: */
158: public void addTupleSetListener(TupleSetListener tsl);
159:
160: /**
161: * Remove a listener from this tuple set.
162: * @param tsl the TupleSetListener to remove
163: */
164: public void removeTupleSetListener(TupleSetListener tsl);
165:
166: // -- Client Properties ---------------------------------------------------
167:
168: /**
169: * Add a PropertyChangeListener to be notified of changes to the properties
170: * bounds to this TupleSet.
171: * @param lstnr the PropertyChangeListener to add
172: */
173: public void addPropertyChangeListener(PropertyChangeListener lstnr);
174:
175: /**
176: * Add a PropertyChangeListener to be notified of changes to a
177: * specific property bound to this TupleSet.
178: * @param key the specific key for which to listen to properties changes
179: * @param lstnr the PropertyChangeListener to add
180: */
181: public void addPropertyChangeListener(String key,
182: PropertyChangeListener lstnr);
183:
184: /**
185: * Remove a PropertyChangeListener from this TupleSet.
186: * @param lstnr the PropertyChangeListener to remove
187: */
188: public void removePropertyChangeListener(
189: PropertyChangeListener lstnr);
190:
191: /**
192: * Remove a PropertyChangeListener from this TupleSet for a specific
193: * bound property.
194: * @param key the specific key for which to remove the listener
195: * @param lstnr the PropertyChangeListener to remove
196: */
197: public void removePropertyChangeListener(String key,
198: PropertyChangeListener lstnr);
199:
200: /**
201: * Set an arbitrary client property with this TupleSet
202: * @param key the name of the property to set
203: * @param value the value of the property to use
204: */
205: public void putClientProperty(String key, Object value);
206:
207: /**
208: * Get an client property bound to this TupleSet
209: * @param key the name of the property to retrieve
210: * @return the client property value, or null if no value was
211: * found for the given key.
212: */
213: public Object getClientProperty(String key);
214:
215: } // end of interface TupleSet
|