Preference (ocap 1.2 API)

java.lang.Object
- org.dvb.user.Preference

Direct Known Subclasses:

GeneralPreference
```
public abstract class Preference
extends 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

Constructors
Modifier	Constructor and Description
`protected`	`Preference()` This protected constructor is only present to enable sub-classes of this one to be defined by the platform.
	`Preference(String name, String value)` Creates a new preference with the specified name and the specified value.
	`Preference(String name, String[] value)` Creates a new preference with the specified name and the specified value set.

Method Summary

Methods
Modifier and Type	Method and Description
`void`	`add(int position, String value)` Adds a new value for this preference.
`void`	`add(String value)` Adds a new value for this preference.
`void`	`add(String[] values)` Adds several new values for this preferences.
`String[]`	`getFavourites()` Returns the list of favourite values for this preference.
`String`	`getMostFavourite()` Returns the most favourite value for this preference, that is, the first element of the list.
`String`	`getName()` Returns the name of the preference.
`int`	`getPosition(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(String value)` Removes the specified value from the list of favourites.
`void`	`removeAll()` Removes all the values of a preference
`void`	`setMostFavourite(String value)` Sets the most favourite value for this preference.
`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(String name,
          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(String name,
          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(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(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,
       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 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.
    value - a String representing the new value to insert.
  - getFavourites
```
public 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 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 String getName()
```
    Returns the name of the preference.
    
    Returns:
    a String object representing the name of the preference.
  - getPosition
```
public int getPosition(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(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(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 String toString()
```
    Convert name and favourites to a String.
    
    Overrides:
    
    toString in class Object
    
    Returns:
    the preference name and favourites

Class Preference

Constructor Summary

Method Summary

Methods inherited from class java.lang.Object

Constructor Detail

Preference

Preference

Preference

Method Detail

add

add

add

getFavourites

getMostFavourite

getName

getPosition

hasValue

remove

removeAll

setMostFavourite

toString