edu.wpi.first.wpilibj
Class Preferences

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

public class Preferences
extends java.lang.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(java.lang.String key)
          Returns whether or not there is a key with the given name.
 boolean getBoolean(java.lang.String key, boolean backup)
          Returns the boolean at the given key.
 double getDouble(java.lang.String key, double backup)
          Returns the double at the given key.
 float getFloat(java.lang.String key, float backup)
          Returns the float at the given key.
static Preferences getInstance()
          Returns the preferences instance.
 int getInt(java.lang.String key, int backup)
          Returns the int at the given key.
 java.util.Vector getKeys()
           
 long getLong(java.lang.String key, long backup)
          Returns the long at the given key.
 java.lang.String getString(java.lang.String key, java.lang.String backup)
          Returns the string at the given key.
 void putBoolean(java.lang.String key, boolean value)
          Puts the given boolean into the preferences table.
 void putDouble(java.lang.String key, double value)
          Puts the given double into the preferences table.
 void putFloat(java.lang.String key, float value)
          Puts the given float into the preferences table.
 void putInt(java.lang.String key, int value)
          Puts the given int into the preferences table.
 void putLong(java.lang.String key, long value)
          Puts the given long into the preferences table.
 void putString(java.lang.String key, java.lang.String value)
          Puts the given string into the preferences table.
 void remove(java.lang.String key)
          Remove a preference
 void save()
          Saves the preferences to a file on the cRIO.
 
Methods inherited from class java.lang.Object
clone, equals, finalize, 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 java.util.Vector getKeys()
Returns:
a vector of the keys

putString

public void putString(java.lang.String key,
                      java.lang.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:
java.lang.NullPointerException - if value is null
java.lang.IllegalArgumentException - if value contains a quotation mark
Preferences.ImproperPreferenceKeyException - if the key contains any whitespace or an equals sign

putInt

public void putInt(java.lang.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(java.lang.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(java.lang.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(java.lang.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(java.lang.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(java.lang.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:
java.lang.NullPointerException - if key is null

remove

public void remove(java.lang.String key)
Remove a preference

Parameters:
key - the key
Throws:
java.lang.NullPointerException - if key is null

getString

public java.lang.String getString(java.lang.String key,
                                  java.lang.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:
java.lang.NullPointerException - if the key is null

getInt

public int getInt(java.lang.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(java.lang.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(java.lang.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(java.lang.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(java.lang.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.