Tuple


1   package prefuse.data;
2   
3   import java.util.Date  ;
4   
5   
6   /**
7    * Tuples are objects representing a row of a data table, providing
8    * a simplified interface to table data. They maintain a pointer to a
9    * corresponding row in a table. When rows are deleted, any live Tuples
10   * for that row become invalidated, and any further attempts to access
11   * or set data with that Tuple will result in an exception.
12   * 
13   * @author <a HREF="http://jheer.org">jeffrey heer</a>
14   */
15  public interface Tuple {
16  
17      /**
18       * Returns the schema for this tuple's data.
19       * @return the Tuple Schema
20       */
21      public Schema getSchema();
22      
23      /**
24       * Returns the Table instance that backs this Tuple, if it exists.
25       * @return the backing Table, or null if there is none.
26       */
27      public Table getTable();
28      
29      /**
30       * Returns the row index for this Tuple's backing Table, if it exists.
31       * @return the backing row index, or -1 if there is no backing table
32       * or if this Tuple has been invalidated (i.e., the Tuple's row was
33       * deleted from the backing table).
34       */
35      public int getRow();
36      
37      /**
38       * Indicates if this Tuple is valid. Trying to get or set values on an
39       * invalid Tuple will result in a runtime exception.
40       * @return true if this Tuple is valid, false otherwise
41       */
42      public boolean isValid();
43      
44      // ------------------------------------------------------------------------
45      // Column Methods
46      
47      /**
48       * Returns the data type of the given field as a Java Class instance.
49       * @param field the data field
50       * @return the data type of the field, a Class instance indicating the
51       * top-level type of data values in this field.
52       */
53      public Class   getColumnType(String   field);
54      
55      /**
56       * Returns the data type of the given column as a Java Class instance.
57       * @param col the column index
58       * @return the data type of the column, a Class instance indicating the
59       * top-level type of data values in this field.
60       */
61      public Class   getColumnType(int col);
62      
63      /**
64       * Get the column index corresponding to the given data field.
65       * @param field the data field to look up
66       * @return the column index of the field within the backing table, or
67       * -1 if no columns with the given name were found
68       */
69      public int getColumnIndex(String   field);
70      
71      /**
72       * Get the number of columns maintained by the backing table.
73       * @return the number of columns / data fields.
74       */
75      public int getColumnCount();
76      
77      /**
78       * Get the data field name of the column at the given index.
79       * @param col the column index to look up
80       * @return the data field name of the given column index
81       */
82      public String   getColumnName(int col);
83      
84      // ------------------------------------------------------------------------
85      // Data Access Methods
86      
87      /**
88       * Check if the <code>get</code> method for the given data field returns
89       * values that are compatible with a given target type.
90       * @param field the data field to check
91       * @param type a Class instance to check for compatibility with the
92       * data field values.
93       * @return true if the data field is compatible with provided type,
94       * false otherwise. If the value is true, objects returned by
95       * the {@link #get(String)} can be cast to the given type.
96       * @see #get(String)
97       */
98      public boolean canGet(String   field, Class   type);
99      
100     /**
101      * Check if the <code>set</code> method for the given data field can
102      * accept values of a given target type.
103      * @param field the data field to check
104      * @param type a Class instance to check for compatibility with the
105      * data field values.
106      * @return true if the data field is compatible with provided type,
107      * false otherwise. If the value is true, objects of the given type
108      * can be used as parameters of the {@link #set(String, Object)} method.
109      * @see #set(String, Object)
110      */
111     public boolean canSet(String   field, Class   type);
112     
113     /**
114      * Get the data value at the given field as an Object.
115      * @param field the data field to retrieve
116      * @return the data value as an Object. The concrete type of this
117      * Object is dependent on the underlying data column used.
118      * @see #canGet(String, Class)
119      * @see #getColumnType(String)
120      */
121     public Object   get(String   field);
122 
123     /**
124      * Set the value of a given data field.
125      * @param field the data field to set
126      * @param value the value for the field. If the concrete type of this
127      * Object is not compatible with the underlying data model, an
128      * Exception will be thrown. Use the {@link #canSet(String, Class)}
129      * method to check the type-safety ahead of time.
130      * @see #canSet(String, Class)
131      * @see #getColumnType(String)
132      */
133     public void set(String   field, Object   value);
134     
135     /**
136      * Get the data value at the given column number as an Object.
137      * @param col the column number
138      * @return the data value as an Object. The concrete type of this
139      * Object is dependent on the underlying data column used.
140      * @see #canGet(String, Class)
141      * @see #getColumnType(int)
142      */
143     public Object   get(int col);
144     
145     /**
146      * Set the value of at the given column number.
147      * @param col the column number
148      * @param value the value for the field. If the concrete type of this
149      * Object is not compatible with the underlying data model, an
150      * Exception will be thrown. Use the {@link #canSet(String, Class)}
151      * method to check the type-safety ahead of time.
152      * @see #canSet(String, Class)
153      * @see #getColumnType(String)
154      */
155     public void set(int col, Object   value);
156     
157     /**
158      * Get the default value for the given data field.
159      * @param field the data field
160      * @return the default value, as an Object, used to populate rows
161      * of the data field.
162      */
163     public Object   getDefault(String   field);
164     
165     /**
166      * Revert this tuple's value for the given field to the default value
167      * for the field.
168      * @param field the data field
169      * @see #getDefault(String)
170      */
171     public void revertToDefault(String   field);
172     
173     // ------------------------------------------------------------------------
174     // Convenience Data Access Methods
175     
176     /**
177      * Check if the given data field can return primitive <code>int</code>
178      * values.
179      * @param field the data field to check
180      * @return true if the data field can return primitive <code>int</code>
181      * values, false otherwise. If true, the {@link #getInt(String)} method
182      * can be used safely.
183      */
184     public boolean canGetInt(String   field);
185     
186     /**
187      * Check if the <code>setInt</code> method can safely be used for the
188      * given data field.
189      * @param field the data field to check
190      * @return true if the {@link #setInt(String, int)} method can safely
191      * be used for the given field, false otherwise.
192      */
193     public boolean canSetInt(String   field);
194     
195     /**
196      * Get the data value at the given field as an <code>int</code>.
197      * @param field the data field to retrieve
198      * @see #canGetInt(String)
199      */
200     public int getInt(String   field);
201     
202     /**
203      * Set the data value of the given field with an <code>int</code>.
204      * @param field the data field to set
205      * @param val the value to set
206      * @see #canSetInt(String)
207      */
208     public void setInt(String   field, int val);
209     
210     /**
211      * Get the data value at the given field as an <code>int</code>.
212      * @param col the column number of the data field to retrieve
213      * @see #canGetInt(String)
214      */
215     public int getInt(int col);
216     
217     /**
218      * Set the data value of the given field with an <code>int</code>.
219      * @param col the column number of the data field to set
220      * @param val the value to set
221      * @see #canSetInt(String)
222      */
223     public void setInt(int col, int val);
224     
225     // --------------------------------------------------------------
226     
227     /**
228      * Check if the given data field can return primitive <code>long</code>
229      * values.
230      * @param field the data field to check
231      * @return true if the data field can return primitive <code>long</code>
232      * values, false otherwise. If true, the {@link #getLong(String)} method
233      * can be used safely.
234      */
235     public boolean canGetLong(String   field);
236     
237     /**
238      * Check if the <code>setLong</code> method can safely be used for the
239      * given data field.
240      * @param field the data field to check
241      * @return true if the {@link #setLong(String, long)} method can safely
242      * be used for the given field, false otherwise.
243      */
244     public boolean canSetLong(String   field);
245     
246     /**
247      * Get the data value at the given field as a <code>long</code>.
248      * @param field the data field to retrieve
249      * @see #canGetLong(String)
250      */
251     public long getLong(String   field);
252     
253     /**
254      * Set the data value of the given field with a <code>long</code>.
255      * @param field the data field to set
256      * @param val the value to set
257      * @see #canSetLong(String)
258      */
259     public void setLong(String   field, long val);
260     
261     /**
262      * Get the data value at the given field as a <code>long</code>.
263      * @param col the column number of the data field to retrieve
264      * @see #canGetLong(String)
265      */
266     public long getLong(int col);
267     
268     /**
269      * Set the data value of the given field with a <code>long</code>.
270      * @param col the column number of the data field to set
271      * @param val the value to set
272      * @see #canSetLong(String)
273      */
274     public void setLong(int col, long val);
275 
276     // --------------------------------------------------------------
277     
278     /**
279      * Check if the given data field can return primitive <code>float</code>
280      * values.
281      * @param field the data field to check
282      * @return true if the data field can return primitive <code>float</code>
283      * values, false otherwise. If true, the {@link #getFloat(String)} method
284      * can be used safely.
285      */
286     public boolean canGetFloat(String   field);
287     
288     /**
289      * Check if the <code>setFloat</code> method can safely be used for the
290      * given data field.
291      * @param field the data field to check
292      * @return true if the {@link #setFloat(String, float)} method can safely
293      * be used for the given field, false otherwise.
294      */
295     public boolean canSetFloat(String   field);
296     
297     /**
298      * Get the data value at the given field as a <code>float</code>.
299      * @param field the data field to retrieve
300      * @see #canGetFloat(String)
301      */
302     public float getFloat(String   field);
303     
304     /**
305      * Set the data value of the given field with a <code>float</code>.
306      * @param field the data field to set
307      * @param val the value to set
308      * @see #canSetFloat(String)
309      */
310     public void setFloat(String   field, float val);
311     
312     /**
313      * Get the data value at the given field as a <code>float</code>.
314      * @param col the column number of the data field to retrieve
315      * @see #canGetFloat(String)
316      */
317     public float getFloat(int col);
318     
319     /**
320      * Set the data value of the given field with a <code>float</code>.
321      * @param col the column number of the data field to set
322      * @param val the value to set
323      * @see #canSetFloat(String)
324      */
325     public void setFloat(int col, float val);
326     
327     // --------------------------------------------------------------
328     
329     /**
330      * Check if the given data field can return primitive <code>double</code>
331      * values.
332      * @param field the data field to check
333      * @return true if the data field can return primitive <code>double</code>
334      * values, false otherwise. If true, the {@link #getDouble(String)} method
335      * can be used safely.
336      */
337     public boolean canGetDouble(String   field);
338     
339     /**
340      * Check if the <code>setDouble</code> method can safely be used for the
341      * given data field.
342      * @param field the data field to check
343      * @return true if the {@link #setDouble(String, double)} method can safely
344      * be used for the given field, false otherwise.
345      */
346     public boolean canSetDouble(String   field);
347     
348     /**
349      * Get the data value at the given field as a <code>double</code>.
350      * @param field the data field to retrieve
351      * @see #canGetDouble(String)
352      */
353     public double getDouble(String   field);
354     
355     /**
356      * Set the data value of the given field with a <code>double</code>.
357      * @param field the data field to set
358      * @param val the value to set
359      * @see #canSetDouble(String)
360      */
361     public void setDouble(String   field, double val);
362     
363     /**
364      * Get the data value at the given field as a <code>double</code>.
365      * @param col the column number of the data field to retrieve
366      * @see #canGetDouble(String)
367      */
368     public double getDouble(int col);
369     
370     /**
371      * Set the data value of the given field with a <code>double</code>.
372      * @param col the column number of the data field to set
373      * @param val the value to set
374      * @see #canSetDouble(String)
375      */
376     public void setDouble(int col, double val);
377     
378     // --------------------------------------------------------------
379     
380     /**
381      * Check if the given data field can return primitive <code>boolean</code>
382      * values.
383      * @param field the data field to check
384      * @return true if the data field can return primitive <code>boolean</code>
385      * values, false otherwise. If true, the {@link #getBoolean(String)} method
386      * can be used safely.
387      */
388     public boolean canGetBoolean(String   field);
389     
390     /**
391      * Check if the <code>setBoolean</code> method can safely be used for the
392      * given data field.
393      * @param field the data field to check
394      * @return true if the {@link #setBoolean(String, boolean)} method can
395      * safely be used for the given field, false otherwise.
396      */
397     public boolean canSetBoolean(String   field);
398     
399     /**
400      * Get the data value at the given field as a <code>boolean</code>.
401      * @param field the data field to retrieve
402      * @see #canGetBoolean(String)
403      */
404     public boolean getBoolean(String   field);
405     
406     /**
407      * Set the data value of the given field with a <code>boolean</code>.
408      * @param field the data field to set
409      * @param val the value to set
410      * @see #canSetBoolean(String)
411      */
412     public void setBoolean(String   field, boolean val);
413     
414     /**
415      * Get the data value at the given field as a <code>boolean</code>.
416      * @param col the column number of the data field to retrieve
417      * @see #canGetBoolean(String)
418      */
419     public boolean getBoolean(int col);
420     
421     /**
422      * Set the data value of the given field with a <code>boolean</code>.
423      * @param col the column number of the data field to set
424      * @param val the value to set
425      * @see #canSetBoolean(String)
426      */
427     public void setBoolean(int col, boolean val);
428     
429     // --------------------------------------------------------------
430     
431     /**
432      * Check if the given data field can return <code>String</code>
433      * values.
434      * @param field the data field to check
435      * @return true if the data field can return <code>String</code>
436      * values, false otherwise. If true, the {@link #getString(String)} method
437      * can be used safely.
438      */
439     public boolean canGetString(String   field);
440     
441     /**
442      * Check if the <code>setString</code> method can safely be used for the
443      * given data field.
444      * @param field the data field to check
445      * @return true if the {@link #setString(String, String)} method can safely
446      * be used for the given field, false otherwise.
447      */
448     public boolean canSetString(String   field);
449     
450     /**
451      * Get the data value at the given field as a <code>String</code>.
452      * @param field the data field to retrieve
453      * @see #canGetString(String)
454      */
455     public String   getString(String   field);
456     
457     /**
458      * Set the data value of the given field with a <code>String</code>.
459      * @param field the data field to set
460      * @param val the value to set
461      * @see #canSetString(String)
462      */
463     public void setString(String   field, String   val);
464     
465     /**
466      * Get the data value at the given field as a <code>String</code>.
467      * @param col the column number of the data field to retrieve
468      * @see #canGetString(String)
469      */
470     public String   getString(int col);
471     
472     /**
473      * Set the data value of the given field with a <code>String</code>.
474      * @param col the column number of the data field to set
475      * @param val the value to set
476      * @see #canSetString(String)
477      */
478     public void setString(int col, String   val);
479     
480     // --------------------------------------------------------------
481     
482     /**
483      * Check if the given data field can return <code>Date</code>
484      * values.
485      * @param field the data field to check
486      * @return true if the data field can return <code>Date</code>
487      * values, false otherwise. If true, the {@link #getDate(String)} method
488      * can be used safely.
489      */
490     public boolean canGetDate(String   field);
491     
492     /**
493      * Check if the <code>setDate</code> method can safely be used for the
494      * given data field.
495      * @param field the data field to check
496      * @return true if the {@link #setDate(String, Date)} method can safely
497      * be used for the given field, false otherwise.
498      */
499     public boolean canSetDate(String   field);
500     
501     /**
502      * Get the data value at the given field as a <code>Date</code>.
503      * @param field the data field to retrieve
504      * @see #canGetDate(String)
505      */
506     public Date   getDate(String   field);
507     
508     /**
509      * Set the data value of the given field with a <code>Date</code>.
510      * @param field the data field to set
511      * @param val the value to set
512      * @see #canSetDate(String)
513      */
514     public void setDate(String   field, Date   val);
515     
516     /**
517      * Get the data value at the given field as a <code>Date</code>.
518      * @param col the column number of the data field to retrieve
519      * @see #canGetDate(String)
520      */
521     public Date   getDate(int col);
522     
523     /**
524      * Set the data value of the given field with a <code>Date</code>.
525      * @param col the column number of the data field to set
526      * @param val the value to set
527      * @see #canSetDate(String)
528      */
529     public void setDate(int col, Date   val);
530     
531 } // end of interface Tuple
532
A to Z: JavaDoc & Examples Daily Java News & Articles Open Source Projects Open Source Codes Free Computer Books Remove Frame
Popular Tags