Skip to content

Persist preferences

This operation serializes every in-memory Preference record belonging to the store's current application to JSON and hands each one to SAIF.Framework.Preferences.PreferenceData.SavePreferences. This library issues no SQL; the write is executed entirely inside the SAIF.BOF.Framework package.

Field Value
Operation ID OP-PRES-005
Trigger Consuming code calls Save() after a batch of Add / Remove / Clear calls
Inputs The in-memory _Preferences list, m_DPI
Outputs Persisted preference records; the function always returns False
Primary components clsPreferences.Save
Entry point SAIF.Presentation/clsPreferences.vb

Steps

  1. Log method entry via clsLogTrace.MethodBegin(). No SQL.
  2. Construct PreferenceData(m_DPI).
  3. Delegates to SAIF.Framework.Preferences; the framework's own persistence logic is not visible from this repository.**
  4. Iterate _Preferences, skipping any record whose ApplicationName differs from the store's current application (BR-PRES-020).
  5. For each matching record, serialize PreferenceItems to JSON with JavaScriptSerializer when the dictionary is non-empty, or pass an empty string when it is empty (BR-PRES-021, BR-PRES-022).
  6. Call PreferenceData.SavePreferences(applicationName, pagename, m_DPI.UserID, json) (BR-PRES-023).
  7. The write is executed inside the framework package; the SQL and target table are not visible from this repository.**
  8. On any exception, wrap and re-throw as ApplicationException("Unable to save preferences.", ex) (BR-PRES-024).
  9. Return result, which is never assigned and is therefore always False.
  10. The trailing clsLogTrace.MethodEnd() call after Return result is unreachable — a verified defect in this library's source.

Process flow

The following diagram visualizes this operation's control flow.

flowchart TD
    Start([Save called]) --> S1[Log method entry]
    S1 --> S2[Construct PreferenceData]
    S2 --> S3[Iterate _Preferences]
    S3 --> D1{ApplicationName matches current application?}
    D1 -->|No| Skip[Skip record]
    D1 -->|Yes| S4[Serialize PreferenceItems to JSON, or empty string]
    S4 --> S5[PreferenceData.SavePreferences]
    S5 --> D2{Exception thrown?}
    D2 -->|Yes| Err([Wrap and re-throw ApplicationException])
    D2 -->|No| Loop{More records?}
    Loop -->|Yes| S3
    Loop -->|No| EndOk([Return False, unreachable MethodEnd])
    Skip --> Loop

Failure and edge-case behavior

  • Any exception raised by PreferenceData.SavePreferences is wrapped and re-thrown as ApplicationException("Unable to save preferences.", ex) (BR-PRES-024).
  • Save() always returns False even on success, because the result local is never assigned True — callers cannot use the return value to detect success; only a thrown ApplicationException signals failure.

Note: Statements marked with ** could not be confirmed; treat as unknown until verified.

Sources

  • SAIF.Presentation/clsPreferences.vb