README.md

Context Mapper DSL (CML)

ContextMapper is an open source tool providing a Domain-specific Language based on Domain-Driven Design (DDD) patterns for context mapping and service decomposition.

With the ContextMapper DSL language you can express DDD context maps. Once you have modeled your system with the language you can use the provided generators to create UML diagrams, service contracts, and calculate proposals for service decomposition with Service Cutter.

Checkout our website https://contextmapper.org/ to get started. The Context Mapper project has originally been developed as part of research projects at OST (former HSR). You can find the project reports and further background information here.

• Installation links: Context Mapper is available for Visual Studio Code and Eclipse:
  • VS Code:
    • VS Code Marketplace
    • Note: We have only recently published the VS Code extension and it does not support all features yet. Find a feature support table here. We continuously work on the extension and it should support all features soon!
  • Eclipse:
    • Eclipse Marketplace
    • Update Site: https://contextmapper.jfrog.io/artifactory/context-mapper-eclipse/updates/
• Release notes for latest releases

Features

• ContextMapper DSL language support (CML files)
  • Write context maps with bounded contexts and their relationships (Strategic DDD)
  • Specify bounded contexts (Tactic DDD): Tactic DSL based on Sculptor
  • Find examples in our examples repository
  • Consult our online documentation to get detailed language documentation, manuals and how to get started.
• Use our Architectural Refactorings (ARs) to evolve and improve your DDD context maps iteratively.
• Generate graphical Context Maps
• Generate PlantUML component diagram from context map
• Generate PlantUML class diagram from bounded context and/or subdomain (tactic DDD)
• Generate MDSL (micro-) service contracts out of DDD context maps
• Generate generic text files using Freemarker templates
• Generate ServiceCutter input files for service decomposition proposals
• Convert ServiceCutter output back into context map (CML)

System Requirements

To use the ContextMapper DSL (CML) you need the following tools:

• Java JDK (JDK 8 or newer)
• Eclipse or Visual Studio Code
• If you want to use our Context Map generator you need to have Graphviz installed on your system.
  • Ensure that the binaries are part of the PATH environment variable and can be called from the terminal.
  • Especially on Windows this is not the case after the installation of Graphviz. The default installation path is C:\Program Files (x86)\GraphvizX.XX, which means you have to add C:\Program Files (x86)\GraphvizX.XX\bin to your PATH variable.
• You may want to install one of the following two plugins to display the plantUML diagrams directly in Eclipse:
  • Asciidoctor Editor (Update site: https://dl.bintray.com/de-jcup/asciidoctoreditor)
  • PlantUML Eclipse Plugin (Update site: http://hallvard.github.io/plantuml/)
  • Note: Both plugins require Graphviz to be installed on your machine!
  • Alternatively you can use the plantUML online server.

Getting Started

If you want to use our Context Mapper tool, install the plugin in Eclipse or the extension in VS Code:

1. Installation of Context Mapper:
   • Eclipse Marketplace
   • VS Code Marketplace
2. Find a detailed manual how to create your first CML project here.
3. Examples which introduce the language (CML) capabilities can be found here: https://github.com/ContextMapper/context-mapper-examples
4. Further instructions, user guides and documentation can be found on our website https://contextmapper.org/.

Getting Started (Standalone Library Usage)

If you want to use the Context Mapper DSL (CML) language and the generator tools as standalone library within your Java application you can add the following dependency to your project.

Gradle:

implementation 'org.contextmapper:context-mapper-dsl:6.6.0'

Maven:

<dependency>
  <groupId>org.contextmapper</groupId>
  <artifactId>context-mapper-dsl</artifactId>
  <version>6.6.0</version>
</dependency>

In our context-mapper-standalone-example repository you find an example project showing how to include the library within your project. It further contains code examples illustrating how to use the CML models and the generator tools (PlantUML, MDSL, etc.).

Development

If you want to contribute and setup the IDE for this project on your local system follow the following instructions. Here you get the instructions in more details.

Building the Project

The project currently has two builds since we have to use Maven for building the Eclipse plugin but prefer Gradle in the standalone case. With Gradle you can only build the DSL and the IDE (LSP) project. It is further used to deploy these standalone JARs to the Maven central.

Complete Build with Eclipse Plugin (Maven)

The project uses the Maven Wrapper.

After cloning the project it can be built with the following command within the root directory of the project:

./mvnw clean install

Note: This is an Xtext project and the tests which are evaluating the correctness of the language grammar need an additional maven goal besides test to be executed. Use this command if you want to execute the tests:

./mvnw clean integration-test

Of course they are also executed with a clean install.

Standalone Build Only (Gradle)

To build the standalone projects only, you can use the Gradle Wrapper:

./gradlew clean build

Note: If you want to deploy the libraries into your local Maven repository, you need a GPG key to sign the artifacts:

./gradlew clean publishToMavenLocal -Psigning.keyId=<your-gpg-key-id> -Psigning.password=<gpg-passphrase> -Psigning.secretKeyRingFile=<path-to-gpg-keyring-file>

Setup Eclipse IDE

Since this is an Xtext project you need an Eclipse IDE to work on it. Download the Eclipse IDE for Java and DSL Developers from here. The latest version of Eclipse we worked with is 2019-12.

Additional requirements

Before importing the project you need to install the Tycho Configurator m2e connector. This can be done by following these steps:

1. Start your Eclipse
2. Open the maven preferences page: Window -> Preferences -> Maven
3. Under Discovery press the button Open Catalog and search for Tycho. You should find the Tycho Configurator.
4. Select the Configurator and press Finish.
5. An eclipse installation wizard will appear. Go through the wizard to finish the installation and restart eclipse.

Importing the project

After having installed the Tycho Configurator you can import the project with as an existing maven project (Import -> Existing Maven Project).

Build in Eclipse

After importing the project you will have lots of build errors. This is because you have to generate some Xtext sources first. There exists an eclipse launch configuration called 'GenerateContextMappingDSLInfrastructure' delivered with the project. Run this launch configuration (yes, even if there exist build errors). As soon this has completed, execute a clean build with Project -> Clean... -> Clean all projects.

That's it. You should have a clean workspace now without build errors.

Contributing

Contribution is always welcome! Here are some ways how you can contribute:

• Create Github issues if you find bugs or just want to give suggestions for improvements.
• This is an open source project: if you want to code, create pull requests from forks of this repository. Please refer to a Github issue if you contribute this way. In our wiki you can find out how to build the project and setup the development environment locally.
• If you want to contribute to our documentation and user guides on our website https://contextmapper.org/, create pull requests from forks of the corresponding page repo https://github.com/ContextMapper/contextmapper.github.io or create issues there.

Licence

ContextMapper is released under the Apache License, Version 2.0.