Introduced new TopicNotFoundException

In order to provide more fine-tuned error handling of cases where a specific topic is requested from the repository, but cannot be found, we are now returning a new `TopicNotFoundException`. As this derives from the previous `TopicRepositoryException`, this should remain compatible with previous exception handlers, while offerring callers more specificity.

(Though, it's worth noting, there is a bug in `Load(string topicKey)` which trips on the retrieval of the return code from the `GetTopicId` function if no topic is found. As such, it continues to throw an off-target exception. Further, `Load(int topicKey)` previously threw a `NullReferenceException` if a topic wasn't found, which it shouldn't have been doing. Fortunately, it wasn't publicly documented, and no implementers have been catching it, so we're going to treat this as a bug fix, not a breaking change.)

Author: JeremyCaney

OnTopic.Data.Sql/SqlTopicRepository.cs

@@ -80,7 +80,7 @@ public override Topic Load(string? topicKey = null, bool isRecursive = true) {
       \-----------------------------------------------------------------------------------------------------------------------*/
       var connection            = new SqlConnection(_connectionString);
       var command               = new SqlCommand("GetTopicID", connection);
-      int topicId;
+      var topicId               = -1;
 
       command.CommandType       = CommandType.StoredProcedure;
 
@@ -117,6 +117,13 @@ public override Topic Load(string? topicKey = null, bool isRecursive = true) {
         connection.Close();
       }
 
+      /*------------------------------------------------------------------------------------------------------------------------
+      | Validate results
+      \-----------------------------------------------------------------------------------------------------------------------*/
+      if (topicId < 0) {
+        throw new TopicNotFoundException(topicKey);
+      }
+
       /*------------------------------------------------------------------------------------------------------------------------
       | Return topic
       \-----------------------------------------------------------------------------------------------------------------------*/
@@ -177,7 +184,7 @@ public override Topic Load(int topicId, bool isRecursive = true) {
           topic = TopicFactory.Create("Root", "Container");
         }
         else {
-          throw new NullReferenceException($"Load() was unable to successfully load the topic with the TopicID '{topicId}'");
+          throw new TopicNotFoundException(topicId);
         }
       }
 

OnTopic/Repositories/TopicNotFoundException.cs

@@ -0,0 +1,77 @@
+/*==============================================================================================================================
+| Author        Ignia, LLC
+| Client        Ignia, LLC
+| Project       Topics Library
+\=============================================================================================================================*/
+using System;
+using System.Data.Common;
+using System.Runtime.Serialization;
+using OnTopic.Internal.Diagnostics;
+
+namespace OnTopic.Repositories {
+
+  /*============================================================================================================================
+  | CLASS: TOPIC NOT FOUND EXCEPTION
+  \---------------------------------------------------------------------------------------------------------------------------*/
+  /// <summary>
+  ///   The <see cref="TopicNotFoundException"/> will be thrown when a topic is requested from the repository, but one cannot be
+  ///   found and there is not a logical fallback.
+  /// </summary>
+  /// <remarks>
+  ///   As the <see cref="TopicNotFoundException"/> derives from both <see cref="TopicRepositoryException"/> and <see
+  ///   cref="DbException"/>, it retains compatability with previous exception handling, while offering callers the option of
+  ///   capturing a more specific error for this individual use case.
+  /// </remarks>
+  [Serializable]
+  public class TopicNotFoundException: TopicRepositoryException {
+
+    /*==========================================================================================================================
+    | CONSTRUCTOR: TOPIC NOT FOUND EXCEPTION
+    \-------------------------------------------------------------------------------------------------------------------------*/
+    /// <summary>
+    ///   Initializes a new <see cref="TopicNotFoundException" /> instance.
+    /// </summary>
+    public TopicNotFoundException() : base() { }
+
+    /// <summary>
+    ///   Initializes a new <see cref="TopicNotFoundException" /> instance based on a missing topic ID.
+    /// </summary>
+    /// <param name="topicId">The requested <see cref="Topic.Id"/> which cannot be found.</param>
+    public TopicNotFoundException(int topicId):
+      base($"The topic {topicId} cannot be found in the repository.") { }
+
+    /// <summary>
+    ///   Initializes a new <see cref="TopicNotFoundException" /> instance based on a missing topic ID.
+    /// </summary>
+    /// <param name="topicId">The requested <see cref="Topic.Id"/> which cannot be found.</param>
+    /// <param name="innerException">The reference to the original, underlying exception.</param>
+    public TopicNotFoundException(int topicId, Exception innerException):
+      base($"The topic {topicId} cannot be found in the repository.", innerException) { }
+
+    /// <summary>
+    ///   Initializes a new <see cref="TopicNotFoundException" /> instance based on a missing topic key.
+    /// </summary>
+    /// <param name="topicKey">The requests <see cref="Topic.Key"/> which cannot be found.</param>
+    public TopicNotFoundException(string? topicKey):
+      base($"The topic {topicKey} cannot be found in the repository.") { }
+
+    /// <summary>
+    ///   Initializes a new <see cref="TopicNotFoundException" /> instance based on a missing topic key.
+    /// </summary>
+    /// <param name="topicKey">The requests <see cref="Topic.Key"/> which cannot be found.</param>
+    /// <param name="innerException">The reference to the original, underlying exception.</param>
+    public TopicNotFoundException(string? topicKey, Exception innerException):
+      base($"The topic {topicKey} cannot be found in the repository.", innerException) { }
+
+    /// <summary>
+    ///   Instantiates a new <see cref="TopicRepositoryException"/> instance for serialization.
+    /// </summary>
+    /// <param name="info">A <see cref="SerializationInfo"/> instance with details about the serialization requirements.</param>
+    /// <param name="context">A <see cref="StreamingContext"/> instance with details about the request context.</param>
+    /// <returns>A new <see cref="InvalidKeyException"/> instance.</returns>
+    protected TopicNotFoundException(SerializationInfo info, StreamingContext context) : base(info, context) {
+      Contract.Requires(info);
+    }
+
+  } //Class
+} //Namespace