Merge branch 'maintenance/mapping-exceptions' into develop

Introduced the more specific `InvalidTypeException` and `MappingModelValidationException`, both of which derive from the existing `TopicMappingException`, in order to provide (even more specific) exceptions for predictable errors with the various topic mapping services.

Currently, the `InvalidTypeException` occurs when the target topic view model determined by the `Topic.ContentType` cannot be retrieved from the `ITypeLookupService`, while the `MappingModelValidationException` occurs when the `ReverseTopicMappingService` discovers a disconnect between the source model and the target `Topic` which might result in an unexpected data integrity or data loss issue when that `Topic` is `Save()`d to the persistence layer.

Author: JeremyCaney

OnTopic/Mapping/InvalidTypeException.cs

@@ -0,0 +1,60 @@
+/*==============================================================================================================================
+| Author        Ignia, LLC
+| Client        Ignia, LLC
+| Project       Topics Library
+\=============================================================================================================================*/
+using System;
+using System.Runtime.Serialization;
+using OnTopic.Internal.Diagnostics;
+using OnTopic.Lookup;
+
+namespace OnTopic.Mapping {
+
+  /*============================================================================================================================
+  | CLASS: INVALID TYPE EXCEPTION
+  \---------------------------------------------------------------------------------------------------------------------------*/
+  /// <summary>
+  ///   The <see cref="InvalidTypeException"/> is thrown when an <see cref="ITopicMappingService"/> implementation requests a
+  ///   target type that cannot be located using the supplied <see cref="ITypeLookupService"/>.
+  /// </summary>
+  /// <remarks>
+  ///   Having one (base) class used for all expected exceptions from the <see cref="ITopicMappingService"/> and other mapping
+  ///   service interfaces allows implementors to capture all exceptions—while, potentially, catching more specific exceptions
+  ///   based on derived classes, if we discover the need for more specific exceptions.
+  /// </remarks>
+  [Serializable]
+  public class InvalidTypeException: TopicMappingException {
+
+    /*==========================================================================================================================
+    | CONSTRUCTOR: INVALID TYPE EXCEPTION
+    \-------------------------------------------------------------------------------------------------------------------------*/
+    /// <summary>
+    ///   Initializes a new <see cref="InvalidTypeException" /> instance.
+    /// </summary>
+    public InvalidTypeException() : base() { }
+
+    /// <summary>
+    ///   Initializes a new <see cref="InvalidTypeException" /> instance with a specific error message.
+    /// </summary>
+    /// <param name="message">The message to display for this exception.</param>
+    public InvalidTypeException(string message) : base(message) { }
+
+    /// <summary>
+    ///   Initializes a new <see cref="InvalidTypeException" /> instance with a specific error message and nested exception.
+    /// </summary>
+    /// <param name="message">The message to display for this exception.</param>
+    /// <param name="innerException">The reference to the original, underlying exception.</param>
+    public InvalidTypeException(string message, Exception innerException) : base(message, innerException) { }
+
+    /// <summary>
+    ///   Instantiates a new <see cref="InvalidTypeException"/> 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 InvalidTypeException(SerializationInfo info, StreamingContext context) : base(info, context) {
+      Contract.Requires(info);
+    }
+
+  } //Class
+} //Namespace

OnTopic/Mapping/MappingModelValidationException.cs

@@ -0,0 +1,64 @@
+/*==============================================================================================================================
+| Author        Ignia, LLC
+| Client        Ignia, LLC
+| Project       Topics Library
+\=============================================================================================================================*/
+using System;
+using System.Runtime.Serialization;
+using OnTopic.Internal.Diagnostics;
+using OnTopic.Mapping.Reverse;
+using OnTopic.Metadata;
+
+namespace OnTopic.Mapping {
+
+  /*============================================================================================================================
+  | CLASS: MAPPING MODEL VALIDATION EXCEPTION
+  \---------------------------------------------------------------------------------------------------------------------------*/
+  /// <summary>
+  ///   The <see cref="MappingModelValidationException"/> is thrown when an <see cref="IReverseTopicMappingService"/>
+  ///   implementation is provided a model that cannot be reliably mapped back to the target <see cref="Topic"/>, thus
+  ///   introducing potential data integrity issues.
+  /// </summary>
+  /// <remarks>
+  ///   The read-only mapping services, such as <see cref="ITopicMappingService"/>, are generally designed to be forgiving of
+  ///   mismatches. By contrast, because the <see cref="IReverseTopicMappingService"/> is intended to update the persistence
+  ///   store, it is generally designed to fail if there are any discrepancies between the source model and the target <see cref
+  ///   ="ContentTypeDescriptor"/>. Given this, the <see cref="MappingModelValidationException"/> is expected to be thrown for
+  ///   validation errors caused by e.g. the <see cref="ReverseTopicMappingService"/>.
+  /// </remarks>
+  [Serializable]
+  public class MappingModelValidationException: TopicMappingException {
+
+    /*==========================================================================================================================
+    | CONSTRUCTOR: MAPPING MODEL VALIDATION EXCEPTION
+    \-------------------------------------------------------------------------------------------------------------------------*/
+    /// <summary>
+    ///   Initializes a new <see cref="MappingModelValidationException" /> instance.
+    /// </summary>
+    public MappingModelValidationException() : base() { }
+
+    /// <summary>
+    ///   Initializes a new <see cref="MappingModelValidationException" /> instance with a specific error message.
+    /// </summary>
+    /// <param name="message">The message to display for this exception.</param>
+    public MappingModelValidationException(string message) : base(message) { }
+
+    /// <summary>
+    ///   Initializes a new <see cref="MappingModelValidationException" /> instance with a specific error message and nested exception.
+    /// </summary>
+    /// <param name="message">The message to display for this exception.</param>
+    /// <param name="innerException">The reference to the original, underlying exception.</param>
+    public MappingModelValidationException(string message, Exception innerException) : base(message, innerException) { }
+
+    /// <summary>
+    ///   Instantiates a new <see cref="MappingModelValidationException"/> 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 MappingModelValidationException(SerializationInfo info, StreamingContext context) : base(info, context) {
+      Contract.Requires(info);
+    }
+
+  } //Class
+} //Namespace

