com.sun.dtv.platform
Class User

java.lang.Object
  com.sun.dtv.platform.User

public final class User
extends Object

The User class contains several useful class fields and methods that are specific to the consumer of the platform. It cannot be instantiated.

Among the facilities provided by the User class are access and manipulation of user properties. User properties are defined to be a set of properties that are specific at runtime to a given user for a given platform, application or third party library.

The user properties sub-system described here differs to the system properties defined in System.getProperties()! The main difference between the two property management sub-systems is that one is for system properties and is unique to the platform whereas the second is bound to a given user. A platform may support multiple users, e.g. identified by a token card and for which the platform must load (e.g. from the token card) the corresponding profile and user properties.

These properties are persistently stored and may be read at any time by any application provided the corresponding read permission is granted. These properties may be changed at any time by any application provided the corresponding write permission is granted for that specific permission.

The permission framework is managed by SecurityManager through UserPropertyPermission which allows to configure permissions at application granularity: any given application can be granted different read and write actions for each of the property available. Defining a permission for a property that is not (yet) stored and handled by the platform has no consequences.

Properties

The following properties must be supported by and be always present on the platform:

property	description	default right
com.sun.dtv.user.name	The name of the user composed by his first and last name. The order is only defined by being culturally appropriated.	"read"
com.sun.dtv.user.languages	a semi-colon separated list of 3 letter ISO-639 language codes.	"read"
com.sun.dtv.user.email	The user's email address as defined by RFC821.	"read"
com.sun.dtv.user.address	The user's postal address. It may contain multiple lines separated by carriage returns (CR, 13d, 0x0D).	"read"
com.sun.dtv.location.country	The country code of the location of the TV box. The format is a two letter country code as specified in ISO-3166-1.	"read"
com.sun.dtv.rating.parental	A string using the same encoding as returned by ContentRatingAdvisory.getDisplayText().	"read"
com.sun.dtv.ui.font.size	A string which value represents in points the preferred font size.	"read"

This property tree may be extended by applications and third party libraries. The limit on the number of properties is platform specific. New properties must follow the same convention for their name as for creating new java package name that is: taking the Internet domain name of your organization, such as example.com. Then reverse this name, component by component, appending a prefix for your tree or package name: com.example.voting. Conventions used beyond the reversed domain name is left to the discretion of any given company.

The creation of a new property is allowed provided the corresponding write permission has been granted for the corresponding property name. Consequently the application may read this property out only if it is given the read access permission. Consequently any property added is not accessible per default.

The domain name com.sun.dtv is reserved for properties defined in this specification.

Properties, examples and default value

Property	example	default value
com.sun.dtv.user.name	"Jean-Yves Mustermann"	""
com.sun.dtv.user.languages	"deu;fre;eng"	""
com.sun.dtv.user.email	"jy.muster@example.net"	""
com.sun.dtv.user.address	"Heidestr. 17 81500 Munich Germany"	""
com.sun.dtv.location.country	"de"	""
com.sun.dtv.rating.parental	"PG16	""
com.sun.dtv.ui.font.size	"18"	"26"

The default values defined in the table above are to be provided within every Properties object returned by this class.

Property Naming and Filtering

A name is the name of the property ("com.sun.dtv.user.name", "com.sun.dtv.ui.font.size", etc). The naming convention follows the hierarchical property naming convention.

In case of a filter, an asterisk may appear at the end of the name, following a ".", or by itself, to signify a wildcard match. For example: "com.sun.dtv.*" or "*" are valid. On the other hand, "*user" or "a*b" are not valid.

A filter may also be a semi-colon separated list of filters as described previously. For example "com.sun.dtv.user.*;com.sun.dtv.ui.*" is also a valid filter expression. The filter "com.sun.dtv.user.*;;" is also valid and is equivalent to "com.sun.dtv.user.*".

Code Sample

A typical code sample would be:

 import com.sun.dtv.platform.User;
 
 // Will be stored persistently immediately, assuming the application
 // has 'write' access on that property.
 User.setProperty("com.sun.dtv.user.name", "myself");
 

