Merge pull request #8 from wintoncode/generic-types-not-methods

Internalised implementations, provided factories, and moved generics …

Author: iscottb122

README.md

@@ -9,39 +9,33 @@ A facade library useful for [Entity](https://github.com/wintoncode/Winton.Domain
 
 This implementations allow multiple types to be transparently stored in one collection using 'wrapper' documents with type discriminators and namespaced IDs (for entities). It can be tempting for those from a traditional SQL background to provision a separate collection per type. However, this is often unnecessarily expensive, especially if much of the reserved throughput for a given collection is unused. Taking advantage of the "schemaless" nature of a document store, such as DocumentDb, can both reduce cost and simplify infrastructural complexity. This implementation provides an easy way to work with a single collection within a bounded context (within which persisted type names are unique) while outwardly still achieving the desired level of strong typing. There really is a schema, but the database doesn't need to know about it.
 
-## Types
+## Facade Types
 
-### IEntityFacade
-
-An abstraction layer over [Entity](https://github.com/wintoncode/Winton.DomainModelling.Abstractions#entity) CRUD operations in DocumentDb. Provides strong typed Create, Read, **Upsert**, Delete, and Query methods.
-
-### EntityFacade
+Note that the default implementations are currently **incompatible with partitioned collections**. This restriction could potentially be lifted in a future version, at the expense of implementation complexity (and probably a leakier abstraction). However, for applications requiring large collections, where partitioning is actually needed, the conveniences provided by this facade are unlikely to be suitable anyway.
 
-The default implementation of `IEntityFacade`. The Create method supports automatic ID generation for string-serializable ID types, otherwise IDs must be set before creating.
+### IEntityFacade
 
-Note that this implementation is currently **incompatible with partitioned collections**. This restriction could potentially be lifted in a future version, at the expense of implementation complexity (and probably a leakier abstraction). However, for applications requiring large collections, where partitioning is actually needed, the conveniences provided by this facade are unlikely to be suitable anyway.
+An abstraction layer over [Entity](https://github.com/wintoncode/Winton.DomainModelling.Abstractions#entity) CRUD operations in DocumentDb. Provides strong typed Create, Read, **Upsert**, Delete, and Query methods. The Create method supports automatic ID generation for string-serializable ID types, otherwise IDs must be set before creating.
 
 ### IValueObjectFacade
 
 An abstraction layer over Value Object operations in DocumentDb. Provides strong typed Create, Delete, and Query methods.
 
-### ValueObjectFacade
-
-The default implementation of `IValueObjectFacade`.
-
-Note that this implementation is currently **incompatible with partitioned collections**. This restriction could potentially be lifted in a future version, at the expense of implementation complexity (and probably a leakier abstraction). However, for applications requiring large collections, where partitioning is actually needed, the conveniences provided by this facade are unlikely to be suitable anyway.
-
 ## Usage
 
-The constructors for both `EntityFacade` and `ValueObjectFacade` take a [Database](https://docs.microsoft.com/en-us/dotnet/api/microsoft.azure.documents.database), a [DocumentCollection](https://docs.microsoft.com/en-us/dotnet/api/microsoft.azure.documents.documentcollection), and an [IDocumentClient](https://docs.microsoft.com/en-us/dotnet/api/microsoft.azure.documents.idocumentclient). Of course, resolving all dependencies from a DI container is preferred, but for clarity they can be manually constructed as
+The default implementations of both `IEntityFacade` and `IValueObjectFacade` should be created from their provided factories. These can each be constructed from an [IDocumentClient](https://docs.microsoft.com/en-us/dotnet/api/microsoft.azure.documents.idocumentclient). Their Create methods both take a [Database](https://docs.microsoft.com/en-us/dotnet/api/microsoft.azure.documents.database) and a [DocumentCollection](https://docs.microsoft.com/en-us/dotnet/api/microsoft.azure.documents.documentcollection). Of course, resolving all dependencies from a DI container is preferred, but for clarity they can be manually constructed as
 
 ```csharp
+IDocumentClient documentClient = new DocumentClient(...);
+
 Database database = new Database { Id = "AllTheData" };
 DocumentCollection documentCollection = new DocumentCollection { Id = "AccountingData" };
-IDocumentClient documentClient = new DocumentClient(...);
 
-IEntityFacade entityFacade = new EntityFacade(database, documentCollection, documentClient);
-IValueObjectFacade valueObjectFacade = new ValueObjectFacade(database, documentCollection, documentClient);
+IEntityFacadeFactory entityFacadeFactory = new EntityFacadeFactory(documentClient);
+IValueObjectFacadeFactory valueObjectFacadeFactory = new ValueObjectFacadeFactory(documentClient);
+
+IEntityFacade<Account, AccountId> entityFacade = entityFacadeFactory.Create<Account, AccountId>(database, documentCollection);
+IValueObjectFacade<AccountType> valueObjectFacade = valueObjectFacadeFactory.Create<AccountType>(database, documentCollection);
 ```
 
 Consider some application with an "Accounting" domain containing 2 entity types, `Account` and `Transaction`, each with a [strong typed](https://tech.winton.com/2017/06/strong-typing-a-pattern-for-more-robust-code/) ID. Note that both ID types use [SingleValueConverter](https://github.com/wintoncode/Winton.Extensions.Serialization.Json#singlevalueconverter), so they are string-serializable. The "Accounting" domain also contains a value object type, `AccountType`, used as reference data.
@@ -155,43 +149,43 @@ The respective implementations of these repositories, potentially defined in a s
 ```csharp
 internal sealed class AccountRepository : IAccountRepository
 {
-    private readonly IEntityFacade _entityFacade;
+    private readonly IEntityFacade<Account, AccountId> _entityFacade;
 
-    public AccountRepository(IEntityFacade entityFacade)
+    public AccountRepository(IEntityFacade<Account, AccountId> entityFacade)
     {
         _entityFacade = entityFacade;
     }
 
     public async Task<AccountId> Create(Account account)
     {
-        return (await _entityFacade.Create<Account, AccountId>(account)).Id;
+        return (await _entityFacade.Create(account)).Id;
     }
 
     public async Task<Account> Get(AccountId id)
     {
-        return await _entityFacade.Read<Account, AccountId>(id);
+        return await _entityFacade.Read(id);
     }
 
     ...
 }
 
 internal sealed class TransactionRepository : ITransactionRepository
 {
-    private readonly IEntityFacade _entityFacade;
+    private readonly IEntityFacade<Transaction, TransactionId> _entityFacade;
 
-    public TransactionRepository(IEntityFacade entityFacade)
+    public TransactionRepository(IEntityFacade<Transaction, TransactionId> entityFacade)
     {
         _entityFacade = entityFacade;
     }
 
     public async Task<TransactionId> Create(Transaction transaction)
     {
-        return (await _entityFacade.Create<Transaction, TransactionId>(transaction)).Id;
+        return (await _entityFacade.Create(transaction)).Id;
     }
 
     public IEnumerable<Transaction> GetAllSentBy(AccountId accountId)
     {
-        return _entityFacade.Query<Transaction, TransactionId>()
+        return _entityFacade.Query()
                             .Where(t => t.Sender == accountId)
                             .AsEnumerable();
     }
@@ -201,21 +195,21 @@ internal sealed class TransactionRepository : ITransactionRepository
 
 internal sealed class AccountTypeRepository : IAccountTypeRepository
 {
-    private readonly IValueObjectFacade _valueObjectFacade;
+    private readonly IValueObjectFacade<AccountType> _valueObjectFacade;
 
-    public AccountTypeRepository(IValueObjectFacade valueObjectFacade)
+    public AccountTypeRepository(IValueObjectFacade<AccountType> valueObjectFacade)
     {
         _valueObjectFacade = valueObjectFacade;
     }
 
     public async Task Create(AccountType accountType)
     {
-        await _valueObjectFacade.Create<AccountType>(accountType);
+        await _valueObjectFacade.Create(accountType);
     }
 
     public IEnumerable<AccountType> GetAll()
     {
-        return _valueObjectFacade.Query<AccountType>()
+        return _valueObjectFacade.Query()
                                  .AsEnumerable();
     }
 

src/Winton.DomainModelling.DocumentDb/EntityFacade.cs

@@ -10,24 +10,14 @@
 
 namespace Winton.DomainModelling.DocumentDb
 {
-    /// <inheritdoc />
-    /// <summary>
-    ///     An abstraction layer over <see cref="Entity{TEntityId}" /> CRUD operations in DocumentDb. Allows multiple types to
-    ///     be transparently stored in one collection using a 'wrapper' document type with a type discriminator and namespaced
-    ///     ID.
-    /// </summary>
-    public sealed class EntityFacade : IEntityFacade
+    internal sealed class EntityFacade<TEntity, TEntityId> : IEntityFacade<TEntity, TEntityId>
+        where TEntity : Entity<TEntityId>
+        where TEntityId : IEquatable<TEntityId>
     {
         private readonly Database _database;
         private readonly IDocumentClient _documentClient;
         private readonly DocumentCollection _documentCollection;
 
-        /// <summary>
-        ///     Initializes a new instance of the <see cref="EntityFacade" /> class.
-        /// </summary>
-        /// <param name="database">The DocumentDb database.</param>
-        /// <param name="documentCollection">The DocumentDb collection. Partitioned collections are not supported.</param>
-        /// <param name="documentClient">A document client implementation.</param>
         public EntityFacade(Database database, DocumentCollection documentCollection, IDocumentClient documentClient)
         {
             if (documentCollection.PartitionKey.Paths.Any())
@@ -40,18 +30,7 @@ public EntityFacade(Database database, DocumentCollection documentCollection, ID
             _documentClient = documentClient;
         }
 
-        /// <inheritdoc />
-        /// <summary>
-        ///     Create an <see cref="T:Winton.DomainModelling.Entity`1" /> of a specified type. Supports automatic ID generation
-        ///     for <see cref="T:System.String" />-serializable ID types, otherwise IDs must be set before creating.
-        /// </summary>
-        /// <typeparam name="TEntity">The type of the entity.</typeparam>
-        /// <typeparam name="TEntityId">The ID type of the entity.</typeparam>
-        /// <param name="entity">The <see cref="T:Winton.DomainModelling.Entity`1" /> to persist.</param>
-        /// <returns>The created <see cref="T:Winton.DomainModelling.Entity`1" />.</returns>
-        public async Task<TEntity> Create<TEntity, TEntityId>(TEntity entity)
-            where TEntity : Entity<TEntityId>
-            where TEntityId : IEquatable<TEntityId>
+        public async Task<TEntity> Create(TEntity entity)
         {
             var document = new EntityDocument<TEntity, TEntityId>(entity.WithId<TEntity, TEntityId>());
 
@@ -62,31 +41,12 @@ public async Task<TEntity> Create<TEntity, TEntityId>(TEntity entity)
             return responseDocument.Entity;
         }
 
-        /// <inheritdoc />
-        /// <summary>
-        ///     Delete an <see cref="T:Winton.DomainModelling.Entity`1" /> of a specified type by ID.
-        /// </summary>
-        /// <typeparam name="TEntity">The type of the entity.</typeparam>
-        /// <typeparam name="TEntityId">The ID type of the entity.</typeparam>
-        /// <param name="id">The ID of the <see cref="T:Winton.DomainModelling.Entity`1" /> to delete.</param>
-        /// <returns>A Task.</returns>
-        public async Task Delete<TEntity, TEntityId>(TEntityId id)
-            where TEntity : Entity<TEntityId>
-            where TEntityId : IEquatable<TEntityId>
+        public async Task Delete(TEntityId id)
         {
-            await _documentClient.DeleteDocumentAsync(GetUri<TEntity, TEntityId>(id));
+            await _documentClient.DeleteDocumentAsync(GetUri(id));
         }
 
-        /// <inheritdoc />
-        /// <summary>
-        ///     Query <see cref="T:Winton.DomainModelling.Entity`1" /> instances of a specified type.
-        /// </summary>
-        /// <typeparam name="TEntity">The type of the entity.</typeparam>
-        /// <typeparam name="TEntityId">The ID type of the entity.</typeparam>
-        /// <returns>An <see cref="T:System.Linq.IQueryable`1" />.</returns>
-        public IQueryable<TEntity> Query<TEntity, TEntityId>()
-            where TEntity : Entity<TEntityId>
-            where TEntityId : IEquatable<TEntityId>
+        public IQueryable<TEntity> Query()
         {
             string entityType = EntityDocument<TEntity, TEntityId>.GetDocumentType();
 
@@ -95,22 +55,11 @@ public IQueryable<TEntity> Query<TEntity, TEntityId>()
                                   .Select(x => x.Entity);
         }
 
-        /// <inheritdoc />
-        /// <summary>
-        ///     Read an <see cref="T:Winton.DomainModelling.Entity`1" /> of a specified type by ID.
-        /// </summary>
-        /// <typeparam name="TEntity">The type of the entity.</typeparam>
-        /// <typeparam name="TEntityId">The ID type of the entity.</typeparam>
-        /// <param name="id">The ID of the <see cref="T:Winton.DomainModelling.Entity`1" /> to read.</param>
-        /// <returns>The <see cref="T:Winton.DomainModelling.Entity`1" /> with the given ID, if it exists, otherwise null.</returns>
-        public async Task<TEntity> Read<TEntity, TEntityId>(TEntityId id)
-            where TEntity : Entity<TEntityId>
-            where TEntityId : IEquatable<TEntityId>
+        public async Task<TEntity> Read(TEntityId id)
         {
             try
             {
-                ResourceResponse<Document> response =
-                    await _documentClient.ReadDocumentAsync(GetUri<TEntity, TEntityId>(id));
+                ResourceResponse<Document> response = await _documentClient.ReadDocumentAsync(GetUri(id));
 
                 EntityDocument<TEntity, TEntityId> responseDocument = (dynamic)response.Resource;
 
@@ -122,17 +71,7 @@ public async Task<TEntity> Read<TEntity, TEntityId>(TEntityId id)
             }
         }
 
-        /// <inheritdoc />
-        /// <summary>
-        ///     Upsert an <see cref="T:Winton.DomainModelling.Entity`1" /> of a specified type. The ID must be set.
-        /// </summary>
-        /// <typeparam name="TEntity">The type of the entity.</typeparam>
-        /// <typeparam name="TEntityId">The ID type of the entity.</typeparam>
-        /// <param name="entity">The <see cref="T:Winton.DomainModelling.Entity`1" /> to upsert.</param>
-        /// <returns>The upserted <see cref="T:Winton.DomainModelling.Entity`1" />.</returns>
-        public async Task<TEntity> Upsert<TEntity, TEntityId>(TEntity entity)
-            where TEntity : Entity<TEntityId>
-            where TEntityId : IEquatable<TEntityId>
+        public async Task<TEntity> Upsert(TEntity entity)
         {
             if (Equals(entity.Id, default(TEntityId)))
             {
@@ -153,9 +92,7 @@ private Uri GetUri()
             return UriFactory.CreateDocumentCollectionUri(_database.Id, _documentCollection.Id);
         }
 
-        private Uri GetUri<TEntity, TEntityId>(TEntityId id)
-            where TEntity : Entity<TEntityId>
-            where TEntityId : IEquatable<TEntityId>
+        private Uri GetUri(TEntityId id)
         {
             return UriFactory.CreateDocumentUri(
                 _database.Id,

src/Winton.DomainModelling.DocumentDb/EntityFacadeFactory.cs

@@ -0,0 +1,47 @@
+// Copyright (c) Winton. All rights reserved.
+// Licensed under the Apache License, Version 2.0. See LICENSE in the project root for license information.
+
+using System;
+using Microsoft.Azure.Documents;
+
+namespace Winton.DomainModelling.DocumentDb
+{
+    /// <inheritdoc />
+    /// <summary>
+    ///     The default factory to create an <see cref="IEntityFacade{TEntity,TEntityId}" /> for an
+    ///     <see cref="Entity{TEntityId}" /> of a specified type.
+    /// </summary>
+    public sealed class EntityFacadeFactory : IEntityFacadeFactory
+    {
+        private readonly IDocumentClient _documentClient;
+
+        /// <summary>
+        ///     Initializes a new instance of the <see cref="EntityFacadeFactory" /> class.
+        /// </summary>
+        /// <param name="documentClient">A document client implementation.</param>
+        public EntityFacadeFactory(IDocumentClient documentClient)
+        {
+            _documentClient = documentClient;
+        }
+
+        /// <inheritdoc />
+        /// <summary>
+        ///     Create an <see cref="IEntityFacade{TEntity,TEntityId}" /> for an <see cref="Entity{TEntityId}" /> of a specified
+        ///     type. The default implementation allows multiple types to be transparently stored in one collection using a
+        ///     'wrapper' document type with a type discriminator and namespaced ID.
+        /// </summary>
+        /// <typeparam name="TEntity">The type of the entity.</typeparam>
+        /// <typeparam name="TEntityId">The ID type of the entity.</typeparam>
+        /// <param name="database">The DocumentDb database.</param>
+        /// <param name="documentCollection">The DocumentDb collection. Partitioned collections are not supported.</param>
+        /// <returns>The created <see cref="IEntityFacade{TEntity,TEntityId}" />.</returns>
+        public IEntityFacade<TEntity, TEntityId> Create<TEntity, TEntityId>(
+            Database database,
+            DocumentCollection documentCollection)
+            where TEntity : Entity<TEntityId>
+            where TEntityId : IEquatable<TEntityId>
+        {
+            return new EntityFacade<TEntity, TEntityId>(database, documentCollection, _documentClient);
+        }
+    }
+}