Release v5.4.6

Author: socadk

README.md

@@ -18,25 +18,23 @@ This is the "hello world" of cross-platform service contracting, specified in MD
 ~~~
 API description HelloWorldAPI
 
-data type SampleDTO {ID, D} 
+data type SampleDTO {ID, "someData": D<string>} 
 
 endpoint type HelloWorldEndpoint
 exposes 
   operation sayHello 
     expecting payload D<string>  
     delivering payload SampleDTO
 
-API provider HelloWorldAPIProvider1
-  offers HelloWorldEndpoint
-
-API client HelloWorldAPIClient1
-  consumes HelloWorldEndpoint
+API provider HelloWorldAPIProvider
+  offers HelloWorldEndpoint at endpoint location "http://localhost:8080"
+  via protocol HTTP binding resource Home at "/hello"
 ~~~
 
 As the example shows, the MDSL grammar defines two related specification languages:
 
 1. An *API description language*: API `endpoints type`s (a.k.a. service contracts types) can be defined, including their operations; API client and providers of instances of these endpoint types can be specified elaborately, including Service Level Agreements (SLAs).
-2. A *data contract language* providing a type system for DTRs in request and response messages (which is very compact): `data type SampleDTO {ID, D}`.
+2. A *data contract language* providing a type system for DTRs in request and response messages (which is very compact): `data type SampleDTO {ID, "someData": D<string>}`. This type definition pairs an ID (without a name) with some string data.
 
 These two languages can be used independently of each other; for instance, data contracts for operations in contract types can also be specified in JSON Schema (or XML Schema). Specifications do not have to be complete to be useful (e.g., in early stages of service design); tools will be expected to check that, use defaults, etc. 
 

changelog.md

@@ -1,5 +1,19 @@
 ## MDSL Change Log (and Release Notes)
 
+V5.4.6, February 2022
+
+* Blog posts featuring quick fixes and flow modeling extensions in action: 
+    * <https://ozimmer.ch/practices/2022/01/20/StoryDrivenServiceDesignDemo.html>
+    * <https://ozimmer.ch/practices/2022/01/13/EventDrivenServiceDesignDemo.html>
+    * (from 2021) <https://medium.com/olzzio/domain-driven-service-design-with-context-mapper-and-mdsl-d5a0fc6091c2>
+* MDSL2JaamSim and JaamSim2MDSL transformations/template-based generation and supporting genmodel extensions
+    * <https://ozimmer.ch//practices/2022/02/01/ProcessOrientedServiceDesignDemo.html>
+* Documentation enhancements
+* Bug fix AND SketchMiner generation (getter for case check, not instanceof)
+* bug fix fgm process view: AND->JOIN events do not terminate flow
+* JaamSim layout improvements (FTL template V2.4.2)
+* Sample model for P-SOAD blog post
+
 V5.4.5, January 2022
 
 * Improved quick fixes (INFORMATION_HOLDER_RESOURCE operation generation, addWishList for AP and TR requests)
@@ -227,4 +241,4 @@ V0.93b, May 10, 2019 (experimental):
 * Only `V<int>` supported as parameter role/type pair, `Value<int>` removed to avoid confusion with `<<stereotypes>>`
 * `<<Identifier>>` and `<<Link>>` and `<<Metadata>>` now available as pattern stereotypes (`<<Entity>>` was supported already)
 
