View source for 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]].

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