Skip to content

SAIF.Framework.Preferences operations and processes

SAIF.Framework.Preferences exposes a small, focused surface for reading and writing user preference data: two read operations and one save entry point that internally routes to delete, update, or insert. This page is the operation catalog and cross-operation hub for the library; each operation's detailed, step-by-step logic lives in its own page under operations/.

Operation catalog

Operation Intent Trigger Inputs Outputs Rules Tables SQL
Retrieve single preference blob Read one stored preference payload for an application/user/page scope. Caller invokes PreferenceData.GetPreferences. appName, pageName, userId string payload or string.Empty BR-001, BR-003 USER_PREFERENCE SQL-002
Retrieve all preferences for a user Load every stored preference row for one user and hydrate DTOs. Caller invokes PreferenceData.GetPreferencesForUser. userId List<Preference> BR-001, BR-006 USER_PREFERENCE SQL-003
Save preference Route a save request to delete, update, or insert behavior. Caller invokes PreferenceData.SavePreferences. appName, pageName, userId, preferenceText bool or exception BR-001, BR-002, BR-003, BR-004, BR-005 USER_PREFERENCE SQL-001, SQL-004, SQL-005, SQL-006, SQL-007
Insert preference row Create a new preference row with inline sequence-generated identity. SavePreferences calls InsertPref after DoesPrefExist returns false. appName, pageName, userId, preferenceText true after the insert request is issued BR-001, BR-003, BR-005 USER_PREFERENCE SQL-001, SQL-004
Update preference row Replace stored preference text and audit columns when the value changed. SavePreferences calls UpdatePref after DoesPrefExist returns true. appName, pageName, userId, preferenceText true after the update request is issued BR-001, BR-003, BR-004, BR-005 USER_PREFERENCE SQL-005
Delete preference row Remove the scoped preference row. SavePreferences calls DeletePref for blank preference text. appName, pageName, userId, preferenceText true after the delete request is issued BR-001, BR-003 USER_PREFERENCE SQL-006
Check preference existence Count matching rows before choosing update versus insert. SavePreferences calls DoesPrefExist. appName, pageName, userId bool BR-001, BR-003 USER_PREFERENCE SQL-007

Process flow diagram

The diagram below traces a caller request from entry point through the read/save split and, on the save path, through the delete/update/insert branch that SavePreferences selects.

flowchart TD
    Start([Caller request]) --> Choice{Read or save?}
    Choice -->|Read one| GetOne[Retrieve single preference blob]
    Choice -->|Read all| GetAll[Retrieve all preferences for a user]
    Choice -->|Save| Save[Save preference]
    Save --> Empty{Trimmed text empty?}
    Empty -->|Yes| Delete[Delete preference row]
    Empty -->|No| Exists[Check preference existence]
    Exists -->|Yes| Update[Update preference row]
    Exists -->|No| Insert[Insert preference row]
    GetOne --> EndRead([Return payload])
    GetAll --> EndList([Return preference list])
    Delete --> EndSave([Return true])
    Update --> EndSave
    Insert --> EndSave

Inherited operations and processes

Every SQL statement in this library ultimately executes through one shared dependency operation. That operation originates outside this library and is embedded, not reimplemented, wherever it is used.

From SqlHelper / IDataPortalInfo (SAIF.Framework.Core)

Operation Intent Provided by Origin Embedded in
Data portal request execution Route inline SQL plus bind parameters through the configured portal and return a result. SqlHelper.ResultSetQuery, SqlHelper.ScalarQuery<T>, IDataPortalInfo SAIF.Framework.Core Retrieve single preference blob, Retrieve all preferences for a user, Insert preference row, Update preference row, Delete preference row, Check preference existence

Origin: These operations are defined in SAIF.Framework.Core / SqlHelper and IDataPortalInfo and inherited or delegated by this component. Their step-by-step logic is embedded inline (with > Origin callouts) in the consuming operation's detail page.

Database interactions

Every operation in this library ultimately touches the same single table. The table below summarizes which operations read from or write to it; per-step SQL and table citations live in each operation's detail page under operations/.

Operation SQL Tables Type
Retrieve single preference blob SQL-002 USER_PREFERENCE Read
Retrieve all preferences for a user SQL-003 USER_PREFERENCE Read
Save preference SQL-001, SQL-004, SQL-005, SQL-006, SQL-007 USER_PREFERENCE Read / Write
Insert preference row SQL-001, SQL-004 USER_PREFERENCE Write
Update preference row SQL-005 USER_PREFERENCE Write
Delete preference row SQL-006 USER_PREFERENCE Write
Check preference existence SQL-007 USER_PREFERENCE Read

Failure and edge-case behavior

  • GetPreferences returns string.Empty when no row matches the supplied scope, rather than returning null or throwing.
  • GetPreferencesForUser leaves Preference.PreferenceItems as an empty dictionary when PREFERENCE_TEXT trims to an empty string.
  • SavePreferences calls preferenceText.Trim() before any null check; a null preferenceText raises NullReferenceException before delete/update/insert routing begins.
  • UpdatePref and DeletePref ignore the affected-row count and still return true, including no-op updates or deletes that match zero rows.

Sources

  • SAIF.Framework.Preferences\PreferenceData.cs
  • SAIF.Framework.Preferences\Preference.cs
  • SAIF.Framework.Core\V1\DataAccessLayer\SqlHelper.vb
  • SAIF.Framework.Core\V1\DataAccessLayer\clsResultSet.vb