edu.wpi.first.wpilibj
Class Preferences

java.lang.Object
  edu.wpi.first.wpilibj.Preferences

public class Preferences
extends Object

The preferences class provides a relatively simple way to save important values to the cRIO to access the next time the cRIO is booted.

This class loads and saves from a file inside the cRIO. The user can not access the file directly, but may modify values at specific fields which will then be saved to the file when save() is called.

This class is thread safe.

This will also interact with NetworkTable by creating a table called "Preferences" with all the key-value pairs. To save using NetworkTable, simply set the boolean at position ~S A V E~ to true. Also, if the value of any variable is " in the NetworkTable, then that represents non-existence in the Preferences table

Author:

Joe Grinstead

Nested Class Summary

static class	Preferences.ImproperPreferenceKeyException Should be thrown if a string can not be used as a key in the preferences file.
static class	Preferences.IncompatibleTypeException This exception is thrown if the a value requested cannot be converted to the requested type.

Method Summary

boolean	containsKey(String key) Returns whether or not there is a key with the given name.
boolean	getBoolean(String key, boolean backup) Returns the boolean at the given key.
double	getDouble(String key, double backup) Returns the double at the given key.
float	getFloat(String key, float backup) Returns the float at the given key.
static Preferences	getInstance() Returns the preferences instance.
int	getInt(String key, int backup) Returns the int at the given key.
Vector	getKeys()
long	getLong(String key, long backup) Returns the long at the given key.
String	getString(String key, String backup) Returns the string at the given key.
void	putBoolean(String key, boolean value) Puts the given boolean into the preferences table.
void	putDouble(String key, double value) Puts the given double into the preferences table.
void	putFloat(String key, float value) Puts the given float into the preferences table.
void	putInt(String key, int value) Puts the given int into the preferences table.
void	putLong(String key, long value) Puts the given long into the preferences table.
void	putString(String key, String value) Puts the given string into the preferences table.
void	remove(String key) Remove a preference
void	save() Saves the preferences to a file on the cRIO.

Methods inherited from class java.lang.Object

equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Method Detail

getInstance

public static Preferences getInstance()

Returns the preferences instance.

Returns:

the preferences instance

getKeys

public Vector getKeys()

Returns:

a vector of the keys

putString

public void putString(String key,
                      String value)

Puts the given string into the preferences table.

The value may not have quotation marks, nor may the key have any whitespace nor an equals sign

This will NOT save the value to memory between power cycles, to do that you must call save() (which must be used with care). at some point after calling this.

Parameters:

key - the key

value - the value

Throws:

NullPointerException - if value is null

IllegalArgumentException - if value contains a quotation mark

Preferences.ImproperPreferenceKeyException - if the key contains any whitespace or an equals sign

putInt

public void putInt(String key,
                   int value)

Puts the given int into the preferences table.

The key may not have any whitespace nor an equals sign

This will NOT save the value to memory between power cycles, to do that you must call save() (which must be used with care) at some point after calling this.

Parameters:

key - the key

value - the value

Throws:

Preferences.ImproperPreferenceKeyException - if the key contains any whitespace or an equals sign

putDouble

public void putDouble(String key,
                      double value)

Puts the given double into the preferences table.

The key may not have any whitespace nor an equals sign

This will NOT save the value to memory between power cycles, to do that you must call save() (which must be used with care) at some point after calling this.

Parameters:

key - the key

value - the value

Throws:

Preferences.ImproperPreferenceKeyException - if the key contains any whitespace or an equals sign

putFloat

public void putFloat(String key,
                     float value)

Puts the given float into the preferences table.

The key may not have any whitespace nor an equals sign

This will NOT save the value to memory between power cycles, to do that you must call save() (which must be used with care) at some point after calling this.

Parameters:

key - the key

value - the value

Throws:

Preferences.ImproperPreferenceKeyException - if the key contains any whitespace or an equals sign

putBoolean

public void putBoolean(String key,
                       boolean value)

Puts the given boolean into the preferences table.

The key may not have any whitespace nor an equals sign

This will NOT save the value to memory between power cycles, to do that you must call save() (which must be used with care) at some point after calling this.

Parameters:

key - the key

value - the value

Throws:

Preferences.ImproperPreferenceKeyException - if the key contains any whitespace or an equals sign

putLong

public void putLong(String key,
                    long value)

Puts the given long into the preferences table.

The key may not have any whitespace nor an equals sign

This will NOT save the value to memory between power cycles, to do that you must call save() (which must be used with care) at some point after calling this.

Parameters:

key - the key

value - the value

Throws:

Preferences.ImproperPreferenceKeyException - if the key contains any whitespace or an equals sign

containsKey

public boolean containsKey(String key)

Returns whether or not there is a key with the given name.

Parameters:

key - the key

Returns:

if there is a value at the given key

Throws:

NullPointerException - if key is null

remove

public void remove(String key)

Remove a preference

Parameters:

key - the key

Throws:

NullPointerException - if key is null

getString

public String getString(String key,
                        String backup)

Returns the string at the given key. If this table does not have a value for that position, then the given backup value will be returned.

Parameters:

key - the key

backup - the value to return if none exists in the table

Returns:

either the value in the table, or the backup

Throws:

NullPointerException - if the key is null

getInt

public int getInt(String key,
                  int backup)

Returns the int at the given key. If this table does not have a value for that position, then the given backup value will be returned.

Parameters:

key - the key

backup - the value to return if none exists in the table

Returns:

either the value in the table, or the backup

Throws:

Preferences.IncompatibleTypeException - if the value in the table can not be converted to an int

getDouble

public double getDouble(String key,
                        double backup)

Returns the double at the given key. If this table does not have a value for that position, then the given backup value will be returned.

Parameters:

key - the key

backup - the value to return if none exists in the table

Returns:

either the value in the table, or the backup

Throws:

Preferences.IncompatibleTypeException - if the value in the table can not be converted to an double

getBoolean

public boolean getBoolean(String key,
                          boolean backup)

Returns the boolean at the given key. If this table does not have a value for that position, then the given backup value will be returned.

Parameters:

key - the key

backup - the value to return if none exists in the table

Returns:

either the value in the table, or the backup

Throws:

Preferences.IncompatibleTypeException - if the value in the table can not be converted to a boolean

getFloat

public float getFloat(String key,
                      float backup)

Returns the float at the given key. If this table does not have a value for that position, then the given backup value will be returned.

Parameters:

key - the key

backup - the value to return if none exists in the table

Returns:

either the value in the table, or the backup

Throws:

Preferences.IncompatibleTypeException - if the value in the table can not be converted to a float

getLong

public long getLong(String key,
                    long backup)

Returns the long at the given key. If this table does not have a value for that position, then the given backup value will be returned.

Parameters:

key - the key

backup - the value to return if none exists in the table

Returns:

either the value in the table, or the backup

Throws:

Preferences.IncompatibleTypeException - if the value in the table can not be converted to a long

save

public void save()

Saves the preferences to a file on the cRIO.

This should NOT be called often. Too many writes can damage the cRIO's flash memory. While it is ok to save once or twice a match, this should never be called every run of IterativeRobot.teleopPeriodic().

The actual writing of the file is done in a separate thread. However, any call to a get or put method will wait until the table is fully saved before continuing.