TupleSet


1   package prefuse.data.tuple;
2   
3   import java.beans.PropertyChangeListener  ;
4   import java.util.Iterator  ;
5   
6   import prefuse.data.Schema;
7   import prefuse.data.Tuple;
8   import prefuse.data.event.TupleSetListener;
9   import prefuse.data.expression.Expression;
10  import prefuse.data.expression.Predicate;
11  import prefuse.data.util.Sort;
12  
13  /**
14   * A collection of data tuples. This is the top level interface for all
15   * data collections in the prefuse framework.
16   * 
17   * @author <a HREF="http://jheer.org">jeffrey heer</a>
18   * @see prefuse.data.Tuple
19   */
20  public interface TupleSet {
21  
22      /**
23       * An empty, zero-length array of tuples.
24       */
25      public static final Tuple[] EMPTY_ARRAY = new Tuple[0];
26      
27      /**
28       * Add a Tuple to this TupleSet. This method is optional, and may result
29       * in an UnsupportedOperationException on some TupleSet implementations.
30       * @param t the Tuple add
31       * @return the actual Tuple instance stored in the TupleSet. This may be
32       * null to signify that the add failed, may be a new Tuple with
33       * values copied from the input tuple, or may be the input Tuple itself.
34       */
35      public Tuple addTuple(Tuple t);
36      
37      /**
38       * Set the TupleSet contents to be a single Tuple. This method is
39       * optional, and may result in an UnsupportedOperationException on some
40       * TupleSet implementations.
41       * @param t the Tuple to set as the content of this TupleSet
42       * @return the actual Tuple instance stored in the TupleSet. This may be
43       * null to signify that the add failed, may be a new Tuple with
44       * values copied from the input tuple, or may be the input Tuple itself.
45       */
46      public Tuple setTuple(Tuple t);
47      
48      /**
49       * Remove a Tuple from this TupleSet.
50       * @param t the Tuple to remove
51       * @return true if the Tuple was found and removed, false otherwise
52       */
53      public boolean removeTuple(Tuple t);
54      
55      /**
56       * Clear this TupleSet, removing all contained Tuples.
57       */
58      public void clear();
59      
60      /**
61       * Indicates if a given Tuple is contained within this TupleSet.
62       * @param t the tuple to check for containment
63       * @return true if the Tuple is in this TupleSet, false otherwise
64       */
65      public boolean containsTuple(Tuple t);
66      
67      /**
68       * Get the number of tuples in this set.
69       * @return the tuple count
70       */
71      public int getTupleCount();
72      
73      /**
74       * Indicates if this TupleSet supports the addition of data columns to
75       * its contained Tuple instances.
76       * @return true is add column operations are supported, false otherwise
77       */
78      public boolean isAddColumnSupported();
79      
80      /**
81       * Add the data fields of the given Schema to the Tuples in this TupleSet.
82       * If this TupleSet contains heterogeneous Tuples (i.e., those from
83       * different source tables), all backing tables involved will be updated.
84       * @param s the Schema of data columns to add to this TupleSet
85       */
86      public void addColumns(Schema s);
87      
88      /**
89       * Add a data field / column to this TupleSet's members.
90       * @param name the name of the data field
91       * @param type the type of the data field
92       */
93      public void addColumn(String   name, Class   type);
94      
95      /**
96       * Add a data field / column to this TupleSet's members.
97       * @param name the name of the data field
98       * @param type the type of the data field
99       * @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     
152     // -- Listeners -----------------------------------------------------------
153     
154     /**
155      * Add a listener to this tuple set that will be notified when tuples
156      * are added and removed from the set.
157      * @param tsl the TupleSetListener to add
158      */
159     public void addTupleSetListener(TupleSetListener tsl);
160     
161     /**
162      * Remove a listener from this tuple set.
163      * @param tsl the TupleSetListener to remove
164      */
165     public void removeTupleSetListener(TupleSetListener tsl);
166     
167     
168     // -- Client Properties ---------------------------------------------------
169     
170     /**
171      * Add a PropertyChangeListener to be notified of changes to the properties
172      * bounds to this TupleSet.
173      * @param lstnr the PropertyChangeListener to add
174      */
175     public void addPropertyChangeListener(PropertyChangeListener   lstnr);
176 
177     /**
178      * Add a PropertyChangeListener to be notified of changes to a
179      * specific property bound to this TupleSet.
180      * @param key the specific key for which to listen to properties changes
181      * @param lstnr the PropertyChangeListener to add
182      */
183     public void addPropertyChangeListener(String   key, 
184                                           PropertyChangeListener   lstnr);
185 
186     /**
187      * Remove a PropertyChangeListener from this TupleSet.
188      * @param lstnr the PropertyChangeListener to remove
189      */
190     public void removePropertyChangeListener(PropertyChangeListener   lstnr);
191     
192     /**
193      * Remove a PropertyChangeListener from this TupleSet for a specific
194      * bound property.
195      * @param key the specific key for which to remove the listener
196      * @param lstnr the PropertyChangeListener to remove
197      */
198     public void removePropertyChangeListener(String   key,
199                                              PropertyChangeListener   lstnr);
200     
201     /**
202      * Set an arbitrary client property with this TupleSet
203      * @param key the name of the property to set
204      * @param value the value of the property to use
205      */
206     public void putClientProperty(String   key, Object   value);
207     
208     /**
209      * Get an client property bound to this TupleSet
210      * @param key the name of the property to retrieve
211      * @return the client property value, or null if no value was
212      * found for the given key.
213      */
214     public Object   getClientProperty(String   key);
215     
216 } // end of interface TupleSet
217
A to Z: JavaDoc & Examples Daily Java News & Articles Open Source Projects Open Source Codes Free Computer Books Remove Frame
Popular Tags