Thoughts on Implementing the Server Side of the Shepherds

Shepherd Scenarios

• A Shepherd can be...
  • ... a 'Standalone Shepherd'.
    • Has got no Sub-Shepherds and is not itself used as a Sub-Shepherd (as in Petra 2.x's 'New Person Shepherd')
  • ... a 'Master Shepherd'.
    • Has Sub-Shepherds, but it is not itself used as a Sub-Shepherd (as in Petra 2.x's 'Personnel Data Shepherd')
  • ... both a 'Standalone Shepherd' and a 'Sub-Shepherd'
    • E.g. Petra 2.x's 'New Family Shepherd'!
  • ... theoretical possibility: a 'Sub-Shepherd' only
    • Never run as a Shepherd on its own, only embedded in 'Master Shepherds'.
      • No example in Petra 2.x for that scenario yet, but Address/Contact entry would be a prime example for that.
  • ... theoretical possibility: both a 'Master Shepherd' and a 'Sub-Shepherd'!
    • No example in Petra 2.x for that scenario yet.

Shepherd Logic <-> UIConnector Relationship

• One (Sub-)Shepherd Logic (not GUI!) Class = One UIConnector Class.
  • Sub-Shepherd's Logic Classes will utilise their own UIConnector Class (and not the Master Shepherds' UIConnector Classes!), just as if the Sub-Shepherds would be running as 'Standalone Shepherds' or 'Master Shepherds'.
    • A Sub-Shepherd's UIConnector is therefore different from the Master Shepherd's UIConnector!

Workflows

Entering a Shepherd

• if the Master Shepherd's GUI/Standalone Shepherds' GUI is to be opened:
  • Master Shepherd's Logic creates its own UIConnector
• if a Sub-Shepherd is to be opened: see Thoughts on Implementing the Server Side of the Shepherds#Navigating through Shepherd Pages

Navigating through Shepherd Pages

• Master Shepherd's Logic calls necessary UIConnector Methods to retrieve/verify data for it's own Shepherd Pages, as needed, as the Shepherds' Pages are navigated to.
• If a Sub-Shepherd is to be entered:
  • Master Shepherd's Logic creates the Sub-Shepherd's Logic (if that has not already happened [one can enter a Shepherd Page multiple times]), which in turn creates its own UIConnector.
  • Sub-Shepherd's Logic calls necessary UIConnector Methods to retrieve/verify data, as needed, as Sub-Shepherds' Pages are navigated to.

Leaving a Shepherd

• Happens when...
  • ... the 'Finish' Button is pressed on a Standalone Shepherd or a Master Shepherd.
  • ... the 'Next' or 'Back' Button is pressed on a Master Shepherd and the user is on the last/first Shepherd Page of the Sub-Shepherd; that means leaving of a Sub-Shepherd is triggered.
    • only the 'Next' Button is considered for processing Sub-Shepherd data (at least in Petra 2.x)

• If a Sub-Shepherd is left with the 'Next' Button:
  • Sub-Shepherd's Logic makes a call to it's own UIConnector for processing/(server-side-)verification of data
    • that call does almost the same as a call to SubmitChanges of it's UIConnector, except that it doesn't save any data, but that call would return a DataSet to it's Logic that is ready for committing through that UIConnector, using it's UIConnector's SubmitChangesServerSide Method - at a later point.
  • Sub-Shepherd's Logic invokes a Delegate, passing out Arguments that
    • tell whether the call was successful;
    • contain a DataSet that was returned from it's UIConnector, if the call to it was successful;
    • contain a TVerificationResultCollection.
  • Master Shepherd's Logic processes the Delegate callback.
    • If the call wasn't successful, don't move to the 'next' Shepherd Page but stay on the Shepherd Page where the user was and display a TVerificationResultCollection in a MessageBox.
    • If the call was successful: store the returned DataSet in a Dictionary in the Master Shepherd's Logic.
    • The Key of the Dictionary entry is the Class name of the Logic Class of the Sub-Shepherd.
      • That way, the data of several Sub-Shepherds can be kept separately. (If there would be several instances of the same Logic, a number would need to be appended to the class name).
  • A Sub-Shepherd can be left x times, and everytime the same order of events will happen.

• If a Master Shepherd/Standalone Shepherd is left with the 'Finish' Button:
  • Makes a call to it's own UIConnector for processing/(server-side-)verification of data and saving of data (it's SubmitChanges Method is called).
    • The SubmitChanges Method would not accept a Typed DataSet (as is normally the case), but a Dictionary that contains 1..n Typed DataSets!
      • This would be the Dictionary that contains n Sub-Shepherd's DataSets, as well as the Master Shepherd's DataSet.
    • The SubmitChanges Method starts a DB Transaction.
      • The Typed DataSet that the UIConnector can process itself is processed as in a 'normal' SubmitChanges Method.
      • The Typed DataSet(s) that the UIConnector cannot process itself are passed to static SubmitChangesServerSide Methods of the respective Sub-Shepherds, if there are any Sub-Shepherds, for the saving of their specific data.
        • The open DB Transaction is passed through to those SubmitChangesServerSide Methods.
    • The SubmitChanges Method returns success only if all saving of data was fine and commits the DB Transaction, otherwise it rolls back the DB Transaction.
  • The Shepherd is closed.