refactor(serialization): introduce new interfaces and composition root at JsonApiOutputFormatter

removes logic from JsonApiOutputFormatter and into JsonApiWriter. this also reduces the large method parameter requirements throughout the affected classes

Author: jaredcnance

.vscode/launch.json

@@ -1,41 +1,11 @@
 {
     "version": "0.2.0",
     "configurations": [
-        {
-            "name": ".NET Core Launch (web)",
-            "type": "coreclr",
-            "request": "launch",
-            "preLaunchTask": "build",
-            "program": "${workspaceRoot}/src/JsonApiDotNetCoreExample/bin/Debug/netcoreapp1.0/JsonApiDotNetCoreExample.dll",
-            "args": [],
-            "cwd": "${workspaceRoot}/src/JsonApiDotNetCoreExample",
-            "stopAtEntry": false,
-            "launchBrowser": {
-                "enabled": false,
-                "args": "${auto-detect-url}",
-                "windows": {
-                    "command": "cmd.exe",
-                    "args": "/C start ${auto-detect-url}"
-                },
-                "osx": {
-                    "command": "open"
-                },
-                "linux": {
-                    "command": "xdg-open"
-                }
-            },
-            "env": {
-                "ASPNETCORE_ENVIRONMENT": "Development"
-            },
-            "sourceFileMap": {
-                "/Views": "${workspaceRoot}/Views"
-            }
-        },
         {
             "name": ".NET Core Attach",
             "type": "coreclr",
             "request": "attach",
-            "processId": "${command.pickProcess}"
+            "processId": "${command:pickProcess}"
         }
     ]
 }

src/JsonApiDotNetCore/Builders/DocumentBuilder.cs

