~~ODT~~

# IT:AD:Design:Briefs:Services #

* [[../|(UP)]]
{{indexmenu>.#2|nsort tsort}}

<pagebreak>
## Document ##


### Purpose ###

The purpose of this document is to outline key elements of the design of a *Core Service* of the current *System*.


### Synopsis ###

Eric Evan's seminal book introduced a development pattern called *Domain Driven Design (DDD)* appropriate for non-trivial enterprise applications. DDD principles applied at the design level, combined with Robert Martin's SOLID development principles applied at the development level, are the two most significant factors for significantly decreasing confusion over the the intent, scope and organisation of application design.






### Background ###



<pagebreak>
## Views ##


### Context View ###
*Services* are required within all applications meeting the organisation's *Design Principles* – specifically, meeting *Domain Driven Design*(([[../Domain Driven Design/]])) design patterns.



### Definition View ###

Requirements were developed for this service. The requirements are available in the appendices, summarized below:


<list ?r "Ref-Id" ?ti [wiki] "Ref-Title">
  ?r is a: requirement
  optional {
    ?r Id: ?id
  }
  optional {
    ?r Title: ?ti
  }
  optional {
    ?r Tags: ?tg
  }
  ?tg ~ [Services]
  sort {
    ?id (asc)
  }
</list>


### Design View


#### Contract Backed

SOLID principles lead to a development style that emphasises modularity by depending (via Dependency Injection) on other Services in such a way as to to allow a required Service to be replaced with another service without the dependent Service having to change. In other words, the dependent Service can reasonably expect its original Contract of Service with the required Service to not be changed.

In .NET framework languages (such as C#) this is achieved by developing first the Contract, then developing a Service that meets that Contract.

<sxh c#>
interface IFooService {
  void DoSomething();
  string SaySomething();
}
class FooService : IFooService {
  void DoSomething(){SaySomething();};
  string SaySomething(){return "Hello";}
}
</sxh> 

Services that require the above Service state int their Constructor that they require the functionality of FooService, without expecting it to be delivered by FooService:

<sxh C#>
class BarService: IBarService {
  private readonly IFooService _fooService;
  public BarService(IFooService fooService){_fooService = fooService;}
  void SayHiBritishLike(){return _fooService.SaySomething();}
}
</sxh>

In the above code, at no point in time:
* was `FooService` created in the code (`new` something`Service` is actively avoided)


<uml>
!includeurl http://skysigal.com/_media/resources/configuration/plantuml/minimalist.txt

together {
interface IService1 
interface IService2 
}

together {
class Service1
class Service2
}
IService1 <|.. Service1  


IService2 <|.. Service2  

Service2 --> IService1
</uml>




<pagebreak>
## Appendices ##

### Glossary ###

* **Domain Driven Design:** an software development approach based on placing the project's focus on domains – both their model and their logic – and initiating a creative collaboration and dialogue between technical and domain experts in order to iteratively refine a conceptual model that addresses particular domain problems. Key development concepts of DDD are listed below5):
  * **Entities:** An object that is not defined by its attributes, but rather by a thread of continuity and its identity. In other words, an object with an ID.
Value Object: An object that contains attributes but has no conceptual identity. They should be treated as immutable.
  * **Aggregate:** a collection of objects that are bound together by a root entity, otherwise known as an aggregate root . The aggregate root guarantees the consistency of changes being made within the aggregate by forbidding external objects from holding references to its members. Your car is an aggregate of several objects. One of which is engine block with an ID (an Entity).
  * **Domain Event:** a domain object that defines an event (something that happens). A domain event is an event that domain experts care about.
Service: When an operation does not conceptually belong to any object. Following the natural contours of the problem, you can implement these operations in services.
  * **Repository:** A Object management service wrapped around specialized storage.
  * **Factory:** a Method for creating domain objects should delegate to a specialized Factory object such that alternative implementations may be easily interchanged.


### Requirements ###

<data requirement  #SFREQ-cw6m8>
  Guid: 
  Id: SFREQ-cw6m8
  Title: Service class *constructors* `MUST` define as parameters the *contract* of any required dependency services.
  Tags: [Services], [Code]
  Stakeholders: [Developers]
  Summary [wiki]: To adhere to LSP design patterns as well as avoid the duplicate construction of singelton services, dependencies should be injected into the the constructor:\\ `class FooService : IFooService {`\\     `private readonly IBarService _barService;`\\     `public Foo(IBarService barService) {_barService = barService;}`\\     `public Do(_barService.Do();}`\\   `}`\\ \\ 
</data>

<data requirement  #SFREQ-cw5x6>
  Guid: 
  Id: SFREQ-cw5x6
  Title: Service class names `MUST` end with a suffix of `Service`.
  Tags: [Services], [Code]
  Stakeholders: [Developers]
  Summary [wiki]: For code maintainability quality objectives, Services `MUST` be clearly marked as such.\\ \\ By having a standard suffix, build servers can more readily scan code for undesired patterns such as `new [Something]Service(`  \\ \\   
</data>


<data requirement  #SFREQ-cvrx6>
  Guid: 0ab1333e-37b4-4426-8555-8f7b8aa6c512
  Id: SFREQ-cvrx6
  Title: When possible, Services `MUST` be backed by Contracts.
  Tags: [Services], [Service], [Core Service]
  Stakeholders: [Developers]
  Summary [wiki]: In languages that provide Contracts, use them to apply `Liskov's Substitution Principle` (`LSP`) in order to improve modularity and maintainability of the code base.
  Statement [wiki]: **Requirement:**\\ When possible, Services `MUST` be backed by Contracts.\\ \\ **Rational:**\\ For modularity and maintainability reasons, apply `Liskov's Substitution Principle` (`LSP`).\\ \\ **Context**:\\ In languages that allow Contracts (eg: `.NET`, not `Javascript`).\\ \\ **Impact**\\  \\ **Comments:**\\ The use of Contracts are hard for beginner, mid-level, and support developers to understand, but development tools (eg: *Resharper*) have made it easier to manage highly decoupled code bases. \\ \\ 
</data>



### Resources ###

* [[https://en.wikipedia.org/wiki/Domain-driven_design|Domain Driven Design]]
* https://www.amazon.com/dp/0321125215