Ensure consistent usage of the "service" terminology

[davidkopp]

As a developer it is crucial to have a clear and unambiguous understanding of the terms that are used escpecially regarding the term "service". Unfortunately the term "service" is overloaded and its meaning takes on different shades depending on the context.

In MICO we have to differentiate between at least 3 different meanings:

• MICO Service is the resource that is managed by the MICO system, is part of the MICO domain model and relates to the term "micro-service". Such a MICO Service originates either from a GitHub repository or from DockerHub.

• Kubernetes Service "is an abstraction which defines a logical set of Pods and a policy by which to access them - sometimes called a micro-service". Pods themselves "serve as unit of deployment, horizontal scaling, and replication". (quoted by Kubernetes documentation The relationship between a MICO Service and a Kubernetes Service is quite confusing because of following association:

  • MICO Service → Kubernetes Deployment
  • MICO Service Interface → Kubernetes Service (MICO Service Interface is a different resource within the mico system, but is part of a MICO Service, actually it is a 1:n releationship)

• Service in a Domain-Driven Design have different meanings. To be honest we don't have applied DDD in MICO, however I think the terms used in DDD are quite helpful to understand the different meanings of the Service term. A good article about this topic is Services in Domain-Driven Design (DDD). Here my summary about the 3 Service terms in DDD:

  • Domain Service is part of the domain layer that extends the domain model with more business logic. A Domain Service adds operations to the model in ubiquitous language (not CRUD, that would be a Repository), but is completely stateless. Within the MICO system we don't really have Domain Services. Currently the most domain logic is placed in the Controllers.

  Side note: KubernetesNameNormalizer could be considered as a Domain Service because it extends the domain knowledge with logic regarding the naming of the domain model entity MicoService.

  • Application Service lives outside of the domain layer. It exposes the functionality of the domain to other application layers as an API. As a hosting environment for the execution of domain logic, it is a convenient point to inject various gateways such as a repository or wrappers for external services. An application service retrieve the information required by an entity, effectively setting up the execution environment, and provide it to the entity. For example for the use-case of importing MicoServices based on GitHub repositories the Application Service GitHubCrawler exists.

  • Infrastructure Service is used to abstract the technical concerns (messaging, notifications, email, retrieving data from external services etc.). For example the ImageBuilder is a infrastructure service to perform the build task of images that is part of a deployment.

  Side note: An Application Service like DeploymentService would be a perfect supplement for the current MICO architecture that uses the ImageBuilder instance. However this service does currently not exist, because the whole logic is part of the DeploymentController.

Furthermore we have to consider the terminology of a service in the context of the Spring Framework and how DDD could be applied in Spring based web applications. In DDD the Controller is considered to be part of the UI layer. The Spring Framework annotation type Service relates to the definition of a Domain Service. The official documentation also mentions, that a class annotated with @Service is a "Business Service Facade" (in the Core J2EE patterns sense).

In issue #537 it was suggested to use the Java EE Pattern Boundary-Control-Entity Pattern that uses different terms like Broker (instead of Service) and Resource (instead of Controller). The renaming was introduced in PR #538. Unfortunately it was already merged into master.

Tasks:

• [ ] Find a consistent wording of the term MICO Service, e.g. camel casing (MicoService) for better usage in the code (consider the future naming of the project → M3Service?)
• [ ] Add more precisely descriptions to our glossary
• [ ] Evaluate a good package name for the business layer and possibly rename it.

---

My proposal regarding the package naming is to use the terms of Spring and DDD and not use the Boundary-Control-Entity Pattern. For example the introduced term ServiceBroker is also be misleading. The Open Service Broker API specifies a Service Broker as a component that is "responsible for advertising a catalog of service offerings and service plans to the marketplace, and acting on requests from the marketplace for provisioning, binding, unbinding, and deprovisioning" (quoted by Open Service Broker API).

Therefore revert the changes made by PR #538 to go back to the terms Service and Controller to stick to the Spring naming conventions. If we want to have a Domain Service for the entity MicoService we could use the naming MicoServiceDomainService. Sounds ugly, but I think it would be clear. I'm open for better naming options.

Nevertheless it is important to never say just Service. Depending on the current context, use e.g. MICO Service, Kubernetes Service or Domain Service.

[spethso]

In accordance with the PO, there was a refactoring from service to broker