@@ -8,12 +8,18 @@
 
 namespace JsonApiDotNetCore.Builders
 {
-    public class DocumentBuilder
+    public class DocumentBuilder : IDocumentBuilder
     {
         private IJsonApiContext _jsonApiContext;
         private IContextGraph _contextGraph;
         private readonly IRequestMeta _requestMeta;
 
+        public DocumentBuilder(IJsonApiContext jsonApiContext)
+        {
+            _jsonApiContext = jsonApiContext;
+            _contextGraph = jsonApiContext.ContextGraph;
+        }
+
         public DocumentBuilder(IJsonApiContext jsonApiContext, IRequestMeta requestMeta)
         {
             _jsonApiContext = jsonApiContext;
@@ -73,9 +79,8 @@ private Dictionary<string, object> _getMeta(IIdentifiable entity)
             if(_jsonApiContext.Options.IncludeTotalRecordCount)
                 builder.Add("total-records", _jsonApiContext.PageManager.TotalRecords);
 
-            var requestMeta = _requestMeta?.GetMeta();
-            if(requestMeta != null)
-                builder.Add(requestMeta);
+            if(_requestMeta != null)
+                builder.Add(_requestMeta.GetMeta());
 
             var meta = builder.Build();
             if(meta.Count > 0) return meta;

src/JsonApiDotNetCore/Builders/IDocumentBuilder.cs

@@ -0,0 +1,11 @@
+using System.Collections.Generic;
+using JsonApiDotNetCore.Models;
+
+namespace JsonApiDotNetCore.Builders
+{
+    public interface IDocumentBuilder
+    {
+        Document Build(IIdentifiable entity);
+        Documents Build(IEnumerable<IIdentifiable> entities);
+    }
+}

src/JsonApiDotNetCore/Extensions/IServiceCollectionExtensions.cs

@@ -4,6 +4,7 @@
 using JsonApiDotNetCore.Data;
 using JsonApiDotNetCore.Formatters;
 using JsonApiDotNetCore.Internal;
+using JsonApiDotNetCore.Serialization;
 using JsonApiDotNetCore.Services;
 using Microsoft.AspNetCore.Http;
 using Microsoft.AspNetCore.Mvc;
@@ -57,6 +58,9 @@ public static void AddJsonApiInternals<TContext>(this IServiceCollection service
             services.AddScoped<JsonApiRouteHandler>();
 
             services.AddScoped<IMetaBuilder, MetaBuilder>();
+            services.AddScoped<IDocumentBuilder, DocumentBuilder>();
+            services.AddScoped<IJsonApiSerializer, JsonApiSerializer>();
+            services.AddScoped<IJsonApiWriter, JsonApiWriter>();
         }
 
         public static void SerializeAsJsonApi(this MvcOptions options, JsonApiOptions jsonApiOptions)

src/JsonApiDotNetCore/Formatters/IJsonApiWriter.cs

@@ -0,0 +1,10 @@
+using System.Threading.Tasks;
+using Microsoft.AspNetCore.Mvc.Formatters;
+
+namespace JsonApiDotNetCore.Formatters
+{
+    public interface IJsonApiWriter
+    {
+        Task WriteAsync(OutputFormatterWriteContext context);
+    }
+}

src/JsonApiDotNetCore/Formatters/JsonApiOutputFormatter.cs

@@ -1,14 +1,7 @@
 using System;
-using System.Text;
 using System.Threading.Tasks;
-using JsonApiDotNetCore.Internal;
-using JsonApiDotNetCore.Models;
-using JsonApiDotNetCore.Serialization;
-using JsonApiDotNetCore.Services;
 using Microsoft.AspNetCore.Mvc.Formatters;
 using Microsoft.Extensions.DependencyInjection;
-using Microsoft.Extensions.Logging;
-using Newtonsoft.Json;
 
 namespace JsonApiDotNetCore.Formatters
 {
@@ -26,81 +19,8 @@ public bool CanWriteResult(OutputFormatterCanWriteContext context)
 
         public async Task WriteAsync(OutputFormatterWriteContext context)
         {
-            if (context == null)
-                throw new ArgumentNullException(nameof(context));
-
-            var logger = GetService<ILoggerFactory>(context)?
-                .CreateLogger<JsonApiOutputFormatter>();
-
-            var requestMeta = GetService<IRequestMeta>(context);
-
-            logger?.LogInformation("Formatting response as JSONAPI");
-
-            var response = context.HttpContext.Response;
-            using (var writer = context.WriterFactory(response.Body, Encoding.UTF8))
-            {
-                var jsonApiContext = GetService<IJsonApiContext>(context);
-
-                response.ContentType = "application/vnd.api+json";
-                string responseContent;
-                try
-                {
-                    responseContent = GetResponseBody(context.Object, jsonApiContext, requestMeta, logger);
-                }
-                catch (Exception e)
-                {
-                    logger?.LogError(new EventId(), e, "An error ocurred while formatting the response");
-                    var errors = new ErrorCollection();
-                    errors.Add(new Error("400", e.Message));
-                    responseContent = errors.GetJson();
-                    response.StatusCode = 400;
-                }
-
-                await writer.WriteAsync(responseContent);
-                await writer.FlushAsync();
-            }
-        }
-
-        private T GetService<T>(OutputFormatterWriteContext context)
-        {
-            return context.HttpContext.RequestServices.GetService<T>();
-        }
-
-        private string GetResponseBody(object responseObject, 
-            IJsonApiContext jsonApiContext, 
-            IRequestMeta requestMeta, 
-            ILogger logger)
-        {
-            if (responseObject == null)
-                return GetNullDataResponse();
-
-            if (responseObject.GetType() == typeof(Error) || jsonApiContext.RequestEntity == null)
-                return GetErrorJson(responseObject, logger);
-            
-            return JsonApiSerializer.Serialize(responseObject, jsonApiContext, requestMeta);
-        }
-
-        private string GetNullDataResponse()
-        {
-            return JsonConvert.SerializeObject(new Document
-            {
-                Data = null
-            });
-        }
-
-        private string GetErrorJson(object responseObject, ILogger logger)
-        {
-            if (responseObject.GetType() == typeof(Error))
-            {
-                var errors = new ErrorCollection();
-                errors.Add((Error)responseObject);
-                return errors.GetJson();
-            }
-            else
-            {
-                logger?.LogInformation("Response was not a JSONAPI entity. Serializing as plain JSON.");
-                return JsonConvert.SerializeObject(responseObject);
-            }
+            var writer = context.HttpContext.RequestServices.GetService<IJsonApiWriter>();
+            await writer.WriteAsync(context);
         }
     }
 }

src/JsonApiDotNetCore/Formatters/JsonApiWriter.cs

@@ -0,0 +1,93 @@
+using System;
+using System.Text;
+using System.Threading.Tasks;
+using JsonApiDotNetCore.Internal;
+using JsonApiDotNetCore.Models;
+using JsonApiDotNetCore.Serialization;
+using JsonApiDotNetCore.Services;
+using Microsoft.AspNetCore.Mvc.Formatters;
+using Microsoft.Extensions.Logging;
+using Newtonsoft.Json;
+
+namespace JsonApiDotNetCore.Formatters
+{
+    public class JsonApiWriter : IJsonApiWriter
+    {
+        private readonly ILogger<JsonApiWriter> _logger;
+        private readonly IJsonApiContext _jsonApiContext;
+        private readonly IJsonApiSerializer _serializer;
+
+        public JsonApiWriter(IJsonApiContext jsonApiContext, 
+            IJsonApiSerializer serializer, 
+            ILoggerFactory loggerFactory)
+        {
+            _jsonApiContext = jsonApiContext;
+            _serializer = serializer;
+            _logger = loggerFactory.CreateLogger<JsonApiWriter>();
+        }
+
+        public async Task WriteAsync(OutputFormatterWriteContext context)
+        {
+            if (context == null)
+                throw new ArgumentNullException(nameof(context));
+
+            _logger?.LogInformation("Formatting response as JSONAPI");
+
+            var response = context.HttpContext.Response;
+            using (var writer = context.WriterFactory(response.Body, Encoding.UTF8))
+            {
+                response.ContentType = "application/vnd.api+json";
+                string responseContent;
+                try
+                {
+                    responseContent = GetResponseBody(context.Object);
+                }
+                catch (Exception e)
+                {
+                    _logger?.LogError(new EventId(), e, "An error ocurred while formatting the response");
+                    var errors = new ErrorCollection();
+                    errors.Add(new Error("400", e.Message));
+                    responseContent = errors.GetJson();
+                    response.StatusCode = 400;
+                }
+
+                await writer.WriteAsync(responseContent);
+                await writer.FlushAsync();
+            }
+        }
+
+        private string GetResponseBody(object responseObject)
+        {
+            if (responseObject == null)
+                return GetNullDataResponse();
+
+            if (responseObject.GetType() == typeof(Error) || _jsonApiContext.RequestEntity == null)
+                return GetErrorJson(responseObject, _logger);
+            
+            return _serializer.Serialize(responseObject);
+        }
+
+        private string GetNullDataResponse()
+        {
+            return JsonConvert.SerializeObject(new Document
+            {
+                Data = null
+            });
+        }
+
+        private string GetErrorJson(object responseObject, ILogger logger)
+        {
+            if (responseObject.GetType() == typeof(Error))
+            {
+                var errors = new ErrorCollection();
+                errors.Add((Error)responseObject);
+                return errors.GetJson();
+            }
+            else
+            {
+                logger?.LogInformation("Response was not a JSONAPI entity. Serializing as plain JSON.");
+                return JsonConvert.SerializeObject(responseObject);
+            }
+        }
+    }
+}

src/JsonApiDotNetCore/Serialization/IJsonApiSerializer.cs

@@ -0,0 +1,7 @@
+namespace JsonApiDotNetCore.Serialization
+{
+    public interface IJsonApiSerializer
+    {
+        string Serialize(object entity);
+    }
+}

src/JsonApiDotNetCore/Serialization/JsonApiSerializer.cs

@@ -1,38 +1,42 @@
 using System.Collections.Generic;
 using JsonApiDotNetCore.Builders;
 using JsonApiDotNetCore.Models;
-using JsonApiDotNetCore.Services;
 using Newtonsoft.Json;
 
 namespace JsonApiDotNetCore.Serialization
 {
-    public static class JsonApiSerializer
+    public class JsonApiSerializer : IJsonApiSerializer
     {
-        public static string Serialize(object entity, IJsonApiContext jsonApiContext, IRequestMeta requestMeta)
+        private readonly IDocumentBuilder _documentBuilder;
+
+        public JsonApiSerializer(IDocumentBuilder documentBuilder)
+        {
+            _documentBuilder = documentBuilder;
+        }
+
+        public string Serialize(object entity)
         {
             if (entity is IEnumerable<IIdentifiable>)
-                return _serializeDocuments(entity, jsonApiContext, requestMeta);
+                return _serializeDocuments(entity);
 
-            return _serializeDocument(entity, jsonApiContext, requestMeta);           
+            return _serializeDocument(entity);           
         }
 
-        private static string _serializeDocuments(object entity, IJsonApiContext jsonApiContext, IRequestMeta requestMeta)
+        private string _serializeDocuments(object entity)
         {
-            var documentBuilder = new DocumentBuilder(jsonApiContext, requestMeta);
             var entities = entity as IEnumerable<IIdentifiable>;
-            var documents = documentBuilder.Build(entities);
+            var documents = _documentBuilder.Build(entities);
             return _serialize(documents);
         }
 
-        private static string _serializeDocument(object entity, IJsonApiContext jsonApiContext, IRequestMeta requestMeta)
+        private string _serializeDocument(object entity)
         {
-            var documentBuilder = new DocumentBuilder(jsonApiContext, requestMeta);
             var identifiableEntity = entity as IIdentifiable;
-            var document = documentBuilder.Build(identifiableEntity);
+            var document = _documentBuilder.Build(identifiableEntity);
             return _serialize(document);
         }
 
-        private static string _serialize(object obj)
+        private string _serialize(object obj)
         {
             return JsonConvert.SerializeObject(obj, new JsonSerializerSettings {
                 NullValueHandling = NullValueHandling.Ignore

test/JsonApiDotNetCoreExampleTests/Unit/Extensions/IServiceCollectionExtensionsTests.cs

@@ -11,6 +11,8 @@
 using JsonApiDotNetCoreExample.Data;
 using Microsoft.Extensions.Caching.Memory;
 using JsonApiDotNetCoreExample.Models;
+using JsonApiDotNetCore.Serialization;
+using JsonApiDotNetCore.Formatters;
 
 namespace JsonApiDotNetCoreExampleTests.Unit.Extensions
 {
@@ -40,6 +42,9 @@ public void AddJsonApiInternals_Adds_All_Required_Services()
             Assert.NotNull(provider.GetService<IJsonApiContext>());
             Assert.NotNull(provider.GetService<IHttpContextAccessor>());
             Assert.NotNull(provider.GetService<IMetaBuilder>());
+            Assert.NotNull(provider.GetService<IDocumentBuilder>());
+            Assert.NotNull(provider.GetService<IJsonApiSerializer>());
+            Assert.NotNull(provider.GetService<IJsonApiWriter>());
         }
     }
 }