... or for batch editing:

 import com.sun.dtv.platform.User;
 import java.util.Properties;

 Properties props = User.getProperties("com.sun.dtv.user.*");
 props.setProperty("com.sun.dtv.user.name",  "myself");
 props.setProperty("com.sun.dtv.user.email", "myself@example.net");
 //...
 
 // Now will be stored persistently
 User.setProperties(props);  
 

See Also:

Properties, SecurityManager

Field Summary

static String	PROPKEY_LOCATION_COUNTRY Default property name for location country code.
static String	PROPKEY_RATING_PARENTAL Default property name for parental rating.
static String	PROPKEY_UI_FONT_SIZE Default property name for UI font size.
static String	PROPKEY_USER_ADDRESS Default property name for user address.
static String	PROPKEY_USER_EMAIL Default property name for user email.
static String	PROPKEY_USER_LANGUAGES Default property name for user languages.
static String	PROPKEY_USER_NAME Default property name for user name.

Method Summary

static void	addListener(UserPropertyListener listener, String filter) Attaches a listener that is triggered for changes to any properties within the range defined by filter.
static Properties	getProperties(String filter) Retrieves a copy of all user properties that matches filter and for which the application has read access right.
static String	getProperty(String key) Gets the user property indicated by the specified key.
static String	getProperty(String key, String def) Gets the user property indicated by the specified key.
static void	removeListener(UserPropertyListener listener) Detaches a user property listener that was previously attached using addListener().
static void	removeProperties(String filter) Removes this property and all of its descendants, invalidating any properties contained in the removed nodes.
static void	setProperties(Properties properties) Adds new properties and/or replaces existing properties.
static String	setProperty(String key, String value) Sets the user property indicated by the specified key.

Methods inherited from class java.lang.Object

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

Field Detail

PROPKEY_USER_NAME

public static String PROPKEY_USER_NAME

Default property name for user name.

PROPKEY_USER_LANGUAGES

public static String PROPKEY_USER_LANGUAGES

Default property name for user languages.

PROPKEY_USER_EMAIL

public static String PROPKEY_USER_EMAIL

Default property name for user email.

PROPKEY_USER_ADDRESS

public static String PROPKEY_USER_ADDRESS

Default property name for user address.

PROPKEY_LOCATION_COUNTRY

public static String PROPKEY_LOCATION_COUNTRY

Default property name for location country code.

PROPKEY_RATING_PARENTAL

public static String PROPKEY_RATING_PARENTAL

Default property name for parental rating.

PROPKEY_UI_FONT_SIZE

public static String PROPKEY_UI_FONT_SIZE

Default property name for UI font size.

Method Detail

addListener

public static void addListener(UserPropertyListener listener,
                               String filter)
                        throws NullPointerException,
                               IllegalArgumentException

Attaches a listener that is triggered for changes to any properties within the range defined by filter. Attaching the same listener to different filter is allowed and does not throw any exception. Attaching the same or more listeners to ranges that overlaps is allowed and changes will trigger the corresponding listener(s) as many times as there are associations.

Parameters:

listener - The UserPropertyListener to be attached.

filter - The filter to associate the user property listener to.

Throws:

NullPointerException - If any of the arguments is null.

IllegalArgumentException - If filter does not follow the convention defined in the class description above. null.

See Also:

removeListener(com.sun.dtv.platform.UserPropertyListener)

removeListener

public static void removeListener(UserPropertyListener listener)
                           throws NullPointerException

Detaches a user property listener that was previously attached using addListener(). If listener is null or if listener was not attached previously, no exception is thrown and no action is performed. If the listener was attached to several property ranges, all associations must be cleared and all instances of that listener removed.

Parameters:

listener - The UserPropertyListener to be detached. It may be null.

Throws:

NullPointerException - If listener is null.

See Also:

addListener(com.sun.dtv.platform.UserPropertyListener, java.lang.String)

getProperties

public static Properties getProperties(String filter)
                                throws SecurityException,
                                       IllegalArgumentException,
                                       NullPointerException

Retrieves a copy of all user properties that matches filter and for which the application has read access right. If there is no match, an empty Properties object is returned.

The returned object must contain in its defaults attribute, a copy of the list of all mandatory properties with their default values (see Properties.defaults). However any modifications done by the application to this collection of values and default values must be ignored by the implementation i.e. will not overwrite the default platform properties. The application must call the getProperties(java.lang.String) method to change and store properties.

