- Introduction
- Getting help
- Build and contribute
- SDK Structure
- Java Core Components
- Version Handling
- SAMM CLI
- Artifact Generation facilities
- License
The ESMF SDK contains artifacts and resources for all parties that intent to use, extend or integrate with the Semantic Aspect Meta Model (SAMM), e.g., solution developers, domain experts or OEMs.
At its core are components which help to work with the Semantic Aspect Meta Model. The SDK comprises components to load and validate models generate artifacts such as static classes, documentation, DTOs (data transfer objects) and so on.
To fully leverage SAMM, provided components include language-specific meta model implementations, code generators, validators etc.
This document provides an overall overview of the SDK, and the concepts applied throughout it. Detailed documentation and concepts for each component can be found in the respective subfolders.
This repository contains a detailed developer documentation written in AsciiDoc. The source files (AsciiDoc) are located here and are built using Antora which generates the documentation as HTML files. A site generated using Antora is self-contained and can be viewed entirely offline via a web browser without setting up a web server. To build the documentation locally, please check out and follow the instructions in ESMF documentation repository.
Are you having trouble with ESMF SDK? We want to help!
- Check the ESMF SDK developer documentation
- Ask a question the community forum.
- Check the SAMM specification
- Having issues with the ESMF SDK? Open a GitHub issue.
The top level elements of the SDK structure are all carried out as Maven multimodule projects. Building the SDK requires a Java 17-compatible GraalVM JDK with the 'js' component installed. If you want to build the samm-cli (see below), you will also have to have the 'native-image' GraalVM component installed.
To build the SDK core components, run the following command:
mvn -pl '!org.eclipse.esmf:samm-cli' clean installTo also build SDK core components and the CLI tool, run the above command, followed by:
cd tools/samm-cli
mvn -B clean verify
mvn -B verify -PnativeWe are always looking forward to your contributions. For more details on how to contribute just take a look at the contribution guidelines. Please create an issue first before opening a pull request.
To ease navigation through the SDK and its components, the repository employs the following structure:
esmf-sdk
│
├─── core # e.g. meta model implementations etc.
│ ├─── esmf-aspect-meta-model-interface
│ ├─── esmf-aspect-meta-model-java
│ ├─── ...
├─── tools # accompanying tools, build system integrations etc.
│ ├─── samm-cli
│ └─── ...
└─── documentation # the Antora documentation module for the SDK
The Java core components are those to be consumed by developers that aim to build applications or tools dealing with SAMM.
Contains the Java implementation of the SAMM.
An Aspect Model can be used in (primarily) two ways:
- Dynamically instantiated - this is done by tooling and applications that don't have any a-priori knowledge except for the Aspect Model file/URN and also don't or can't use generated source code artifacts. Any form of Java source code generator will use the meta model this way.
- Statically generated - the preferred way for applications that are built against known Aspect
Models. A static meta model provides full information about Java types, including types
(
Entitys,Enumerations etc.) derived from the Aspect Model itself. Implementation parts specific to the static variant are located in their own componentesmf-aspect-static-meta-model.
Contains the parts of the Java implementation of the SAMM that are specific to the static variant, e.g. common base classes of static meta model elements. Consumers of a static meta model can use this component as their main entrance dependency.
Can be used to validate an Aspect Model against the SAMM definition. This component is mainly of interest for tool developers or as a utility during a modeling phase.
The model validator is also available through the SAMM CLI.
SAMM and its SDKs evolve over time. While measures are taken to do this in a non-breaking manner, some changes cannot be carried out without the need to define a new, breaking version. Due to this fact it is important to understand the versioning concept that is applied to the SAMM, APIs and SDK components that are derived from them.
In case of a prerelease a postfix will be added to the version, such as -M1, and it will be
released on Github. The way to access the artifact is described in the Java Aspect Tooling
Guide.
For the esmf-sdk, semantic versioning (major.minor.micro) is applied with the following rules:
- The
majorpart designates the supported SAMM major version - A breaking change increases the
minorpart - Backwards compatible new features, changes to existing features or bugfixes increase the
minorpart
A new SAMM version implies new releases of the SDK components that depend on this SAMM version, however not the other way round. New releases of SDK components may be released that are built on an existing SAMM version.
Complex applications might have the need to be implemented against different versions of the SAMM, especially if Aspects should be integrated where there is no control over the underlying meta model version. Thus, Java artifacts for different SAMM versions exist.
Version information encoded into the package name and/or class name solve any issues concerning unique addressability of a class in a concrete version, however any version update forces consumers to change the code base if they want to stay on the latest version.
As this is not very convenient, the following concept is applied:
The base package for all meta model elements does not carry any version encoding, neither do any classes that represent the latest version of the SAMM. This has the advantage that consumers who want to stay on the latest version and don't need multiple versions of the meta model can simply upgrade and don't need to apply any changes to their code base (that is, if the newer version did not introduce any breaking changes).
One primary use case of a meta model is to use it as a basis for generated artifacts. Most prominent example is generating domain model classes, however usage is of course by no means restricted to this.
The ESMF SDK already comes with a set of useful generators. They all accept any Aspect Model given
as a Turtle (.ttl) file. All generators are also available through the SAMM CLI.
The POJO generator takes any Aspect Model and generates all Java classes that are necessary to
represent the Aspect. This includes at least a class for the Aspect itself, in most cases however
multiple files are generated, e.g. for embedded Entitys or Enumerations.
Especially when the Aspect Models that are worked with are known a priori (which should be the case for most solutions built on the ESMF SDK) using the dynamically instantiated meta model does not give developers the full potential of what's possible. For those use cases a generator can be used to generate Java source code representing the meta model in a static form, with meta classes that allow direct access to all important information of one or more Aspect Models, notably properties and their types.
The static meta model uses the Java implementation from esmf-aspect-meta-model adding further
details that are specific to the static case through the component esmf-aspect-static-meta-model.
The diagram generator takes any Aspect Model and provides a rendering of a diagram representing the Aspect Model with all its elements.
Possible output formats are png and svg.
The documentation generator takes any Aspect Model and provides an HTML document describing the Aspect Model.
The resulting document can be seen as a reference documentation as it includes any information that can be derived from the Aspect Model such as the diagram and a list of all properties with information about their characteristics, data type etc.
All migrators are in the module esmf-aspect-meta-model-version-migrator to execute a model
migration. If the internal SDK migrations are not sufficient, it is possible to add custom
migrator(s). For this the interface MigratorFactory has to be implemented and added to the
classpath. The AspectResolver collects this automatically and executes the custom migrator depending
on availability. Important: The implementation of the MigratorFactory have to be the package name
or a subpackage of org.eclipse.esmf.aspectmodel.versionupdate
The SAMM CLI provides all generation as well as validation functionality as a CLI for ad-hoc usage outside an IDE, automated build or any project at all. Provided functions are:
- Model validation
- Model documentation generation
- Model diagram generation (multiple output formats)
- Sample JSON payload generation
- Java class generation
- Static meta model generation
New SDK functionality based on the Aspect Meta Model will always be also provided through the SAMM CLI. Built binary versions of the SAMM CLI are available as part of the ESMF SDK releases on GitHub.
For information regarding running the command line tool, the available commands and their description, please have a look at the documentation.
SPDX-License-Identifier: MPL-2.0
This program and the accompanying materials are made available under the terms of the Mozilla Public License, v. 2.0.
The Notice file details contained third party materials.