001package edu.wpi.first.wpilibj.tables;
002
003import java.util.NoSuchElementException;
004
005
006/**
007 * A table whose values can be read and written to
008 * 
009 * @author Mitchell
010 * 
011 */
012public interface ITable {
013
014        /**
015         * @param key the key to search for
016         * @return true if the table as a value assigned to the given key
017         */
018        public boolean containsKey(String key);
019
020        /**
021         * @param key the key to search for
022         * @return true if there is a subtable with the key which contains at least one key/subtable of its own
023         */
024        public boolean containsSubTable(String key);
025        
026    /**
027     * @param key the name of the table relative to this one
028     * @return a sub table relative to this one
029     */
030    public ITable getSubTable(String key);
031        
032    
033        /**
034         * Gets the value associated with a key as an object
035         * @param key the key of the value to look up
036         * @return the value associated with the given key
037         * @throws TableKeyNotDefinedException if there is no value associated with the given key
038         */
039        public Object getValue(String key) throws TableKeyNotDefinedException;
040        /**
041         * Put a value in the table
042         * @param key the key to be assigned to
043         * @param value the value that will be assigned
044         * @throws IllegalArgumentException when the value is not supported by the table
045         */
046        public void putValue(String key, Object value) throws IllegalArgumentException;
047        
048        public void retrieveValue(String key, Object externalValue);
049        
050        
051
052        /**
053         * Put a number in the table
054         * @param key the key to be assigned to
055         * @param value the value that will be assigned
056         */
057        public void putNumber(String key, double value);
058        /**
059         * @param key the key to look up
060         * @return the value associated with the given key 
061         * @throws TableKeyNotDefinedException if there is no value associated with the given key
062         */
063        public double getNumber(String key) throws TableKeyNotDefinedException;
064        /**
065         * @param key the key to look up
066         * @param defaultValue the value to be returned if no value is found
067         * @return the value associated with the given key or the given default value if there is no value associated with the key
068         */
069        public double getNumber(String key, double defaultValue);
070
071        /**
072         * Put a string in the table
073         * @param key the key to be assigned to
074         * @param value the value that will be assigned
075         */
076        public void putString(String key, String value);
077        /**
078         * @param key the key to look up
079         * @return the value associated with the given key 
080         * @throws TableKeyNotDefinedException if there is no value associated with the given key
081         */
082        public String getString(String key) throws TableKeyNotDefinedException;
083        /**
084         * @param key the key to look up
085         * @param defaultValue the value to be returned if no value is found
086         * @return the value associated with the given key or the given default value if there is no value associated with the key
087         */
088        public String getString(String key, String defaultValue);
089
090        /**
091         * Put a boolean in the table
092         * @param key the key to be assigned to
093         * @param value the value that will be assigned
094         */
095        public void putBoolean(String key, boolean value);
096        /**
097         * @param key the key to look up
098         * @return the value associated with the given key 
099         * @throws TableKeyNotDefinedException if there is no value associated with the given key
100         */
101        public boolean getBoolean(String key) throws TableKeyNotDefinedException;
102        /**
103         * @param key the key to look up
104         * @param defaultValue the value to be returned if no value is found
105         * @return the value associated with the given key or the given default value if there is no value associated with the key
106         */
107        public boolean getBoolean(String key, boolean defaultValue);
108
109        
110        
111        
112        
113        /**
114         * Add a listener for changes to the table
115         * @param listener the listener to add
116         */
117        public void addTableListener(ITableListener listener);
118        /**
119         * Add a listener for changes to the table
120         * @param listener the listener to add
121         * @param immediateNotify if true then this listener will be notified of all current entries (marked as new)
122         */
123        public void addTableListener(ITableListener listener, boolean immediateNotify);
124        
125        /**
126         * Add a listener for changes to a specific key the table
127         * @param key the key to listen for
128         * @param listener the listener to add
129         * @param immediateNotify if true then this listener will be notified of all current entries (marked as new)
130         */
131        public void addTableListener(String key, ITableListener listener, boolean immediateNotify);
132        /**
133         * This will immediately notify the listener of all current sub tables
134         * @param listener
135         */
136        public void addSubTableListener(final ITableListener listener);
137        /**
138         * Remove a listener from receiving table events
139         * @param listener the listener to be removed
140         */
141        public void removeTableListener(ITableListener listener);
142        
143        
144        
145     /*
146      * Depricated Methods
147      */
148     /**
149      * @deprecated 
150     * Maps the specified key to the specified value in this table.
151     * The key can not be null.
152     * The value can be retrieved by calling the get method with a key that is equal to the original key.
153     * @param key the key
154     * @param value the value
155     * @throws IllegalArgumentException if key is null
156     */
157    public void putInt(String key, int value);
158
159    /**
160     * @deprecated 
161     * Returns the value at the specified key.
162     * @param key the key
163     * @return the value
164     * @throws TableKeyNotDefinedException if there is no value mapped to by the key
165     * @throws IllegalArgumentException if the value mapped to by the key is not an int
166     * @throws IllegalArgumentException if the key is null
167     */
168    public int getInt(String key) throws TableKeyNotDefinedException;
169
170    /**
171     * @deprecated 
172     * Returns the value at the specified key.
173     * @param key the key
174     * @param defaultValue the value returned if the key is undefined
175     * @return the value
176     * @throws NetworkTableKeyNotDefined if there is no value mapped to by the key
177     * @throws IllegalArgumentException if the value mapped to by the key is not an int
178     * @throws IllegalArgumentException if the key is null
179     */
180    public int getInt(String key, int defaultValue) throws TableKeyNotDefinedException;
181
182    /**
183     * @deprecated 
184     * Maps the specified key to the specified value in this table.
185     * The key can not be null.
186     * The value can be retrieved by calling the get method with a key that is equal to the original key.
187     * @param key the key
188     * @param value the value
189     * @throws IllegalArgumentException if key is null
190     */
191    public void putDouble(String key, double value);
192
193    /**
194     * @deprecated 
195     * Returns the value at the specified key.
196     * @param key the key
197     * @return the value
198     * @throws NoSuchEleNetworkTableKeyNotDefinedmentException if there is no value mapped to by the key
199     * @throws IllegalArgumentException if the value mapped to by the key is not a double
200     * @throws IllegalArgumentException if the key is null
201     */
202    public double getDouble(String key) throws TableKeyNotDefinedException;
203
204    /**
205     * @deprecated 
206     * Returns the value at the specified key.
207     * @param key the key
208     * @param defaultValue the value returned if the key is undefined
209     * @return the value
210     * @throws NoSuchEleNetworkTableKeyNotDefinedmentException if there is no value mapped to by the key
211     * @throws IllegalArgumentException if the value mapped to by the key is not a double
212     * @throws IllegalArgumentException if the key is null
213     */
214    public double getDouble(String key, double defaultValue);
215        
216}