Context Mapper

Context Mapper provides a Domain-specific Language (CML) for Domain-Driven Design (DDD) patterns. Key capabilities include:

• Strategic DDD: Write context maps with bounded contexts and their relationships.
• Tactic DDD: Specify bounded contexts using a Tactic DSL based on Sculptor.
• Architectural Refactorings (ARs): Iteratively evolve and improve DDD context maps.
• Code & Diagram Generation:
  • Graphical Context Maps (requires Graphviz).
  • PlantUML Diagrams: Component diagrams (from context maps), Class diagrams (from bounded contexts/subdomains), State diagrams (for aggregate states), and Use case diagrams.
  • MDSL: Generate (micro-) service contracts.
  • Generic Text: Generate files using Freemarker templates.

In Context Mapper Language (CML), domain services should be modeled at the same level as aggregates. This means they should be defined directly inside a BoundedContext object rather than being nested inside an Aggregate.

While the DSL supports the older pattern of modeling services inside aggregates for backwards compatibility, the recommended DDD pattern is to place them within the bounded context to ensure they are treated as first-class citizens alongside aggregates.

When using the Context Mapper PlantUML generator for Use Case diagrams, the layout follows the 'Larman' standard rather than the default PlantUML arrow-based approach.

Key visualization rules:

• Connections: Instead of using arrows, actors are connected to use cases with simple lines.
• Actor Placement: Primary actors are positioned on the left side of the diagram, and secondary actors are positioned on the right side.
• Use Case Flow: Use cases are visualized in a top-to-bottom orientation.

Because Context Mapper is an Xtext project, follow these steps to set up a development environment in Eclipse:

1. Download Eclipse: Use the Eclipse IDE for Java and DSL Developers (version 2019-12 or newer is recommended).
2. Import Project: Use Import -> Existing Maven Project.
3. Generate Infrastructure: You will see build errors initially because Xtext sources must be generated.
   • Locate the Eclipse launch configuration named GenerateContextMappingDSLInfrastructure.
   • Run this configuration.
4. Clean Workspace: After the generation completes, execute Project -> Clean... -> Clean all projects to resolve remaining build errors.

To use Context Mapper as an interactive modeling tool, install the appropriate plugin for your IDE:

• Visual Studio Code: Install the extension from the VS Code Marketplace.
• Eclipse:
  • Install via the Eclipse Marketplace.
  • Or use the Update Site: https://contextmapper.org/eclipse-update-site/.

If you want to integrate the Context Mapper DSL (CML) and its generator tools (PlantUML, MDSL, etc.) directly into your Java application, add the following dependency to your build configuration.

For a complete implementation guide and code examples, refer to the context-mapper-standalone-example repository.

// Gradle
implementation 'org.contextmapper:context-mapper-dsl:6.12.0'

<!-- Maven -->
<dependency>
  <groupId>org.contextmapper</groupId>
  <artifactId>context-mapper-dsl</artifactId>
  <version>6.12.0</version>
</dependency>

The project uses different build tools depending on the target:

Complete Build (Eclipse Plugin)

Use the Maven Wrapper to build the full project, including the Eclipse plugin.

# Standard build
./mvnw clean install

# Build with integration tests
./mvnw clean integration-test

Standalone Build (DSL and LSP)

Use the Gradle Wrapper to build only the standalone DSL and IDE (LSP) projects.

./gradlew clean build

To publish to your local Maven repository (requires a GPG key):

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

To run Context Mapper, ensure your system meets these requirements:

• Java: JDK 11 or newer.
• IDE: Eclipse or Visual Studio Code.
• Graphviz: Required if using the Context Map generator.
  • You must add the Graphviz bin directory to your system PATH.
  • Windows Note: If installed to C:\Program Files (x86)\GraphvizX.XX, you must manually add C:\Program Files (x86)\GraphvizX.XX\bin to your PATH variable.
• PlantUML Visualization (Eclipse only): To view diagrams directly in Eclipse, install either Asciidoctor Editor or the PlantUML Eclipse Plugin. Both require Graphviz to be installed.

This project uses the MADR template to document design and architectural decisions. To create a new decision record, use the standard MADR template format.

https://github.com/adr/madr/blob/develop/template/adr-template.md