blackboard.platform.session
Interface UserDataService

public interface UserDataService

A service for storing user-specific data (e.g. tool preferences) either temporarily (for the duration of the user's session) or permanently (cross-session)

The data stored by this service is always represented by a String. The methods that operate on other types all convert to/from the backing String.

All of the "get" methods require that a default value be passed. This value is used in two cases:

1. When a value with the specified key does not exist in specified scope (or any scope if the scopeless "get" methods are called )
2. The value with the specified key cannot be converted into the specified data type ( whenever the non-string get methods are called )

Passing false as the "required" parameter in the setter methods will (for the PERMANENT scope) set the value as being disposable. This value will not be guaranteed to be persistent forever as it may be removed by the system administrator. The required attribute has no effect on the TEMPORARY scope.

Care should be taken when using operations that access the PERMANENT scope so that unnecessary database calls are not made. The permanent scope is write-on-set, so a database call will be made each time a "set" method is called for the permanent scope. On the first "get" call on the permanent scope, all of the permanent data for the current user will be loaded and cached int the context for the duration of the request.

If a given scope is not supported, for example for temporary scope if the HttpSession can't be resolved, a ScopeNotSupportedException exception will be thrown by any method called on that scope.

Since:

Bb 7.3

Version:

$Revision: #1 $ $Date: 2007/06/27 $

Nested Class Summary

static class

UserDataService.Scope The options for scopes to store the data in.

Field Summary

static java.lang.String

PERMANENT_SCOPE_CACHE

Method Summary

boolean	getBoolean(java.lang.String key, UserDataService.Scope scope, boolean def) Retrieves the boolean associated with the specified key in the specified scope.
byte[]	getByteArray(java.lang.String key, UserDataService.Scope scope, byte[] def) Retrieves the byte array associated with the specified key in the specified scope.
double	getDouble(java.lang.String key, UserDataService.Scope scope, double def) Retrieves the double associated with the specified key in the specified scope.
float	getFloat(java.lang.String key, UserDataService.Scope scope, float def) Retrieves the float associated with the specified key in the specified scope.
int	getInt(java.lang.String key, UserDataService.Scope scope, int def) Retrieves the int associated with the specified key in the specified scope.
long	getLong(java.lang.String key, UserDataService.Scope scope, long def) Retrieves the long associated with the specified key in the specified scope.
java.lang.String	getString(java.lang.String key, UserDataService.Scope scope, java.lang.String def) Retrieves the String associated with the specified key in the specified scope.
void	removeValue(java.lang.String key, UserDataService.Scope scope) Removes the value associated with the specified key in the specified scope.
void	setBoolean(java.lang.String key, boolean value, UserDataService.Scope scope) Associates the specified boolean value with the specified key in the specified scope.
void	setBoolean(java.lang.String key, boolean value, UserDataService.Scope scope, boolean required) Associates the specified boolean value with the specified key in the specified scope.
void	setByteArray(java.lang.String key, byte[] value, UserDataService.Scope scope) Associates the specified byte array value with the specified key in the specified scope.
void	setByteArray(java.lang.String key, byte[] value, UserDataService.Scope scope, boolean required) Associates the specified byte array value with the specified key in the specified scope.
void	setDouble(java.lang.String key, double value, UserDataService.Scope scope) Associates the specified double value with the specified key in the specified scope.
void	setDouble(java.lang.String key, double value, UserDataService.Scope scope, boolean required) Associates the specified double value with the specified key in the specified scope.
void	setFloat(java.lang.String key, float value, UserDataService.Scope scope) Associates the specified float value with the specified key in the specified scope.
void	setFloat(java.lang.String key, float value, UserDataService.Scope scope, boolean required) Associates the specified float value with the specified key in the specified scope.
void	setInt(java.lang.String key, int value, UserDataService.Scope scope) Associates the specified int value with the specified key in the specified scope.
void	setInt(java.lang.String key, int value, UserDataService.Scope scope, boolean required) Associates the specified int value with the specified key in the specified scope.
void	setLong(java.lang.String key, long value, UserDataService.Scope scope) Associates the specified long value with the specified key in the specified scope.
void	setLong(java.lang.String key, long value, UserDataService.Scope scope, boolean required) Associates the specified long value with the specified key in the specified scope.
void	setString(java.lang.String key, java.lang.String value, UserDataService.Scope scope) Associates the specified String value with the specified key in the specified scope.
void	setString(java.lang.String key, java.lang.String value, UserDataService.Scope scope, boolean required) Associates the specified String value with the specified key in the specified scope.

Field Detail

PERMANENT_SCOPE_CACHE

static final java.lang.String PERMANENT_SCOPE_CACHE

See Also:

Constant Field Values

Method Detail

setBoolean

void setBoolean(java.lang.String key,
                boolean value,
                UserDataService.Scope scope)

Associates the specified boolean value with the specified key in the specified scope. Equivalent to calling setBoolean( key, value, scope, true )

Parameters:

key - key with which the value is to be associated.

value - value to be associated with the specified key.

scope - scope in which to store the association.

Throws:

ScopeNotSupportedException - if the specified scope is not available/supported.

setBoolean

void setBoolean(java.lang.String key,
                boolean value,
                UserDataService.Scope scope,
                boolean required)

Associates the specified boolean value with the specified key in the specified scope.

Parameters:

key - key with which the value is to be associated.

value - value to be associated with the specified key.

scope - scope in which to store the association.

required - whether or not the association may be removed to save space.

Throws:

ScopeNotSupportedException - if the specified scope is not available/supported.

setByteArray

void setByteArray(java.lang.String key,
                  byte[] value,
                  UserDataService.Scope scope)

Associates the specified byte array value with the specified key in the specified scope. Equivalent to calling setByteArray( key, value, scope, true )

Parameters:

key - key with which the value is to be associated.

value - value to be associated with the specified key.

scope - scope in which to store the association.

Throws:

ScopeNotSupportedException - if the specified scope is not available/supported.

setByteArray

void setByteArray(java.lang.String key,
                  byte[] value,
                  UserDataService.Scope scope,
                  boolean required)

Associates the specified byte array value with the specified key in the specified scope.

Parameters:

key - key with which the value is to be associated.

value - value to be associated with the specified key.

scope - scope in which to store the association.

required - whether or not the association may be removed to save space.

Throws:

ScopeNotSupportedException - if the specified scope is not available/supported.

setDouble

void setDouble(java.lang.String key,
               double value,
               UserDataService.Scope scope)

Associates the specified double value with the specified key in the specified scope. Equivalent to calling setDouble( key, value, scope, true )

Parameters:

key - key with which the value is to be associated.

value - value to be associated with the specified key.

scope - scope in which to store the association.

Throws:

ScopeNotSupportedException - if the specified scope is not available/supported.

setDouble

void setDouble(java.lang.String key,
               double value,
               UserDataService.Scope scope,
               boolean required)

Associates the specified double value with the specified key in the specified scope.

Parameters:

key - key with which the value is to be associated.

value - value to be associated with the specified key.

scope - scope in which to store the association.

required - whether or not the association may be removed to save space.

Throws:

ScopeNotSupportedException - if the specified scope is not available/supported.

setFloat

void setFloat(java.lang.String key,
              float value,
              UserDataService.Scope scope)

Associates the specified float value with the specified key in the specified scope. Equivalent to calling setFloat( key, value, scope, true )

Parameters:

key - key with which the value is to be associated.

value - value to be associated with the specified key.

scope - scope in which to store the association.

Throws:

ScopeNotSupportedException - if the specified scope is not available/supported.

setFloat

void setFloat(java.lang.String key,
              float value,
              UserDataService.Scope scope,
              boolean required)

Associates the specified float value with the specified key in the specified scope.

Parameters:

key - key with which the value is to be associated.

value - value to be associated with the specified key.

scope - scope in which to store the association.

required - whether or not the association may be removed to save space.

Throws:

ScopeNotSupportedException - if the specified scope is not available/supported.

setInt

void setInt(java.lang.String key,
            int value,
            UserDataService.Scope scope)

Associates the specified int value with the specified key in the specified scope. Equivalent to calling setInt( key, value, scope, true )

Parameters:

key - key with which the value is to be associated.

value - value to be associated with the specified key.

scope - scope in which to store the association.

Throws:

ScopeNotSupportedException - if the specified scope is not available/supported.

setInt

void setInt(java.lang.String key,
            int value,
            UserDataService.Scope scope,
            boolean required)

Associates the specified int value with the specified key in the specified scope.

Parameters:

key - key with which the value is to be associated.

value - value to be associated with the specified key.

scope - scope in which to store the association.

required - whether or not the association may be removed to save space.

Throws:

ScopeNotSupportedException - if the specified scope is not available/supported.

setLong

void setLong(java.lang.String key,
             long value,
             UserDataService.Scope scope)

Associates the specified long value with the specified key in the specified scope. Equivalent to calling setLong( key, value, scope, true )

Parameters:

key - key with which the value is to be associated.

value - value to be associated with the specified key.

scope - scope in which to store the association.

Throws:

ScopeNotSupportedException - if the specified scope is not available/supported.

setLong

void setLong(java.lang.String key,
             long value,
             UserDataService.Scope scope,
             boolean required)

Associates the specified long value with the specified key in the specified scope.

Parameters:

key - key with which the value is to be associated.

value - value to be associated with the specified key.

scope - scope in which to store the association.

required - whether or not the association may be removed to save space.

Throws:

ScopeNotSupportedException - if the specified scope is not available/supported.

setString

void setString(java.lang.String key,
               java.lang.String value,
               UserDataService.Scope scope)

Associates the specified String value with the specified key in the specified scope. Equivalent to calling setString( key, value, scope, true )

Parameters:

key - key with which the value is to be associated.

value - value to be associated with the specified key.

scope - scope in which to store the association.

Throws:

ScopeNotSupportedException - if the specified scope is not available/supported.

setString

void setString(java.lang.String key,
               java.lang.String value,
               UserDataService.Scope scope,
               boolean required)

Associates the specified String value with the specified key in the specified scope.

Parameters:

key - key with which the value is to be associated.

value - value to be associated with the specified key.

scope - scope in which to store the association.

required - whether or not the association may be removed to save space.

Throws:

ScopeNotSupportedException - if the specified scope is not available/supported.

getBoolean

boolean getBoolean(java.lang.String key,
                   UserDataService.Scope scope,
                   boolean def)

Retrieves the boolean associated with the specified key in the specified scope. Returns the specified default value if the key cannot be found in the specified scope, or if the value cannot be converted into a boolean.

Parameters:

key - key whose value is to be retrieved.

scope - the scope in which to look for the key.

def - value that will be returned if the specified key cannot be found or if the value cannot be converted into a boolean.

Returns:

the value associated with the key.

Throws:

ScopeNotSupportedException - if the specified scope is not available/supported.

getByteArray

byte[] getByteArray(java.lang.String key,
                    UserDataService.Scope scope,
                    byte[] def)

Retrieves the byte array associated with the specified key in the specified scope. Returns the specified default value if the key cannot be found in the specified scope, or if the value cannot be converted into a byte array.

Parameters:

key - key whose value is to be retrieved.

scope - the scope in which to look for the key.

def - value that will be returned if the specified key cannot be found or if the value cannot be converted into a byte array.

Returns:

the value associated with the key.

Throws:

ScopeNotSupportedException - if the specified scope is not available/supported.

getDouble

double getDouble(java.lang.String key,
                 UserDataService.Scope scope,
                 double def)

Retrieves the double associated with the specified key in the specified scope. Returns the specified default value if the key cannot be found in the specified scope, or if the value cannot be converted into a double.

Parameters:

key - key whose value is to be retrieved.

scope - the scope in which to look for the key.

def - value that will be returned if the specified key cannot be found or if the value cannot be converted into a double.

Returns:

the value associated with the key.

Throws:

ScopeNotSupportedException - if the specified scope is not available/supported.

getFloat

float getFloat(java.lang.String key,
               UserDataService.Scope scope,
               float def)

Retrieves the float associated with the specified key in the specified scope. Returns the specified default value if the key cannot be found in the specified scope, or if the value cannot be converted into a float.

Parameters:

key - key whose value is to be retrieved.

scope - the scope in which to look for the key.

def - value that will be returned if the specified key cannot be found or if the value cannot be converted into a float.

Returns:

the value associated with the key.

Throws:

ScopeNotSupportedException - if the specified scope is not available/supported.

getInt

int getInt(java.lang.String key,
           UserDataService.Scope scope,
           int def)

Retrieves the int associated with the specified key in the specified scope. Returns the specified default value if the key cannot be found in the specified scope, or if the value cannot be converted into a int.

Parameters:

key - key whose value is to be retrieved.

scope - the scope in which to look for the key.

def - value that will be returned if the specified key cannot be found or if the value cannot be converted into a int.

Returns:

the value associated with the key.

Throws:

ScopeNotSupportedException - if the specified scope is not available/supported.

getLong

long getLong(java.lang.String key,
             UserDataService.Scope scope,
             long def)

Retrieves the long associated with the specified key in the specified scope. Returns the specified default value if the key cannot be found in the specified scope, or if the value cannot be converted into a long.

Parameters:

key - key whose value is to be retrieved.

scope - the scope in which to look for the key.

def - value that will be returned if the specified key cannot be found or if the value cannot be converted into a boolean.

Returns:

the value associated with the key.

Throws:

ScopeNotSupportedException - if the specified scope is not available/supported.

getString

java.lang.String getString(java.lang.String key,
                           UserDataService.Scope scope,
                           java.lang.String def)

Retrieves the String associated with the specified key in the specified scope. Returns the specified default value if the key cannot be found in the specified scope.

Parameters:

key - key whose value is to be retrieved.

scope - the scope in which to look for the key.

def - value that will be returned if the specified key cannot be found.

Returns:

the value associated with the key.

Throws:

ScopeNotSupportedException - if the specified scope is not available/supported.

removeValue

void removeValue(java.lang.String key,
                 UserDataService.Scope scope)

Removes the value associated with the specified key in the specified scope.

Parameters:

key - key whose value is to be removed.

scope - the scope from which to remove the value.

Throws:

ScopeNotSupportedException - if the specified scope is not available/supported.