Skip to content

Commit 475b143

Browse files
atextoratextor
committed
Add BAMM to SAMM migration guide
1 parent a22ab89 commit 475b143

File tree

2 files changed

+136
-3
lines changed

2 files changed

+136
-3
lines changed

‎documentation/developer-guide/modules/tooling-guide/nav.adoc‎

Lines changed: 3 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,5 @@
11
.Tooling Guide
22
* xref:samm-cli.adoc[SAMM CLI]
3-
* xref:java-aspect-tooling.adoc[Java Tooling for Aspect Models]
4-
* Java Build Tooling
5-
** xref:maven-plugin.adoc[Maven Plugin]
3+
* xref:java-aspect-tooling.adoc[Java APIs for Aspect Models]
4+
* xref:maven-plugin.adoc[Maven Plugin]
5+
* xref:bamm-migration.adoc[Migration from BAMM]

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

Lines changed: 133 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,133 @@
1+
:page-partial:
2+
3+
[[migration-from-bamm]]
4+
= Migration from BAMM Aspect Meta Model
5+
6+
[quote]
7+
BAMM is now known as SAMM.
8+
9+
Since january 2023, the Semantic Aspect Meta Model (SAMM) is developed by the
10+
Eclipse Semantic Modeling Framework (ESMF) project. However, SAMM and its
11+
accompanying tooling was not developed from scratch here but is based on what
12+
was previously known as the _BAMM Aspect Meta Model_. BAMM was developed and
13+
maintained by the Semantic Data Structuring (SDS) working group of the Open
14+
Manufacturing Platform (OMP). With the transition from OMP to ESMF, identifiers
15+
and artifact names changed. The following sections guide you through the
16+
necessary changes in order to migrate from BAMM to SAMM.
17+
18+
[[changes-in-semantics]]
19+
== Changes in semantics
20+
21+
Meta model semantics have not changed between BAMM 2.0.0 and SAMM 2.0.0. This
22+
means that the way an Aspect Model is constructed remains the same after
23+
updating to SAMM. However, since the meta model namespaces have changed, models
24+
need to be updated to use the new namespaces.
25+
26+
== Namespaces and artifacts
27+
28+
=== Meta model namespaces
29+
30+
As a rule of thumb, every occurence of `io.openmanufacturing` changes to
31+
`org.eclipse.esmf.samm` and every occurence of `bamm` changes to `samm`.
32+
33+
The RDF namespaces have changed as follows:
34+
35+
.Prefixes
36+
[options="header"]
37+
|===
38+
| BAMM prefix | SAMM prefix
39+
| `bamm` | `samm`
40+
| `bamm-c` | `samm-c`
41+
| `bamm-e` | `samm-e`
42+
| `unit` | `unit`
43+
|===
44+
45+
.Meta model URNs
46+
[options="header"]
47+
|===
48+
| BAMM namespace | SAMM namespace
49+
| `urn:bamm:io.openmanufacturing:meta-model:2.0.0#` | `urn:samm:org.eclipse.esmf.samm:meta-model:2.0.0#`
50+
| `urn:bamm:io.openmanufacturing:characteristic:2.0.0#` | `urn:samm:org.eclipse.esmf.samm:characteristic:2.0.0#`
51+
| `urn:bamm:io.openmanufacturing:entity:2.0.0#` | `urn:samm:org.eclipse.esmf.samm:entity:2.0.0#`
52+
| `urn:bamm:io.openmanufacturing:unit:2.0.0#` | `urn:samm:org.eclipse.esmf.samm:unit:2.0.0#`
53+
|===
54+
55+
=== Aspect model namespaces
56+
57+
The change of the URN schema part from `urn:bamm` to `urn:samm` implies that
58+
Aspect Model elements now must use the URN schema:
59+
60+
`urn:samm:<namespace>:<version>#<element-name>`
61+
62+
=== Java artifact names
63+
64+
The Maven groupId has changed from `io.openmanufacturing` to `org.eclipse.esmf`.
65+
Every occurence of `sds` in the artifactIds has changed to `esmf`.
66+
67+
What as previously known as the `sds-sdk` is now the `esmf-sdk`.
68+
69+
.Java artifacts
70+
[options="header"]
71+
|===
72+
| BAMM Java artifact | SAMM Java artifact
73+
| `io.openmanufacturing:sds-aspect-meta-model` | `org.eclipse.esmf:esmf-semantic-aspect-meta-model`
74+
| `io.openmanufacturing:sds-aspect-model-urn` | `org:eclipse.esmf:esmf-aspect-model-urn`
75+
| `io.openmanufacturing:sds-aspect-meta-model-interface` | `org:eclipse.esmf:esmf-aspect-meta-model-interface`
76+
| `io.openmanufacturing:sds-aspect-meta-model-resolver` | `org:eclipse.esmf:esmf-aspect-meta-model-resolver`
77+
| `io.openmanufacturing:sds-aspect-model-resolver` | `org:eclipse.esmf:esmf-aspect-model-resolver`
78+
| `io.openmanufacturing:sds-aspect-meta-model-types` | `org:eclipse.esmf:esmf-aspect-meta-model-types`
79+
| `io.openmanufacturing:sds-aspect-meta-model-version-migrator` | `org:eclipse.esmf:esmf-aspect-meta-model-version-migrator`
80+
| `io.openmanufacturing:sds-aspect-meta-model-java` | `org:eclipse.esmf:esmf-aspect-meta-model-java`
81+
| `io.openmanufacturing:sds-aspect-model-generator` | `org:eclipse.esmf:esmf-aspect-model-generator`
82+
| `io.openmanufacturing:sds-aspect-model-document-generators` | `org:eclipse.esmf:esmf-aspect-model-document-generators`
83+
| `io.openmanufacturing:sds-aspect-model-validator` | `org:eclipse.esmf:esmf-aspect-model-validator`
84+
| `io.openmanufacturing:sds-aspect-model-java-generator` | `org:eclipse.esmf:esmf-aspect-model-java-generator`
85+
| `io.openmanufacturing:sds-aspect-model-starter` | `org:eclipse.esmf:esmf-aspect-model-starter`
86+
| `io.openmanufacturing:sds-aspect-static-meta-model-java` | `org:eclipse.esmf:esmf-aspect-static-meta-model-java`
87+
| `io.openmanufacturing:sds-aspect-model-java-core` | `org:eclipse.esmf:esmf-aspect-model-java-core`
88+
| `io.openmanufacturing:sds-aspect-model-serializer` | `org:eclipse.esmf:esmf-aspect-model-serializer`
89+
| `io.openmanufacturing:sds-aspect-model-jackson` | `org:eclipse.esmf:esmf-aspect-model-jackson`
90+
| `io.openmanufacturing:sds-test-aspect-models` | `org:eclipse.esmf:esmf-test-aspect-models`
91+
| `io.openmanufacturing:sds-test-resources` | `org:eclipse.esmf:esmf-test-resources`
92+
| `io.openmanufacturing:sds-aspect-model-aas-generator` | `org.eclipse.esmf:esmf-aspect-model-aas-generator`
93+
| `io.openmanufacturing:bamm-cli` | `org:eclipse.esmf:samm-cli`
94+
|===
95+
96+
=== Java packages and classes
97+
98+
For the esmf-sdk, as a rule of thumb, every occurence of
99+
`io.openmanufacturing.sds` in package names was renamed to `org.eclipse.esmf`.
100+
In addition to that, several classes were renamed.
101+
102+
.Renamed specific classes
103+
[options="header"]
104+
|===
105+
| BAMM Java class | SAMM Java class
106+
| `io.openmanufacturing.sds.aspectmetamodel.KnownVersion` | `org.eclipse.esmf.samm.KnownVersion`
107+
| `io.openmanufacturing.sds.aspectmodel.resolver.services.SdsAspectMetaModelResourceResolver` | `org.eclipse.esmf.aspectmodel.resolver.services.SammAspectMetaModelResourceResolver`
108+
| `io.openmanufacturing.sds.aspectmodel.versionupdate.migrator.SdsMetaModelVersionUriRewriter` | `org.eclipse.esmf.aspectmodel.versionupdate.migrator.SammMetaModelVersionUriRewriter`
109+
| `io.openmanufacturing.sds.aspectmodel.versionupdate.SdsMigratorFactory` | `org.eclipse.esmf.aspectmodel.versionupdate.SammMigratorFactory`
110+
|===
111+
112+
== Compatibility
113+
114+
* Since BAMM 2.0.0 and SAMM 2.0.0 are structurally and semantically identically,
115+
migrating an BAMM-based Aspect Model is done by simply renaming RDF prefixes
116+
and namespaces.
117+
* ESMF SDK 2.2.0 (including SAMM CLI 2.2.0) has the ability to load BAMM-based
118+
Aspect Models and convert them on-the-fly to SAMM-based Aspect Models.
119+
120+
[options="header"]
121+
|===
122+
| | sds-sdk/bamm-cli 2.1.3 | esmf-sdk/samm-cli 2.2.0
123+
| Read BAMM 1.0.0 | {ok} | {ok}
124+
| Write BAMM 1.0.0 | {nok} | {nok}
125+
| Read BAMM 2.0.0 | {ok} | {ok}
126+
| Write BAMM 2.0.0 | {ok} | {nok}
127+
| Read SAMM 2.0.0 | {nok} | {ok}
128+
| Write SAMM 2.0.0 | {nok} | {ok}
129+
|===
130+
131+
NOTE: _Read_ refers to the capability to load, validate and generate artifacts for
132+
an Aspect Model. _Write_ refers to the capability to pretty-print and write out
133+
Aspect Models after meta model version migration.

0 commit comments

Comments
 (0)