Merge commit 'feature/TopicReferences' into develop

JeremyCaney · JeremyCaney · commit 2cfbc523f70c · 2021-02-11T19:35:00.000-08:00
Introduced support for `Topic.References` via a `TopicData.References` property (aac6394), which is populated via the `Export()` extension method (f156c25), and read via the `Import()` extension method (6d5938b), while honoring the new `DeleteUnmatchedReferences` import option (79f64c1). Finally, unified the handling of unresolved associations to work with _both_ `Topic.Relationships`—as it was originally intended for—as well as `Topic.References` (6d22172).
diff --git a/OnTopic.Data.Transfer.Tests/SerializationTest.cs b/OnTopic.Data.Transfer.Tests/SerializationTest.cs
@@ -41,6 +41,7 @@ public void Serialize_TopicData_ReturnsExpectedResults() {
         $"\"ContentType\":\"{topicData.ContentType}\"," +
         $"\"Attributes\":[]," +
         $"\"Relationships\":[]," +
+        $"\"References\":[]," +
         $"\"Children\":[]" +
         $"}}";
 
@@ -149,13 +150,15 @@ public void Serialize_TopicGraph_ReturnsExpectedResults() {
             $"\"Relationships\":[\"Root:Web\"]" +
           $"}}" +
         $"]," +
+        $"\"References\":[]," +
         $"\"Children\":[" +
           $"{{" +
             $"\"Key\":\"{childTopicData.Key}\"," +
             $"\"UniqueKey\":\"{childTopicData.UniqueKey}\"," +
             $"\"ContentType\":\"{childTopicData.ContentType}\"," +
             $"\"Attributes\":[]," +
             $"\"Relationships\":[]," +
+            $"\"References\":[]," +
             $"\"Children\":[]" +
           $"}}" +
         $"]" +
diff --git a/OnTopic.Data.Transfer/Interchange/ImportOptions.cs b/OnTopic.Data.Transfer/Interchange/ImportOptions.cs
@@ -28,6 +28,7 @@ public class ImportOptions {
     \-------------------------------------------------------------------------------------------------------------------------*/
     private                     bool?                           _deleteUnmatchedAttributes;
     private                     bool?                           _deleteUnmatchedRelationships;
+    private                     bool?                           _deleteUnmatchedReferences;
     private                     bool?                           _deleteUnmatchedChildren;
     private                     bool?                           _deleteUnmatchedNestedTopics;
     private                     bool?                           _overwriteContentType;
@@ -77,6 +78,21 @@ public bool DeleteUnmatchedRelationships {
       set => _deleteUnmatchedRelationships = value;
     }
 
+    /*==========================================================================================================================
+    | DELETE UNMATCHED REFERENCES
+    \-------------------------------------------------------------------------------------------------------------------------*/
+    /// <summary>
+    ///   Delete references in the target database which don't exist in the source <see cref="TopicData"/> graph.
+    /// </summary>
+    /// <remarks>
+    ///   This will delete any existing references that aren't <i>also</i> represented in the source <see cref="TopicData"/>
+    ///   graph.
+    /// </remarks>
+    public bool DeleteUnmatchedReferences {
+      get => _deleteUnmatchedReferences?? Strategy is ImportStrategy.Replace;
+      set => _deleteUnmatchedReferences = value;
+    }
+
     /*==========================================================================================================================
     | DELETE UNMATCHED CHILDREN
     \-------------------------------------------------------------------------------------------------------------------------*/
diff --git a/OnTopic.Data.Transfer/Interchange/TopicExtensions.cs b/OnTopic.Data.Transfer/Interchange/TopicExtensions.cs
@@ -100,6 +100,25 @@ public static TopicData Export(this Topic topic, [NotNull]ExportOptions? options
         );
       }
 
+      /*------------------------------------------------------------------------------------------------------------------------
+      | Set topic references
+      \-----------------------------------------------------------------------------------------------------------------------*/
+      foreach (var reference in topic.References) {
+        if (
+          !options.IncludeExternalReferences &&
+          !(reference.Value?.GetUniqueKey().StartsWith(options.ExportScope, StringComparison.InvariantCultureIgnoreCase)?? true)
+        ) {
+          continue;
+        }
+        topicData.References.Add(
+          new() {
+            Key               = reference.Key,
+            Value             = reference.Value?.GetUniqueKey(),
+            LastModified      = reference.LastModified
+          }
+        );
+      }
+
       /*------------------------------------------------------------------------------------------------------------------------
       | Set relationships
       \-----------------------------------------------------------------------------------------------------------------------*/
@@ -165,24 +184,25 @@ public static void Import(this Topic topic, TopicData topicData, [NotNull]Import
       /*------------------------------------------------------------------------------------------------------------------------
       | Establish cache
       \-----------------------------------------------------------------------------------------------------------------------*/
-      var unresolvedRelationships = new List<Tuple<Topic, string, string>>();
+      var unresolvedAssociations = new List<Tuple<Topic, bool, string, string>>();
 
       /*------------------------------------------------------------------------------------------------------------------------
       | Handle first pass
       \-----------------------------------------------------------------------------------------------------------------------*/
-      topic.Import(topicData, options, unresolvedRelationships);
+      topic.Import(topicData, options, unresolvedAssociations);
 
       /*------------------------------------------------------------------------------------------------------------------------
-      | Attempt to resolve outstanding relationships
+      | Attempt to resolve outstanding assocations
       \-----------------------------------------------------------------------------------------------------------------------*/
-      foreach (var relationship in unresolvedRelationships) {
+      foreach (var relationship in unresolvedAssociations) {
 
-        //Attempt to find the target relationship
+        //Attempt to find the target association
         var source              = relationship.Item1;
-        var target              = topic.GetByUniqueKey(relationship.Item3);
-        var key                 = relationship.Item2;
+        var isRelationship      = relationship.Item2;
+        var key                 = relationship.Item3;
+        var target              = topic.GetByUniqueKey(relationship.Item4);
 
-        //If the relationship STILL can't be resolved, skip it
+        //If the association STILL can't be resolved, skip it
         if (target is null) {
           continue;
         }
@@ -193,10 +213,15 @@ public static void Import(this Topic topic, TopicData topicData, [NotNull]Import
         }
 
         //Wire up relationships
-        else {
+        else if (isRelationship) {
           source.Relationships.SetValue(key, target);
         }
 
+        //Wire up topic references
+        else {
+          source.References.SetValue(key, target);
+        }
+
       }
 
     }
@@ -219,13 +244,15 @@ public static void Import(this Topic topic, TopicData topicData, [NotNull]Import
     ///     this via <see cref="Import"/> directly.
     ///   </para>
     /// </remarks>
-    /// <param name="topic">The source <see cref="Topic"/> to operate off of.</param>
+    /// <param name="topic">The target <see cref="Topic"/> to write data to.</param>
+    /// <param name="topicData">The source <see cref="TopicData"/> to import data from.</param>
     /// <param name="options">An optional <see cref="ImportOptions"/> object to specify import settings.</param>
+    /// <param name="unresolvedAssociations">A list of associations that could not be resolved on the first </param>
     private static void Import(
       this Topic topic,
       TopicData topicData,
       [NotNull]ImportOptions? options,
-      List<Tuple<Topic, string, string>> unresolvedRelationships
+      List<Tuple<Topic, bool, string, string>> unresolvedAssociations
     ) {
 
       /*------------------------------------------------------------------------------------------------------------------------
@@ -266,7 +293,7 @@ List<Tuple<Topic, string, string>> unresolvedRelationships
           topic.BaseTopic = target;
         }
         else {
-          unresolvedRelationships.Add(new(topic, "DerivedTopic", topicData.BaseTopicKey));
+          unresolvedAssociations.Add(new(topic, false, "DerivedTopic", topicData.BaseTopicKey));
         }
       }
 
@@ -349,11 +376,44 @@ List<Tuple<Topic, string, string>> unresolvedRelationships
             topic.Relationships.SetValue(relationship.Key, relatedTopic);
           }
           else {
-            unresolvedRelationships.Add(new(topic, relationship.Key!, relatedTopicKey));
+            unresolvedAssociations.Add(new(topic, true, relationship.Key!, relatedTopicKey));
           }
         }
       }
 
+
+      /*------------------------------------------------------------------------------------------------------------------------
+      | Set topic references
+      \-----------------------------------------------------------------------------------------------------------------------*/
+
+      //First delete any unmatched records, if appropriate
+      if (options.DeleteUnmatchedReferences) {
+        var unmatchedReferences = topic.References.Where(a1 =>
+          !topicData.Attributes.Any(a2 => a1.Key == a2.Key)
+        );
+        foreach (var reference in unmatchedReferences.ToArray()) {
+          topic.References.Remove(reference);
+        };
+      }
+
+      //Update records based on the source collection
+      foreach (var reference in topicData.References) {
+        if (useCustomMergeRules(reference)) continue;
+        var matchedReference = topic.References.FirstOrDefault(a => a.Key == reference.Key);
+        if (matchedReference is not null && isStrategy(ImportStrategy.Add)) continue;
+        if (matchedReference?.LastModified >= reference.LastModified && isStrategy(ImportStrategy.Merge)) continue;
+        var referencedTopic = topic.GetByUniqueKey(reference.Key);
+        if (reference.Value is null || referencedTopic != null) {
+          topic.References.SetValue(
+            reference.Key,
+            referencedTopic
+          );
+        }
+        else {
+          unresolvedAssociations.Add(new(topic, false, reference.Key, reference.Value));
+        }
+      }
+
       /*------------------------------------------------------------------------------------------------------------------------
       | Recurse over children
       \-----------------------------------------------------------------------------------------------------------------------*/
@@ -376,7 +436,7 @@ topic.ContentType is not "List" && options.DeleteUnmatchedChildren
         if (childTopic is null) {
           childTopic = TopicFactory.Create(childTopicData.Key, childTopicData.ContentType, topic);
         }
-        childTopic.Import(childTopicData, options, unresolvedRelationships);
+        childTopic.Import(childTopicData, options, unresolvedAssociations);
       }
 
       /*------------------------------------------------------------------------------------------------------------------------
diff --git a/OnTopic.Data.Transfer/TopicData.cs b/OnTopic.Data.Transfer/TopicData.cs
@@ -7,7 +7,6 @@
 using System.Collections.ObjectModel;
 using System.Diagnostics.CodeAnalysis;
 using System.Text.Json;
-using System.Text.Json.Serialization;
 
 namespace OnTopic.Data.Transfer {
 
@@ -118,6 +117,15 @@ public string? BaseTopicKey {
     /// </summary>
     public RelationshipDataCollection Relationships { get; set; } = new();
 
+    /*==========================================================================================================================
+    | TOPIC REFERENCES
+    \-------------------------------------------------------------------------------------------------------------------------*/
+    /// <summary>
+    ///   Provides a collection of <see cref="AttributeData"/> representing the topic references from the associated <see
+    ///   cref="Topic"/> object.
+    /// </summary>
+    public AttributeDataCollection References { get; set; } = new();
+
     /*==========================================================================================================================
     | CHILDREN
     \-------------------------------------------------------------------------------------------------------------------------*/
