001: package prefuse.data;
002:
003: import java.util.Date;
004:
005: /**
006: * Tuples are objects representing a row of a data table, providing
007: * a simplified interface to table data. They maintain a pointer to a
008: * corresponding row in a table. When rows are deleted, any live Tuples
009: * for that row become invalidated, and any further attempts to access
010: * or set data with that Tuple will result in an exception.
011: *
012: * @author <a href="http://jheer.org">jeffrey heer</a>
013: */
014: public interface Tuple {
015:
016: /**
017: * Returns the schema for this tuple's data.
018: * @return the Tuple Schema
019: */
020: public Schema getSchema();
021:
022: /**
023: * Returns the Table instance that backs this Tuple, if it exists.
024: * @return the backing Table, or null if there is none.
025: */
026: public Table getTable();
027:
028: /**
029: * Returns the row index for this Tuple's backing Table, if it exists.
030: * @return the backing row index, or -1 if there is no backing table
031: * or if this Tuple has been invalidated (i.e., the Tuple's row was
032: * deleted from the backing table).
033: */
034: public int getRow();
035:
036: /**
037: * Indicates if this Tuple is valid. Trying to get or set values on an
038: * invalid Tuple will result in a runtime exception.
039: * @return true if this Tuple is valid, false otherwise
040: */
041: public boolean isValid();
042:
043: // ------------------------------------------------------------------------
044: // Column Methods
045:
046: /**
047: * Returns the data type of the given field as a Java Class instance.
048: * @param field the data field
049: * @return the data type of the field, a Class instance indicating the
050: * top-level type of data values in this field.
051: */
052: public Class getColumnType(String field);
053:
054: /**
055: * Returns the data type of the given column as a Java Class instance.
056: * @param col the column index
057: * @return the data type of the column, a Class instance indicating the
058: * top-level type of data values in this field.
059: */
060: public Class getColumnType(int col);
061:
062: /**
063: * Get the column index corresponding to the given data field.
064: * @param field the data field to look up
065: * @return the column index of the field within the backing table, or
066: * -1 if no columns with the given name were found
067: */
068: public int getColumnIndex(String field);
069:
070: /**
071: * Get the number of columns maintained by the backing table.
072: * @return the number of columns / data fields.
073: */
074: public int getColumnCount();
075:
076: /**
077: * Get the data field name of the column at the given index.
078: * @param col the column index to look up
079: * @return the data field name of the given column index
080: */
081: public String getColumnName(int col);
082:
083: // ------------------------------------------------------------------------
084: // Data Access Methods
085:
086: /**
087: * Check if the <code>get</code> method for the given data field returns
088: * values that are compatible with a given target type.
089: * @param field the data field to check
090: * @param type a Class instance to check for compatibility with the
091: * data field values.
092: * @return true if the data field is compatible with provided type,
093: * false otherwise. If the value is true, objects returned by
094: * the {@link #get(String)} can be cast to the given type.
095: * @see #get(String)
096: */
097: public boolean canGet(String field, Class type);
098:
099: /**
100: * Check if the <code>set</code> method for the given data field can
101: * accept values of a given target type.
102: * @param field the data field to check
103: * @param type a Class instance to check for compatibility with the
104: * data field values.
105: * @return true if the data field is compatible with provided type,
106: * false otherwise. If the value is true, objects of the given type
107: * can be used as parameters of the {@link #set(String, Object)} method.
108: * @see #set(String, Object)
109: */
110: public boolean canSet(String field, Class type);
111:
112: /**
113: * Get the data value at the given field as an Object.
114: * @param field the data field to retrieve
115: * @return the data value as an Object. The concrete type of this
116: * Object is dependent on the underlying data column used.
117: * @see #canGet(String, Class)
118: * @see #getColumnType(String)
119: */
120: public Object get(String field);
121:
122: /**
123: * Set the value of a given data field.
124: * @param field the data field to set
125: * @param value the value for the field. If the concrete type of this
126: * Object is not compatible with the underlying data model, an
127: * Exception will be thrown. Use the {@link #canSet(String, Class)}
128: * method to check the type-safety ahead of time.
129: * @see #canSet(String, Class)
130: * @see #getColumnType(String)
131: */
132: public void set(String field, Object value);
133:
134: /**
135: * Get the data value at the given column number as an Object.
136: * @param col the column number
137: * @return the data value as an Object. The concrete type of this
138: * Object is dependent on the underlying data column used.
139: * @see #canGet(String, Class)
140: * @see #getColumnType(int)
141: */
142: public Object get(int col);
143:
144: /**
145: * Set the value of at the given column number.
146: * @param col the column number
147: * @param value the value for the field. If the concrete type of this
148: * Object is not compatible with the underlying data model, an
149: * Exception will be thrown. Use the {@link #canSet(String, Class)}
150: * method to check the type-safety ahead of time.
151: * @see #canSet(String, Class)
152: * @see #getColumnType(String)
153: */
154: public void set(int col, Object value);
155:
156: /**
157: * Get the default value for the given data field.
158: * @param field the data field
159: * @return the default value, as an Object, used to populate rows
160: * of the data field.
161: */
162: public Object getDefault(String field);
163:
164: /**
165: * Revert this tuple's value for the given field to the default value
166: * for the field.
167: * @param field the data field
168: * @see #getDefault(String)
169: */
170: public void revertToDefault(String field);
171:
172: // ------------------------------------------------------------------------
173: // Convenience Data Access Methods
174:
175: /**
176: * Check if the given data field can return primitive <code>int</code>
177: * values.
178: * @param field the data field to check
179: * @return true if the data field can return primitive <code>int</code>
180: * values, false otherwise. If true, the {@link #getInt(String)} method
181: * can be used safely.
182: */
183: public boolean canGetInt(String field);
184:
185: /**
186: * Check if the <code>setInt</code> method can safely be used for the
187: * given data field.
188: * @param field the data field to check
189: * @return true if the {@link #setInt(String, int)} method can safely
190: * be used for the given field, false otherwise.
191: */
192: public boolean canSetInt(String field);
193:
194: /**
195: * Get the data value at the given field as an <code>int</code>.
196: * @param field the data field to retrieve
197: * @see #canGetInt(String)
198: */
199: public int getInt(String field);
200:
201: /**
202: * Set the data value of the given field with an <code>int</code>.
203: * @param field the data field to set
204: * @param val the value to set
205: * @see #canSetInt(String)
206: */
207: public void setInt(String field, int val);
208:
209: /**
210: * Get the data value at the given field as an <code>int</code>.
211: * @param col the column number of the data field to retrieve
212: * @see #canGetInt(String)
213: */
214: public int getInt(int col);
215:
216: /**
217: * Set the data value of the given field with an <code>int</code>.
218: * @param col the column number of the data field to set
219: * @param val the value to set
220: * @see #canSetInt(String)
221: */
222: public void setInt(int col, int val);
223:
224: // --------------------------------------------------------------
225:
226: /**
227: * Check if the given data field can return primitive <code>long</code>
228: * values.
229: * @param field the data field to check
230: * @return true if the data field can return primitive <code>long</code>
231: * values, false otherwise. If true, the {@link #getLong(String)} method
232: * can be used safely.
233: */
234: public boolean canGetLong(String field);
235:
236: /**
237: * Check if the <code>setLong</code> method can safely be used for the
238: * given data field.
239: * @param field the data field to check
240: * @return true if the {@link #setLong(String, long)} method can safely
241: * be used for the given field, false otherwise.
242: */
243: public boolean canSetLong(String field);
244:
245: /**
246: * Get the data value at the given field as a <code>long</code>.
247: * @param field the data field to retrieve
248: * @see #canGetLong(String)
249: */
250: public long getLong(String field);
251:
252: /**
253: * Set the data value of the given field with a <code>long</code>.
254: * @param field the data field to set
255: * @param val the value to set
256: * @see #canSetLong(String)
257: */
258: public void setLong(String field, long val);
259:
260: /**
261: * Get the data value at the given field as a <code>long</code>.
262: * @param col the column number of the data field to retrieve
263: * @see #canGetLong(String)
264: */
265: public long getLong(int col);
266:
267: /**
268: * Set the data value of the given field with a <code>long</code>.
269: * @param col the column number of the data field to set
270: * @param val the value to set
271: * @see #canSetLong(String)
272: */
273: public void setLong(int col, long val);
274:
275: // --------------------------------------------------------------
276:
277: /**
278: * Check if the given data field can return primitive <code>float</code>
279: * values.
280: * @param field the data field to check
281: * @return true if the data field can return primitive <code>float</code>
282: * values, false otherwise. If true, the {@link #getFloat(String)} method
283: * can be used safely.
284: */
285: public boolean canGetFloat(String field);
286:
287: /**
288: * Check if the <code>setFloat</code> method can safely be used for the
289: * given data field.
290: * @param field the data field to check
291: * @return true if the {@link #setFloat(String, float)} method can safely
292: * be used for the given field, false otherwise.
293: */
294: public boolean canSetFloat(String field);
295:
296: /**
297: * Get the data value at the given field as a <code>float</code>.
298: * @param field the data field to retrieve
299: * @see #canGetFloat(String)
300: */
301: public float getFloat(String field);
302:
303: /**
304: * Set the data value of the given field with a <code>float</code>.
305: * @param field the data field to set
306: * @param val the value to set
307: * @see #canSetFloat(String)
308: */
309: public void setFloat(String field, float val);
310:
311: /**
312: * Get the data value at the given field as a <code>float</code>.
313: * @param col the column number of the data field to retrieve
314: * @see #canGetFloat(String)
315: */
316: public float getFloat(int col);
317:
318: /**
319: * Set the data value of the given field with a <code>float</code>.
320: * @param col the column number of the data field to set
321: * @param val the value to set
322: * @see #canSetFloat(String)
323: */
324: public void setFloat(int col, float val);
325:
326: // --------------------------------------------------------------
327:
328: /**
329: * Check if the given data field can return primitive <code>double</code>
330: * values.
331: * @param field the data field to check
332: * @return true if the data field can return primitive <code>double</code>
333: * values, false otherwise. If true, the {@link #getDouble(String)} method
334: * can be used safely.
335: */
336: public boolean canGetDouble(String field);
337:
338: /**
339: * Check if the <code>setDouble</code> method can safely be used for the
340: * given data field.
341: * @param field the data field to check
342: * @return true if the {@link #setDouble(String, double)} method can safely
343: * be used for the given field, false otherwise.
344: */
345: public boolean canSetDouble(String field);
346:
347: /**
348: * Get the data value at the given field as a <code>double</code>.
349: * @param field the data field to retrieve
350: * @see #canGetDouble(String)
351: */
352: public double getDouble(String field);
353:
354: /**
355: * Set the data value of the given field with a <code>double</code>.
356: * @param field the data field to set
357: * @param val the value to set
358: * @see #canSetDouble(String)
359: */
360: public void setDouble(String field, double val);
361:
362: /**
363: * Get the data value at the given field as a <code>double</code>.
364: * @param col the column number of the data field to retrieve
365: * @see #canGetDouble(String)
366: */
367: public double getDouble(int col);
368:
369: /**
370: * Set the data value of the given field with a <code>double</code>.
371: * @param col the column number of the data field to set
372: * @param val the value to set
373: * @see #canSetDouble(String)
374: */
375: public void setDouble(int col, double val);
376:
377: // --------------------------------------------------------------
378:
379: /**
380: * Check if the given data field can return primitive <code>boolean</code>
381: * values.
382: * @param field the data field to check
383: * @return true if the data field can return primitive <code>boolean</code>
384: * values, false otherwise. If true, the {@link #getBoolean(String)} method
385: * can be used safely.
386: */
387: public boolean canGetBoolean(String field);
388:
389: /**
390: * Check if the <code>setBoolean</code> method can safely be used for the
391: * given data field.
392: * @param field the data field to check
393: * @return true if the {@link #setBoolean(String, boolean)} method can
394: * safely be used for the given field, false otherwise.
395: */
396: public boolean canSetBoolean(String field);
397:
398: /**
399: * Get the data value at the given field as a <code>boolean</code>.
400: * @param field the data field to retrieve
401: * @see #canGetBoolean(String)
402: */
403: public boolean getBoolean(String field);
404:
405: /**
406: * Set the data value of the given field with a <code>boolean</code>.
407: * @param field the data field to set
408: * @param val the value to set
409: * @see #canSetBoolean(String)
410: */
411: public void setBoolean(String field, boolean val);
412:
413: /**
414: * Get the data value at the given field as a <code>boolean</code>.
415: * @param col the column number of the data field to retrieve
416: * @see #canGetBoolean(String)
417: */
418: public boolean getBoolean(int col);
419:
420: /**
421: * Set the data value of the given field with a <code>boolean</code>.
422: * @param col the column number of the data field to set
423: * @param val the value to set
424: * @see #canSetBoolean(String)
425: */
426: public void setBoolean(int col, boolean val);
427:
428: // --------------------------------------------------------------
429:
430: /**
431: * Check if the given data field can return <code>String</code>
432: * values.
433: * @param field the data field to check
434: * @return true if the data field can return <code>String</code>
435: * values, false otherwise. If true, the {@link #getString(String)} method
436: * can be used safely.
437: */
438: public boolean canGetString(String field);
439:
440: /**
441: * Check if the <code>setString</code> method can safely be used for the
442: * given data field.
443: * @param field the data field to check
444: * @return true if the {@link #setString(String, String)} method can safely
445: * be used for the given field, false otherwise.
446: */
447: public boolean canSetString(String field);
448:
449: /**
450: * Get the data value at the given field as a <code>String</code>.
451: * @param field the data field to retrieve
452: * @see #canGetString(String)
453: */
454: public String getString(String field);
455:
456: /**
457: * Set the data value of the given field with a <code>String</code>.
458: * @param field the data field to set
459: * @param val the value to set
460: * @see #canSetString(String)
461: */
462: public void setString(String field, String val);
463:
464: /**
465: * Get the data value at the given field as a <code>String</code>.
466: * @param col the column number of the data field to retrieve
467: * @see #canGetString(String)
468: */
469: public String getString(int col);
470:
471: /**
472: * Set the data value of the given field with a <code>String</code>.
473: * @param col the column number of the data field to set
474: * @param val the value to set
475: * @see #canSetString(String)
476: */
477: public void setString(int col, String val);
478:
479: // --------------------------------------------------------------
480:
481: /**
482: * Check if the given data field can return <code>Date</code>
483: * values.
484: * @param field the data field to check
485: * @return true if the data field can return <code>Date</code>
486: * values, false otherwise. If true, the {@link #getDate(String)} method
487: * can be used safely.
488: */
489: public boolean canGetDate(String field);
490:
491: /**
492: * Check if the <code>setDate</code> method can safely be used for the
493: * given data field.
494: * @param field the data field to check
495: * @return true if the {@link #setDate(String, Date)} method can safely
496: * be used for the given field, false otherwise.
497: */
498: public boolean canSetDate(String field);
499:
500: /**
501: * Get the data value at the given field as a <code>Date</code>.
502: * @param field the data field to retrieve
503: * @see #canGetDate(String)
504: */
505: public Date getDate(String field);
506:
507: /**
508: * Set the data value of the given field with a <code>Date</code>.
509: * @param field the data field to set
510: * @param val the value to set
511: * @see #canSetDate(String)
512: */
513: public void setDate(String field, Date val);
514:
515: /**
516: * Get the data value at the given field as a <code>Date</code>.
517: * @param col the column number of the data field to retrieve
518: * @see #canGetDate(String)
519: */
520: public Date getDate(int col);
521:
522: /**
523: * Set the data value of the given field with a <code>Date</code>.
524: * @param col the column number of the data field to set
525: * @param val the value to set
526: * @see #canSetDate(String)
527: */
528: public void setDate(int col, Date val);
529:
530: } // end of interface Tuple
|