Class SoPreference

Reads user preferences at several levels, returning the preference value that is defined at the lowest level.

A user preference defined at level 5 is more specific than a preference read at level 2.

Inheritance

Object

SoPreference

Namespace: SuperOffice.Data

Assembly: SoDataBase.dll

Syntax

public static class SoPreference : Object

Remarks

Caching is done using the SoPrincipal-based cache mechanism. This is emptied on every roundtrip. That is intentional, to avoid stale data. In the interest of performance, we read complete sections, so if you ask for one preference we read-ahead all the preferences in that section and cache them for this roundtrip.

We assume that the in CurrentPrincipal will accept multiple Set calls on the same item, and that the latest value will be the one that survives.

Properties

CacheLifetime

Cache lifetime in seconds for user preferences; note that the cache used will expire when principal is recycled (roundtrip end if in typical Web context)

Declaration

public static double CacheLifetime { get; set; }

Property Value

Type	Description
Double	The cache lifetime in seconds (default 60).

Remarks

Caching is done using the SoPrincipal-based cache mechanism. This is emptied on every roundtrip. That is intentional, to avoid stale data. In the interest of performance, we read complete sections, so if you ask for one preference we read-ahead all the preferences in that section and cache them for this roundtrip.

We assume that the in CurrentPrincipal will accept multiple Set calls on the same item, and that the latest value will be the one that survives.

Methods

AsyncFullInit()

Reserved for internal use

Declaration

public static AsyncContext AsyncFullInit()

Returns

Type	Description
AsyncContext

Remarks

This method calls GetSections() to trigger a full initialization (read all sections and data), asynchronously. Use the WaitForOperationsToComplete(Int32, AsyncContext[]) to wait for it to complete at your convenience, and DO NOT call any other preference-related methods in the meantime.

GetBool(String, String, Boolean)

Get boolean value for a user preference, from the cache if possible. If not, read all keys and their values from the database, update the caches, and return the wanted value.

Declaration

public static bool GetBool(string section, string key, bool defaultValue)

Parameters

Type	Name	Description
String	section	Name of the section.
String	key	Name of the key.
Boolean	defaultValue	Default value

Returns

Type	Description
Boolean	User preference. If the user preference does not excist, the defualtValue is returned.

Remarks

Caching is done using the SoPrincipal-based cache mechanism. This is emptied on every roundtrip. That is intentional, to avoid stale data. In the interest of performance, we read complete sections, so if you ask for one preference we read-ahead all the preferences in that section and cache them for this roundtrip.

We assume that the in CurrentPrincipal will accept multiple Set calls on the same item, and that the latest value will be the one that survives.

GetDateTime(String, String)

Get DateTime value for a user preference, from the cache if possible. If not, read all keys and their values from the database, update the caches, and return the wanted value.

Declaration

public static DateTime GetDateTime(string section, string key)

Parameters

Type	Name	Description
String	section	Name of the section.
String	key	Name of the key.

Returns

Type	Description
DateTime	User preference. If the user preference does not excist, midnight January 1st, 1970 is returned.

Remarks

Caching is done using the SoPrincipal-based cache mechanism. This is emptied on every roundtrip. That is intentional, to avoid stale data. In the interest of performance, we read complete sections, so if you ask for one preference we read-ahead all the preferences in that section and cache them for this roundtrip.

We assume that the in CurrentPrincipal will accept multiple Set calls on the same item, and that the latest value will be the one that survives.

GetDateTime(String, String, DateTime)

Get DateTime value for a user preference, from the cache if possible. If not, read all keys and their values from the database, update the caches, and return the wanted value.

Declaration

public static DateTime GetDateTime(string section, string key, DateTime defaultValue)

Parameters

Type	Name	Description
String	section	Name of the section.
String	key	Name of the key.
DateTime	defaultValue	Default value

Returns

Type	Description
DateTime	User preference. If the user preference does not excist, the defualtValue is returned.

Remarks

Caching is done using the SoPrincipal-based cache mechanism. This is emptied on every roundtrip. That is intentional, to avoid stale data. In the interest of performance, we read complete sections, so if you ask for one preference we read-ahead all the preferences in that section and cache them for this roundtrip.

We assume that the in CurrentPrincipal will accept multiple Set calls on the same item, and that the latest value will be the one that survives.

GetInt(String, String, Int32)

