com.leafdigital.prefs.api
Interface PreferencesGroup


public interface PreferencesGroup

Represents a group of preferences.

Each group has its own set of named preferences. You can create child groups that are named, or 'anonymous' numbered child groups (0, 1, ...) in an array that can be rearranged. When you use anonymous groups, you can request preferences in a hierarchical manner.


Field Summary
static int ANON_LAST
          Constant referring to last entry in index
 
Method Summary
 PreferencesGroup addAnon()
          Creates a new anonymous child group.
 int addAnon(PreferencesGroup pg, int position)
          Adds a group from somewhere else into this anonymous array.
 void clearAnon()
          Removes all anon children at once (to save you calling remove() on each one)
 boolean exists(java.lang.String name)
          Check whether a program preference has been set.
 PreferencesGroup findAnonGroup(java.lang.String pref, java.lang.String value, boolean recursive)
          Looks for a preferences group in all anonymous children (and their anonymous children, optionally) that contains the given preference.
 PreferencesGroup findAnonGroup(java.lang.String pref, java.lang.String value, boolean recursive, boolean ignoreCase)
          Looks for a preferences group in all anonymous children (and their anonymous children, optionally) that contains the given preference.
 java.lang.String get(java.lang.String name)
          Return value of a named preference within group.
 java.lang.String get(java.lang.String name, java.lang.String defaultValue)
          Return value of a named preference within group.
 PreferencesGroup[] getAnon()
           
 java.lang.String getAnonHierarchical(java.lang.String name)
          Return value of a named preference within group or parent anonymous groups, up to the first non-anonymous ancestor.
 java.lang.String getAnonHierarchical(java.lang.String name, java.lang.String defaultValue)
          Return value of a named preference within group or parent anonymous groups.
 java.lang.String getAnonHierarchical(java.lang.String name, java.lang.String defaultValue, boolean includeThis)
          Return value of a named preference within parent anonymous groups or, optionally, this group.
 PreferencesGroup getAnonParent()
           
 PreferencesGroup getChild(java.lang.String name)
          Returns a nested preference group.
 Preferences getPreferences()
           
 void remove()
          Removes this group from its parent.
 java.lang.String set(java.lang.String name, java.lang.String value)
          Sets value of a named program preference.
 void set(java.lang.String name, java.lang.String value, java.lang.String defaultValue)
          Sets value of a named program preference.
 boolean unset(java.lang.String name)
          Unsets an existing preference (exists() will return false after this).
 

Field Detail

ANON_LAST

static final int ANON_LAST
Constant referring to last entry in index

See Also:
Constant Field Values
Method Detail

getPreferences

Preferences getPreferences()
Returns:
Main preferences object

exists

boolean exists(java.lang.String name)
Check whether a program preference has been set.

Parameters:
name - Name of preference
Returns:
True if it exists

get

java.lang.String get(java.lang.String name)
Return value of a named preference within group.

Parameters:
name - Name of preference
Returns:
Value of preference as string
Throws:
BugException - If the preference doesn't exist

get

java.lang.String get(java.lang.String name,
                     java.lang.String defaultValue)
Return value of a named preference within group.

Parameters:
name - Name of preference
defaultValue - Value to use for preference if it isn't found
Returns:
Value of preference as string

getAnonHierarchical

java.lang.String getAnonHierarchical(java.lang.String name)
Return value of a named preference within group or parent anonymous groups, up to the first non-anonymous ancestor. For instance, if this group is /frog/server/1/3, then this will search for the preference in this group, in /frog/server/1, and in /frog/server.

Parameters:
name - Name of preference
Returns:
Value of preference as string
Throws:
BugException - If the preference doesn't exist

getAnonHierarchical

java.lang.String getAnonHierarchical(java.lang.String name,
                                     java.lang.String defaultValue)
Return value of a named preference within group or parent anonymous groups. (See getAnonHierarchical(String) for description of procedure.

Parameters:
name - Name of preference
defaultValue - Value to use for preference if it isn't found
Returns:
Value of preference as string

getAnonHierarchical

java.lang.String getAnonHierarchical(java.lang.String name,
                                     java.lang.String defaultValue,
                                     boolean includeThis)
Return value of a named preference within parent anonymous groups or, optionally, this group. (See getAnonHierarchical(String) for description of procedure.

Parameters:
name - Name of preference
defaultValue - Value to use for preference if it isn't found
includeThis - If true, includes this group; otherwise ignores any setting within this group
Returns:
Value of preference as string

findAnonGroup

PreferencesGroup findAnonGroup(java.lang.String pref,
                               java.lang.String value,
                               boolean recursive)
Looks for a preferences group in all anonymous children (and their anonymous children, optionally) that contains the given preference. Case-sensitive.

Parameters:
pref - Name of pref
value - Value of pref
recursive - If true, follows into anonymous children of subgroups
Returns:
Group that contains this pref, or null if none

findAnonGroup

PreferencesGroup findAnonGroup(java.lang.String pref,
                               java.lang.String value,
                               boolean recursive,
                               boolean ignoreCase)
Looks for a preferences group in all anonymous children (and their anonymous children, optionally) that contains the given preference.

Parameters:
pref - Name of pref
value - Value of pref
recursive - If true, follows into anonymous children of subgroups
ignoreCase - If true, ignores case of 'value' parameter
Returns:
Group that contains this pref, or null if none

set

java.lang.String set(java.lang.String name,
                     java.lang.String value)
Sets value of a named program preference.

Parameters:
name - Name of preference (be sure to follow restrictions)
value - String value of preference
Returns:
Previous value, null if none
Throws:
BugException - If name or owner didn't follow restrictions

set

void set(java.lang.String name,
         java.lang.String value,
         java.lang.String defaultValue)
Sets value of a named program preference. If the value is equal to the default, actually unsets it.

Parameters:
name - Name of preference (be sure to follow restrictions)
value - String value of preference
defaultValue - Default value of preference
Throws:
BugException - If name or owner didn't follow restrictions

unset

boolean unset(java.lang.String name)
Unsets an existing preference (exists() will return false after this).

Parameters:
name - Name of preference
Returns:
True if preference previously existed and was unset, false if it didn't exist anyhow

getAnonParent

PreferencesGroup getAnonParent()
Returns:
Parent of anonymous group; null if this isn't an anonymous group.

getChild

PreferencesGroup getChild(java.lang.String name)
Returns a nested preference group. Creates the group if it doesn't already exist.

Parameters:
name - Name of preference group
Returns:
Group that can be used to check preferences within that name
Throws:
BugException - If name isn't valid

remove

void remove()
Removes this group from its parent. If this is an anonymous group, other entries in the group will be shuffled along. If the group doesn't have a parent, nothing will happen.


getAnon

PreferencesGroup[] getAnon()
Returns:
Array of anonymous child groups (may be zero-length)

addAnon

PreferencesGroup addAnon()
Creates a new anonymous child group.

Returns:
New group (will be last in the array)

addAnon

int addAnon(PreferencesGroup pg,
            int position)
Adds a group from somewhere else into this anonymous array. If the group has another parent, it will automatically be removed from there.

Parameters:
pg - Group to add
position - Index for new group (others will be shuffled along) or ANON_LAST for end of group
Returns:
Index of new group

clearAnon

void clearAnon()
Removes all anon children at once (to save you calling remove() on each one)



Copyright © 2011 Samuel Marshall. All rights reserved.