org.dvb.user

Class UserPreferenceManager

java.lang.Object

org.dvb.user.UserPreferenceManager

public class UserPreferenceManager
extends Object

The UserPreferenceManager class gives access to the user preference settings. This class provides a set of methods that allow an application to read or save user settings. It also provides a mechanism to notify applications when a preference has been modified. The value of a user setting, retrieved with the read method, is a copy of the value that is stored in the receiver. The write method, if authorized, overwrites the stored value.

NOTE: MHP implementations are not required to validate the values in Preference objects, even those which are saved using the write method. Applications with write permissions need to be very careful that the values written are valid. Applications reading permissions need to be aware of the possibility that a previous application has set an invalid value.

Method Summary

Methods

Modifier and Type	Method and Description
void	addUserPreferenceChangeListener(UserPreferenceChangeListener l) Adds a listener for changes in user preferences as held in the MHP terminal.
static UserPreferenceManager	getInstance() Return an instance of the UserPreferenceManager for this application.
void	read(Preference p) Allows an application to read a specified user preference.
void	read(Preference p, Facility facility) Allows an application to read a specified user preference taking into account the facility defined by the application.
void	removeUserPreferenceChangeListener(UserPreferenceChangeListener l) Removes a listener for changes in user preferences.
void	write(Preference p) Saves the specified user preference.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Method Detail

getInstance

public static UserPreferenceManager getInstance()

Return an instance of the UserPreferenceManager for this application. Repeated calls to this method by the same application shall return the same instance.

Returns:

an instance of UserPreferenceManager

read

public void read(Preference p)

Allows an application to read a specified user preference. When end-user preferences are read into a Preference object from the MHP terminal, the ordering of these values shall be as determined by the end-user, from most preferred to least preferred to the extent that this is known.

Parameters:

p - an object representing the preference to read.

Throws:

SecurityException - if the calling application is denied access to this preference

read

public void read(Preference p,
        Facility facility)

Allows an application to read a specified user preference taking into account the facility defined by the application. After this method returns, the values in the Preference object shall be the values of that user preference with any unsupported values from the Facility removed from that list. Note that the order of values returned here need not be the same as that returned by read(Preference).

If the intersection between the two sets of values is empty then the preference will have no value. If there is a mis-match between the name of the preference used when constructing the facility and the name of the preference used in this method then the preference will have no value.

Parameters:

p - an object representing the preference to read.

facility - the preferred values of the application for the preference

Throws:

SecurityException - if the calling application is denied access to this preference

write

public void write(Preference p)
           throws UnsupportedPreferenceException,
                  IOException

Saves the specified user preference. If this method succeeds then it will change the value of this preference for all future MHP applications.

Parameters:

p - the preference to save.

Throws:

UnsupportedPreferenceException - if the preference provided is not a standardized preference as defined for use with GeneralPreference.

SecurityException - if the application does not have permission to call this method

IOException - if saving the preference fails for other I/O reasons

addUserPreferenceChangeListener

public void addUserPreferenceChangeListener(UserPreferenceChangeListener l)

Adds a listener for changes in user preferences as held in the MHP terminal. Specifically this includes changes made by MHP applications succeeding in calling the write() method on this class. If the implementation of the MHP terminal allows the end user to change preferences then these changes also includes changes made to preferences by this mechanism. It does not include changes made to a Preference instance within the scope of a single MHP application. *

Parameters:

l - the listener to add.

removeUserPreferenceChangeListener

public void removeUserPreferenceChangeListener(UserPreferenceChangeListener l)

Removes a listener for changes in user preferences.

Parameters:

l - the listener to remove.