---
title: PreferenceData
summary: API reference for PreferenceData.
status: draft
owner: <owner>
last_reviewed: 2026-07-23
library: SAIF.Framework.Preferences
reference_type: package
---

# PreferenceData

`PreferenceData` is the sole data-access class in `SAIF.Framework.Preferences`. It reads and writes rows in [USER_PREFERENCE](../../database-tables.md#user_preference) directly via inline Oracle SQL executed through `SqlHelper.ResultSetQuery` and `SqlHelper.ScalarQuery<T>`, bypassing the framework's standard `clsBusinessBase`/`IBusinessCriteria` business-object pattern.

## Purpose
- Provide the read (`GetPreferences`, `GetPreferencesForUser`) and write (`SavePreferences`) surface for per-user application/page preference blobs stored in `USER_PREFERENCE`.

## Context
- Namespace: `SAIF.Framework.Preferences`
- Assembly/package: `SAIF.Framework.Preferences`

## Public members
| Member | Signature | Purpose |
| --- | --- | --- |
| `PreferenceData(IDataPortalInfo dpi)` | `public PreferenceData(IDataPortalInfo dpi)` | Constructs the data-access object with a caller-supplied `IDataPortalInfo`, stored in the private `DPI` field and used for query execution context and audit-user resolution. |
| `GetPreferences` | `public string GetPreferences(string appName, string pageName, string userId)` | Retrieves the stored `PREFERENCE_TEXT` for one application/user/page combination (see [SQL-002](../../sql/SQL-002-get-preferences.md)); returns `string.Empty` if no row matches. |
| `GetPreferencesForUser` | `public List<Preference> GetPreferencesForUser(string userId)` | Retrieves all preference rows for a user, building and returning a `Preference` object per row, with `PreferenceItems` deserialized from JSON (see [SQL-003](../../sql/SQL-003-get-preferences-for-user.md)). |
| `SavePreferences` | `public bool SavePreferences(string appName, string pageName, string userId, string preferenceText)` | Single write entry point; dispatches to `DeletePref`, `UpdatePref`, or `InsertPref` depending on `preferenceText` and existing-row state. Always returns `true`. |
| `InsertPref` (private) | `private int InsertPref(string appName, string pageName, string userId, string preferenceText)` | Inserts a new `USER_PREFERENCE` row with a sequence-generated key (see [SQL-001](../../sql/SQL-001-insert-preference-sequence.md), [SQL-004](../../sql/SQL-004-insert-preference.md)). |
| `UpdatePref` (private) | `private int UpdatePref(string appName, string pageName, string userId, string preferenceText)` | Updates an existing row's `PREFERENCE_TEXT` and audit columns, guarded against no-op writes (see [SQL-005](../../sql/SQL-005-update-preference.md)). |
| `DeletePref` (private) | `private int DeletePref(string appName, string pageName, string userId)` | Deletes a matching `USER_PREFERENCE` row (see [SQL-006](../../sql/SQL-006-delete-preference.md)). |
| `DoesPrefExist` (private) | `private bool DoesPrefExist(string appName, string pageName, string userId)` | Returns whether a matching row already exists, via a scalar `Count(*)` check (see [SQL-007](../../sql/SQL-007-does-pref-exist.md)). |

## Behavioral notes
- User IDs are lower-cased before being bound to `:userid` in every method — see [BR-001](../../business-rules.md#br-001-user-ids-are-normalized-to-lower-case).
- `SavePreferences` routes to `DeletePref` when `preferenceText` is empty or whitespace-only — see [BR-002](../../business-rules.md#br-002-empty-preference-text-triggers-deletion).
- Preference identity is scoped by application name, user ID, and an optional page name across all read/write/delete methods — see [BR-003](../../business-rules.md#br-003-preference-identity-is-scoped-by-app-user-and-optional-page).
- `UpdatePref` skips the write when the stored value is unchanged (`PREFERENCE_TEXT <> :prefs`) — see [BR-004](../../business-rules.md#br-004-update-is-skipped-when-stored-value-is-unchanged).
- Preference text is trimmed before being persisted in `InsertPref`/`UpdatePref` — see [BR-005](../../business-rules.md#br-005-preference-text-is-trimmed-before-storage).
- `GetPreferencesForUser` deserializes the JSON-encoded `PREFERENCE_TEXT` payload into `Preference.PreferenceItems` — see [BR-006](../../business-rules.md#br-006-preference-item-payload-is-json-encoded-keyvalue-data).
- This class does not implement `IBusinessCriteria` and has no nested `Criteria` class or `CreateSQL`/`RetrieveSQL`/`InsertSQL`/`UpdateSQL`/`DeleteSQL` properties, unlike most BOF business-object classes.*

## Constraints and usage notes
- Callers must supply a valid `IDataPortalInfo` at construction time; this class resolves no connection or configuration context of its own.
- All internal write methods (`InsertPref`, `UpdatePref`, `DeletePref`) execute via `SqlHelper.ScalarQuery<int>` and return a rows-affected/status integer that `SavePreferences` does not directly propagate to its own `bool` return value.*
- No authentication, authorization, or segregation-of-duties checks are performed on `userId`; it is used purely as a data key.

> **Note:** Statements marked with * were inferred from code structure, naming conventions, or
> contextual evidence where direct confirmation was not available in source artifacts.

## Sources
- SAIF.Framework.Preferences\PreferenceData.cs