MDSL Tools: Users Guide
At present, two types of MDSL tools are available (more to come):
- Command Line Interface (CLI) tools: validation, technology-specific contract generation
- Eclipse Plugin: editor, API Linter (validation) , technology-specific contract generation
Command Line Interface (CLI) Tools
The CLI tools can validate MDSL files and call our generators from the command line. When calling
mdsl.bat in Windows), the CLI shows you the available parameters:
usage: mdsl -f,--outputFile <arg> The name of the file that shall be generated (only used by Freemarker generator, as we cannot know the file extension). -g,--generator <arg> The generator you want to call. Use one of the following values: oas (Open API Specification), jolie (Jolie), text (arbitraty text file by using a Freemarker template), proto (Protocol Buffers), gen-model-json (Generator model as JSON (exporter)), gen-model-yaml (Generator model as YAML (exporter)) -h,--help Prints this message. -i,--input <arg> Path to the MDSL file for which you want to generate output. -o,--outputDir <arg> The output directory into which the generated files shall be written. By default files are generated into the execution directory. -t,--template <arg> Path to the Freemarker template you want to use. This parameter is only used if you pass 'text' to the 'generator' (-g) parameter.
The MDSL Eclipse plugin provides editing support (syntax highlighting, auto completion, etc.) for our DSL. You can install the plugin in your Eclipse from the following update site:
Once you have installed the plugin successfully, the MDSL editor should open for any file that ends with
.mdsl. You can create one and copy-paste the above hello world example, or find additional examples in this folder.
If you want to check whether the plugin has installed successfully, you can go to the Eclipse “Help” menu, select “About Eclipse IDE” and then “Installation Details”. Two MDSL entries should be there.
The API Linter comes with the MDSL Editor as well as the CLI (see above); every time a file is saved or parsed, a number of validation rules and some simple metrics are evaluated and the results displayed in the Problems view of Eclipse.
In addition to the usual editor features such as syntax highlighting, completion and syntax checking, it implements a few simple semantic validators (as a basic API linter demonstrator):
- The modeler is warned about incomplete and unsuited data types such as
- The constraints of the message exchange patterns such as REQUEST_REPLY, ONE_WAY and NOTIFICATION are validated (if specified).
- Some MAP pattern decorator combination are checked and warned about (for instance, a COMPUTATION_FUNCTION in an INFORMATION_HOLDER_RESOURCE is a modeling smell).
- The number of operations per endpoint is reported; if is likely that the endpoint cannot be mapped to OpenAPI due to a large amount of operations, the user is warned.
An example that features all validators in action can be found in the examples folder of the repository here.
In the MDSL Editor, you can invoke four generators from the “MDSL” entry in the context menu:
- Generate Text File with Freemarker Template
- Generate OpenAPI Specification
- Generate Protocol Buffers Specification
- Generate Jolie Lan Specification
These generator features are also available in the CLI (see above).
IDL Generators: OpenAPI, Proticol Buffers, Jolie
The OpenAPI specification generator maps endpoint types to HTTP resource paths, and operations to HTTP methods/verbs like this:
- If a MAP decorator is used, it is mapped as this:
STATE_CREATION_OPERATIONis transformed to
POSTalso would make sense)
RETRIEVAL_OPERATIONis transformed to
GET(which causes problems if the request message has a complex structure)
STATE_TRANSITION_OPERATIONis transformed to
COMPUTATION_FUNCTIONis transformed to
- If an HTTP verb is used instead of a MAP decorator (
"POST"etc.), it is passed through
- If the operation name suggests CRUDish semantics (or starts with HTTP verb names), it is mapped as this:
- createX is transformed into
- readX and getX are transformed into
- putX is transformed into
- updateX and patchX are transformed into
- deleteX is transformed into
- createX is transformed into
If an HTTP verb appears more than once in a resource endpoint, nothing will be generated on the endpoint type level. An HTTP binding has to be defined then; at present one and only one such binding should be present; the generator will use the first one it finds.
See this demo for the time being (only Open API featured so far).
The entire grammar is available as a data model to the Freemarker templating feature.
Examples of such reports can be found here.
The intermediate model that is available to the template-based generator can be exported:
- Export Generator Model as JSON
- Export Generator Model as YAML
- Quick reference and tutorial.
- Language specification:
- Back to MDSL homepage.
Copyright: Olaf Zimmermann, 2018-2020. All rights reserved. See license information.