Introduced new IsDirty() overloads for AttributeValueCollection

JeremyCaney · JeremyCaney · commit d3b49ffd47cf · 2020-05-03T12:55:03.000-07:00
Previously, there was an `IsDirty()` method that accepted an attribute key (`name`) to check the status of an individual attribute. In most use cases, though, it makes more sense to check the entire `AttributeValueCollection` to see if there are _any_ dirty attributes, as that's a condition that will determine if the topic itself should be saved. To support this, a new overload is introduced which, absent any parameters, will return true of any `AttribtueValue`s stored in it are marked as `IsDirty`. In addition, however, this presents an opportunity to centralize logic for identifying extraneous byline (`LastModifiedBy`) and dateline (`LastModified`) attributes. These attribute values are automatically and dynamically generated by some clients, such as the **OnTopic Editor**. As a result, if you save a topic five times without making any changes, you'll end up with five versions due to the `DateModified` being automatically updated. To help address that in a centralized fashion, the `IsDirty()` method also accepts an `excludeLastModified` parameter which will only report `true` if there are `AttributeValue`s marked as `IsDirty` whose `Key`s don't start with `LastModified`. This provides a useful condition for excluding extraneous updates—and, therefore, "orphaned" versions. This supports Remove byline and dateline if no other attributes are updated (#20).
diff --git a/OnTopic.Tests/AttributeValueCollectionTest.cs b/OnTopic.Tests/AttributeValueCollectionTest.cs
@@ -8,6 +8,7 @@
 using OnTopic.Attributes;
 using OnTopic.Collections;
 using Microsoft.VisualStudio.TestTools.UnitTesting;