Get integer value for a user preference, from the cache if possible. If not, read all keys and their values from the database, update the caches, and return the wanted value.

Declaration

public static int GetInt(string section, string key, int defaultValue)

Parameters

Type	Name	Description
String	section	Name of the section.
String	key	Name of the key.
Int32	defaultValue	Default value

Returns

Type	Description
Int32	User preference. If the user preference does not exist, the defualtValue is returned.

Remarks

Caching is done using the SoPrincipal-based cache mechanism. This is emptied on every roundtrip. That is intentional, to avoid stale data. In the interest of performance, we read complete sections, so if you ask for one preference we read-ahead all the preferences in that section and cache them for this roundtrip.

We assume that the in CurrentPrincipal will accept multiple Set calls on the same item, and that the latest value will be the one that survives.

GetKeys(String)

Get all available keys within a section from the cache if possible, otherwise from the database.

Declaration

public static string[] GetKeys(string section)

Parameters

Type	Name	Description
String	section	Name of the section.

Returns

Type	Description
String[]	Available keys in the section.

Remarks

An intended side effect is that the value cache for each key are set.

GetPreference(String, String, Int32, PreferenceLevel, Boolean)

Get a preference value directly from the database, specifying a full section/key/level/owner independent of the current user

Declaration

public static string GetPreference(string section, string key, int ownerId, PreferenceLevel level, bool skipPermissionCheck = false)

Parameters

Type	Name	Description
String	section	Preference section
String	key	Preference key
Int32	ownerId	The id to set for the ownerId field. This will point to different id type depending on the preference type
PreferenceLevel	level	The level to set for this preference
Boolean	skipPermissionCheck	Set this to true to skip the check for setting system wide preferences

Returns

Type	Description
String

Remarks

Caching is done using the SoPrincipal-based cache mechanism. This is emptied on every roundtrip. That is intentional, to avoid stale data. In the interest of performance, we read complete sections, so if you ask for one preference we read-ahead all the preferences in that section and cache them for this roundtrip.

We assume that the in CurrentPrincipal will accept multiple Set calls on the same item, and that the latest value will be the one that survives.

GetSectionAndKeyFromId(Int32)

Reads user preferences at several levels, returning the preference value that is defined at the lowest level.

A user preference defined at level 5 is more specific than a preference read at level 2.

Declaration

public static UserPreferenceCacheObject GetSectionAndKeyFromId(int primaryId)

Parameters

Type	Name	Description
Int32	primaryId

Returns

Type	Description
UserPreferenceCacheObject

Remarks

Caching is done using the SoPrincipal-based cache mechanism. This is emptied on every roundtrip. That is intentional, to avoid stale data. In the interest of performance, we read complete sections, so if you ask for one preference we read-ahead all the preferences in that section and cache them for this roundtrip.

We assume that the in CurrentPrincipal will accept multiple Set calls on the same item, and that the latest value will be the one that survives.

GetSections()

Get all sections defined for the current associate, from the cache if possible, otherwise from the database.

Declaration

public static string[] GetSections()

Returns

Type	Description
String[]	Array of sections

Remarks

An intended side effect is that the key cache for each section plus the value cache for each key are set.

GetString(String, String)

Get string value for a user preference, from the cache if possible. If not, read all keys and their values from the database, update the caches, and return the wanted value.

Declaration

public static string GetString(string section, string key)

Parameters

Type	Name	Description
String	section	Name of the section.
String	key	Name of the key.

Returns

Type	Description
String	User preference. If the user preference does not exist, Empty is returned.

Remarks

Caching is done using the SoPrincipal-based cache mechanism. This is emptied on every roundtrip. That is intentional, to avoid stale data. In the interest of performance, we read complete sections, so if you ask for one preference we read-ahead all the preferences in that section and cache them for this roundtrip.

We assume that the in CurrentPrincipal will accept multiple Set calls on the same item, and that the latest value will be the one that survives.

GetString(String, String, String)

Get string value for a user preference, from the cache if possible. If not, read all keys and their values from the database, update the caches, and return the wanted value.

Declaration

public static string GetString(string section, string key, string defaultValue)

Parameters

Type	Name	Description
String	section	Name of the section.
String	key	Name of the key.
String	defaultValue	Default value

Returns

Type	Description
String	User preference. If the user preference does not exist, the defualtValue is returned.

Remarks

