Merge branch 'feature/LegacyTopicReferences' into develop

Refactored support for legacy topic references—what was previously known as topic pointers—so that they are migrated to `Topic.References` on `Import()`. This continues to provide support for legacy JSON data that uses topic pointers, but ensures they are treated as `Topic.References` in OnTopic 5.0.0 database; this is consistent with the OnTopic 5.0.0 database migration process, which migrated topic references from `Attributes` to `TopicReferences`.

As part of this, the following breaking changes were made to the interface in order to unify the nomenclature:
- Renamed the `ExportOptions.IncludeExternalReferences` to `IncludeExternalAssociations` for consistency in nomenclature (a471a7e).
- Renamed the `ExportOptions.TranslateTopicPointers` to `TrnaslateLegacyTopicReferences` for consistency in nomenclature (b67e87f).

Author: JeremyCaney

OnTopic.Data.Transfer.Tests/ExportOptionsTest.cs

@@ -76,7 +76,7 @@ public void ExportWithNestedTopic_TopicWithNestedTopics_IncludesNestedTopics() {
     \-------------------------------------------------------------------------------------------------------------------------*/
     /// <summary>
     ///   Creates a <see cref="Topic"/> with several <see cref="Topic.Relationships"/> and ensures that the <see
-    ///   cref="TopicData.Relationships"/> collection does <i>not</i> include external references—i.e., relationships that point
+    ///   cref="TopicData.Relationships"/> collection does <i>not</i> include external references—i.e., relationships that refer
     ///   to <see cref="Topic"/>s outside of the current export scope.
     /// </summary>
     [TestMethod]
@@ -96,23 +96,24 @@ public void Export_TopicWithRelationships_ExcludesExternalReferences() {
     }
 
     /*==========================================================================================================================
-    | TEST: EXPORT WITH TOPIC POINTERS: EXTERNAL TOPIC POINTER: EXPORTS UNIQUE KEY
+    | TEST: EXPORT WITH LEGACY TOPIC REFERENCES: EXTERNAL TOPIC REFERENCE: EXPORTS UNIQUE KEY
     \-------------------------------------------------------------------------------------------------------------------------*/
     /// <summary>
-    ///   Creates a <see cref="Topic"/> with an arbitrary <see cref="AttributeValue"/> that points to another topic. Confirms
-    ///   that it is converted to a <c>UniqueKey</c> if valid, and otherwise left as is.
+    ///   Creates a <see cref="Topic"/> with an arbitrary <see cref="AttributeValue"/> that references another topic. Confirms
+    ///   that it is converted to a <see cref="Topic.GetUniqueKey"/> if valid, and is otherwise left as is.
     /// </summary>
     [TestMethod]
-    public void ExportWithTopicPointers_ExternalTopicPointer_ExportsUniqueKey() {
+    public void ExportWithLegacyTopicReferences_ExternalTopicReference_ExportsUniqueKey() {
 
       var parentTopic           = TopicFactory.Create("Root", "Container", 5);
       var topic                 = TopicFactory.Create("Topic", "Container", parentTopic);
 
       topic.Attributes.SetValue("SomeId", "5");
 
-      var topicData             = topic.Export(
+      var topicData = topic.Export(
         new() {
-          IncludeExternalReferences = true
+          IncludeExternalAssociations                           = true,
+          TranslateLegacyTopicReferences                        = true
         }
       );
 

OnTopic.Data.Transfer.Tests/TopicExtensionsTest.cs

@@ -113,16 +113,16 @@ public void Export_TopicWithRelationships_MapsRelationshipDataCollection() {
     }
 
     /*==========================================================================================================================
-    | TEST: EXPORT WITH EXTERNAL REFERENCES: TOPIC WITH RELATIONSHIPS: INCLUDE EXTERNAL REFERENCES
+    | TEST: EXPORT WITH EXTERNAL ASSOCIATIONS: TOPIC WITH RELATIONSHIPS: INCLUDE EXTERNAL REFERENCES
     \-------------------------------------------------------------------------------------------------------------------------*/
     /// <summary>
-    ///   Creates a <see cref="Topic"/> with several <see cref="Topic.Relationships"/> and ensures that the <see
-    ///   cref="TopicData.Relationships"/> collection <i>does</i> include external references—i.e., relationships that point
-    ///   to <see cref="Topic"/>s outside of the current export scope—when permitted with the <see
-    ///   cref="ExportOptions.IncludeExternalReferences"/> option.
+    ///   Creates a <see cref="Topic"/> with several <see cref="Topic.Relationships"/> and ensures that the <see cref="TopicData
+    ///   .Relationships"/> collection <i>does</i> include external associations—i.e., relationships that reference <see cref="
+    ///   Topic"/>s outside of the current export scope—when permitted with the <see cref="ExportOptions.
+    ///   IncludeExternalAssociations"/> option.
     /// </summary>
     [TestMethod]
-    public void ExportWithExternalReferences_TopicWithRelationships_ExcludesExternalReferences() {
+    public void ExportWithExternalAssociations_TopicWithRelationships_ExcludesExternalReferences() {
 
       var rootTopic             = TopicFactory.Create("Root", "Container");
       var topic                 = TopicFactory.Create("Test", "Container", rootTopic);
@@ -132,7 +132,7 @@ public void ExportWithExternalReferences_TopicWithRelationships_ExcludesExternal
 
       var topicData             = topic.Export(
         new() {
-          IncludeExternalReferences = true
+          IncludeExternalAssociations = true
         }
       );
 
@@ -184,19 +184,21 @@ public void Export_ExcludesReservedAttributes() {
 
       var topicData             = topic.Export();
 
-      Assert.AreEqual<int>(0, topicData.Attributes.Count);
+      Assert.AreEqual<int>(1, topicData.Attributes.Count);
+      Assert.AreEqual<string>("8", topicData.Attributes.FirstOrDefault().Value);
 
     }
 
     /*==========================================================================================================================
-    | TEST: EXPORT WITH TOPIC POINTERS: OUT OF SCOPE: SKIPS ATTRIBUTE
+    | TEST: EXPORT WITH LEGACY TOPIC REFERENCES: OUT OF SCOPE: SKIPS REFERENCE
     \-------------------------------------------------------------------------------------------------------------------------*/
     /// <summary>
-    ///   Creates a <see cref="Topic"/> with an arbitrary <see cref="AttributeValue"/> that points to a topic outside of the
-    ///   <see cref="ExportOptions.ExportScope"/>. Confirms that it is ignored.
+    ///   Creates a <see cref="Topic"/> with an arbitrary <see cref="AttributeValue"/> that references a <see cref="Topic.Id"/>
+    ///   outside of the <see cref="ExportOptions.ExportScope"/>. Confirms that the reference is maintained as an attribute, but
+    ///   not added as a reference.
     /// </summary>
     [TestMethod]
-    public void ExportWithTopicPointers_OutOfScope_SkipsAttribute() {
+    public void ExportWithLegacyTopicReferences_OutOfScope_SkipsReference() {
 
       var parentTopic           = TopicFactory.Create("Root", "Container", 5);
       var topic                 = TopicFactory.Create("Topic", "Container", parentTopic);
@@ -206,20 +208,22 @@ public void ExportWithTopicPointers_OutOfScope_SkipsAttribute() {
       var topicData             = topic.Export();
 
       topicData.Attributes.TryGetValue("SomeId", out var someAttribute);
+      topicData.References.TryGetValue("Some", out var someReference);
 
-      Assert.IsNull(someAttribute);
+      Assert.IsNotNull(someAttribute);
+      Assert.IsNull(someReference);
 
     }
 
     /*==========================================================================================================================
-    | TEST: EXPORT WITH TOPIC POINTERS: MISSING TOPIC POINTER: SKIPS ATTRIBUTE
+    | TEST: EXPORT WITH LEGACY TOPIC REFERENCES: MISSING TOPIC REFERENCE: SKIPS REFERENCE
     \-------------------------------------------------------------------------------------------------------------------------*/
     /// <summary>
-    ///   Creates a <see cref="Topic"/> with an arbitrary <see cref="AttributeValue"/> that points to a missing <see
-    ///   cref="Topic.Id"/>. Confirms that the attribute is skipped.
+    ///   Creates a <see cref="Topic"/> with an arbitrary <see cref="AttributeValue"/> that references a missing <see cref="
+    ///   Topic.Id"/>. Confirms that the reference is maintained as an attribute, but not added as a reference.
     /// </summary>
     [TestMethod]
-    public void ExportWithTopicPointers_MissingTopicPointer_SkipsAttribute() {
+    public void ExportWithLegacyTopicReferences_MissingTopicReference_SkipsReference() {
 
       var topic                 = TopicFactory.Create("Topic", "Container");
 
@@ -228,20 +232,24 @@ public void ExportWithTopicPointers_MissingTopicPointer_SkipsAttribute() {
       var topicData             = topic.Export();
 
       topicData.Attributes.TryGetValue("InitialBid", out var initialBidAttribute);
+      topicData.References.TryGetValue("InitialB", out var initialBReference);
+      topicData.References.TryGetValue("InitialB", out var initialBidReference);
 
-      Assert.IsNull(initialBidAttribute);
+      Assert.IsNotNull(initialBidAttribute);
+      Assert.IsNull(initialBReference);
+      Assert.IsNull(initialBidReference);
 
     }
 
     /*==========================================================================================================================
-    | TEST: EXPORT WITH TOPIC POINTERS: INVALID TOPIC POINTER: EXPORTS ORIGINAL VALUE
+    | TEST: EXPORT WITH LEGACY TOPIC REFERENCES: INVALID TOPIC REFERENCE: EXPORTS ORIGINAL VALUE
     \-------------------------------------------------------------------------------------------------------------------------*/
     /// <summary>
     ///   Creates a <see cref="Topic"/> with an arbitrary <see cref="AttributeValue"/> that that contains a non-numeric (i.e.,
-    ///   invalid) topic pointers. Confirms that the original value is exported.
+    ///   invalid) topic reference. Confirms that the original value is exported.
     /// </summary>
     [TestMethod]
-    public void ExportWithTopicPointers_InvalidTopicPointer_ExportsOriginalValue() {
+    public void ExportWithLegacyTopicReferences_InvalidTopicReference_ExportsOriginalValue() {
 
       var topic                 = TopicFactory.Create("Topic", "Container");
 
@@ -337,7 +345,7 @@ public void Import_DerivedTopicKey_MapsDerivedTopic() {
     \-------------------------------------------------------------------------------------------------------------------------*/
     /// <summary>
     ///   Creates a <see cref="TopicData"/> with a <see cref="AttributeData"/> with the <see cref="AttributeData.Key"/> of <c>
-    ///   BaseTopic</c> in the <see cref="TopicData.References"/> collection, which points to a topic in the topic graph.
+    ///   BaseTopic</c> in the <see cref="TopicData.References"/> collection, which references a topic in the topic graph.
     ///   Ensures that it is correctly wired up.
     /// </summary>
     [TestMethod]
@@ -372,8 +380,8 @@ public void Import_BaseTopic_MapsBaseTopic() {
     \-------------------------------------------------------------------------------------------------------------------------*/
     /// <summary>
     ///   Creates a <see cref="TopicData"/> with a <see cref="AttributeData"/> with the <see cref="AttributeData.Key"/> of <c>
-    ///   BaseTopic</c> in the <see cref="TopicData.References"/> collection, which points to a newly imported topic that occurs
-    ///   later in the tree, ensuring that the <see cref="Topic.BaseTopic"/> is set correctly.
+    ///   BaseTopic</c> in the <see cref="TopicData.References"/> collection, which references a newly imported topic that
+    ///   occurs later in the tree, ensuring that the <see cref="Topic.BaseTopic"/> is set correctly.
     /// </summary>
     [TestMethod]
     public void Import_BaseTopic_MapsNewBaseTopic() {
@@ -717,14 +725,14 @@ public void Import_TopicDataWithChild_SkipsOrphanedChild() {
     }
 
     /*==========================================================================================================================
-    | TEST: IMPORT: TOPIC DATA WITH TOPIC POINTER: MAPS TOPIC ID
+    | TEST: IMPORT: TOPIC DATA WITH LEGACY TOPIC REFERENCE: MAPS TOPIC ID
     \-------------------------------------------------------------------------------------------------------------------------*/
     /// <summary>
-    ///   Creates a <see cref="TopicData"/> with an arbitrary <see cref="AttributeData"/> that points to another topic. Confirms
-    ///   that it is converted to a <c>TopicID</c> if valid, and otherwise left as is.
+    ///   Creates a <see cref="TopicData"/> with an arbitrary <see cref="AttributeData"/> that references another topic.
+    ///   Confirms that it is converted to a <see cref="Topic.Id"/> if valid, and otherwise left as is.
     /// </summary>
     [TestMethod]
-    public void Import_TopicDataWithTopicPointer_MapsTopicID() {
+    public void Import_TopicDataWithLegacyTopicReference_MapsTopicID() {
 
       var rootTopic             = TopicFactory.Create("Root", "Container");
       var topic                 = TopicFactory.Create("Topic", "Container", rootTopic);
@@ -745,19 +753,19 @@ public void Import_TopicDataWithTopicPointer_MapsTopicID() {
 
       topic.Import(topicData);
 
-      Assert.AreEqual<string>("5", topic.Attributes.GetValue("SomeId"));
+      Assert.AreEqual<int>(5, topic.References.GetValue("Some")?.Id?? -1);
 
     }
 
     /*==========================================================================================================================
-    | TEST: IMPORT: TOPIC DATA WITH MISSING TOPIC POINTER: SKIPS ATTRIBUTE
+    | TEST: IMPORT: TOPIC DATA WITH MISSING LEGACY TOPIC REFERENCE: SKIPS ATTRIBUTE
     \-------------------------------------------------------------------------------------------------------------------------*/
     /// <summary>
-    ///   Creates a <see cref="TopicData"/> with an arbitrary <see cref="AttributeData"/> that points to a missing topic.
+    ///   Creates a <see cref="TopicData"/> with an arbitrary <see cref="AttributeData"/> that references to a missing topic.
     ///   Confirms that the attribute is skipped.
     /// </summary>
     [TestMethod]
-    public void Import_TopicDataWithMissingTopicPointer_SkipsAttribute() {
+    public void Import_TopicDataWithMissingLegacyTopicReference_SkipsAttribute() {
 
       var topic                 = TopicFactory.Create("Topic", "Container");
 
@@ -770,7 +778,7 @@ public void Import_TopicDataWithMissingTopicPointer_SkipsAttribute() {
       topicData.Attributes.Add(
         new() {
           Key                   = "SomeId",
-          Value                 = "Root:Missing:Topic:Pointer"
+          Value                 = "Root:Missing:Legacy:Topic:Reference"
         }
       );
 
@@ -781,14 +789,14 @@ public void Import_TopicDataWithMissingTopicPointer_SkipsAttribute() {
     }
 
     /*==========================================================================================================================
-    | TEST: IMPORT: TOPIC DATA WITH INVALID TOPIC POINTER: IMPORTS ORIGINAL VALUE
+    | TEST: IMPORT: TOPIC DATA WITH INVALID LEGACY TOPIC REFERENCE: IMPORTS ORIGINAL VALUE
     \-------------------------------------------------------------------------------------------------------------------------*/
     /// <summary>
     ///   Creates a <see cref="TopicData"/> with an arbitrary <see cref="AttributeData"/> that does not reference a topic key
     ///   (i.e., it doesn't start with <c>Root</c>). Confirms that the original attribute value is imported.
     /// </summary>
     [TestMethod]
-    public void Import_TopicDataWithInvalidTopicPointer_ImportsOriginalValue() {
+    public void Import_TopicDataWithInvalidLegacyTopicReference_ImportsOriginalValue() {
 
       var topic                 = TopicFactory.Create("Topic", "Container");
 
@@ -811,6 +819,5 @@ public void Import_TopicDataWithInvalidTopicPointer_ImportsOriginalValue() {
 
     }
 
-
   } //Class
 } //Namespace