Thoughts on Implementing the Server Side of the Shepherds

From OpenPetra Wiki
Jump to navigation Jump to search

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!


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 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.