Team2890/allwpilib
4
0
Fork 0
mirror of https://github.com/wpilibsuite/allwpilib synced 2026-06-21 01:01:43 +00:00
Code Issues Packages Projects Releases Wiki Activity

Add exception-generating C++ functions, but mark as deprecated.

Browse Source 
These are good to have for backwards compatibility, but discouraged for new
development (default-taking functions should be used instead).  The reason
is that the exceptions must be explicitly handled and may initially work but
then fail at an inopportune moment.

Mark the similar Java functions as deprecated as well for the same reason.

Update all the docs for consistency.

Mark overridden functions as such in both C++ and Java.

Make IsPersistent and GetFlags const in C++.
This commit is contained in:
Peter Johnson
2015-12-06 22:39:38 -08:00
parent 9e6635ec13
commit 76ee093e92
7 changed files with 538 additions and 462 deletions
Download Patch File Download Diff File Expand all files Collapse all files

99
java/src/edu/wpi/first/wpilibj/tables/ITable.java
View File

@@ -7,13 +7,12 @@ import java.util.Set;
/**
* A table whose values can be read and written to
*
* @author Mitchell
*
*/
public interface ITable {
/**
* Checks the table and tells if it contains the specified key
*
* @param key the key to search for
* @return true if the table as a value assigned to the given key
*/
@@ -27,6 +26,9 @@ public interface ITable {
public boolean containsSubTable(String key);
/**
* Returns the table at the specified key. If there is no table at the
* specified key, it will create a new table
*
* @param key the name of the table relative to this one
* @return a sub table relative to this one
*/
@@ -94,8 +96,7 @@ public interface ITable {
/**
* Returns the flags for the specified key.
*
* @param key
* the key name
* @param key the key name
* @return the flags, or 0 if the key is not defined
*/
public int getFlags(String key);
@@ -109,14 +110,32 @@ public interface ITable {
public void delete(String key);
/**
* Gets the value associated with a key as an object
* Gets the value associated with a key as an object. If the key does not
* exist, it will return the default value
* NOTE: If the value is a double, it will return a Double object,
* not a primitive. To get the primitive, use
* {@link #getDouble(String, double)}.
* @param key the key of the value to look up
* @return the value associated with the given key
* @throws TableKeyNotDefinedException if there is no value associated with
* the given key
* @deprecated This exception-raising method has been replaced by the
* default-taking method {@link #getValue(String, Object)}.
*/
@Deprecated
public Object getValue(String key) throws TableKeyNotDefinedException;
/**
* Gets the value associated with a key as an object.
* NOTE: If the value is a double, it will return a Double object,
* not a primitive. To get the primitive, use
* {@link #getDouble(String, double)}.
* @param key the key of the value to look up
* @param defaultValue the default value if the key is null
* @return the value associated with the given key
*/
public Object getValue(String key, Object defaultValue);
/**
* Put a value in the table
* @param key the key to be assigned to
@@ -136,6 +155,7 @@ public interface ITable {
* the given key
* @deprecated Use get*Array functions instead.
*/
@Deprecated
public void retrieveValue(String key, Object externalValue) throws TableKeyNotDefinedException;
/**
@@ -146,13 +166,19 @@ public interface ITable {
*/
public boolean putNumber(String key, double value);
/**
* Returns the number the key maps to.
* @param key the key to look up
* @return the value associated with the given key
* @throws TableKeyNotDefinedException if there is no value associated with
* the given key
* @deprecated This exception-raising method has been replaced by the
* default-taking method {@link #getNumber(String, double)}.
*/
@Deprecated
public double getNumber(String key) throws TableKeyNotDefinedException;
/**
* Returns the number the key maps to. If the key does not exist or is of
* different type, it will return the default value.
* @param key the key to look up
* @param defaultValue the value to be returned if no value is found
* @return the value associated with the given key or the given default value
@@ -168,13 +194,19 @@ public interface ITable {
*/
public boolean putString(String key, String value);
/**
* Returns the string the key maps to.
* @param key the key to look up
* @return the value associated with the given key
* @throws TableKeyNotDefinedException if there is no value associated with
* the given key
* @deprecated This exception-raising method has been replaced by the
* default-taking method {@link #getString(String, String)}.
*/
@Deprecated
public String getString(String key) throws TableKeyNotDefinedException;
/**
* Returns the string the key maps to. If the key does not exist or is of
* different type, it will return the default value.
* @param key the key to look up
* @param defaultValue the value to be returned if no value is found
* @return the value associated with the given key or the given default value
@@ -190,13 +222,19 @@ public interface ITable {
*/
public boolean putBoolean(String key, boolean value);
/**
* Returns the boolean the key maps to.
* @param key the key to look up
* @return the value associated with the given key
* @throws TableKeyNotDefinedException if there is no value associated with
* the given key
* @deprecated This exception-raising method has been replaced by the
* default-taking method {@link #getBoolean(String, boolean)}.
*/
@Deprecated
public boolean getBoolean(String key) throws TableKeyNotDefinedException;
/**
* Returns the boolean the key maps to. If the key does not exist or is of
* different type, it will return the default value.
* @param key the key to look up
* @param defaultValue the value to be returned if no value is found
* @return the value associated with the given key or the given default value
@@ -219,13 +257,19 @@ public interface ITable {
*/
public boolean putBooleanArray(String key, Boolean[] value);
/**
* Returns the boolean array the key maps to.
* @param key the key to look up
* @return the value associated with the given key
* @throws TableKeyNotDefinedException if there is no value associated with
* the given key
* @deprecated This exception-raising method has been replaced by the
* default-taking method {@link #getBooleanArray(String, boolean[])}.
*/
@Deprecated
public boolean[] getBooleanArray(String key) throws TableKeyNotDefinedException;
/**
* Returns the boolean array the key maps to. If the key does not exist or is
* of different type, it will return the default value.
* @param key the key to look up
* @param defaultValue the value to be returned if no value is found
* @return the value associated with the given key or the given default value
@@ -233,6 +277,8 @@ public interface ITable {
*/
public boolean[] getBooleanArray(String key, boolean[] defaultValue);
/**
* Returns the boolean array the key maps to. If the key does not exist or is
* of different type, it will return the default value.
* @param key the key to look up
* @param defaultValue the value to be returned if no value is found
* @return the value associated with the given key or the given default value
@@ -255,13 +301,19 @@ public interface ITable {
*/
public boolean putNumberArray(String key, Double[] value);
/**
* Returns the number array the key maps to.
* @param key the key to look up
* @return the value associated with the given key
* @throws TableKeyNotDefinedException if there is no value associated with
* the given key
* @deprecated This exception-raising method has been replaced by the
* default-taking method {@link #getNumberArray(String, double[])}.
*/
@Deprecated
public double[] getNumberArray(String key) throws TableKeyNotDefinedException;
/**
* Returns the number array the key maps to. If the key does not exist or is
* of different type, it will return the default value.
* @param key the key to look up
* @param defaultValue the value to be returned if no value is found
* @return the value associated with the given key or the given default value
@@ -269,6 +321,8 @@ public interface ITable {
*/
public double[] getNumberArray(String key, double[] defaultValue);
/**
* Returns the number array the key maps to. If the key does not exist or is
* of different type, it will return the default value.
* @param key the key to look up
* @param defaultValue the value to be returned if no value is found
* @return the value associated with the given key or the given default value
@@ -284,13 +338,19 @@ public interface ITable {
*/
public boolean putStringArray(String key, String[] value);
/**
* Returns the string array the key maps to.
* @param key the key to look up
* @return the value associated with the given key
* @throws TableKeyNotDefinedException if there is no value associated with
* the given key
* @deprecated This exception-raising method has been replaced by the
* default-taking method {@link #getStringArray(String, String[])}.
*/
@Deprecated
public String[] getStringArray(String key) throws TableKeyNotDefinedException;
/**
* Returns the string array the key maps to. If the key does not exist or is
* of different type, it will return the default value.
* @param key the key to look up
* @param defaultValue the value to be returned if no value is found
* @return the value associated with the given key or the given default value
@@ -314,13 +374,19 @@ public interface ITable {
*/
public boolean putRaw(String key, ByteBuffer value, int len);
/**
* Returns the raw value (byte array) the key maps to.
* @param key the key to look up
* @return the value associated with the given key
* @throws TableKeyNotDefinedException if there is no value associated with
* the given key
* @deprecated This exception-raising method has been replaced by the
* default-taking method {@link #getRaw(String, byte[])}.
*/
@Deprecated
public byte[] getRaw(String key) throws TableKeyNotDefinedException;
/**
* Returns the raw value (byte array) the key maps to. If the key does not
* exist or is of different type, it will return the default value.
* @param key the key to look up
* @param defaultValue the value to be returned if no value is found
* @return the value associated with the given key or the given default value
@@ -397,7 +463,6 @@ public interface ITable {
*/
/**
* @deprecated
* Maps the specified key to the specified value in this table.
* The key can not be null.
* The value can be retrieved by calling the get method with a key that is
@@ -406,11 +471,12 @@ public interface ITable {
* @param value the value
* @return False if the table key already exists with a different type
* @throws IllegalArgumentException if key is null
* @deprecated Use {@link #putNumber(String, double)} instead.
*/
@Deprecated
public boolean putInt(String key, int value);
/**
* @deprecated
* Returns the value at the specified key.
* @param key the key
* @return the value
@@ -419,25 +485,26 @@ public interface ITable {
* @throws IllegalArgumentException if the value mapped to by the key is not
* an int
* @throws IllegalArgumentException if the key is null
* @deprecated Use {@link #getNumber(String, double)} instead.
*/
@Deprecated
public int getInt(String key) throws TableKeyNotDefinedException;
/**
* @deprecated
* Returns the value at the specified key.
* @param key the key
* @param defaultValue the value returned if the key is undefined
* @return the value
* @throws TableKeyNotDefinedException if there is no value mapped to by the key
* @throws IllegalArgumentException if the value mapped to by the key is not
* an int
* @throws IllegalArgumentException if the key is null
* @deprecated Use {@link #getNumber(String, double)} instead.
*/
@Deprecated
public int getInt(String key, int defaultValue)
throws TableKeyNotDefinedException;
/**
* @deprecated
* Maps the specified key to the specified value in this table.
* The key can not be null.
* The value can be retrieved by calling the get method with a key that is
@@ -446,11 +513,12 @@ public interface ITable {
* @param value the value
* @return False if the table key already exists with a different type
* @throws IllegalArgumentException if key is null
* @deprecated Use {@link #putNumber(String, double)} instead.
*/
@Deprecated
public boolean putDouble(String key, double value);
/**
* @deprecated
* Returns the value at the specified key.
* @param key the key
* @return the value
@@ -459,20 +527,21 @@ public interface ITable {
* @throws IllegalArgumentException if the value mapped to by the key is not a
* double
* @throws IllegalArgumentException if the key is null
* @deprecated Use {@link #getNumber(String, double)} instead.
*/
@Deprecated
public double getDouble(String key) throws TableKeyNotDefinedException;
/**
* @deprecated
* Returns the value at the specified key.
* @param key the key
* @param defaultValue the value returned if the key is undefined
* @return the value
* @throws TableKeyNotDefinedException if there is no
* value mapped to by the key
* @throws IllegalArgumentException if the value mapped to by the key is not a
* double
* @throws IllegalArgumentException if the key is null
* @deprecated Use {@link #getNumber(String, double)} instead.
*/
@Deprecated
public double getDouble(String key, double defaultValue);
}