Caching is done using the SoPrincipal-based cache mechanism. This is emptied on every roundtrip. That is intentional, to avoid stale data. In the interest of performance, we read complete sections, so if you ask for one preference we read-ahead all the preferences in that section and cache them for this roundtrip.

We assume that the in CurrentPrincipal will accept multiple Set calls on the same item, and that the latest value will be the one that survives.

IndividualCacheKey(String, String)

Get the cache key for one single value

Declaration

public static string IndividualCacheKey(string section, string key)

Parameters

Type	Name	Description
String	section	Section name
String	key	Key name

Returns

Type	Description
String	Cache key for use in SoPrincipal

Remarks

Caching is done using the SoPrincipal-based cache mechanism. This is emptied on every roundtrip. That is intentional, to avoid stale data. In the interest of performance, we read complete sections, so if you ask for one preference we read-ahead all the preferences in that section and cache them for this roundtrip.

We assume that the in CurrentPrincipal will accept multiple Set calls on the same item, and that the latest value will be the one that survives.

ParseBooleanPreference(String, Boolean)

Parse a string value into a boolean; if that is not possible then return the default instead

Declaration

public static bool ParseBooleanPreference(string value, bool defaultValue)

Parameters

Type	Name	Description
String	value
Boolean	defaultValue

Returns

Type	Description
Boolean

Remarks

Caching is done using the SoPrincipal-based cache mechanism. This is emptied on every roundtrip. That is intentional, to avoid stale data. In the interest of performance, we read complete sections, so if you ask for one preference we read-ahead all the preferences in that section and cache them for this roundtrip.

We assume that the in CurrentPrincipal will accept multiple Set calls on the same item, and that the latest value will be the one that survives.

SectionCacheKey(String)

Get the cache key for the list of keys in one section

Declaration

public static string SectionCacheKey(string section)

Parameters

Type	Name	Description
String	section	Section name

Returns

Type	Description
String	Cache key for use in SoPrincipal

Remarks

Caching is done using the SoPrincipal-based cache mechanism. This is emptied on every roundtrip. That is intentional, to avoid stale data. In the interest of performance, we read complete sections, so if you ask for one preference we read-ahead all the preferences in that section and cache them for this roundtrip.

We assume that the in CurrentPrincipal will accept multiple Set calls on the same item, and that the latest value will be the one that survives.

SetCachedValue(Int32, String, String, String, PreferenceLevel)

Update individual and section caches

Declaration

public static void SetCachedValue(int primaryId, string section, string key, string value, PreferenceLevel level)

Parameters

Type	Name	Description
Int32	primaryId	Obsolete, not used
String	section
String	key
String	value
PreferenceLevel	level	Obsolete, not used

Remarks

Caching is done using the SoPrincipal-based cache mechanism. This is emptied on every roundtrip. That is intentional, to avoid stale data. In the interest of performance, we read complete sections, so if you ask for one preference we read-ahead all the preferences in that section and cache them for this roundtrip.

We assume that the in CurrentPrincipal will accept multiple Set calls on the same item, and that the latest value will be the one that survives.

SetCachedValue(String, String, String)

Update the cache with one item. This method is internal since it is also called from UserPreferenceRow/implementation, to keep the cache up to date with saved changes. NOTE that this does NOT take into account farm/cluster situations, where we instead rely on a fairly short cache lifetime... that may or may not be good enough.

Declaration

public static void SetCachedValue(string section, string key, string value)

Parameters

Type	Name	Description
String	section	Preference section
String	key	Preference key
String	value	Raw value to set

Remarks

Caching is done using the SoPrincipal-based cache mechanism. This is emptied on every roundtrip. That is intentional, to avoid stale data. In the interest of performance, we read complete sections, so if you ask for one preference we read-ahead all the preferences in that section and cache them for this roundtrip.

We assume that the in CurrentPrincipal will accept multiple Set calls on the same item, and that the latest value will be the one that survives.

SetKeys(String)

Reads user preferences at several levels, returning the preference value that is defined at the lowest level.

A user preference defined at level 5 is more specific than a preference read at level 2.

Declaration

public static string[] SetKeys(string section)

Parameters

Type	Name	Description
String	section

Returns

Type	Description
String[]

Remarks