+using System.Globalization;
 
 namespace OnTopic.Tests {
 
@@ -251,6 +252,65 @@ public void SetValue_ValueUnchanged_IsNotDirty() {
 
     }
 
+    /*==========================================================================================================================
+    | TEST: IS DIRTY: DIRTY VALUES: RETURNS TRUE
+    \-------------------------------------------------------------------------------------------------------------------------*/
+    /// <summary>
+    ///   Populates the <see cref="AttributeValueCollection"/> with a <see cref="AttributeValue"/> that is marked as <see
+    ///   cref="AttributeValue.IsDirty"/>. Confirms that <see cref="AttributeValueCollection.IsDirty(Boolean)"/> returns
+    ///   <c>true</c>/
+    /// </summary>
+    [TestMethod]
+    public void IsDirty_DirtyValues_ReturnsTrue() {
+
+      var topic = TopicFactory.Create("Test", "Container");
+
+      topic.Attributes.SetValue("Foo", "Bar");
+
+      Assert.IsTrue(topic.Attributes.IsDirty());
+
+    }
+
+    /*==========================================================================================================================
+    | TEST: IS DIRTY: NO DIRTY VALUES: RETURNS FALSE
+    \-------------------------------------------------------------------------------------------------------------------------*/
+    /// <summary>
+    ///   Populates the <see cref="AttributeValueCollection"/> with a <see cref="AttributeValue"/> that is <i>not</i> marked as
+    ///   <see cref="AttributeValue.IsDirty"/>. Confirms that <see cref="AttributeValueCollection.IsDirty(Boolean)"/> returns
+    ///   <c>false</c>/
+    /// </summary>
+    [TestMethod]
+    public void IsDirty_NoDirtyValues_ReturnsFalse() {
+
+      var topic = TopicFactory.Create("Test", "Container", 1);
+
+      topic.Attributes.SetValue("Foo", "Bar", false);
+
+      Assert.IsFalse(topic.Attributes.IsDirty());
+
+    }
+
+    /*==========================================================================================================================
+    | TEST: IS DIRTY: EXCLUDE LAST MODIFIED: RETURNS FALSE
+    \-------------------------------------------------------------------------------------------------------------------------*/
+    /// <summary>
+    ///   Populates the <see cref="AttributeValueCollection"/> with a <see cref="AttributeValue"/> that is <i>not</i> marked as
+    ///   <see cref="AttributeValue.IsDirty"/> as well as a <c>LastModified</c> <see cref="AttributeValue"/> that is. Confirms
+    ///   that <see cref="AttributeValueCollection.IsDirty(Boolean)"/> returns <c>false</c>.
+    /// </summary>
+    [TestMethod]
+    public void IsDirty_ExcludeLastModified_ReturnsFalse() {
+
+      var topic = TopicFactory.Create("Test", "Container", 1);
+
+      topic.Attributes.SetValue("Foo", "Bar", false);
+      topic.Attributes.SetValue("LastModified", DateTime.Now.ToString(CultureInfo.InvariantCulture));
+      topic.Attributes.SetValue("LastModifiedBy", "System");
+
+      Assert.IsFalse(topic.Attributes.IsDirty(true));
+
+    }
+
     /*==========================================================================================================================
     | TEST: SET VALUE: INVALID VALUE: THROWS EXCEPTION
     \-------------------------------------------------------------------------------------------------------------------------*/
diff --git a/OnTopic/Collections/AttributeValueCollection.cs b/OnTopic/Collections/AttributeValueCollection.cs
@@ -6,6 +6,7 @@
 using System;
 using System.Collections.ObjectModel;
 using System.Diagnostics.CodeAnalysis;
+using System.Linq;
 using OnTopic.Attributes;
 using OnTopic.Internal.Diagnostics;
 using OnTopic.Internal.Reflection;
@@ -54,14 +55,37 @@ internal AttributeValueCollection(Topic parentTopic) : base(StringComparer.Invar
     /*==========================================================================================================================
     | METHOD: IS DIRTY
     \-------------------------------------------------------------------------------------------------------------------------*/
+    /// <summary>
+    ///   Determine if <i>any</i> attributes in the <see cref="AttributeValueCollection"/> are dirty.
+    /// </summary>
+    /// <remarks>
+    ///   This method is intended primarily for data storage providers, such as
+    ///   <see cref="Repositories.ITopicRepository"/>, which may need to determine if any attributes are dirty prior to saving
+    ///   them to the data storage medium. Be aware that this does <i>not</i> track any <see cref="AttributeValue"/>s that may
+    ///   have been <i>deleted</i>, nor whether any <see cref="Topic.Relationships"/> have been modified; as such, it may still
+    ///   be necessary to persist changes to the storage medium.
+    /// </remarks>
+    /// <param name="excludeLastModified">
+    ///   Optionally excludes <see cref="AttributeValue"/>s whose keys start with <c>LastModified</c>. This is useful for
+    ///   excluding the byline (<c>LastModifiedBy</c>) and dateline (<c>LastModified</c>) since these values are automatically
+    ///   generated by e.g. the OnTopic Editor and, thus, may be irrelevant updates if no other attribute values have changed.
+    /// </param>
+    /// <returns>True if the attribute value is marked as dirty; otherwise false.</returns>
+    public bool IsDirty(bool excludeLastModified = false)
+      => Items.Any(a =>
+        a.IsDirty &&
+        (!excludeLastModified || !a.Key.StartsWith("LastModified", StringComparison.InvariantCultureIgnoreCase))
+      );
+
     /// <summary>
     ///   Determine if a given attribute is marked as dirty. Will return false if the attribute key cannot be found.
     /// </summary>
     /// <remarks>
     ///   This method is intended primarily for data storage providers, such as
     ///   <see cref="OnTopic.Repositories.ITopicRepository"/>, which may need to determine if a specific attribute key is
-    ///   dirty prior to saving it to the data storage medium. Because isDirty is a state of the current attribute value, it
-    ///   does not support inheritFromParent or inheritFromDerived (which otherwise default to true).
+    ///   dirty prior to saving it to the data storage medium. Because <c>IsDirty</c> is a state of the current <see
+    ///   cref="AttributeValue"/>, it does not support <c>inheritFromParent</c> or <c>inheritFromDerived</c> (which otherwise
+    ///   default to <c>true</c>).
     /// </remarks>
     /// <param name="name">The string identifier for the <see cref="AttributeValue"/>.</param>
     /// <returns>True if the attribute value is marked as dirty; otherwise false.</returns>
