|
| 1 | +--- |
| 2 | +title: MDSL (Micro-)Service Contracts Generator |
| 3 | +permalink: /docs/mdsl/ |
| 4 | +--- |
| 5 | + |
| 6 | +## Introduction and Motivation |
| 7 | +The [Microservices Domain Specific Language (MDSL)](https://socadk.github.io/MDSL/) is a DSL to specify (micro-)service contracts |
| 8 | +and data representations realizing API Description patterns from [Microservice API Patterns (MAP)](https://microservice-api-patterns.org/). |
| 9 | + |
| 10 | +With our [MDSL](https://socadk.github.io/MDSL/) generator you can automatically produce (micro-)service contracts out of you strategic |
| 11 | +DDD context map written in CML. The generator creates the contracts according to the following mapping, which reflects our proposal |
| 12 | +how we would derive (micro-)services from models based on strategic DDD. The generator aims for providing assistance regarding how your |
| 13 | +system can be implemented in an (micro-)service-oriented architectural style. |
| 14 | + |
| 15 | +### Generator Mapping |
| 16 | + |
| 17 | +| CML Input | MDSL Output | Description | |
| 18 | +|----------------------------------------------------------------------------------------------------------------------------------|----------------------------------------------------|-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| |
| 19 | +| Upstream Bounded Contexts from upstream-downstream [relationships](/docs/context-map/#relationships) | Service Specification (API description) | We create one service specification for each upstream Bounded Context of your Context Map. | |
| 20 | +| [Exposed Aggregates](/docs/context-map/#exposed-aggregates) | Endpoint | Every exposed Aggregate of your upstream Bounded Context results in one endpoint. | |
| 21 | +| Public methods/operations of the [aggregate root entity](/docs/tactic-ddd/#entity) or of [Services](/docs/tactic-ddd/#services). | Operation | Your exposed Aggregates should contain methods/operations, either on the [aggregate root entity](/docs/tactic-ddd/#entity) or in [Services](/docs/tactic-ddd/#services). For every method/operation in those objects we generate an operation in MDSL. | |
| 22 | +| Parameters & return values of methods/operations | Base types or data type specifications if possible | If you use primitive data types in CML, they are mapped to the base types of MDSL. If you refer to objects (such as entities) in CML, we produce a corresponding parameter tree. Types which are not further declared are mapped to abstract, unspecified elements (P). | |
| 23 | +| Upstream Bounded Contexts from upstream-downstream [relationships](/docs/context-map/#relationships) | API provider | For the upstream Bounded Context we also generate an API provider. | |
| 24 | +| Downstream Bounded Contexts from upstream-downstream [relationships](/docs/context-map/#relationships) | API client | Downstream Bounded Contexts are mapped to corresponding API clients. | |
| 25 | + |
| 26 | +### Data Type Mapping |
| 27 | +The base/primitive types are mapped as follows: |
| 28 | + |
| 29 | +| CML type | MDSL type | |
| 30 | +|------------------|---------------------------------------------| |
| 31 | +| String | V<string> | |
| 32 | +| int or Integer | V<int> | |
| 33 | +| long or Long | V<long> | |
| 34 | +| double or Double | V<double> | |
| 35 | +| boolean | V<bool> | |
| 36 | +| Blob | V<blob> | |
| 37 | +| Date | V<string> (no date available in MDSL) | |
| 38 | + |
| 39 | +<div class="alert alert-custom"> |
| 40 | +<strong>Note:</strong> Types in CML are case sensitive. For example: If you write "string" instead of "String", you create a new abstract |
| 41 | +data type instead of using the primitive type "String". |
| 42 | +</div> |
| 43 | + |
| 44 | +If you declare a method with multiple parameters or refer to an object (such as entity or value object) in CML, we generate a corresponding |
| 45 | +parameter tree. For example the following entity would be mapped to the parameter tree below: |
| 46 | + |
| 47 | +CML input: |
| 48 | +``` |
| 49 | +Entity Address { |
| 50 | + String street |
| 51 | + int postalCode |
| 52 | + String city |
| 53 | +} |
| 54 | +``` |
| 55 | +MDSL data type result: |
| 56 | +``` |
| 57 | +data type Address { "street":V<string>, "postalCode":V<int>, "city":V<string> } |
| 58 | +``` |
| 59 | + |
| 60 | +All abstract data types which are not base types and not specified in CML (no references to objects) will produce an abstract, |
| 61 | +unspecified element in [MDSL](https://socadk.github.io/MDSL/), as the following example illustrates: |
| 62 | +``` |
| 63 | +data type JustAnUnspecifiedParameterType P |
| 64 | +``` |
| 65 | + |
| 66 | +### Example |
| 67 | +An example [MDSL](https://socadk.github.io/MDSL/) API description looks as follows: |
| 68 | +``` |
| 69 | +API description CustomerManagementContextAPI |
| 70 | +
|
| 71 | +data type Address { "street":V<string>, "postalCode":V<int>, "city":V<string> } |
| 72 | +data type AddressId P |
| 73 | +data type changeCustomerParameter { "firstname":V<string>, "lastname":V<string> } |
| 74 | +
|
| 75 | +endpoint type CustomersAggregate |
| 76 | + exposes |
| 77 | + operation createAddress |
| 78 | + expecting |
| 79 | + payload Address |
| 80 | + delivering |
| 81 | + payload AddressId |
| 82 | + operation changeCustomer |
| 83 | + expecting |
| 84 | + payload changeCustomerParameter |
| 85 | +
|
| 86 | +API provider CustomerManagementContextProvider |
| 87 | + offers CustomersAggregate |
| 88 | + at endpoint location "http://localhost:8001" |
| 89 | + via protocol "RESTful HTTP" |
| 90 | +
|
| 91 | +API client PolicyManagementContextClient |
| 92 | + consumes CustomersAggregate |
| 93 | +API client CustomerSelfServiceContextClient |
| 94 | + consumes CustomersAggregate |
| 95 | +
|
| 96 | +IPA |
| 97 | +``` |
| 98 | +**Note:** This example has been generated from our [insurance example](https://github.com/ContextMapper/context-mapper-examples/tree/master/src/main/resources/insurance-example) |
| 99 | +which you can find in our [examples repository](https://github.com/ContextMapper/context-mapper-examples). |
| 100 | + |
| 101 | +### Know Limitations |
| 102 | +We are aware of the following generator issues, which may lead to [MDSL](https://socadk.github.io/MDSL/) results which do not compile: |
| 103 | + * If you use reserved keywords of the MDSL language as _Aggregate name_, _Bounded Context name_, _operation name_ or _data type name_ |
| 104 | + in CML, the result may not be valid MDSL. |
| 105 | + * Workaround: Do not use MDSL keywords within your CML model. |
| 106 | + |
| 107 | +## User Guide |
| 108 | +You can generate [MDSL](https://socadk.github.io/MDSL/) (micro-)service contracts from your CML model as follows. |
| 109 | + |
| 110 | +With a right-click to your CML-file in Eclipse you will find a **Context Mapper** context menu. With the action **MDSL: |
| 111 | +Generate Service Contracts** you generate the contracts for all upstreams in your Context Map: |
| 112 | + |
| 113 | +<a href="/img/mdsl-generator-1.png"></a> |
| 114 | + |
| 115 | +<div class="alert alert-custom"> |
| 116 | +<strong>Note</strong> that the <strong>Context Mapper</strong> menu entry is also available within the context menu uf the CML editor. |
| 117 | +(right-click anywhere in the editor) |
| 118 | +</div> |
| 119 | + |
| 120 | +All [MDSL](https://socadk.github.io/MDSL/) files will be generated into the **src-gen** folder of your project: |
| 121 | + |
| 122 | +<a href="/img/mdsl-generator-2.png"></a> |
| 123 | + |
| 124 | +<div class="alert alert-custom"> |
| 125 | +<strong>Note:</strong> The MDSL Eclipse plugin is not yet available for download (update site). At the moment you can open the *.mdsl |
| 126 | +files with a text editor only (no syntax highlighting and editor support available yet). |
| 127 | +</div> |
| 128 | + |
| 129 | +## MDSL Support |
| 130 | +For further questions regarding [MDSL](https://socadk.github.io/MDSL/) please visit the website [https://socadk.github.io/MDSL](https://socadk.github.io/MDSL) |
| 131 | +or contact Olaf Zimmermann. |
0 commit comments