Skip to content

Commit deb09f1

Browse files
atextoratextor
authored
Merge pull request #218 from bci-oss/feature/OMP-SDK-98-custom-model-resolution
Custom model resolution in bamm-cli
2 parents d53aeef + 5e89af5 commit deb09f1

25 files changed

+578
-104
lines changed

‎documentation/developer-guide/modules/tooling-guide/pages/bamm-cli.adoc‎

Lines changed: 36 additions & 16 deletions
Original file line numberDiff line numberDiff line change
@@ -38,32 +38,38 @@ The available options and their meaning can also be seen in the help text of the
3838
| help | Get overview of all commands | `bamm help`
3939
| help <subcommand> | Get help for a specific subcommand | `bamm help aspect`
4040
| aspect help <aspect subcommand> | Get help for `aspect` subcommands | `bamm aspect help validate`
41-
| aspect <model> validate | Validate Aspect Model | `bamm aspect AspectModel.ttl validate`
41+
.2+| aspect <model> validate | Validate Aspect Model | `bamm aspect AspectModel.ttl validate`
42+
| _--custom-resolver_ : use an external resolver for the resolution of the model elements | `bamm aspect AspectModel.ttl validate --custom-resolver myresolver.sh`
4243
.2+| aspect <model> prettyprint | Pretty-print Aspect Model | `bamm aspect AspectModel.ttl prettyprint`
43-
| _--output, -o_ : the output will be saved to the given file | `bamm aspect AspectModel.ttl prettyprint -o c:\Results\PrettyPrinted.ttl`
44+
| _--output, -o_ : the output will be saved to the given file | `bamm aspect AspectModel.ttl prettyprint -o c:\Results\PrettyPrinted.ttl`
4445
.2+| aspect <model> migrate | Migrate Aspect Model to the latest BAMM version | `bamm aspect AspectModel.ttl migrate AspectModel.ttl`
45-
| _--output, -o_ : the output will be saved to the given file | `bamm aspect AspectModel.ttl migrate AspectModel.ttl -o c:\Results\MigratedModel.ttl`
46-
.4+| aspect <model> to html | Generate HTML documentation for an Aspect Model | `bamm aspect AspectModel.ttl to html`
47-
| _--output, -o_ : the output will be saved to the given file | `bamm aspect AspectModel.ttl to html -o c:\Model.html`
48-
| _--css, -c_ : CSS file with custom styles to be included in the generated HTML documentation | `bamm aspect AspectModel.ttl to html -c c:\styles.css`
49-
| _--language, -l_ : The language from the model for which the HTML should be generated (default: en) | `bamm aspect AspectModel.ttl to html -l de`
50-
.3+| aspect <model> to png | Generate PNG diagram for Aspect Model | `bamm aspect AspectModel.ttl to png`
51-
| _--output, -o_ : output file path (default: stdout); as PNG is a binary format, it is strongly recommended to output the result to a file by using the -o option or the console redirection operator '>')|
46+
| _--output, -o_ : the output will be saved to the given file | `bamm aspect AspectModel.ttl migrate AspectModel.ttl -o c:\Results\MigratedModel.ttl`
47+
.5+| aspect <model> to html | Generate HTML documentation for an Aspect Model | `bamm aspect AspectModel.ttl to html`
48+
| _--output, -o_ : the output will be saved to the given file | `bamm aspect AspectModel.ttl to html -o c:\Model.html`
49+
| _--css, -c_ : CSS file with custom styles to be included in the generated HTML documentation | `bamm aspect AspectModel.ttl to html -c c:\styles.css`
50+
| _--language, -l_ : The language from the model for which the HTML should be generated (default: en) | `bamm aspect AspectModel.ttl to html -l de`
51+
| _--custom-resolver_ : use an external resolver for the resolution of the model elements | `bamm aspect AspectModel.ttl to html --custom-resolver myresolver.bat`
52+
.4+| aspect <model> to png | Generate PNG diagram for Aspect Model | `bamm aspect AspectModel.ttl to png`
53+
| _--output, -o_ : output file path (default: stdout); as PNG is a binary format, it is strongly recommended to output the result to a file by using the -o option or the console redirection operator '>')|
5254
| _--language, -l_ : the language from the model for which the diagram should be generated (default: en)|
53-
.3+| aspect <model> to svg | Generate SVG diagram for Aspect Model | `bamm aspect AspectModel.ttl to svg`
55+
| _--custom-resolver_ : use an external resolver for the resolution of the model elements | `bamm aspect AspectModel.ttl to png --custom-resolver resolver.jar`
56+
.4+| aspect <model> to svg | Generate SVG diagram for Aspect Model | `bamm aspect AspectModel.ttl to svg`
5457
| _--output, -o_ : the output will be saved to the given file |
5558
| _--language, -l_ : the language from the model for which the diagram should be generated (default: en)|
56-
.3+| aspect <model> to dot | Generate https://graphviz.org/doc/info/lang.html[DOT] diagram for Aspect Model | `bamm aspect AspectModel.ttl to dot`
59+
| _--custom-resolver_ : use an external resolver for the resolution of the model elements | `bamm aspect AspectModel.ttl to svg --custom-resolver "java -jar resolver.jar"`
60+
.4+| aspect <model> to dot | Generate https://graphviz.org/doc/info/lang.html[DOT] diagram for Aspect Model | `bamm aspect AspectModel.ttl to dot`
5761
| _--output, -o_ : output file path (default: stdout) |
5862
| _--language, -l_ : the language from the model for which the diagram should be generated (default: en)|
59-
.7+| aspect <model> to java | Generate Java classes from an Aspect Model | `bamm aspect AspectModel.ttl to java`
63+
| _--custom-resolver_ : use an external resolver for the resolution of the model elements |
64+
.8+| aspect <model> to java | Generate Java classes from an Aspect Model | `bamm aspect AspectModel.ttl to java`
6065
| _--output-directory, -d_ : output directory to write files to (default: current directory)|
6166
| _--package-name, -pn_ : package to use for generated Java classes| `bamm aspect AspectModel.ttl to java -pn org.company.product`
6267
| _--no-jackson, -nj_ : disable https://github.com/FasterXML/jackson[Jackson] annotation generation in generated Java classes|
6368
| _--template-library-file, -tlf_ : the path and name of the https://velocity.apache.org/[Velocity] template file containing the macro library|
6469
| _--execute-library-macros, -elm_ : Execute the macros provided in the https://velocity.apache.org/[Velocity] macro library|
6570
| _--static, -s_ : generate Java domain classes for a Static Meta Model|
66-
.12+| aspect <model> to openapi | Generate https://spec.openapis.org/oas/v3.0.3[OpenAPI] specification for an Aspect Model | `bamm aspect AspectModel.ttl to openapi -j`
71+
| _--custom-resolver_ : use an external resolver for the resolution of the model elements |
72+
.13+| aspect <model> to openapi | Generate https://spec.openapis.org/oas/v3.0.3[OpenAPI] specification for an Aspect Model | `bamm aspect AspectModel.ttl to openapi -j`
6773
| _--output, -o_ : output file path (default: stdout) |
6874
| _--api-base-url, -b_ : the base url for the Aspect API used in the https://spec.openapis.org/oas/v3.0.3[OpenAPI] specification| `bamm aspect AspectModel.ttl to openapi -j -b \http://mysite.de`
6975
| _--json, -j_ : generate a JSON specification for an Aspect Model (default format is YAML)|
@@ -75,15 +81,29 @@ The available options and their meaning can also be seen in the help text of the
7581
| _--paging-cursor-based, -pc_ : in case there is more than one paging possibility, it has to be cursor based paging|
7682
| _--paging-offset-based, -po_ : in case there is more than one paging possibility, it has to be offset based paging|
7783
| _--paging-time-based, -pt_ : in case there is more than one paging possibility, it has to be time based paging|
78-
.2+| aspect <model> to json | Generate OpenAPI JSON specification for an Aspect Model | `bamm aspect AspectModel.ttl to json`
84+
| _--custom-resolver_ : use an external resolver for the resolution of the model elements |
85+
.3+| aspect <model> to json | Generate OpenAPI JSON specification for an Aspect Model | `bamm aspect AspectModel.ttl to json`
7986
| _--output, -o_ : output file path (default: stdout) |
80-
.2+| aspect <model> to schema | Generate JSON schema for an Aspect Model | `bamm aspect AspectModel.ttl to schema`
87+
| _--custom-resolver_ : use an external resolver for the resolution of the model elements |
88+
.3+| aspect <model> to schema | Generate JSON schema for an Aspect Model | `bamm aspect AspectModel.ttl to schema`
8189
| _--output, -o_ : output file path (default: stdout) |
82-
.3+| aspect <model> to aas | Generate Asset Administration Shell (AAS) submodel template for an Aspect Model | `bamm aspect AspectModel.ttl to aas`
90+
| _--custom-resolver_ : use an external resolver for the resolution of the model elements |
91+
.4+| aspect <model> to aas | Generate Asset Administration Shell (AAS) submodel template for an Aspect Model | `bamm aspect AspectModel.ttl to aas`
8392
| _--output, -o_ : output file path (default: stdout) |
8493
| _--format, -f_ : output file format (xml or aasx, default: xml)|
94+
| _--custom-resolver_ : use an external resolver for the resolution of the model elements |
8595
|===
8696

97+
=== Custom model resolver
98+
99+
To allow the users to provide their own custom implementations of a model resolver, `--custom-resolver` command-line switch can be used.
100+
The value of the switch can be any command which is directly executable by the underlying operating system (such as a batch script on Windows or a shell script on Linux/Unix).
101+
When a model element needs to be resolved, this command is executed with the URN of the element to resolve passed as the last parameter.
102+
The command can provide other parameters as well, the element URN will be added automatically as the last one by bamm-cli.
103+
The resolved model definition is expected to be output to the stdout in Turtle format.
104+
From there, it is read by the bamm-cli and passed on to the internal processing pipeline.
105+
In this way the extension can be flexibly done in any programming language/script language, including complex logic if necessary.
106+
87107
== Using the CLI to create a JSON OpenAPI Specification
88108

89109
Every specification is based on one Aspect, which needs a separately defined server URL where the given aspect will be.

0 commit comments

Comments
 (0)