001package edu.wpi.first.wpilibj.tables;
002
003import java.nio.ByteBuffer;
004import java.util.NoSuchElementException;
005import java.util.Set;
006
007
008/**
009 * A table whose values can be read and written to
010 */
011public interface ITable {
012
013  /**
014   * Checks the table and tells if it contains the specified key
015   *
016   * @param key the key to search for
017   * @return true if the table as a value assigned to the given key
018   */
019  public boolean containsKey(String key);
020
021  /**
022   * @param key the key to search for
023   * @return true if there is a subtable with the key which contains at least
024   * one key/subtable of its own
025   */
026  public boolean containsSubTable(String key);
027
028  /**
029   * Returns the table at the specified key. If there is no table at the
030   * specified key, it will create a new table
031   *
032   * @param key the name of the table relative to this one
033   * @return a sub table relative to this one
034   */
035  public ITable getSubTable(String key);
036
037  /**
038   * @param types bitmask of types; 0 is treated as a "don't care".
039   * @return keys currently in the table
040   */
041  public Set<String> getKeys(int types);
042
043  /**
044   * @return keys currently in the table
045   */
046  public Set<String> getKeys();
047
048  /**
049   * @return subtables currently in the table
050   */
051  public Set<String> getSubTables();
052
053  /**
054   * Makes a key's value persistent through program restarts.
055   * The key cannot be null.
056   *
057   * @param key the key name
058   */
059  public void setPersistent(String key);
060
061  /**
062   * Stop making a key's value persistent through program restarts.
063   * The key cannot be null.
064   *
065   * @param key the key name
066   */
067  public void clearPersistent(String key);
068
069  /**
070   * Returns whether the value is persistent through program restarts.
071   * The key cannot be null.
072   *
073   * @param key the key name
074   * @return True if the value is persistent.
075   */
076  public boolean isPersistent(String key);
077
078  /**
079   * Sets flags on the specified key in this table. The key can
080   * not be null.
081   *
082   * @param key the key name
083   * @param flags the flags to set (bitmask)
084   */
085  public void setFlags(String key, int flags);
086
087  /**
088   * Clears flags on the specified key in this table. The key can
089   * not be null.
090   *
091   * @param key the key name
092   * @param flags the flags to clear (bitmask)
093   */
094  public void clearFlags(String key, int flags);
095
096  /**
097   * Returns the flags for the specified key.
098   *
099   * @param key the key name
100   * @return the flags, or 0 if the key is not defined
101   */
102  public int getFlags(String key);
103
104  /**
105   * Deletes the specified key in this table. The key can
106   * not be null.
107   *
108   * @param key the key name
109   */
110  public void delete(String key);
111
112  /**
113   * Gets the value associated with a key as an object. If the key does not
114   * exist, it will return the default value
115   * NOTE: If the value is a double, it will return a Double object,
116   * not a primitive.  To get the primitive, use
117   * {@link #getDouble(String, double)}.
118   * @param key the key of the value to look up
119   * @return the value associated with the given key
120   * @throws TableKeyNotDefinedException if there is no value associated with
121   * the given key
122   * @deprecated This exception-raising method has been replaced by the
123   * default-taking method {@link #getValue(String, Object)}.
124   */
125  @Deprecated
126  public Object getValue(String key) throws TableKeyNotDefinedException;
127
128  /**
129   * Gets the value associated with a key as an object.
130   * NOTE: If the value is a double, it will return a Double object,
131   * not a primitive.  To get the primitive, use
132   * {@link #getDouble(String, double)}.
133   * @param key the key of the value to look up
134   * @param defaultValue the default value if the key is null
135   * @return the value associated with the given key
136   */
137  public Object getValue(String key, Object defaultValue);
138
139  /**
140   * Put a value in the table
141   * @param key the key to be assigned to
142   * @param value the value that will be assigned
143   * @return False if the table key already exists with a different type
144   * @throws IllegalArgumentException when the value is not supported by the
145   * table
146   */
147  public boolean putValue(String key, Object value)
148      throws IllegalArgumentException;
149
150  /**
151   * Retrieve an array data type from the table.
152   * @param key the key to be assigned to
153   * @param externalValue the array data type to retreive into
154   * @throws TableKeyNotDefinedException if there is no value associated with
155   * the given key
156   * @deprecated Use get*Array functions instead.
157   */
158  @Deprecated
159  public void retrieveValue(String key, Object externalValue) throws TableKeyNotDefinedException;
160
161  /**
162   * Put a number in the table
163   * @param key the key to be assigned to
164   * @param value the value that will be assigned
165   * @return False if the table key already exists with a different type
166   */
167  public boolean putNumber(String key, double value);
168  
169  /** 
170   * Gets the current value in the table, setting it if it does not exist.
171   * @param key the key
172   * @param defaultValue the default value to set if key doens't exist.
173   * @return False if the table key exists with a different type
174   */
175  public boolean setDefaultNumber(String key, double defaultValue);
176  
177  /**
178   * Returns the number the key maps to.
179   * @param key the key to look up
180   * @return the value associated with the given key
181   * @throws TableKeyNotDefinedException if there is no value associated with
182   * the given key
183   * @deprecated This exception-raising method has been replaced by the
184   * default-taking method {@link #getNumber(String, double)}.
185   */
186  @Deprecated
187  public double getNumber(String key) throws TableKeyNotDefinedException;
188  /**
189   * Returns the number the key maps to. If the key does not exist or is of
190   * different type, it will return the default value.
191   * @param key the key to look up
192   * @param defaultValue the value to be returned if no value is found
193   * @return the value associated with the given key or the given default value
194   * if there is no value associated with the key
195   */
196  public double getNumber(String key, double defaultValue);
197
198  /**
199   * Put a string in the table
200   * @param key the key to be assigned to
201   * @param value the value that will be assigned
202   * @return False if the table key already exists with a different type
203   */
204  public boolean putString(String key, String value);
205  
206  /** 
207   * Gets the current value in the table, setting it if it does not exist.
208   * @param key the key
209   * @param defaultValue the default value to set if key doens't exist.
210   * @return False if the table key exists with a different type
211   */
212  public boolean setDefaultString(String key, String defaultValue);
213  
214  /**
215   * Returns the string the key maps to.
216   * @param key the key to look up
217   * @return the value associated with the given key
218   * @throws TableKeyNotDefinedException if there is no value associated with
219   * the given key
220   * @deprecated This exception-raising method has been replaced by the
221   * default-taking method {@link #getString(String, String)}.
222   */
223  @Deprecated
224  public String getString(String key) throws TableKeyNotDefinedException;
225  /**
226   * Returns the string the key maps to. If the key does not exist or is of
227   * different type, it will return the default value.
228   * @param key the key to look up
229   * @param defaultValue the value to be returned if no value is found
230   * @return the value associated with the given key or the given default value
231   * if there is no value associated with the key
232   */
233  public String getString(String key, String defaultValue);
234
235  /**
236   * Put a boolean in the table
237   * @param key the key to be assigned to
238   * @param value the value that will be assigned
239   * @return False if the table key already exists with a different type
240   */
241  public boolean putBoolean(String key, boolean value);
242  
243  /** 
244   * Gets the current value in the table, setting it if it does not exist.
245   * @param key the key
246   * @param defaultValue the default value to set if key doens't exist.
247   * @return False if the table key exists with a different type
248   */
249  public boolean setDefaultBoolean(String key, boolean defaultValue);
250  
251  /**
252   * Returns the boolean the key maps to.
253   * @param key the key to look up
254   * @return the value associated with the given key
255   * @throws TableKeyNotDefinedException if there is no value associated with
256   * the given key
257   * @deprecated This exception-raising method has been replaced by the
258   * default-taking method {@link #getBoolean(String, boolean)}.
259   */
260  @Deprecated
261  public boolean getBoolean(String key) throws TableKeyNotDefinedException;
262  /**
263   * Returns the boolean the key maps to. If the key does not exist or is of
264   * different type, it will return the default value.
265   * @param key the key to look up
266   * @param defaultValue the value to be returned if no value is found
267   * @return the value associated with the given key or the given default value
268   * if there is no value associated with the key
269   */
270  public boolean getBoolean(String key, boolean defaultValue);
271
272  /**
273   * Put a boolean array in the table
274   * @param key the key to be assigned to
275   * @param value the value that will be assigned
276   * @return False if the table key already exists with a different type
277   */
278  public boolean putBooleanArray(String key, boolean[] value);
279  
280  /** 
281   * Gets the current value in the table, setting it if it does not exist.
282   * @param key the key
283   * @param defaultValue the default value to set if key doens't exist.
284   * @return False if the table key exists with a different type
285   */
286  public boolean setDefaultBooleanArray(String key, boolean[] defaultValue);
287  
288  /**
289   * Put a boolean array in the table
290   * @param key the key to be assigned to
291   * @param value the value that will be assigned
292   * @return False if the table key already exists with a different type
293   */
294  public boolean putBooleanArray(String key, Boolean[] value);
295  
296  /** 
297   * Gets the current value in the table, setting it if it does not exist.
298   * @param key the key
299   * @param defaultValue the default value to set if key doens't exist.
300   * @return False if the table key exists with a different type
301   */
302  public boolean setDefaultBooleanArray(String key, Boolean[] defaultValue);
303  
304  /**
305   * Returns the boolean array the key maps to.
306   * @param key the key to look up
307   * @return the value associated with the given key
308   * @throws TableKeyNotDefinedException if there is no value associated with
309   * the given key
310   * @deprecated This exception-raising method has been replaced by the
311   * default-taking method {@link #getBooleanArray(String, boolean[])}.
312   */
313  @Deprecated
314  public boolean[] getBooleanArray(String key) throws TableKeyNotDefinedException;
315  /**
316   * Returns the boolean array the key maps to. If the key does not exist or is
317   * of different type, it will return the default value.
318   * @param key the key to look up
319   * @param defaultValue the value to be returned if no value is found
320   * @return the value associated with the given key or the given default value
321   * if there is no value associated with the key
322   */
323  public boolean[] getBooleanArray(String key, boolean[] defaultValue);
324  /**
325   * Returns the boolean array the key maps to. If the key does not exist or is
326   * of different type, it will return the default value.
327   * @param key the key to look up
328   * @param defaultValue the value to be returned if no value is found
329   * @return the value associated with the given key or the given default value
330   * if there is no value associated with the key
331   */
332  public Boolean[] getBooleanArray(String key, Boolean[] defaultValue);
333
334  /**
335   * Put a number array in the table
336   * @param key the key to be assigned to
337   * @param value the value that will be assigned
338   * @return False if the table key already exists with a different type
339   */
340  public boolean putNumberArray(String key, double[] value);
341  
342  /** 
343   * Gets the current value in the table, setting it if it does not exist.
344   * @param key the key
345   * @param defaultValue the default value to set if key doens't exist.
346   * @return False if the table key exists with a different type
347   */
348  public boolean setDefaultNumberArray(String key, double[] defaultValue);
349  
350  /**
351   * Put a number array in the table
352   * @param key the key to be assigned to
353   * @param value the value that will be assigned
354   * @return False if the table key already exists with a different type
355   */
356  public boolean putNumberArray(String key, Double[] value);
357  
358  /** 
359   * Gets the current value in the table, setting it if it does not exist.
360   * @param key the key
361   * @param defaultValue the default value to set if key doens't exist.
362   * @return False if the table key exists with a different type
363   */
364  public boolean setDefaultNumberArray(String key, Double[] defaultValue);
365  
366  /**
367   * Returns the number array the key maps to.
368   * @param key the key to look up
369   * @return the value associated with the given key
370   * @throws TableKeyNotDefinedException if there is no value associated with
371   * the given key
372   * @deprecated This exception-raising method has been replaced by the
373   * default-taking method {@link #getNumberArray(String, double[])}.
374   */
375  @Deprecated
376  public double[] getNumberArray(String key) throws TableKeyNotDefinedException;
377  /**
378   * Returns the number array the key maps to. If the key does not exist or is
379   * of different type, it will return the default value.
380   * @param key the key to look up
381   * @param defaultValue the value to be returned if no value is found
382   * @return the value associated with the given key or the given default value
383   * if there is no value associated with the key
384   */
385  public double[] getNumberArray(String key, double[] defaultValue);
386  /**
387   * Returns the number array the key maps to. If the key does not exist or is
388   * of different type, it will return the default value.
389   * @param key the key to look up
390   * @param defaultValue the value to be returned if no value is found
391   * @return the value associated with the given key or the given default value
392   * if there is no value associated with the key
393   */
394  public Double[] getNumberArray(String key, Double[] defaultValue);
395
396  /**
397   * Put a string array in the table
398   * @param key the key to be assigned to
399   * @param value the value that will be assigned
400   * @return False if the table key already exists with a different type
401   */
402  public boolean putStringArray(String key, String[] value);
403  
404  /** 
405   * Gets the current value in the table, setting it if it does not exist.
406   * @param key the key
407   * @param defaultValue the default value to set if key doens't exist.
408   * @return False if the table key exists with a different type
409   */
410  public boolean setDefaultStringArray(String key, String[] defaultValue);
411  
412  /**
413   * Returns the string array the key maps to.
414   * @param key the key to look up
415   * @return the value associated with the given key
416   * @throws TableKeyNotDefinedException if there is no value associated with
417   * the given key
418   * @deprecated This exception-raising method has been replaced by the
419   * default-taking method {@link #getStringArray(String, String[])}.
420   */
421  @Deprecated
422  public String[] getStringArray(String key) throws TableKeyNotDefinedException;
423  /**
424   * Returns the string array the key maps to. If the key does not exist or is
425   * of different type, it will return the default value.
426   * @param key the key to look up
427   * @param defaultValue the value to be returned if no value is found
428   * @return the value associated with the given key or the given default value
429   * if there is no value associated with the key
430   */
431  public String[] getStringArray(String key, String[] defaultValue);
432
433  /**
434   * Put a raw value (byte array) in the table
435   * @param key the key to be assigned to
436   * @param value the value that will be assigned
437   * @return False if the table key already exists with a different type
438   */
439  public boolean putRaw(String key, byte[] value);
440  
441  /** 
442   * Gets the current value in the table, setting it if it does not exist.
443   * @param key the key
444   * @param defaultValue the default value to set if key doens't exist.
445   * @return False if the table key exists with a different type
446   */
447  public boolean setDefaultRaw(String key, byte[] defaultValue);
448  
449  /**
450   * Put a raw value (bytes from a byte buffer) in the table
451   * @param key the key to be assigned to
452   * @param value the value that will be assigned
453   * @param len the length of the value
454   * @return False if the table key already exists with a different type
455   */
456  public boolean putRaw(String key, ByteBuffer value, int len);
457  /**
458   * Returns the raw value (byte array) the key maps to.
459   * @param key the key to look up
460   * @return the value associated with the given key
461   * @throws TableKeyNotDefinedException if there is no value associated with
462   * the given key
463   * @deprecated This exception-raising method has been replaced by the
464   * default-taking method {@link #getRaw(String, byte[])}.
465   */
466  @Deprecated
467  public byte[] getRaw(String key) throws TableKeyNotDefinedException;
468  /**
469   * Returns the raw value (byte array) the key maps to. If the key does not
470   * exist or is of different type, it will return the default value.
471   * @param key the key to look up
472   * @param defaultValue the value to be returned if no value is found
473   * @return the value associated with the given key or the given default value
474   * if there is no value associated with the key
475   */
476  public byte[] getRaw(String key, byte[] defaultValue);
477
478  /** Notifier flag values. */
479  public static final int NOTIFY_IMMEDIATE = 0x01;
480  public static final int NOTIFY_LOCAL = 0x02;
481  public static final int NOTIFY_NEW = 0x04;
482  public static final int NOTIFY_DELETE = 0x08;
483  public static final int NOTIFY_UPDATE = 0x10;
484  public static final int NOTIFY_FLAGS = 0x20;
485
486  /**
487   * Add a listener for changes to the table
488   * @param listener the listener to add
489   */
490  public void addTableListener(ITableListener listener);
491  /**
492   * Add a listener for changes to the table
493   * @param listener the listener to add
494   * @param immediateNotify if true then this listener will be notified of all
495   * current entries (marked as new)
496   */
497  public void addTableListener(ITableListener listener,
498                               boolean immediateNotify);
499  /**
500   * Add a listener for changes to the table
501   * @param listener the listener to add
502   * @param flags bitmask specifying desired notifications
503   */
504  public void addTableListenerEx(ITableListener listener, int flags);
505
506  /**
507   * Add a listener for changes to a specific key the table
508   * @param key the key to listen for
509   * @param listener the listener to add
510   * @param immediateNotify if true then this listener will be notified of all
511   * current entries (marked as new)
512   */
513  public void addTableListener(String key, ITableListener listener,
514                               boolean immediateNotify);
515  /**
516   * Add a listener for changes to a specific key the table
517   * @param key the key to listen for
518   * @param listener the listener to add
519   * @param flags bitmask specifying desired notifications
520   */
521  public void addTableListenerEx(String key, ITableListener listener,
522                                 int flags);
523  /**
524   * This will immediately notify the listener of all current sub tables
525   * @param listener the listener to notify
526   */
527  public void addSubTableListener(final ITableListener listener);
528  /**
529   * This will immediately notify the listener of all current sub tables
530   * @param listener the listener to notify
531   * @param localNotify if true then this listener will be notified of all
532   * local changes in addition to all remote changes
533   */
534  public void addSubTableListener(final ITableListener listener,
535                                  boolean localNotify);
536  /**
537   * Remove a listener from receiving table events
538   * @param listener the listener to be removed
539   */
540  public void removeTableListener(ITableListener listener);
541
542  /*
543   * Deprecated Methods
544   */
545
546  /**
547   * Maps the specified key to the specified value in this table.
548   * The key can not be null.
549   * The value can be retrieved by calling the get method with a key that is
550   * equal to the original key.
551   * @param key the key
552   * @param value the value
553   * @return False if the table key already exists with a different type
554   * @throws IllegalArgumentException if key is null
555   * @deprecated Use {@link #putNumber(String, double)} instead.
556   */
557  @Deprecated
558  public boolean putInt(String key, int value);
559
560  /**
561   * Returns the value at the specified key.
562   * @param key the key
563   * @return the value
564   * @throws TableKeyNotDefinedException if there is no value mapped to by the
565   * key
566   * @throws IllegalArgumentException if the value mapped to by the key is not
567   * an int
568   * @throws IllegalArgumentException if the key is null
569   * @deprecated Use {@link #getNumber(String, double)} instead.
570   */
571  @Deprecated
572  public int getInt(String key) throws TableKeyNotDefinedException;
573
574  /**
575   * Returns the value at the specified key.
576   * @param key the key
577   * @param defaultValue the value returned if the key is undefined
578   * @return the value
579   * @throws IllegalArgumentException if the value mapped to by the key is not
580   * an int
581   * @throws IllegalArgumentException if the key is null
582   * @deprecated Use {@link #getNumber(String, double)} instead.
583   */
584  @Deprecated
585  public int getInt(String key, int defaultValue)
586      throws TableKeyNotDefinedException;
587
588  /**
589   * Maps the specified key to the specified value in this table.
590   * The key can not be null.
591   * The value can be retrieved by calling the get method with a key that is
592   * equal to the original key.
593   * @param key the key
594   * @param value the value
595   * @return False if the table key already exists with a different type
596   * @throws IllegalArgumentException if key is null
597   * @deprecated Use {@link #putNumber(String, double)} instead.
598   */
599  @Deprecated
600  public boolean putDouble(String key, double value);
601
602  /**
603   * Returns the value at the specified key.
604   * @param key the key
605   * @return the value
606   * @throws TableKeyNotDefinedException if there is no
607   * value mapped to by the key
608   * @throws IllegalArgumentException if the value mapped to by the key is not a
609   * double
610   * @throws IllegalArgumentException if the key is null
611   * @deprecated Use {@link #getNumber(String, double)} instead.
612   */
613  @Deprecated
614  public double getDouble(String key) throws TableKeyNotDefinedException;
615
616  /**
617   * Returns the value at the specified key.
618   * @param key the key
619   * @param defaultValue the value returned if the key is undefined
620   * @return the value
621   * @throws IllegalArgumentException if the value mapped to by the key is not a
622   * double
623   * @throws IllegalArgumentException if the key is null
624   * @deprecated Use {@link #getNumber(String, double)} instead.
625   */
626  @Deprecated
627  public double getDouble(String key, double defaultValue);
628}