-Also see GitHub [release notes](https://github.com/Microservice-API-Patterns/MDSL-Specification/releases).
+Also see GitHub [release notes](https://github.com/Microservice-API-Patterns/MDSL-Specification/releases).

docs/flows.md

@@ -9,7 +9,7 @@ copyright: Olaf Zimmermann, 2021.  All rights reserved.
 Orchestration Flows
 ===================
 
-_Note:_ The status of the language concepts specified here is [*Experimental Preview*](https://microservice-api-patterns.org/patterns/evolution/ExperimentalPreview.html). Concepts and their tool support might still change in future versions of MDSL.
+_Note:_ The status of the language concepts specified here is [*Experimental Preview*](https://microservice-api-patterns.org/patterns/evolution/ExperimentalPreview.html). Concepts and their tool support have been validated, for instance via code generation to multiple target languages (see below). They are rather stable now; many examples and test cases exist. However, they might still change in future versions of MDSL.
 
 ## Use Cases (When to Specify)
 
@@ -22,12 +22,14 @@ _Note:_ The status of the language concepts specified here is [*Experimental Pre
 <!-- 
 Early "E-SOAD":
 
-* Application flows in inside a service
+* Application flows inside a service
 * Service orchestration, API operation call sequencing
 * EIP-style integration flows (asynch., pipes and filters)
 * Testing (mocking, staging)
 -->
 
+*News (Jan 13, 2022)*: The blog post and demo script ["Event-Driven Service Design: Five Steps from Event Storming to OpenAPI and Camel Flow"](https://ozimmer.ch/practices/2022/01/13/EventDrivenServiceDesignDemo.html) features the MDSL flow modeling concepts in action.
+
 ## Simple Flow Steps 
 
 The following basic flow was generated from the [sample story scenario](./scenarios) with one of the quick fix [transformations](./soad.md) in the [MDSL tools](./tools.md):
@@ -73,21 +75,29 @@ command Command1 emits event Event1 o Event2
 command Command2 emits event Event1 x Event2
 ~~~
 
-Two or more events may be part of a join/aggregate step:
+Two or more events may be part of a join, modeling the [Aggregator](https://www.enterpriseintegrationpatterns.com/Aggregator.html) pattern:
 
 ~~~
-event Command1Done + Command2Done triggers command JoinCommand
-event Event1 + Event2 + FlowTerminated trigger command TerminateCommand + CleanupCommand
+event Command1Done + Command2Done trigger command JoinedContinuationCommand
 ~~~
 
-Note that commands cannot be joined in a single rule. To express alternative event emission (by different commands), it is possible to write:
+Event joining *may* express that something can only happen when two (or more) commands have been executed previously.
+
+Unlike events, commands cannot be joined in a single rule. Alternative event emission (by two or more commands) can be expressed:
 
 ~~~
 command Command1 emits event Event1
 command Command2 emits event Event1
 ~~~
 
-Event joining is required to express that something can only happen when two commands have been executed. 
+The same works for events:
+
+~~~
+event Event 1 triggers Command1
+event Event 2 triggers Command1
+~~~
+
+Either Event1 or Event2 (or both) trigger Command1.
 
 ## Versioning 
 
@@ -105,7 +115,7 @@ The [Version Identifier](https://microservice-api-patterns.org/patterns/evolutio
 
 ## Grammar Excerpts 
 
-*Note:* This is an optional language concept. The flow grammar is subject to change still.
+<!-- *Note:* This is an optional language concept. The flow grammar is subject to change still. -->
 
 ### Flow and flow steps (with technology binding)
 

docs/generators/async-api.md

@@ -275,7 +275,13 @@ More information on the `asyncapi-generator` that we used in this example can be
 
 - The generator does not support security policies.
 - A channel can only transfer messages of one data type.
-- The generator is not yet supported in the CLI.
+- The generator does not work when invoked in the Command Line Interface (CLI). 
+
+<!-- 
+Xtext/Xtend problem: generated class experiences NullPointer exception in 
+io.mdsl.generator.asyncapi.AsyncApiGenerator.compile(AsyncApiGenerator.java:160), line is: 
+QualifiedName _fullyQualifiedName = this._iQualifiedNameProvider.getFullyQualifiedName(serviceSpecificationInstance);
+-->
 
 # Other Generators
 Also checkout our other generators:

docs/generators/graphql.md

@@ -17,10 +17,10 @@ In Eclipse, the generator resides in the MDSL context menu:
 
 <a href="./.../../media/eclipse-graphql-generator-context-menu.png">![GraphQL Generator Context Menu in Eclipse](./.../../media/eclipse-graphql-generator-context-menu.png)</a>
 
-If you work with the CLI, the following command generates the GraphQL specification:
+The following CLI command generates the GraphQL specification:
 
 ```bash
-./mdsl -i model.mdsl -g graphql
+mdsl -i model.mdsl -g graphql
 ```
 
 _Hint:_ Both tools generate the Graphql file into the `src-gen` folder which is located in the projects root directory (Eclipse) or the directory from which the `mdsl` command has been called (CLI). Both tools create the directory automatically in case it does not already exist.
@@ -149,7 +149,7 @@ To validate whether the generated `*.graphql` file, many IDE plugins/extensions
  * [GraphQL extensions for Visual Studio Code](https://marketplace.visualstudio.com/items?itemName=GraphQL.vscode-graphql)
  * [graphqleditor.com](https://graphqleditor.com/)
 
-The [graphqleditor.com](https://graphqleditor.com/) online tool provides an editor that compiles the schema and features a graphical representation of the model (a login/account might be required):
+[graphqleditor.com](https://graphqleditor.com/) provides an editor that compiles the schema and features a graphical representation of the model (an account might be required):
 
 <a target="_blank" href="./../media/graphqleditor.com-screenshot.png">![graphqleditor.com Screenshot](./../media/graphqleditor.com-screenshot.png)</a>
 
@@ -223,7 +223,7 @@ server.listen().then(({ url }) => {
 
 ```
 
-Finally, you just have to implement some resolvers that actually return some data. For our example above, we implemented the following resolver that answers the _lookupPapersFromAuthor_ query:
+Finally, implement some resolvers that actually return some data. For our example above, we implemented the following resolver that answers the _lookupPapersFromAuthor_ query:
 
 ```js
 const papers = {
@@ -309,7 +309,7 @@ mutation createPaper {
 **Note:** The mutation implementation just returns a fake object and does not persist the new paper item. It can therefore not be queried after the insertion mutation has been executed.
 
 #### Client
-Based on [this tutorial](https://www.apollographql.com/docs/react/get-started/) we can now also create a simple React client that calls the query implemented above.
+Based on [this tutorial](https://www.apollographql.com/docs/react/get-started/), we can now also create a simple React client that calls the query implemented above.
 
 Just create a project and initialize it with the following commands:
 
@@ -400,7 +400,7 @@ function App() {
 render(<App />, document.getElementById("root"));
 ```
 
-**Note** that we used the URL `localhost:4000` to connect to our Apollo server started above.
+Note that we used the URL `localhost:4000` to connect to our Apollo server started above.
 
 When adding the following start scripts to your `package.json` file, you can start the client with `npm start`:
 
@@ -429,10 +429,10 @@ An easy way to get an impression of how the code generator works is by using the
 
 <a target="_blank" href="./../media/code-generator-live-demo.png">![Code Generator Live Demo](./../media/code-generator-live-demo.png)</a>
 
-We created an example Java (Spring Boot) application that uses the code generator. You find the complete example project [here](https://github.com/Microservice-API-Patterns/MDSL-Specification/tree/master/examples/graphql-example/spring-boot-example/).
+There is an example Java (Spring Boot) application that uses the code generator. You find the complete example project [here](https://github.com/Microservice-API-Patterns/MDSL-Specification/tree/master/examples/graphql-example/spring-boot-example/).
 
 #### Create Spring Boot (Java) Application
-First, we created a classic Spring Boot project with [Spring initializr](https://start.spring.io/) (Gradle project).
+Start with a classic Spring Boot project with [Spring Initializr](https://start.spring.io/) (Gradle project).
 
 In order to use the code generator, add the following Gradle plugin:
 
@@ -476,6 +476,8 @@ Then, create a `package.json` file for calling the generator via yarn:
 }
 ```
 
+Note that the dependencies might been updated when you read this; use a version that suits you. <!-- TODO v55 use latest ones (see https://github.com/Microservice-API-Patterns/MDSL-Specification/security/dependabot) -->
+
 In addition, create a `codegen.yml` file to configure the code generator:
 
 ```yml
@@ -491,7 +493,15 @@ generates:
 
 As you can see, we expect the GraphQL schema under `src/main/resources/schema.graphql`. We copied our example schema from the top of this page into the corresponding folder.
 
-Now we can call `./gradlew yarn` to call the generator for the first time. From this time on, `./gradlew clean build` will always generate the sources into the `io.mdsl.graphql.javaexampleapp.generated` package.
+Now we can call 
+
+> `gradlew yarn` <!-- TODO v55 not working, lock file needs to be crated first (manual step) -->
+
+to invoke the generator for the first time. From now on, 
+
+> `gradlew clean build` 
+
+will always generate the sources into the `io.mdsl.graphql.javaexampleapp.generated` package.
 
 Based on the generated types we implemented one of the resolver interfaces. Again, the _lookupPapersFromAuthor_ operation: 
 
@@ -567,13 +577,24 @@ public class GraphQLProvider {
 }
 ```
 
-**Note** that we had to provide implementations for our custom scalars (_Void_ and _Raw_). You find it in our [example project](https://github.com/Microservice-API-Patterns/MDSL-Specification/tree/master/examples/graphql-example/spring-boot-example/).
+Note that we had to provide implementations for our custom scalars (_Void_ and _Raw_). You find it in our [example project](https://github.com/Microservice-API-Patterns/MDSL-Specification/tree/master/examples/graphql-example/spring-boot-example/).
 
-The Spring Boot application can now be started with `./gradlew clean bootRun` (please adopt the command invocation to your OS). As soon as the application is started, you can run the same query as we did before with Apollo. The following screenshot shows our test with Postman:
+The Spring Boot application can now be started with `gradlew clean bootRun` (please adopt the command invocation to your OS). As soon as the application is started, you can run the same query as we did before with Apollo. The following screenshot shows our test with Postman:
 
 <a target="_blank" href="./../media/spring-boot-test-with-postman.png">![Test Spring Boot server with Postman](./../media/spring-boot-test-with-postman.png)</a>
 
-That's it. This was a short introduction what you can do with the GraphQL schemas generated by the MDSL tool. Try it out with your own MDSL model, or let [Context Mapper](https://contextmapper.org/docs/mdsl/) generate one for your from your Domain-Driven Design [bounded contexts](https://contextmapper.org/docs/bounded-context/)!
+<!-- 
+    query {
+      lookupPapersFromAuthor(anonymousInput: {anonymous1: "Olaf Zimmermann"}) {
+        entries {
+          title
+          authors
+          venue
+        }
+      }
+-->
+
+This was a short introduction what you can do with the GraphQL schemas generated by the MDSL tool. Try it out with your own MDSL model, or let [Context Mapper](https://contextmapper.org/docs/mdsl/) generate one for your from your Domain-Driven Design [bounded contexts](https://contextmapper.org/docs/bounded-context/)!
 
 
 # Other Generators

docs/generators/jolie.md

@@ -20,20 +20,20 @@ In Eclipse, you find the generator in the MDSL context menu:
 
 <a href="./../media/eclipse-jolie-generator-context-menu.png">![Jolie Generator Context Menu in Eclipse](./../media/eclipse-jolie-generator-context-menu.png)</a>
 
-If you work with the CLI, the following command generates the Jolie specification:
+When working with the CLI, the following command generates the Jolie specification:
 
 ```bash
-./mdsl -i model.mdsl -g jolie
+mdsl -i model.mdsl -g jolie
 ```
 
-_Hint:_ Both tools generate the Graphql file into the `src-gen` folder which is located in the projects root directory (Eclipse) or the directory from which the `mdsl` command has been called (CLI). Both tools create the directory automatically in case it does not already exist.
+_Hint:_ Both plugin and CLI generate the file into the `src-gen` folder located in the project root directory (Eclipse plugin) or the directory from which the `mdsl` command has been called (CLI). The directory is created automatically in case it does not already exist.
 
 ## Example
 The following example illustrates what the generator produces for an exemplary MDSL contract.
 
 You find the complete sources (incl. generated `*.ol` (Jolie) file) of this example [here](https://github.com/Microservice-API-Patterns/MDSL-Specification/tree/master/examples/jolie-example).
 
-We use the following MDSL model which was an outcome of this [blogpost](https://ozimmer.ch/practices/2020/06/10/ICWEKeynoteAndDemo.html) to illustrate our generator outputs:
+We use the following MDSL model, featured in this [blog post](https://ozimmer.ch/practices/2020/06/10/ICWEKeynoteAndDemo.html), to illustrate our generator outputs:
 
 ```
 API description ReferenceManagementServiceAPI