Skip to content

Save managed business collection

This operation is the collection-level persistence workflow for managed clsBusinessCollectionBase instances. It validates the collection and its children, persists every deferred deletion before touching any active item, and then persists active children in order — stopping the entire save immediately, and propagating the failing child's broken rules to the collection, the moment any child save returns False.

Field Value
Operation ID OP-CORE-006
Trigger Caller invokes Save() on a managed root collection or parent logic invokes SaveChild() on a child collection.
Inputs Collection state flags, deleted-child list, active child list, and each child's CriteriaObject.
Outputs Persisted deleted children, persisted active children, or early failure with propagated rules.
Primary components clsBusinessCollectionBase.Save, clsBusinessCollectionBase.SaveChild
Entry point SAIF.Framework.Core\V1\BaseItems\clsBusinessCollectionBase.vb

Steps

  1. Validate collection entry conditions before any child save runs.
  2. The collection must be Managed = True.
  3. Root save rejects child collections; child save rejects non-child collections.
  4. Both entry points reject open edit levels and invalid collections before work begins (BR-001, BR-002).
  5. Re-evaluate collection validity (BR-001, BR-002).
  6. IsValid validates child items first, optionally short-circuiting when ValidateAllChildren = False.
  7. It then checks the collection's own rules and propagates child messages upward (BR-002).
  8. Clear current errors and warnings and short-circuit unchanged collections.
  9. Rules.BrokenRules.ClearErrorsAndWarnings() resets the collection's transient error/warning state (BR-002).
  10. If IsDirty = False, the operation returns True without touching children.
  11. Start the save phase by calling OnSave().
  12. Persist deferred deletions before active items.
  13. For each item in m_deletedList, call BusinessObject.SaveChild().
  14. If any child returns False, propagate that child's rules to the collection and stop immediately (BR-002).
  15. Clear the deleted list only after all deferred deletes succeed.
  16. Persist active child items in collection order.
  17. For each current child, call BusinessObject.SaveChild().
  18. If any child returns False, propagate that child's rules to the collection and stop immediately (BR-002).

Origin: The per-child persistence executed in steps 5 and 7 follows the single-object workflow documented in Save business object, implemented by clsBusinessBase.SaveChild() in this same library. 8. Complete the save only when every child succeeds. - OnSaveComplete() runs after all deleted and active children finish successfully. - The operation returns True.

Process flow

The following diagram visualizes this operation's control flow.

flowchart TD
    Start([Collection Save]) --> Valid{Managed and valid?}
    Valid -->|No| EndErr([Throw ApplicationException])
    Valid -->|Yes| Dirty{Dirty?}
    Dirty -->|No| EndNoop([Return true])
    Dirty -->|Yes| Deleted[Save deleted children]
    Deleted --> DeletedOk{All deleted children saved?}
    DeletedOk -->|No| EndFail([Propagate child rules and stop])
    DeletedOk -->|Yes| Active[Save active children]
    Active --> ActiveOk{All active children saved?}
    ActiveOk -->|No| EndFail
    ActiveOk -->|Yes| Done[Run OnSaveComplete]
    Done --> EndOk([Return true])

Failure and edge-case behavior

  • An unmanaged collection (Managed = False) is rejected before any child processing starts, and a root/child role mismatch is rejected the same way.
  • The deferred-deletion phase must fully succeed for every item in m_deletedList before that list is cleared; a partial failure leaves the deleted list intact so a retry does not lose track of pending deletions.
  • The save stops at the first child that returns False — later children in that same phase are never attempted during that save call, even if they would have succeeded.

Sources

  • SAIF.Framework.Core\V1\BaseItems\clsBusinessCollectionBase.vb
  • SAIF.Framework.Core\V1\BaseItems\clsBusinessBase.vb