Prefs (Randolf's Java library)

Object
- ca.randolf.util.Prefs

public class Prefs
extends Object

Easily load and save user-specific settings in the user's home directory, and efficiently. This class handles the tedious aspects of determining the user's home directory (when an absolute path is not provided), handling file I/O passively so that IOException handling can be deferred, etc.

This class was designed to function in a static context prior to the instantiation of whatever class depends on it, which is why it includes the loadPassive() method that stores java.io.IOException for later retrieval instead of throwing it on-the-fly, hence this class will effectively load the preferences as part of your class's definition, which can then be shared in both a static main() class and a non-static constructor, and without having to be reinstantiated later on or passed along as a method variable.

Configuration file format

The format of the configuration file is a simple ASCII text file that can also be edited with any standard ASCII text editor, with each line containing the keyword and value delimited by a space (equal signs can be supported as delimiters by changing the Equal Sign Policy from its default).

Configuration formatting rules are:

Keys and their respective Values are delimited by any number of whitespace characters
- If you need to use equal signs for delimiters, you'll need to use the setPolicyEqualSign() method to enable that functionality
Blank lines are ignored
Lines beginning with an octothorpe ("#") are ignored
Whitespace characters before/after Keywords and Values are ignored
Keywords and Values may be enclosed within quotation marks to retain leading/trailing whitespace characters
ASCII characters 0 through 32 can optionally be prefixed as a special sequence as documented in Table 1 (below)
Backslash characters must be prefixed by a backslash character (see Table 1)
Octothorpe characters must be prefixed by a backslash character (see Table 1) if they are not to be interpreted as the comments
If the last character on a line is a backslash ("\"), then the next line will be appended to it (and that backslash will not be included)

Table 1: Special characters Note: Sequences are case-sensitive
UNIX/Linux keystroke	ASCII value	Character's meaning	Sequence
n/a	0	Null	\0
CTRL-A	1	Start of heading	\A
CTRL-B	2	Start of text	\B
CTRL-C	3	End of text	\C
CTRL-D	4	End of transmit	\D
CTRL-E	5	Enquiry	\E
CTRL-F	6	Acknowledge	\F
CTRL-G	7	Audible bell	\G
CTRL-H	8	Backspace	\H
CTRL-I	9	Horizontal tab	\I or \t
CTRL-J	10	Line feed	\J or #&92;n
CTRL-K	11	Vertical tab	\K
CTRL-L	12	Form feed	\L
CTRL-M	13	Carriage return	\M or \r
CTRL-N	14	Shift out	\N
CTRL-O	15	Shift in	\O
CTRL-P	16	Data link escape	\P
CTRL-Q	17	Device control 1	\Q
CTRL-R	18	Device control 2	\R
CTRL-S	19	Device control 3	\S
CTRL-T	20	Device control 4	\T
CTRL-U	21	Negative acknowledge	\U
CTRL-V	22	Synchronous idle	\V
CTRL-W	23	End transmission block	\W
CTRL-X	24	Cancel	\X
CTRL-Y	25	End of medium	\Y
CTRL-Z	26	Substitution	\Z
Escape	27	Escape	\[
n/a	28	File separator	\:
n/a	29	Group separator	\]
n/a	30	Record separator	\/
n/a	31	Unit separator	\.
Space bar	32	Blank space	\
"	34	Quotation mark (non-functional)	\"
Shift-3	35	Octothorpe (" # ")	\#
\	92	Backslash (" \ ")	\\
n/a	hex	Hexadecimal value "hh"	\xhh

Example

The following example code reads the default ".java.conf" file, and outputs "<Not defined>" if the "NanoTime" value has never been set before. If it has previously been set, then that value will be output. Run this file multiple times and observe the output (previously set value) and the contents of the ".java.conf" file in the current user's home directory (which is updated each time the program is run).

import ca.randolf.util.Prefs;
public class Example {
  public static final Prefs PREFS = new Prefs(); // Load user preferences from ".java.conf"
  public static void main(String... args) throws java.io.IOException {
    System.out.println(PREFS.get("NanoTime", ""));
    PREFS.set("NanoTime", "" + System.nanoTime()).save();
  } // -x- void main -x-
} // -x- class Example -x-

A slightly more interesting example is the following code, which also serves to demonstrate the appendMax() method. In this file, the most recent 8 "NanoTime" values are saved, with the oldest (first) one being removed automatically, which can be observed by viewing the ".java.conf" file in the current user's home directory between multiple runs of the example code.

import ca.randolf.util.Prefs;
public class Example {
  public static final Prefs PREFS = new Prefs(); // Load user preferences from ".java.conf"
  public static void main(String... args) throws java.io.IOException {
    System.out.println(PREFS.get("NanoTime", ""));
    PREFS.appendMax(8, "NanoTime", "" + System.nanoTime()).save();
  } // -x- void main -x-
} // -x- class Example -x-

Field Summary

Fields
Modifier and Type	Field and Description
`static String`	`DESCRIPTION` Description of this Package (read-only).
`java.nio.file.Path`	`FILENAME` Name of configuration file (defined by a Constructor).
`static String`	`VERSION` Version number of this Package (read-only).

Constructor Summary

Constructors
Constructor and Description
`Prefs()` Instantiate a Prefs object that defaults to using a configuration file named ".java.conf" in the logged-in user's home directory.
`Prefs(java.io.File filename)` Instantiate a Prefs object that uses the specified configuration file in the logged-in user's home directory.
`Prefs(java.io.InputStream in)` Instantiate a Prefs object, reading from the specified InputStream's configuration data in a read-only fashion, then closing the stream using its standard close() method. Internally, the read-only flag is permanently set and FILENAME is set to null.
`Prefs(java.nio.file.Path filename)` Instantiate a Prefs object that uses the specified configuration file in the logged-in user's home directory.
`Prefs(String filename)` Instantiate a Prefs object that uses the specified configuration file in the logged-in user's home directory.
`Prefs(java.net.URL addr)` Instantiate a Prefs object, reading from the specified URL's openStream() method's InputStream in a read-only fashion. Internally, the read-only flag is permanently set and FILENAME is set to null. The URL is also stored internally so that the load() and loadPassive() methods can be used subsequently to re-load the configuration data.

Method Summary

All Methods Instance Methods Concrete Methods
Modifier and Type	Method and Description
`Prefs`	`append(String key, String... values)` Appends the specified String(s) to the underlying (or newly created) ArrayList<String> for the given key.
`Prefs`	`appendMax(int maximum, String key, String... values)` Appends the specified String(s) to the underlying (or newly created) ArrayList<String> for the given key without exceeding the maximum number specified. This is useful for maintaining a "most recently used" list (in the spirit of user-friendly design, I suggest using a higher maximum number rather than a lower maximum, such as 42 instead of 10).
`Prefs`	`appendMax(String key, String... values)` Appends the specified String(s) to the underlying (or newly created) ArrayList<String> for the given key without exceeding the maximum number specified by the setPolicyAppendMax() method. This is useful for maintaining a "most recently used" list.
`String`	`get(String key)` Returns the first String from the underlying ArrayList<String> for the given key.
`String`	`get(String key, int index)` Returns the specified String from the underlying ArrayList<String> for the given key.
`String`	`get(String key, int index, String defaultValue)` Returns the first String from the underlying ArrayList<String> for the given key, if it exists. If it doesn't exist, then the supplied defaultValue will be returned instead.
`String`	`get(String key, String defaultValue)` Returns the first String from the underlying ArrayList<String> for the given key, if it exists. If it doesn't exist, then the supplied defaultValue will be returned instead.
`ArrayList<String>`	`getArrayList(String key)` Returns the underlying ArrayList<String> for the given key.
`java.io.IOException`	`getIOError()` Returns the most recent IOException.
`String`	`getLast(String key)` Returns the last String from the underlying ArrayList<String> for the given key.
`LinkedHashMap<String,ArrayList<String>>`	`getLinkedHashMap()` Returns the underlying LinkedHashMap<String,ArrayList<String>> object.
`boolean`	`getPolicyAppendDuplicates()` Indicates the policy on whether all values stored by any method whose name begins with the word "append" are unique.
`int`	`getPolicyAppendMax()` Indicates the policy for the maximum elements default used by any method whose name begins with the word "appendMax."
`boolean`	`getPolicyEqualSign()` Indicates the policy about whether one equal sign is a delimiter between keys and values.
`boolean`	`getPolicyKeepEmptyFile()` Indicates the policy about whether to keep an empty configuration file (which is 0 bytes) or to delete it (default).
`String`	`glean(String key, int index, String defaultValue)` Returns the specified String from the underlying ArrayList<String> object for the given key, if it exists. If it doesn't exist, then the supplied defaultValue will be set and returned instead.
`String`	`glean(String key, String defaultValue)` Returns the first String from the underlying ArrayList<String> object for the given key, if it exists. If it doesn't exist, then the supplied defaultValue will be set and returned instead.
`boolean`	`isLoaded()` Indicates whether data was loaded from the configuration file. TRUE indicates that the data was loaded successfully, and FALSE indicates that it was not.
`boolean`	`isReadOnly()` Indicates whether the configuration file is read-only. This is set by the constructor that accepts an InputStream.
`boolean`	`isSaved()` Indicates whether data was saved to the configuration file. TRUE indicates that the data was saved successfully, and FALSE indicates that it was not.
`Prefs`	`load()` Attempt to read the contents of the configuration file. If the file does not exist, or any read error occurs, then the isLoaded() method will return FALSE from this point forward.
`Prefs`	`loadPassive()` Attempt to read the contents of the configuration file. If the file does not exist, or any read error occurs, then the isLoaded() method will return FALSE from this point forward.
`Prefs`	`remove(String key)` Removes the underlying ArrayList<String> for the given key (if it exists) so that its entry will be deleted from memory, and consequently also effectively be deleted from the contents of the configuration data upon the next save operation.
`Prefs`	`save()` Attempt to save the contents of the configuration file. If the file can not be overwritten or created, or any write error occurs, then the isSaved() method will return FALSE from this point forward.
`Prefs`	`saveAs(java.io.File filename)` Attempt to save the contents of the configuration data in the alternative filename that was specified. If the file can not be overwritten or created, or any write error occurs, then the isSaved() method will return FALSE from this point forward.
`Prefs`	`saveAs(java.nio.file.Path filename)` Attempt to save the contents of the configuration data in the alternative filename that was specified. If the file can not be overwritten or created, or any write error occurs, then the isSaved() method will return FALSE from this point forward.
`Prefs`	`saveAs(String filename)` Attempt to save the contents of the configuration data in the alternative filename that was specified. If the file can not be overwritten or created, or any write error occurs, then the isSaved() method will return FALSE from this point forward.
`Prefs`	`savePassive()` Attempt to save the contents of the configuration file. If the file can not be overwritten or created, or any write error occurs, then the isSaved() method will return FALSE from this point forward.
`Prefs`	`set(String key, int index, String value)` Sets or replaces the specified String in the underlying (or newly created) ArrayList<String> for the given key. If the ArrayList does not contain enough elements, then the missing number of empty String objects will be inserted automatically.
`Prefs`	`set(String key, String... values)` Creates or replaces the underlying ArrayList<String> for the given key, and populates it with the specified String(s).
`Prefs`	`setArrayList(String key, ArrayList<String> array)` Sets or replaces the underlying ArrayList<String> for the given key.
`Prefs`	`setPolicyAppendDuplicates(boolean policy)` Specifies the policy on whether all values stored by any method whose name begins with the word "append" are unique. This is disabled by default, which means that duplicate values will be eliminated on-the-fly whenever a method beginning with the word "append" is called.
`Prefs`	`setPolicyAppendMax(int policy)` Specifies the policy for the maximum elements default used by any method whose name begins with the word "appendMax" (the default is 42).
`Prefs`	`setPolicyEqualSign(boolean policy)` Specifies the policy about whether one equal sign is a delimiter between keys and values (whitespace characters present in the delimiter set will still be consumed and discarded as expected).
`Prefs`	`setPolicyKeepEmptyFile(boolean policy)` Indicates the policy about whether to keep an empty configuration file (which is 0 bytes) or to delete it (default).
`Prefs`	`setReadOnly()` Indicates that the configuration data cannot be saved. Setting this flag is an irreversible operation (i.e., once this flag has been set to TRUE, it can never be reverted back to FALSE).

Methods inherited from class Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

- Field Detail
  - DESCRIPTION
```
public static final String DESCRIPTION
```
    Description of this Package (read-only).
    
    See Also:
    
    Constant Field Values
  - FILENAME
```
public final java.nio.file.Path FILENAME
```
    Name of configuration file (defined by a Constructor).
  - VERSION
```
public static final String VERSION
```
    Version number of this Package (read-only).
    
    See Also:
    
    Constant Field Values
- Constructor Detail
  - Prefs
```
public Prefs()
```
    Instantiate a Prefs object that defaults to using a configuration file named ".java.conf" in the logged-in user's home directory.
    Note: Internally, this constructor calls the loadPassive() method.
  - Prefs
```
public Prefs(java.io.File filename)
```
    Instantiate a Prefs object that uses the specified configuration file in the logged-in user's home directory.
    Note: Internally, this constructor calls the loadPassive() method.
    
    Parameters:
    
    filename - Name of configuration file to use (filename may optionally include relative or absolute path information; if an absolute path is used, then the user's home directory will be bypassed)
  - Prefs
```
public Prefs(java.io.InputStream in)
```
    Instantiate a Prefs object, reading from the specified InputStream's configuration data in a read-only fashion, then closing the stream using its standard close() method. Internally, the read-only flag is permanently set and FILENAME is set to null.
    This constructor is particularly useful when used in conjunction with the java.class.ClassLoader.getSystemResource("example.conf") method is used to load a configuration file from within a JAR file.
    Note: Internally, this constructor calls the loadPassive() method.
    
    Parameters:
    
    in - The InputStream to use to read the configuration data
  - Prefs
```
public Prefs(java.nio.file.Path filename)
```
    Instantiate a Prefs object that uses the specified configuration file in the logged-in user's home directory.
    Note: Internally, this constructor calls the loadPassive() method.
    
    Parameters:
    
    filename - Name of configuration file to use (filename may optionally include relative or absolute path information; if an absolute path is used, then the user's home directory will be bypassed)
  - Prefs
```
public Prefs(String filename)
```
    Instantiate a Prefs object that uses the specified configuration file in the logged-in user's home directory.
    Note: Internally, this constructor calls the loadPassive() method.
    
    Parameters:
    
    filename - Name of configuration file to use (filename may optionally include relative or absolute path information; if an absolute path is used, then the user's home directory will be bypassed)
  - Prefs
```
public Prefs(java.net.URL addr)
```
    Instantiate a Prefs object, reading from the specified URL's openStream() method's InputStream in a read-only fashion. Internally, the read-only flag is permanently set and FILENAME is set to null. The URL is also stored internally so that the load() and loadPassive() methods can be used subsequently to re-load the configuration data.
    This constructor is particularly useful for reading information from a remote system over a network, such as a web page.
    Note: Internally, this constructor calls the loadPassive() method.
    
    Parameters:
    
    addr - The URL to use to read the configuration data
- Method Detail
  - append
```
public Prefs append(String key,
                    String... values)
```
    Appends the specified String(s) to the underlying (or newly created) ArrayList<String> for the given key.
    
    Parameters:
    
    key - The key to use
    
    values - The Strings to store
    
    Returns:
    
    This object, as a convenience
    
    See Also:
    
    getPolicyAppendDuplicates(), setPolicyAppendDuplicates(boolean)
  - appendMax
```
public Prefs appendMax(int maximum,
                       String key,
                       String... values)
```
    Appends the specified String(s) to the underlying (or newly created) ArrayList<String> for the given key without exceeding the maximum number specified. This is useful for maintaining a "most recently used" list (in the spirit of user-friendly design, I suggest using a higher maximum number rather than a lower maximum, such as 42 instead of 10).
    Note: The underlying ArrayList<String> will be truncated to comply with the maximum limit (the first elements are removed to make room to add the last elements).
    
    Parameters:
    
    maximum - The maximum number of String elements that may remain in the underlying ArrayList<String>. (if 0 is specified, then the maximum set by the setPolicyAppendMax method will be used instead)
    
    key - The key to use
    
    values - The Strings to store
    
    Returns:
    
    This object, as a convenience
    
    See Also:
    
    getPolicyAppendDuplicates(), setPolicyAppendDuplicates(boolean), getPolicyAppendMax(), setPolicyAppendMax(int)
  - appendMax
```
public Prefs appendMax(String key,
                       String... values)
```
    Appends the specified String(s) to the underlying (or newly created) ArrayList<String> for the given key without exceeding the maximum number specified by the setPolicyAppendMax() method. This is useful for maintaining a "most recently used" list.
    Note: The underlying ArrayList<String> will be truncated to comply with the maximum limit (the first elements are removed to make room to add the last elements).
    
    Parameters:
    
    key - The key to use
    
    values - The Strings to store
    
    Returns:
    
    This object, as a convenience
    
    See Also:
    
    getPolicyAppendDuplicates(), setPolicyAppendDuplicates(boolean), getPolicyAppendMax(), setPolicyAppendMax(int)
  - get
```
public String get(String key)
```
    Returns the first String from the underlying ArrayList<String> for the given key.
    Note: If the most recent call to the load() method failed, or this key doesn't exist, or the specified String doesn't exist then null will be returned.
    
    Parameters:
    
    key - The key to use
    
    Returns:
    
    String value
  - get
```
public String get(String key,
                  int index)
```
    Returns the specified String from the underlying ArrayList<String> for the given key.
    Note: If the most recent call to the load() method failed, or this key doesn't exist, or the specified String doesn't exist then null will be returned.
    
    Parameters:
    
    key - The key to use
    
    index - The position from within the ArrayList of the value to retrieve (first element is 0; negative values count backwards from the last element)
    
    Returns:
    
    String value
  - get
```
public String get(String key,
                  int index,
                  String defaultValue)
```
    Returns the first String from the underlying ArrayList<String> for the given key, if it exists. If it doesn't exist, then the supplied defaultValue will be returned instead.
    Note: If the most recent call to the load() method failed, or this key doesn't exist, or the specified String doesn't exist then null will be returned.
    
    Parameters:
    
    key - The key to use
    
    index - The position from within the ArrayList of the value to retrieve (first element is 0; negative values count backwards from the last element)
    
    defaultValue - The alternate default value to use
    
    Returns:
    
    String value
  - get
```
public String get(String key,
                  String defaultValue)
```
    Returns the first String from the underlying ArrayList<String> for the given key, if it exists. If it doesn't exist, then the supplied defaultValue will be returned instead.
    Note: If the most recent call to the load() method failed, or this key doesn't exist, or the specified String doesn't exist then null will be returned.
    
    Parameters:
    
    key - The key to use
    
    defaultValue - The alternate default value to use
    
    Returns:
    
    String value
  - getArrayList
```
public ArrayList<String> getArrayList(String key)
```
    Returns the underlying ArrayList<String> for the given key.
    Note: If the most recent call to the load() method failed, or load() was never called, or this key doesn't exist, then null will be returned.
    
    Parameters:
    
    key - The key to use
    
    Returns:
    
    LinkedHashMap<String,ArrayList<String>>
  - getIOError
```
public java.io.IOException getIOError()
```
    Returns the most recent IOException.
    
    Returns:
    
    IOException or NULL if no error occurred
    
    See Also:
    
    isLoaded(), isSaved(), load(), save()
  - getLast
```
public String getLast(String key)
```
    Returns the last String from the underlying ArrayList<String> for the given key.
    Note: If the most recent call to the load() method failed, or this key doesn't exist, or the specified String doesn't exist then null will be returned.
    
    Parameters:
    
    key - The key to use
    
    Returns:
    
    String value
  - getLinkedHashMap
```
public LinkedHashMap<String,ArrayList<String>> getLinkedHashMap()
```
    Returns the underlying LinkedHashMap<String,ArrayList<String>> object.
    Note: If the most recent call to the load() method failed, or load() was never called, then null will be returned.
    
    Returns:
    
    LinkedHashMap<String,ArrayList<String>>
  - getPolicyAppendDuplicates
```
public boolean getPolicyAppendDuplicates()
```
    Indicates the policy on whether all values stored by any method whose name begins with the word "append" are unique.
    
    Returns:
    
    long Maximum configuration file size
    
    See Also:
    
    append(java.lang.String, java.lang.String...), appendMax(java.lang.String, java.lang.String...), setPolicyAppendDuplicates(boolean)
  - getPolicyAppendMax
```
public int getPolicyAppendMax()
```
    Indicates the policy for the maximum elements default used by any method whose name begins with the word "appendMax."
    
    Returns:
    
    int Maximum number of elements
    
    See Also:
    
    appendMax(java.lang.String, java.lang.String...), setPolicyAppendMax(int)
  - getPolicyEqualSign
```
public boolean getPolicyEqualSign()
```
    Indicates the policy about whether one equal sign is a delimiter between keys and values.
    
    Returns:
    
    boolean FALSE = Equal signs are treated like other non-whitespace characters; TRUE = One equal sign is a required special delimiter character
    
    See Also:
    
    setPolicyEqualSign(boolean)
  - getPolicyKeepEmptyFile
```
public boolean getPolicyKeepEmptyFile()
```
    Indicates the policy about whether to keep an empty configuration file (which is 0 bytes) or to delete it (default).
    
    Returns:
    
    boolean FALSE = Don't keep empty configuration file (delete it); TRUE = Keep empty configuration file (don't delete it)
    
    See Also:
    
    setPolicyKeepEmptyFile(boolean)
  - glean
```
public String glean(String key,
                    int index,
                    String defaultValue)
```
    Returns the specified String from the underlying ArrayList<String> object for the given key, if it exists. If it doesn't exist, then the supplied defaultValue will be set and returned instead.
    Note: If the most recent call to the load() method failed, or this key doesn't exist, or the specified String doesn't exist then defaultValue will be set and returned.
    
    Parameters:
    
    key - The key to use
    
    index - The position from within the ArrayList of the value to retrieve (first element is 0; negative values count backwards from the last element)
    
    defaultValue - The alternate default value to use
    
    Returns:
    
    String value
  - glean
```
public String glean(String key,
                    String defaultValue)
```
    Returns the first String from the underlying ArrayList<String> object for the given key, if it exists. If it doesn't exist, then the supplied defaultValue will be set and returned instead.
    Note: If the most recent call to the load() method failed, or this key doesn't exist, or the specified String doesn't exist then defaultValue will be set and returned.
    
    Parameters:
    
    key - The key to use
    
    defaultValue - The alternate default value to use
    
    Returns:
    
    String value
  - isLoaded
```
public boolean isLoaded()
```
    Indicates whether data was loaded from the configuration file. TRUE indicates that the data was loaded successfully, and FALSE indicates that it was not.
    
    Returns:
    
    boolean TRUE = Data was loaded from file successfully; FALSE = Data was not loaded from file
    
    See Also:
    
    getIOError(), isSaved()
  - isReadOnly
```
public boolean isReadOnly()
```
    Indicates whether the configuration file is read-only. This is set by the constructor that accepts an InputStream.
    
    Returns:
    
    boolean TRUE = Configuration file is read-only; FALSE = Configuration file is expected to be writeable.
    
    See Also:
    
    setReadOnly()
  - isSaved
```
public boolean isSaved()
```
    Indicates whether data was saved to the configuration file. TRUE indicates that the data was saved successfully, and FALSE indicates that it was not.
    
    Returns:
    
    boolean TRUE = Data was save to file successfully; FALSE = Data was not saved to file
    
    See Also:
    
    getIOError(), isLoaded()
  - load
```
public Prefs load()
           throws java.io.IOException
```
    Attempt to read the contents of the configuration file. If the file does not exist, or any read error occurs, then the isLoaded() method will return FALSE from this point forward.
    This method may be called multiple times to re-load the configuration data (the existing LinkedHashMap data will be cleared prior to each load attempt).
    Note: An attempt to open the file is used internally since hidden files on network drives can sometimes fail the standard tests for existence.
    
    Returns:
    
    This object, as a convenience
    
    Throws:
    
    java.io.IOException - if a read-error occurs
    
    See Also:
    
    getIOError(), isLoaded()
  - loadPassive
```
public Prefs loadPassive()
```
    Attempt to read the contents of the configuration file. If the file does not exist, or any read error occurs, then the isLoaded() method will return FALSE from this point forward.
    This method may be called multiple times to re-load the configuration data (the existing LinkedHashMap data will be cleared prior to each load attempt).
    Note: An attempt to open the file is used internally since hidden files on network drives can sometimes fail the standard tests for existence.
    Note: The word "Passive" in this method's name indicates that this method does not throw an Exception in the event of an error; the Exception is instead stored for later retrieval by the getIOError() method. This is particularly useful for setting up class-wide configuration settings before any constructors or methods are used, and for access from a static context.
    
    Returns:
    
    This object, as a convenience
    
    See Also:
    
    getIOError(), isLoaded()
  - remove
```
public Prefs remove(String key)
```
    Removes the underlying ArrayList<String> for the given key (if it exists) so that its entry will be deleted from memory, and consequently also effectively be deleted from the contents of the configuration data upon the next save operation.
    
    Parameters:
    
    key - The key to use
    
    Returns:
    
    This object, as a convenience
  - save
```
public Prefs save()
           throws java.io.IOException
```
    Attempt to save the contents of the configuration file. If the file can not be overwritten or created, or any write error occurs, then the isSaved() method will return FALSE from this point forward.
    This method may be called multiple times to re-save the configuration data, which can be useful for effectively saving incremental changes.
    
    Returns:
    
    This object, as a convenience
    
    Throws:
    
    java.io.IOException - if a write-error occurs
    
    See Also:
    
    getIOError(), isSaved()
  - saveAs
```
public Prefs saveAs(java.io.File filename)
             throws java.io.IOException
```
    Attempt to save the contents of the configuration data in the alternative filename that was specified. If the file can not be overwritten or created, or any write error occurs, then the isSaved() method will return FALSE from this point forward.
    This method is particularly useful for saving configuration data that was acquired from an InputStream or a URL, or when the readOnly flag is set.
    
    Parameters:
    
    filename - Name of configuration file to use (filename may optionally include relative or absolute path information; if an absolute path is used, then the user's home directory will be bypassed)
    
    Returns:
    
    This object, as a convenience
    
    Throws:
    
    java.io.IOException - if a write-error occurs
    
    See Also:
    
    save(), getIOError(), isSaved(), isReadOnly(), setReadOnly(), Prefs(java.io.InputStream), Prefs(java.net.URL)
  - saveAs
```
public Prefs saveAs(java.nio.file.Path filename)
             throws java.io.IOException
```
    Attempt to save the contents of the configuration data in the alternative filename that was specified. If the file can not be overwritten or created, or any write error occurs, then the isSaved() method will return FALSE from this point forward.
    This method is particularly useful for saving configuration data that was acquired from an InputStream or a URL, or when the readOnly flag is set.
    
    Parameters:
    
    filename - Name of configuration file to use (filename may optionally include relative or absolute path information; if an absolute path is used, then the user's home directory will be bypassed)
    
    Returns:
    
    This object, as a convenience
    
    Throws:
    
    java.io.IOException - if a write-error occurs
    
    See Also:
    
    save(), getIOError(), isSaved(), isReadOnly(), setReadOnly(), Prefs(java.io.InputStream), Prefs(java.net.URL)
  - saveAs
```
public Prefs saveAs(String filename)
             throws java.io.IOException
```
    Attempt to save the contents of the configuration data in the alternative filename that was specified. If the file can not be overwritten or created, or any write error occurs, then the isSaved() method will return FALSE from this point forward.
    This method is particularly useful for saving configuration data that was acquired from an InputStream or a URL, or when the readOnly flag is set.
    
    Parameters:
    
    filename - Name of configuration file to use (filename may optionally include relative or absolute path information; if an absolute path is used, then the user's home directory will be bypassed)
    
    Returns:
    
    This object, as a convenience
    
    Throws:
    
    java.io.IOException - if a write-error occurs
    
    See Also:
    
    save(), getIOError(), isSaved(), isReadOnly(), setReadOnly(), Prefs(java.io.InputStream), Prefs(java.net.URL)
  - savePassive
```
public Prefs savePassive()
```
    Attempt to save the contents of the configuration file. If the file can not be overwritten or created, or any write error occurs, then the isSaved() method will return FALSE from this point forward.
    This method may be called multiple times to re-save the configuration data, which can be useful for effectively saving incremental changes.
    Note: The word "Passive" in this method's name indicates that this method does not throw an Exception in the event of an error; the Exception is instead stored for later retrieval by the getIOError() method.
    
    Returns:
    
    This object, as a convenience
    
    See Also:
    
    getIOError(), isSaved()
  - set
```
public Prefs set(String key,
                 int index,
                 String value)
```
    Sets or replaces the specified String in the underlying (or newly created) ArrayList<String> for the given key. If the ArrayList does not contain enough elements, then the missing number of empty String objects will be inserted automatically.
    
    Parameters:
    
    key - The key to use
    
    index - The position from within the ArrayList of the value to set (first element is 0; negative values count backwards from the last element)
    
    value - The String to store
    
    Returns:
    
    This object, as a convenience
  - set
```
public Prefs set(String key,
                 String... values)
```
    Creates or replaces the underlying ArrayList<String> for the given key, and populates it with the specified String(s).
    
    Parameters:
    
    key - The key to use
    
    values - Any number of String objects for the new ArrayList
    
    Returns:
    
    This object, as a convenience
  - setArrayList
```
public Prefs setArrayList(String key,
                          ArrayList<String> array)
```
    Sets or replaces the underlying ArrayList<String> for the given key.
    
    Parameters:
    
    key - The key to use
    
    array - The new ArrayList<String> object
    
    Returns:
    
    This object, as a convenience
  - setPolicyAppendDuplicates
```
public Prefs setPolicyAppendDuplicates(boolean policy)
```
    Specifies the policy on whether all values stored by any method whose name begins with the word "append" are unique. This is disabled by default, which means that duplicate values will be eliminated on-the-fly whenever a method beginning with the word "append" is called.
    
    Parameters:
    
    policy - TRUE = Allow duplicates; FALSE = Eliminate duplicates (default)
    
    Returns:
    
    This object, as a convenience
    
    See Also:
    
    append(java.lang.String, java.lang.String...), appendMax(java.lang.String, java.lang.String...), getPolicyAppendDuplicates()
  - setPolicyAppendMax
```
public Prefs setPolicyAppendMax(int policy)
```
    Specifies the policy for the maximum elements default used by any method whose name begins with the word "appendMax" (the default is 42).
    In the spirit of user-friendly design, I suggest using a higher maximum number rather than a lower maximum, such as 42 instead of 10.
    
    Parameters:
    
    policy - Number of elements (default is 42)
    
    Returns:
    
    This object, as a convenience
    
    See Also:
    
    appendMax(java.lang.String, java.lang.String...), getPolicyAppendMax()
  - setPolicyEqualSign
```
public Prefs setPolicyEqualSign(boolean policy)
```
    Specifies the policy about whether one equal sign is a delimiter between keys and values (whitespace characters present in the delimiter set will still be consumed and discarded as expected).
    This policy option is useful for reading configuration files that use equal signs as delimiters in their configuration files.
    Note: This policy consistently effects all load() and save() methods.
    
    Parameters:
    
    policy - FALSE = Treat equal signs like other non-whitespace characters (default); TRUE = Require one equal sign as a special delimiter character
    
    Returns:
    
    This object, as a convenience
    
    See Also:
    
    getPolicyEqualSign()
  - setPolicyKeepEmptyFile
```
public Prefs setPolicyKeepEmptyFile(boolean policy)
```
    Indicates the policy about whether to keep an empty configuration file (which is 0 bytes) or to delete it (default).
    This policy option is useful for controlling whether empty configuration files are deleted.
    Note: This policy consistently effects all save() methods.
    
    Returns:
    
    boolean FALSE = Don't keep empty configuration file (delete it); TRUE = Keep empty configuration file (don't delete it)
    
    See Also:
    
    getPolicyKeepEmptyFile()
  - setReadOnly
```
public Prefs setReadOnly()
```
    Indicates that the configuration data cannot be saved. Setting this flag is an irreversible operation (i.e., once this flag has been set to TRUE, it can never be reverted back to FALSE).
    
    Returns:
    
    This object, as a convenience
    
    See Also:
    
    isReadOnly()

Class Prefs

Field Summary

Constructor Summary

Method Summary

Methods inherited from class Object

Field Detail

DESCRIPTION

FILENAME

VERSION

Constructor Detail

Prefs

Prefs

Prefs

Prefs

Prefs

Prefs

Method Detail

append

appendMax

appendMax

get

get

get

get

getArrayList

getIOError

getLast

getLinkedHashMap

getPolicyAppendDuplicates

getPolicyAppendMax

getPolicyEqualSign

getPolicyKeepEmptyFile

glean

glean

isLoaded

isReadOnly

isSaved

load

loadPassive

remove

save

saveAs

saveAs

saveAs

savePassive

set

set

setArrayList

setPolicyAppendDuplicates

setPolicyAppendMax

setPolicyEqualSign

setPolicyKeepEmptyFile

setReadOnly