Introduce handling of unresolved references

When recursively saving a topic graph, it is possible for a topic being saved to reference a new topic in the graph that hasn't yet been saved. This prevents it from resolving that reference. I.e., while the _object model_ is able to model that reference, it can't be _persisted_ to the underlying SQL database since the target topic doesn't yet have a `Topic.Id`.

Previously, this required calling `Save()` twice in this scenario. Now, a new private overload allows a `List<Topic>` to be maintained of `unresolvedTopics`. Then, once the entire graph has been saved, `Save()` will save each individual topic with unresolved references, thus ensuring that they are properly persisted. This works for both `Topic.Relationships` and `Topic.DerivedTopic` references.

There are limitations to this implementation. It isn't able to resolve _implicit_ topic pointers (i.e., attributes with an `Id` extension) since those aren't mapped via the object model, but rather runtime interpretation. As such, when working with the **OnTopic Data Transfer** library, which includes special handling for implicit topic pointers, `Save()` must be called twice (alongside `Import()`). That's expected, and there isn't really a clean workaround.

Second, obviously any references that are outside the scope of the current recusive `Save()` operation will continue to be unresolved. This shouldn't happen in most use cases, but could occur with some custom configuration scripts. That's also expected, and not something we plan on resolving.

Still, this addresses the most common and otherwise unintuitive issue, without adding much overhead to most `Save()` operations. (Obviously, the overhead will depend on how many unresolved references there are.)

Author: JeremyCaney

OnTopic.Data.Sql/SqlTopicRepository.cs

@@ -4,6 +4,7 @@
 | Project       Topics Library
 \=============================================================================================================================*/
 using System;
+using System.Collections.Generic;
 using System.Data;
 using System.Data.SqlTypes;
 using System.Diagnostics.CodeAnalysis;
@@ -264,6 +265,56 @@ public override Topic Load(int topicId, DateTime version) {
     /// <inheritdoc />
     public override int Save([NotNull]Topic topic, bool isRecursive = false, bool isDraft = false) {
 
+      /*------------------------------------------------------------------------------------------------------------------------
+      | Establish dependencies
+      \-----------------------------------------------------------------------------------------------------------------------*/
+      var unresolvedTopics      = new List<Topic>();
+
+      /*------------------------------------------------------------------------------------------------------------------------
+      | Handle first pass
+      \-----------------------------------------------------------------------------------------------------------------------*/
+      var topicId = Save(topic, isRecursive, isDraft, unresolvedTopics);
+
+      /*------------------------------------------------------------------------------------------------------------------------
+      | Attempt to resolve outstanding relationships
+      \-----------------------------------------------------------------------------------------------------------------------*/
+      foreach (var unresolvedTopic in unresolvedTopics) {
+        Save(unresolvedTopic, false, isDraft, new List<Topic>());
+      }
+
+      /*------------------------------------------------------------------------------------------------------------------------
+      | Return value
+      \-----------------------------------------------------------------------------------------------------------------------*/
+      return topicId;
+
+    }
+
+    /// <summary>
+    ///   The private overload of the <see cref="Save"/> method provides support for sharing the <see cref="SqlConnection"/>
+    ///   between multiple requests, and maintaining a list of <paramref name="unresolvedRelationships"/>.
+    /// </summary>
+    /// <remarks>
+    ///   <para>
+    ///     When recursively saving a topic graph, it is conceivable that references to other topics—such as <see
+    ///     cref="Topic.Relationships"/> or <see cref="Topic.DerivedTopic"/>—can't yet be persisted because the target <see
+    ///     cref="Topic"/> hasn't yet been saved, and thus the <see cref="Topic.Id"/> is still set to <c>-1</c>. To mitigate
+    ///     this, the <paramref name="unresolvedRelationships"/> allows this private overload to keep track of unresolved
+    ///     relationships. The public <see cref="Save(Topic, Boolean, Boolean)"/> overload uses this list to resave any topics
+    ///     that include such references. This adds some overhead due to the duplicate <see cref="Save"/>, but helps avoid
+    ///     potential data loss when working with complex topic graphs.
+    ///   </para>
+    /// </remarks>
+    /// <param name="topic">The source <see cref="Topic"/> to save.</param>
+    /// <param name="isRecursive">Determines whether or not to recursively save <see cref="Topic.Children"/>.</param>
+    /// <param name="isDraft">Determines if the <see cref="Topic"/> should be saved as a draft version.</param>
+    /// <param name="unresolvedRelationships">A list of <see cref="Topic"/>s with unresolved topic references.</param>
+    private int Save(
+      [NotNull]Topic topic,
+      bool isRecursive,
+      bool isDraft,
+      List<Topic> unresolvedRelationships
+    ) {
+
       /*------------------------------------------------------------------------------------------------------------------------
       | Call base method - will trigger any events associated with the save
       \-----------------------------------------------------------------------------------------------------------------------*/
@@ -361,13 +412,26 @@ void addUnmatchedAttribute(string key) {
         CommandType             = CommandType.StoredProcedure
       };
       var version               = new SqlDateTime(DateTime.Now);
+      var areReferencesResolved = true;
+
+      /*------------------------------------------------------------------------------------------------------------------------
+      | Handle unresolved references
+      >-------------------------------------------------------------------------------------------------------------------------
+      | If it's a recursive save and there are any unresolved relationships, come back to this after the topic graph has been
+      | saved; that ensures that any relationships within the topic graph have been saved and can be properly persisted. The
+      | same can be done for DerivedTopics references, which are effectively establish a 1:1 relationship.
+      \-----------------------------------------------------------------------------------------------------------------------*/
+      if (isRecursive && (topic.DerivedTopic?.Id < 0 || topic.Relationships.Any(r => r.Any(t => t.Id < 0)))) {
+        unresolvedRelationships.Add(topic);
+        areReferencesResolved = false;
+      }
 
       /*------------------------------------------------------------------------------------------------------------------------
       | Establish query parameters
       \-----------------------------------------------------------------------------------------------------------------------*/
       if (!isNew) {
         command.AddParameter("TopicID", topic.Id);
-        command.AddParameter("DeleteRelationships", true);
+        command.AddParameter("DeleteRelationships", areReferencesResolved);
       }
       else if (topic.Parent != null) {
         command.AddParameter("ParentID", topic.Parent.Id);
@@ -423,7 +487,7 @@ void addUnmatchedAttribute(string key) {
       if (isRecursive) {
         foreach (var childTopic in topic.Children) {
           childTopic.Attributes.SetValue("ParentID", topic.Id.ToString(CultureInfo.InvariantCulture));
-          Save(childTopic, isRecursive, isDraft);
+          Save(childTopic, isRecursive, isDraft, unresolvedRelationships);
         }
       }