You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Copy file name to clipboardExpand all lines: _docs/architectural-refactorings/architectural-refactorings.md
+18-1
Original file line number
Diff line number
Diff line change
@@ -6,6 +6,10 @@ image: /img/cm-og-image.png
6
6
7
7
This section provides a documentation of all [architectural refactorings (ARs)](https://www.infoq.com/articles/architectural-refactoring/) available in the Context Mapper tool.
8
8
9
+
<divclass="alert alert-custom">
10
+
<strong>Note:</strong> Architectural Refactorings (AR) are not yet supported in our new Visual Studio Code extension. We continuously work on the extension and will support them soon! To apply the ARs to your CML model you have to use the Eclipse plugin for now. You can find a feature support table for Eclipse and VS Code <ahref="/docs/ide/">here</a>.<br/><br/>The AR "Split Bounded Context by Owner" is already supported now (as an example to illustrate how they will be integrated to VS Code).
11
+
</div>
12
+
9
13
## Motivation: Why Refactoring?
10
14
The provided refactorings ensure that the result is always a correct CML model which compiles without errors.
11
15
If you perform similar changes manually, you also have to fix errors that occur manually within the [Context Map](/docs/context-map/).
@@ -49,7 +53,20 @@ The following ARs to change Context Map relationships are currently implemented:
49
53
## Examples
50
54
You can find [input and corresponding output examples](https://github.com/ContextMapper/context-mapper-examples/tree/master/src/main/cml/architectural-refactorings) for all ARs listed above in our [examples repository](https://github.com/ContextMapper/context-mapper-examples).
51
55
52
-
## How to apply Architectural Refactorings (ARs)
56
+
## How to apply Architectural Refactorings
57
+
58
+
### Visual Studio Code
59
+
In VS Code we suggest the application of Architectural Refactorings via code actions. If your cursor is on a CML object on which an AR can be applied, a light bulb shows up:
60
+
61
+
<ahref="/img/architectural-refactoring-handling-in-vscode-1.png"></a>
62
+
63
+
In the case illustrated above, the _PolicyManagementContext_ contains Aggregates that are maintained by different teams and [Split Bounded Context by Owner (AR-3)](/docs/ar-split-bounded-context-by-owners) can be applied:
64
+
65
+
<ahref="/img/architectural-refactoring-handling-in-vscode-2.png"></a>
66
+
67
+
By clicking on the light bulb and the AR you want to apply the model will be refactored accordingly.
68
+
69
+
### Eclipse
53
70
Architectural refactorings can be applied within the Context Mapper Eclipse plugin by using the context menu in the DSL editor. With a
54
71
right-click on a bounded context or an aggregate the **Context Mapper: Refactor** menu entry appears and lists all refactorings which are applicable to the selected elements:
### How do I create an Eclipse project with a new CML model to start modeling my Context Map?
14
14
Consult the page [Create CML Model](/docs/getting-started-create-project/). It describes how to setup your project to get started with modeling CML Context Maps.
15
15
16
+
### I read about a feature on the Context Mapper website but could not find it in the Visual Studio Code extension. Why?
17
+
We have only recently published Context Mapper for Visual Studio Code and do not support all features yet. You can find a feature support table [here](/docs/ide/). If you need all Context Mapper features, you have to use our Eclipse plugin for now. However, we continuously enhance our VS Code extension and want to support all features soon!
18
+
16
19
### How do I create a new context map?
17
20
Just create a file with the file extension **.cml** (Context Mapping Language). Take a look at our example to get an idea how the file content should look like: [https://github.com/ContextMapper/context-mapper-examples](https://github.com/ContextMapper/context-mapper-examples). Let the code completion and other editor features in Eclipse guide you while completing the map and modeling Bounded Contexts.
Copy file name to clipboardExpand all lines: _docs/generators/context-map-generator.md
+5-16
Original file line number
Diff line number
Diff line change
@@ -81,26 +81,15 @@ Our generator produces the following graphical result for the above Context Map:
81
81
82
82
<ahref="/img/context-map-generator-insurance-sample.png"></a>
83
83
84
-
## User Guide
85
-
The Context Map generator can be used within our Eclipse plugin as described below.
84
+
## Generating Context Maps
85
+
The generators can be called from the context menus of the CML editors in VS Code or Eclipse. A documentation how to call the generators can also be found [here](/docs/generators/#using-the-generators).
86
86
87
-
### System Requirements
87
+
**Note:** All generator outputs will be generated into the *src-gen* folder.
88
+
89
+
### System Requirements for this Generator
88
90
The generator requires [Graphviz](https://www.graphviz.org/) to be installed on your system because it uses it behind the scenes:
89
91
90
92
* Ensure [Graphviz](https://www.graphviz.org/) is installed on your machine.
91
93
* Verify that the binaries of the [Graphviz](https://www.graphviz.org/) installation are part of your PATH environment variable and can be called from the command line, for instance by executing `dot -V` from the command line.
92
94
* In Windows this is not the case after the installation of [Graphviz](https://www.graphviz.org/). The default installation path is
93
95
`C:\Program Files (x86)\GraphvizX.XX`, which means you have to add `C:\Program Files (x86)\GraphvizX.XX\bin` to your PATH variable.
94
-
95
-
### Generating Context Maps
96
-
The generator can be called from the _Context Mapper_ context menu within the CML editor or on the corresponding CML file:
The generators are implemented as commands in VS Code. You can find them in the context menu of the CML editor:
22
+
23
+
<ahref="/img/generators-in-vscode-1.png"></a>
24
+
25
+
Alternatively you find them in the command palette (Ctrl+Shift+P):
26
+
27
+
<ahref="/img/generators-in-vscode-2.png"></a>
28
+
29
+
### Eclipse
19
30
The generators can be accessed through the Context Menu in the project explorer (right-click to *.cml file) or directly in the CML editor as the following screenshot shows:
20
31
21
32
<ahref="/img/generators-context-menu.png"></a>
The generator can be called from the context menus of the CML editors in VS Code or Eclipse. A documentation how to call the generators can also be found [here](/docs/generators/#using-the-generators).
466
+
467
+
**Note:** All generator outputs will be generated into the *src-gen* folder.
468
+
469
+
Eclipse as well as VS Code will ask you to choose a *.ftl file from your filesystem and to define the output file name (which will then be generated into _src-gen_).
476
470
477
471
### Freemarker Version
478
472
Context Mapper uses [Freemarker](https://freemarker.apache.org/), currently Version 2.3.30.
479
473
480
474
## Example Templates
475
+
476
+
### Eclipse
481
477
The Context Mapper Eclipse plugin comes with sample Freemarker templates. Use the _Freemarker Generator Template Examples_ wizard via _File -> New -> Example..._ to create the sample project containing the Freemarker templates:
482
478
483
479
<ahref="/img/screenshot-new-freemarker-example-project-1.png"></a>
484
480
485
481
<ahref="/img/screenshot-new-freemarker-example-project-2.png"></a>
486
482
483
+
### Visual Studio Code
484
+
In VS Code we do not deliver the example templates with the extension itself. However, you can just download the *.ftl files from [here](https://github.com/ContextMapper/context-mapper-dsl/tree/master/org.contextmapper.dsl.ui/samples/freemarker) and use it with our generator in VS Code.
485
+
486
+
### Provided Examples
487
487
The project currently contains the following example templates:
488
488
489
489
* Ubiquitous language glossary written in Markdown (currently a full report)
DDD context maps written in CML. The generator creates the contracts according to the following mapping, which reflects our proposal
11
11
how we would derive (micro-)services from models based on strategic DDD <!-- (submitted for SummerSoC 2020) -->. The generator aims at providing assistance regarding how your system can be implemented as a (micro-)service-oriented architecture.
12
12
13
-
###Language Mapping
13
+
## Language Mapping
14
14
<!-- TODO retrofit SummerSoC paper extensions to this table -->
15
15
16
16
| CML Input | MDSL Output | Description |
@@ -59,7 +59,7 @@ unspecified placeholder element `P` in [MDSL](https://socadk.github.io/MDSL/), a
@@ -105,7 +105,7 @@ An exemplary API description in [MDSL](https://socadk.github.io/MDSL/), generate
105
105
106
106
*Note:* This example has been generated from our [insurance example](https://github.com/ContextMapper/context-mapper-examples/tree/master/src/main/cml/insurance-example), which you can find in our [examples repository](https://github.com/ContextMapper/context-mapper-examples).
107
107
108
-
###Microservice API Patterns (MAP) Decorators
108
+
## Microservice API Patterns (MAP) Decorators
109
109
The MDSL language allows modelers to specify the roles of endpoints and operations according to the endpoint- and operation-level
110
110
[responsibility patterns in MAP](https://microservice-api-patterns.org/patterns/responsibility/). Our generators match the corresponding pattern names in comments on Aggregates and methods. The following CML code illustrates how
111
111
the MAP patterns can be added in CML. In this case we use the _Information Holder Resource_ pattern on the Aggregate level and the _Retrieval Operation_ pattern
@@ -151,7 +151,7 @@ The patterns are detected by our generator and mapped to the corresponding langu
151
151
152
152
As illustrated above, the patterns on the endpoint/resource level are added with the _serves as_ keyword and on the operation level with the _with responsibility_ keyword. In the following we list the supported patterns:
Please refer to the pattern texts on the MAP website for explanations of these decorators.
172
170
173
-
## User Guide
174
-
You can generate [MDSL](https://socadk.github.io/MDSL/) (micro-)service contracts from your CML model as follows.
171
+
## Generating the MDSL Contracts
172
+
The generators can be called from the context menus of the CML editors in VS Code or Eclipse. A documentation how to call the generators can also be found [here](/docs/generators/#using-the-generators).
175
173
176
-
When you a right-click on a CML file in Eclipse, you a **Context Mapper** context menu will pop up. The action *MDSL:
177
-
Generate Service Contracts* allows you to generate the contracts for all upstreams in your Context Map:
174
+
**Note:** All generator outputs will be generated into the *src-gen* folder.
<strong>Note:</strong> The MDSL Eclipse plugin is not yet available for download on an Eclipse update site. At the moment you can open the `*.mdsl` files with a text editor only (with no syntax highlighting and editor support). You can also request access to the MDSL repository on GitHub by [contacting the MAP team](https://microservice-api-patterns.org/about).
192
-
</div>
193
-
194
-
### Protected Regions
176
+
## Protected Regions
195
177
After you have generated an MDSL contract, you can add protected regions for **data types**, **endpoint types**, **API providers**, and **API clients** if you want to modify parts of the contract and protect them from being overwritten. The following example shows the corresponding comments that are required to begin and end the four different protected regions:
196
178
197
179
<divclass="highlight"><pre><span></span><spanclass="c">// Generated from DDD Context Map 'Insurance-Example_Context-Map.cml' at 21.10.2019 17:48:52 CEST.</span>
@@ -275,4 +257,4 @@ For example, you can move a set of _data types_ into the corresponding protected
275
257
</pre></div>
276
258
277
259
## MDSL Support
278
-
The current version of our MDSL generator is compatible with the MDSL version _1.2.0_. For further questions regarding [MDSL](https://socadk.github.io/MDSL/), please visit its website [https://socadk.github.io/MDSL](https://socadk.github.io/MDSL).
260
+
The current version of our MDSL generator is compatible with the MDSL version _3.1.1_. For further questions regarding [MDSL](https://socadk.github.io/MDSL/), please visit its website [https://socadk.github.io/MDSL](https://socadk.github.io/MDSL).
0 commit comments