Note: The implementation is not required to validate the keys and the values available in the platform's user properties. Applications should read the values returned with care.

Parameters:

filter - The filter to apply on all user properties.

Returns:

All user properties that matches filter encapsulated in a Properties object.

Throws:

SecurityException - If the application has no read permission for any of the properties that are about to be read.

IllegalArgumentException - If filter does not follow the convention defined in the class description above.

NullPointerException - if filter is null.

See Also:

Properties, setProperties(java.util.Properties)

getProperty

public static String getProperty(String key,
                                 String def)
                          throws SecurityException,
                                 IllegalArgumentException,
                                 NullPointerException

Gets the user property indicated by the specified key.

Parameters:

key - The name of the user property.

def - A default value.

Returns:

The string value of the user property, or the default value if there is no user property with that key.

Throws:

SecurityException - If the application has no read permission for the property that is about to be read.

IllegalArgumentException - If key is empty.

NullPointerException - If key is null.

See Also:

setProperty(java.lang.String, java.lang.String)

getProperty

public static String getProperty(String key)
                          throws SecurityException,
                                 IllegalArgumentException,
                                 NullPointerException

Gets the user property indicated by the specified key.

Parameters:

key - The name of the user property.

Returns:

The string value of the user property, or null if there is no user property with that key.

Throws:

SecurityException - If the application has no read permission for the property that is about to be read.

IllegalArgumentException - If key is empty.

NullPointerException - If key is null.

See Also:

setProperty(java.lang.String, java.lang.String)

setProperties

public static void setProperties(Properties properties)
                          throws NullPointerException,
                                 SecurityException

Adds new properties and/or replaces existing properties. Depending on whether the properties contained in properties already exists or not, the implementation must respectively replace or add the corresponding property. The implementation must store persistently the updated user properties synchronously to this method.

The implementation will trigger synchronously to this method call a UserPropertyListener.propertyChanged() for every property that has just been added or replaced by this action. However if the replacement does not change the value (i.e. the previous value and the new value of the given property are equal), no propertyChanged() is called.

The values within the Properties.defaults attributes of the properties argument must be ignored by the implementation.

Note: The implementation is not required to validate the keys and the values passed in properties. Applications should carefully validate these strings.

Parameters:

properties - A Properties object that lists all properties that either will be changed or, if not yet existing, added to the user properties.

Throws:

SecurityException - If the application has no write permission for any of the properties that are about to be added or replaced. This permission check must be done before any addition or replacement of existing properties.

NullPointerException - If properties is null.

See Also:

Properties, PropertyPermission, getProperties(java.lang.String)

setProperty

public static String setProperty(String key,
                                 String value)
                          throws SecurityException,
                                 NullPointerException,
                                 IllegalArgumentException

Sets the user property indicated by the specified key. The implementation must store persistently the updated user properties synchronously to this method.

As for setProperties, the implementation will trigger synchronously to this call, a UserPropertyListener.propertyChanged() for the property that has just been added or changed by this action. However if the replacement does not change the value (i.e. the previous value and the new value of the given property are equal), no propertyChanged() is called.

Parameters:

key - The name of the user property.

value - The value of the user property.

Returns:

The previous value of the user property, or null if it did not have one.

Throws:

SecurityException - If the application has no write permission for that property that is about to be added or replaced. This permission check must be done before addition or replacement.

NullPointerException - If key or value is null.

IllegalArgumentException - If key is empty.

See Also:

getProperty(java.lang.String, java.lang.String)

removeProperties

public static void removeProperties(String filter)
                             throws SecurityException,
                                    IllegalArgumentException,
                                    NullPointerException

Removes this property and all of its descendants, invalidating any properties contained in the removed nodes.

The implementation will trigger synchronously to this method call a UserPropertyListener.propertyRemoved() for every property that has just been removed by this action. This method returns when all targeted properties (nodes and descendants) have been removed persistently.

Parameters:

filter - The filter of the properties that are to be removed.

Throws:

SecurityException - If the application has no write permission for any given property that is about to be removed. This permission check must be done before removing any properties matching the filter.

IllegalArgumentException - If filter does not follow the convention defined in the class description above.

NullPointerException - If filter is null.