OnTopic/Mapping/README.md

@@ -20,6 +20,7 @@ The [`ITopicMappingService`](ITopicMappingService.cs) provides the abstract inte
   - [Internal Caching](#internal-caching)
   - [`CachedTopicMappingService`](#cachedtopicmappingservice)
     - [Limitations](#limitations)
+- [Exceptions](#exceptions)
 
 ## `TopicMappingService`
 The [`TopicMappingService`](TopicMappingService.cs) provides a concrete implementation that is expected to satisfy the requirements of most consumers. This supports the following conventions.
@@ -186,4 +187,9 @@ While the `CachedTopicMappingService` can be useful for particular scenarios, it
 
 1. It may take up considerable memory, depending on how many permutations of mapped objects the application has. This is especially true since it caches each unique object graph; no effort is made to centralize object instances referenced by e.g. relationships in multiple graphs.
 2. It makes no effort to validate or evict cache entries. Topics whose values change during the lifetime of the `CachedTopicMappingService` will not be reflected in the mapped responses.
-3. If a graph is manually constructed (by e.g. programmatically mapping `Children`) then each instance will be separated cached, thus potentially allowing an instance to be shared between multiple graphs. This can introduce concerns if edge maintenance is important.
+3. If a graph is manually constructed (by e.g. programmatically mapping `Children`) then each instance will be separated cached, thus potentially allowing an instance to be shared between multiple graphs. This can introduce concerns if edge maintenance is important.
+
+## Exceptions
+The topic mapping services will throw a [`TopicMappingException`](TopicMappingException.cs) if a foreseeable exception occurs. Specifically, the exceptions expected will be:
+- **[`InvalidTypeException`](InvalidTypeException.cs):** The [`TopicMappingService`](TopicMappingService.cs) throws this exception if the source `Topic`'s `ContentType` maps to a `TopicViewModel` which cannot be located in the supplied `ITypeLookupService`.
+- **[`MappingModelValidationException`](MappingModelValidationException.cs):** The [`ReverseTopicMappingService`](Reverse/ReverseTopicMappingService.cs) throws this exception if the source model has any discrepancies with the target `Topic` which may introduce unexpected data integrity or data loss once that `Topic` is saved.

OnTopic/Mapping/Reverse/BindingModelValidator.cs

@@ -198,7 +198,7 @@ static internal void ValidateProperty(
       | Handle children
       \-----------------------------------------------------------------------------------------------------------------------*/
       if (configuration.RelationshipType is RelationshipType.Children) {
-        throw new TopicMappingException(
+        throw new MappingModelValidationException(
           $"The {nameof(ReverseTopicMappingService)} does not support mapping child topics. This property should be " +
           $"removed from the binding model, or otherwise decorated with the {nameof(DisableMappingAttribute)} to prevent " +
           $"it from being evaluated by the {nameof(ReverseTopicMappingService)}. If children must be mapped, then the " +
@@ -211,7 +211,7 @@ static internal void ValidateProperty(
       | Handle parent
       \-----------------------------------------------------------------------------------------------------------------------*/
       if (configuration.AttributeKey is "Parent") {
-        throw new TopicMappingException(
+        throw new MappingModelValidationException(
           $"The {nameof(ReverseTopicMappingService)} does not support mapping Parent topics. This property should be " +
           $"removed from the binding model, or otherwise decorated with the {nameof(DisableMappingAttribute)} to prevent " +
           $"it from being evaluated by the {nameof(ReverseTopicMappingService)}."
@@ -222,7 +222,7 @@ static internal void ValidateProperty(
       | Validate attribute type
       \-----------------------------------------------------------------------------------------------------------------------*/
       if (attributeDescriptor is null) {
-        throw new TopicMappingException(
+        throw new MappingModelValidationException(
           $"A '{nameof(sourceType)}' object was provided with a content type set to '{contentTypeDescriptor.Key}'. This " +
           $"content type does not contain an attribute named '{compositeAttributeKey}', as requested by the " +
           $"'{configuration.Property.Name}' property. If this property is not intended to be mapped by the " +
@@ -245,7 +245,7 @@ attributeDescriptor.ModelType is ModelType.NestedTopic &&
         !typeof(ITopicBindingModel).IsAssignableFrom(listType) &&
         listType is not null
       ) {
-        throw new TopicMappingException(
+        throw new MappingModelValidationException(
           $"The '{property.Name}' property on the '{sourceType.Name}' class has been determined to be a " +
           $"{configuration.RelationshipType}, but the generic type '{listType.Name}' does not implement the " +
           $"{nameof(ITopicBindingModel)} interface. This is required for binding models. If this collection is not intended " +
@@ -262,7 +262,7 @@ listType is not null
         attributeDescriptor.ModelType is ModelType.Reference &&
         !typeof(IRelatedTopicBindingModel).IsAssignableFrom(propertyType)
       ) {
-        throw new TopicMappingException(
+        throw new MappingModelValidationException(
           $"The '{property.Name}' property on the '{sourceType.Name}' class has been determined to be a " +
           $"{ModelType.Reference}, but the generic type '{propertyType.Name}' does not implement the " +
           $"{nameof(IRelatedTopicBindingModel)} interface. This is required for references. If this property is not intended " +
@@ -315,7 +315,7 @@ [AllowNull]Type                      listType
       | Validate list
       \-----------------------------------------------------------------------------------------------------------------------*/
       if (!typeof(IList).IsAssignableFrom(property.PropertyType)) {
-        throw new TopicMappingException(
+        throw new MappingModelValidationException(
           $"The '{property.Name}' property on the '{sourceType.Name}' class maps to a relationship attribute " +
           $"'{attributeDescriptor.Key}', but does not implement {nameof(IList)}. Relationships must implement " +
           $"{nameof(IList)} or derive from a collection that does."
@@ -326,7 +326,7 @@ [AllowNull]Type                      listType
       | Validate relationship type
       \-----------------------------------------------------------------------------------------------------------------------*/
       if (!new[] { RelationshipType.Any, RelationshipType.Relationship }.Contains(configuration.RelationshipType)) {
-        throw new TopicMappingException(
+        throw new MappingModelValidationException(
           $"The '{property.Name}' property on the '{sourceType.Name}' class maps to a relationship attribute " +
           $"'{attributeDescriptor.Key}', but is configured as a {configuration.RelationshipType}. The property should be " +
           $"flagged as either {nameof(RelationshipType.Any)} or {nameof(RelationshipType.Relationship)}."
@@ -337,7 +337,7 @@ [AllowNull]Type                      listType
       | Validate the correct base class for relationships
       \-----------------------------------------------------------------------------------------------------------------------*/
       if (!typeof(IRelatedTopicBindingModel).IsAssignableFrom(listType)) {
-        throw new TopicMappingException(
+        throw new MappingModelValidationException(
           $"The '{property.Name}' property on the '{sourceType.Name}' class has been determined to be a " +
           $"{configuration.RelationshipType}, but the generic type '{listType?.Name}' does not implement the " +
           $"{nameof(IRelatedTopicBindingModel)} interface. This is required for binding models. If this collection is not " +

OnTopic/Mapping/Reverse/README.md

@@ -11,7 +11,7 @@ The [`IReverseTopicMappingService`](IReverseTopicMappingService.cs) and its conc
 Unlike the `TopicMappingService`, the `ReverseTopicMappingService` will not map any plain-old C# object (POCO); binding models must implement the `ITopicBindingModel` interface, which requires a `Key` and `ContentType` property; without these, it can't create a new `Topic` instance. For relationships, it expects implementation of the `IReverseTopicMappingService`, which has a single `UniqueKey` property.
 
 ## Model Validation
-The `ReverseTopicMappingService` is deliberately more conservative than the `TopicMappingService` since assumptions in mapping won't just impact a view, but will be committed to the database.  As a result, all properties are validated against the corresponding `ContentTypeDescriptor`'s `AttributeDescriptors` collection. If a property cannot be mapped back to an attribute, an `InvalidOperationException` is thrown.
+The `ReverseTopicMappingService` is deliberately more conservative than the `TopicMappingService` since assumptions in mapping won't just impact a view, but will be committed to the database.  As a result, all properties are validated against the corresponding `ContentTypeDescriptor`'s `AttributeDescriptors` collection. If a property cannot be mapped back to an attribute, a `MappingModelValidationException` is thrown.
 
 > _Important:_ If a binding model contains properties that are not intended to be mapped, they must explicitly be excluded from mapping using the `[DisableMapping]` attribute.