Caching is done using the SoPrincipal-based cache mechanism. This is emptied on every roundtrip. That is intentional, to avoid stale data. In the interest of performance, we read complete sections, so if you ask for one preference we read-ahead all the preferences in that section and cache them for this roundtrip.

We assume that the in CurrentPrincipal will accept multiple Set calls on the same item, and that the latest value will be the one that survives.

SetPreference(String, String, Boolean)

Set a preference on the Individual (associate) level

Declaration

public static void SetPreference(string section, string key, bool value)

Parameters

Type	Name	Description
String	section	Preference section
String	key	Preference key
Boolean	value	New value, will overwrite the old or create a new record if no associate-level preference existed for the current associate

Remarks

Caching is done using the SoPrincipal-based cache mechanism. This is emptied on every roundtrip. That is intentional, to avoid stale data. In the interest of performance, we read complete sections, so if you ask for one preference we read-ahead all the preferences in that section and cache them for this roundtrip.

We assume that the in CurrentPrincipal will accept multiple Set calls on the same item, and that the latest value will be the one that survives.

SetPreference(String, String, DateTime)

Set a preference on the Individual (associate) level

Declaration

public static void SetPreference(string section, string key, DateTime value)

Parameters

Type	Name	Description
String	section	Preference section
String	key	Preference key
DateTime	value	New value, will overwrite the old or create a new record if no associate-level preference existed for the current associate

Remarks

Caching is done using the SoPrincipal-based cache mechanism. This is emptied on every roundtrip. That is intentional, to avoid stale data. In the interest of performance, we read complete sections, so if you ask for one preference we read-ahead all the preferences in that section and cache them for this roundtrip.

We assume that the in CurrentPrincipal will accept multiple Set calls on the same item, and that the latest value will be the one that survives.

SetPreference(String, String, Int32)

Set a preference on the Individual (associate) level

Declaration

public static void SetPreference(string section, string key, int value)

Parameters

Type	Name	Description
String	section	Preference section
String	key	Preference key
Int32	value	New value, will overwrite the old or create a new record if no associate-level preference existed for the current associate

Remarks

Caching is done using the SoPrincipal-based cache mechanism. This is emptied on every roundtrip. That is intentional, to avoid stale data. In the interest of performance, we read complete sections, so if you ask for one preference we read-ahead all the preferences in that section and cache them for this roundtrip.

We assume that the in CurrentPrincipal will accept multiple Set calls on the same item, and that the latest value will be the one that survives.

SetPreference(String, String, String)

Set a preference on the maximum supported level for the given preference. If the maximum level is "Individual" - .an associate level preference will be created. If the maxiumum level is "Group", a group level preference for the current associate will be created.

Declaration

public static void SetPreference(string section, string key, string value)

Parameters

Type	Name	Description
String	section	Preference section
String	key	Preference key
String	value	New value, will overwrite the old or create a new record if no preference existed for the maximum supported level

Remarks

Caching is done using the SoPrincipal-based cache mechanism. This is emptied on every roundtrip. That is intentional, to avoid stale data. In the interest of performance, we read complete sections, so if you ask for one preference we read-ahead all the preferences in that section and cache them for this roundtrip.

We assume that the in CurrentPrincipal will accept multiple Set calls on the same item, and that the latest value will be the one that survives.

SetPreference(String, String, String, Int32, PreferenceLevel, Boolean, Boolean)

Set a preference

Declaration

public static int SetPreference(string section, string key, string value, int ownerId, PreferenceLevel level, bool removeOnLowerLevels = false, bool skipPermissionCheck = false)

Parameters

Type	Name	Description
String	section	Preference section
String	key	Preference key
String	value	New value, will overwrite the old or create a new record if no associate-level preference existed for the associate
Int32	ownerId	The id to set for the ownerId field. This will point to different id type depending on the preference type
PreferenceLevel	level	The level to set for this preference
Boolean	removeOnLowerLevels	Will remove same preference on lower levels if set to true
Boolean	skipPermissionCheck	Set this to true to skip the check for setting system wide preferences

Returns

Type	Description
Int32

Remarks

Caching is done using the SoPrincipal-based cache mechanism. This is emptied on every roundtrip. That is intentional, to avoid stale data. In the interest of performance, we read complete sections, so if you ask for one preference we read-ahead all the preferences in that section and cache them for this roundtrip.

We assume that the in CurrentPrincipal will accept multiple Set calls on the same item, and that the latest value will be the one that survives.