Skip to content

SAIF.Framework.Core operations and processes

SAIF.Framework.Core has no end-user business processes of its own — it is the base layer every domain business-object library builds on. What it does provide is a fixed set of framework lifecycle operations: editing, validation, creation, retrieval, persistence, low-level data-portal dispatch, and API-client routing. Every business object and collection in the repository that inherits clsBusinessBase or clsBusinessCollectionBase runs through these operations, so understanding them here explains behavior that recurs across the entire framework. This page is the operation catalog and cross-operation hub for this 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
Manage edit session Open, commit, or roll back an in-memory editing scope for a business object or collection graph, including its children. Caller or data-binding infrastructure invokes BeginEdit, CancelEdit, or ApplyEdit. Business object or collection instance, including child objects and collections. State snapshot committed, restored, or discarded; child add/delete state reconciled. — — —
Evaluate business object rules Execute registered rules in severity order, refresh broken-rule state, and expose validity to callers and data binding. Caller invokes IsValid or CheckRules. Business object or collection, plus an optional property/group rule identifier. Boolean validity result and refreshed error, warning, and informational rule state. BR-001, BR-002 — —
Create business object from criteria Instantiate the business object type implied by a criteria instance and drive it through its create lifecycle. Caller invokes IDataAccess.CreateObject(criteria). IBusinessCriteria or IBusinessApiCriteria instance with a populated DataPortalInfo. Newly instantiated, fully initialized business object. — — —
Retrieve business object from criteria Instantiate the business object type implied by a criteria instance and hydrate it through its retrieve lifecycle. Caller invokes IDataAccess.RetrieveObject(criteria). IBusinessCriteria or IBusinessApiCriteria instance with a populated DataPortalInfo. Hydrated business object populated from the data source. — — —
Save business object Validate a root or child business object and dispatch the correct delete, insert, or update path based on its state flags. Caller invokes Save() on a root object or parent logic invokes SaveChild() on a child object. Business object with its current state flags, criteria object, and DataPortalInfo. Object persisted (or left unchanged when not dirty), False when errors remain, or a thrown exception for an invalid entry state. BR-001, BR-002 — —
Save managed business collection Validate a managed collection, persist deferred deletions first, then persist active children, stopping at the first failure. Caller invokes collection Save() or parent logic invokes collection SaveChild(). Managed business collection, including its deleted-child list and active child items. Deleted children removed, active children saved, or an early stop with the failing child's rules propagated to the collection. BR-001, BR-002 — —
Execute data-portal request Turn a scalar, result-set, sequence, or XML request into a portal/data request and dispatch it through the active data portal. Caller invokes a convenience helper on IDataPortalInfo or submits a prepared portal request. Portal ID, request metadata, and caller-supplied SQL or sequence name. Scalar value, next sequence value, result set, XML payload, or updated portal request. — — —
Resolve API client and route Bind API-backed criteria to a named REST client and render route templates with call-site arguments. Caller constructs API criteria or invokes GetApiClient/FormatRoute. IDataPortalInfo, client key, optional controller name, route key, and route arguments. Resolved IApiClient, formatted IApiRoute, or a thrown ArgumentException for a missing client. BR-004 — —
Enforce retrieve-only criteria guard Block create, insert, update, and delete SQL access on criteria types that are intentionally read-only. Caller accesses a SQL property on a clsRetrieveOnlyBusinessCriteria instance. Retrieve-only criteria instance. Stored retrieve SQL, or an immediate ApplicationException for any mutating property. BR-003 — —

Process flow diagram

The following diagram visualizes how a caller's request is routed to the appropriate framework operation, and how the creation, retrieval, and persistence operations converge on the same data-portal dispatch path.

flowchart TD
    Start([Caller request]) --> D{Requested framework workflow?}
    D -->|Edit in memory| Edit[Manage edit session]
    D -->|Validate| Validate[Evaluate business object rules]
    D -->|Create/Retrieve| Lifecycle[Create or retrieve business object]
    D -->|Persist| Save[Save business object or collection]
    D -->|API-backed criteria| Api[Resolve API client and route]
    D -->|Read-only misuse| Guard[Enforce retrieve-only criteria guard]
    Validate --> Save
    Lifecycle --> Portal[Execute data-portal request]
    Save --> Portal
    Portal --> EndOk([Return object or data result])
    Api --> EndOk
    Guard --> EndErr([Raise framework exception])
    Edit --> EndOk

Failure and edge-case behavior

  • Save() and SaveChild() throw ApplicationException when the target is read-only, in the wrong root/child role, still inside an edit level, or invalid after rule evaluation.
  • Collection save stops on the first child that returns False, propagates that child's broken rules to the collection, and does not continue to later items.
  • CreateObject, RetrieveObject, and portal-processing helpers wrap lower-level failures in ApplicationException and disconnect the portal in Finally.
  • GetApiClient() throws ArgumentException when the expected API client key is missing from IDataPortalInfo.ApiClients.
  • clsRetrieveOnlyBusinessCriteria throws ApplicationException("SQL property not available.") as soon as a mutating SQL property is accessed.

Sources

  • SAIF.Framework.Core\V1\BaseItems\clsBusinessBase.vb
  • SAIF.Framework.Core\V1\BaseItems\clsBusinessCollectionBase.vb
  • SAIF.Framework.Core\V1\BaseItems\clsUndoableBase.vb
  • SAIF.Framework.Core\V1\BaseItems\clsRetrieveOnlyBusinessCriteria.vb
  • SAIF.Framework.Core\V1\Api\clsBusinessApiCriteriaBase.vb
  • SAIF.Framework.Core\V1\DataAccessLayer\clsDataPortalInfo.vb
  • SAIF.Framework.Core\V1\DataAccessLayer\clsDataAccess.vb
  • SAIF.Framework.Core\V1\DataAccessLayer\MSOracle\MSOracleDataPortal.vb
  • SAIF.Framework.Core\V1\DataAccessLayer\SQLServer\SQLDataPortal.vb
  • SAIF.Framework.Core\V1\BusinessRules\clsRulesManager.vb