org.dvb.user
Class Preference

java.lang.Object
  extended by org.dvb.user.Preference
Direct Known Subclasses:
GeneralPreference

public abstract class Preference
extends java.lang.Object

This abstract class defines the Preference object. A Preference maps a name to a list of favourite values. The first element in the list is the favourite value for this preference.

The preference names are treated as case-insensitive. The preference names shall be considered equal at least when the method java.lang.String.equalsIgnoreCase() returns true for the strings when the locale "EN.UK" is used. Depending on the locale used in the implementation, implementations are allowed to consider equal also other upper and lower case character pairs in addition to those defined by the "EN.UK" locale.

The standardized preference names in the present document shall only use such letters where the upper and lower case characters are recognized by the "EN.UK" locale.


Constructor Summary
protected Preference()
          This protected constructor is only present to enable sub-classes of this one to be defined by the platform.
  Preference(java.lang.String name, java.lang.String value)
          Creates a new preference with the specified name and the specified value.
  Preference(java.lang.String name, java.lang.String[] value)
          Creates a new preference with the specified name and the specified value set.
 
Method Summary
 void add(int position, java.lang.String value)
          Adds a new value for this preference.
 void add(java.lang.String value)
          Adds a new value for this preference.
 void add(java.lang.String[] values)
          Adds several new values for this preferences.
 java.lang.String[] getFavourites()
          Returns the list of favourite values for this preference.
 java.lang.String getMostFavourite()
          Returns the most favourite value for this preference, that is, the first element of the list.
 java.lang.String getName()
          Returns the name of the preference.
 int getPosition(java.lang.String value)
          Returns the position in the list of the specified value.
 boolean hasValue()
          Tests if this preference has at least one value set.
 void remove(java.lang.String value)
          Removes the specified value from the list of favourites.
 void removeAll()
          Removes all the values of a preference
 void setMostFavourite(java.lang.String value)
          Sets the most favourite value for this preference.
 java.lang.String toString()
          Convert name and favourites to a String.
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait
 

Constructor Detail

Preference

protected Preference()
This protected constructor is only present to enable sub-classes of this one to be defined by the platform. It is not intended to be used by inter-operable applications.


Preference

public Preference(java.lang.String name,
                  java.lang.String value)
Creates a new preference with the specified name and the specified value. This single value will be the favourite one for this preference.

Parameters:
name - a String object representing the name of the preference.
value - a String object representing the value of the preference.

Preference

public Preference(java.lang.String name,
                  java.lang.String[] value)
Creates a new preference with the specified name and the specified value set. Each value in the value set must appear only once. The behaviour if a value is duplicated is implementation dependent.

Parameters:
name - a String object representing the name of the preference.
value - an array of String objects representing the set of values for this preference ordered from the most favourite to the least favourite.
Method Detail

add

public void add(java.lang.String value)
Adds a new value for this preference. The value is added to the end of the list. If the value is already in the list then it is moved to the end of the list.

Parameters:
value - a String object representing the new value.

add

public void add(java.lang.String[] values)
Adds several new values for this preferences. The values are added to the end of the list in the same order as they are found in the array passed to this method. Any values already in the list are moved to the position in the list which they would have if they were not already present.

Parameters:
values - an array of strings representing the values to add
Since:
MHP 1.0.1

add

public void add(int position,
                java.lang.String value)
Adds a new value for this preference. The value is inserted at the specified position. If the value is already in the list then it is moved to the position specified. If the position is greater than or equal to the length of the list, then the value is added to the end of this list. If the position is negative, then the value is added to the beginning of this list.

Parameters:
position - an int representing the position in the list counting from zero.
value - a String representing the new value to insert.

getFavourites

public java.lang.String[] getFavourites()
Returns the list of favourite values for this preference. Returns an empty array if no value sets are defined for this preference.

Returns:
an array of String representing the favourite values for this preference.

getMostFavourite

public java.lang.String getMostFavourite()
Returns the most favourite value for this preference, that is, the first element of the list.

Returns:
a String representing the most favourite value for this preference. Returns null if no value is defined for this preference

getName

public java.lang.String getName()
Returns the name of the preference.

Returns:
a String object representing the name of the preference.

getPosition

public int getPosition(java.lang.String value)
Returns the position in the list of the specified value.

Parameters:
value - a String representing the value to look for.
Returns:
an integer representing the position of the value in the list counting from zero. If the value is not found then it returns -1.

hasValue

public boolean hasValue()
Tests if this preference has at least one value set.

Returns:
true if this preference has at least one value set, false otherwise.

remove

public void remove(java.lang.String value)
Removes the specified value from the list of favourites. If the value is not in the list then the method call has no effect.

Parameters:
value - a String representing the value to remove.

removeAll

public void removeAll()
Removes all the values of a preference

Since:
MHP 1.0.1

setMostFavourite

public void setMostFavourite(java.lang.String value)
Sets the most favourite value for this preference. If the value is already in the list, then it is moved to the head. If the value is not already in the list then it is added at the head.

Parameters:
value - the most favourite value

toString

public java.lang.String toString()
Convert name and favourites to a String.

Overrides:
toString in class java.lang.Object
Returns:
the preference name and favourites