Maven Plugin

The esmf-aspect-model-maven-plugin wraps the functionality provided by the ESMF SDK. Each piece of supported functionality is implemented as a goal. As such, developers can easily work with Aspect Models in the build of their maven projects to, for example, generate code from an Aspect Model.

To include the plugin, use the following dependency:

<dependency>
    <groupId>org.eclipse.esmf</groupId>
    <artifactId>esmf-aspect-model-maven-plugin</artifactId>
    <version>2.9.8</version>
</dependency>
The current implementation of the esmf-aspect-model-maven-plugin uses the FileSystemStrategy to resolve Aspect Models. See Understanding Model Resolution for more information.

Validating an Aspect Model

The validate goal validates whether a given Aspect Model adheres to the SAMM. The default life cycle phase for the goal is validate.

Usage:

<build>
  <plugins>
     <plugin>
        <artifactId>esmf-aspect-model-maven-plugin</artifactId>
        <executions>
           <execution>
              <id>validate-aspect-model</id>
              <goals>
                 <goal>validate</goal>
              </goals>
           </execution>
        </executions>
        <configuration>
           <modelsRootDirectory>${path-to-models-root}</modelsRootDirectory>
           <includes>
              <include>${urn-of-aspect-model-to-be-included}</include>
           </includes>
        </configuration>
     </plugin>
  </plugins>
</build>

Configuration Properties:

Property Description Type Default Value Required

detailedValidationMessages

Print detailed validation messages

Boolean

false

modelsRootDirectory

The path to the root directory containing the Aspect Model file(s).

String

${basedir}/src/main/resources/aspects

includes

A list of Aspect Model URNs identifying the Aspect Models to be included in the plugin execution.

String

none

Generate Java Code for an Aspect Model

Generate Domain Classes

The generateJavaClasses goal generates Java domain classes (POJOs) for a given Aspect Model. The default life cycle phase for the goal is generate-sources.

Usage:

<build>
  <plugins>
     <plugin>
        <artifactId>esmf-aspect-model-maven-plugin</artifactId>
        <executions>
           <execution>
              <id>generate-java-classes</id>
              <goals>
                 <goal>generateJavaClasses</goal>
              </goals>
           </execution>
        </executions>
        <configuration>
           <modelsRootDirectory>${path-to-models-root}</modelsRootDirectory>
           <includes>
              <include>${urn-of-aspect-model-to-be-included}</include>
           </includes>
           <outputDirectory>${directory-for-generated-source-files}</outputDirectory>
        </configuration>
     </plugin>
  </plugins>
</build>

Configuration Properties:

Property Description Type Default Value Required

detailedValidationMessages

Detailed validation messages if the model can not be loaded

Boolean

false

modelsRootDirectory

The path to the root directory containing the Aspect Model file(s).

String

${basedir}/src/main/resources/aspects

includes

A list of Aspect Model URNs identifying the Aspect Models to be included in the plugin execution.

String

none

outputDirectory

The path to the directory where the generated Java files will be written to.

String

none

packageName

The package name for the generated Java files. This may also include the placeholders {{namespace}}, {{majorVersion}}, {{minorVersion}} and {{microVersion}} which will be replaced by their respective values from the Aspect Model URN.

String

The namespace of the given Aspect Model.

stripNamespace

A regular expression that determines which parts of the namespace should be removed, to remove for example common prefixes which are replaced using packageName

String

none

templateFile

The path and name of the velocity template file containing the macro library. See Providing Custom Macros for Code Generation.

String

none

executeLibraryMacros

Execute the macros provided in the velocity macro library.

Boolean

false

disableJacksonAnnotations

Leads to generated Java code that does not contain Jackson annotations.

Boolean

false

skip

Skip execution of plugin and generation

Boolean

false

namePrefix

Name prefix for generated Aspect, Entity Java classes

String

none

namePostfix

Name postfix for generated Aspect, Entity Java classes

String

none

Generate Static Meta Classes

The generateStaticJavaClasses goal generates static meta classes for a given Aspect Model. The default life cycle phase for the goal is generate-sources.

Usage:

<build>
  <plugins>
     <plugin>
        <artifactId>esmf-aspect-model-maven-plugin</artifactId>
        <executions>
           <execution>
              <id>generate-static-java-classes</id>
              <goals>
                 <goal>generateStaticJavaClasses</goal>
              </goals>
           </execution>
        </executions>
        <configuration>
           <modelsRootDirectory>${path-to-models-root}</modelsRootDirectory>
           <includes>
              <include>${urn-of-aspect-model-to-be-included}</include>
           </includes>
           <outputDirectory>${directory-for-generated-source-files}</outputDirectory>
        </configuration>
     </plugin>
  </plugins>
</build>

Configuration Properties:

Property Description Type Default Value Required

detailedValidationMessages

Detailed validation messages if the model can not be loaded

Boolean

false

modelsRootDirectory

The path to the root directory containing the Aspect Model file(s).

String

${basedir}/src/main/resources/aspects

includes

A list of Aspect Model URNs identifying the Aspect Models to be included in the plugin execution.

String

none

outputDirectory

The path to the directory where the generated Java files will be written to.

String

none

packageName

The package name for the generated Java files. This may also include the placeholders {{namespace}}, {{majorVersion}}, {{minorVersion}} and {{microVersion}} which will be replaced by their respective values from the Aspect Model URN.

String

The namespace of the given Aspect Model.

stripNamespace

A regular expression that determines which parts of the namespace should be removed, to remove for example common prefixes which are replaced using packageName

String

none

templateFile

The path and name of the velocity template file containing the macro library. See Providing Custom Macros for Code Generation.

String

none

executeLibraryMacros

Execute the macros provided in the velocity macro library.

Boolean

false

Generate a JSON Schema for an Aspect Model

The generateJsonSchema goal generates a JSON Schema for a given Aspect Model. The default life cycle phase for the goal is generate-resources.

Usage:

<build>
  <plugins>
     <plugin>
        <artifactId>esmf-aspect-model-maven-plugin</artifactId>
        <executions>
           <execution>
              <id>generate-json-schema</id>
              <goals>
                 <goal>generateJsonSchema</goal>
              </goals>
           </execution>
        </executions>
        <configuration>
           <modelsRootDirectory>${path-to-models-root}</modelsRootDirectory>
           <includes>
              <include>${urn-of-aspect-model-to-be-included}</include>
           </includes>
           <outputDirectory>${directory-for-generated-source-files}</outputDirectory>
        </configuration>
     </plugin>
  </plugins>
</build>

Configuration Properties:

Property Description Type Default Value Required

detailedValidationMessages

Detailed validation messages if the model can not be loaded

Boolean

false

modelsRootDirectory

The path to the root directory containing the Aspect Model file(s).

String

${basedir}/src/main/resources/aspects

includes

A list of Aspect Model URNs identifying the Aspect Models to be included in the plugin execution.

String

none

outputDirectory

The path to the directory where the generated JSON Schema will be written to.

String

none

language

The language from the model for which a JSON Schema should be generated.

String

en

Generate an OpenAPI Specification from an Aspect Model

The generateOpenApiSpec goal generates an OpenAPI Specification for a given Aspect Model. The default life cycle phase for the goal is generate-resources.

Usage:

<build>
  <plugins>
     <plugin>
        <artifactId>esmf-aspect-model-maven-plugin</artifactId>
        <executions>
           <execution>
              <id>generate-openapi-spec</id>
              <goals>
                 <goal>generateOpenApiSpec</goal>
              </goals>
           </execution>
        </executions>
        <configuration>
           <modelsRootDirectory>${path-to-models-root}</modelsRootDirectory>
           <includes>
              <include>${urn-of-aspect-model-to-be-included}</include>
           </includes>
           <aspectApiBaseUrl>http://example.com</aspectApiBaseUrl>
           <outputDirectory>${directory-for-generated-source-files}</outputDirectory>
           <outputFormat>yaml</outputFormat>
        </configuration>
     </plugin>
  </plugins>
</build>

Configuration Properties:

Property Description Type Default Value Required

detailedValidationMessages

Detailed validation messages if the model can not be loaded

Boolean

false

modelsRootDirectory

The path to the root directory containing the Aspect Model file(s).

String

${basedir}/src/main/resources/aspects

includes

A list of Aspect Model URNs identifying the Aspect Models to be included in the plugin execution.

String

none

outputDirectory

The path to the directory where the generated OpenAPI Specification will be written to.

String

none

aspectApiBaseUrl

The base URL for the Aspect API OpenAPI specification.

String

none

aspectParameterFile

The path to a file including the schema description for the resource. For JSON the description has to be in json, for YAML it has to be in YAML.

String

none

useSemanticApiVersion

Use the complete semantic version of the Aspect Model as the version of the Aspect API.

Boolean

false

aspectResourcePath

The resource-path for the Aspect API endpoints.

String

none

includeQueryApi

Include the path for the Query Aspect API Endpoint in the OpenAPI specification.

Boolean

false

includeFullCrud

Include the POST/PUT/PATCH methods in the OpenAPI specification.

Boolean

false

includePost

Include the POST method in the OpenAPI specification.

Boolean

false

includePut

Include the PUT method in the OpenAPI specification.

Boolean

false

includePatch

Include the PATCH method in the OpenAPI specification.

Boolean

false

excludePaging

Exclude paging information for the Aspect API Endpoint in the OpenAPI specification.

Boolean

false

aspectCursorBasedPaging

Set the used paging strategy as cursor-based paging.

Boolean

false

aspectOffsetBasedPaging

Set the used paging strategy as offset-based paging.

Boolean

false

aspectTimeBasedPaging

Set the used paging strategy as time-based paging.

Boolean

false

outputFormat

The format of the resulting OpenAPI Specification. May be either JSON or YAML.

String

none

separateFiles

Create separate files for each schema.

Boolean

false

language

The language from the model for which an OpenAPI specification should be generated.

String

en

templateFilePath

The path to the file with a template for the resulting specification, including values undefined by the aspect’s OpenAPI specification. The template can be in JSON or YAML format.

String

none

Generate an AsyncAPI Specification from an Aspect Model

The generateAsyncApiSpec goal generates an AsyncAPI Specification for a given Aspect Model. The default life cycle phase for the goal is generate-resources.

Usage:

<build>
  <plugins>
     <plugin>
        <artifactId>esmf-aspect-model-maven-plugin</artifactId>
        <executions>
           <execution>
              <id>generate-asyncapi-spec</id>
              <goals>
                 <goal>generateAsyncApiSpec</goal>
              </goals>
           </execution>
        </executions>
        <configuration>
           <modelsRootDirectory>${path-to-models-root}</modelsRootDirectory>
           <includes>
              <include>${urn-of-aspect-model-to-be-included}</include>
           </includes>
           <outputDirectory>${directory-for-generated-source-files}</outputDirectory>
           <outputFormat>json</outputFormat>
        </configuration>
     </plugin>
  </plugins>
</build>

Configuration Properties:

Property Description Type Default Value Required

modelsRootDirectory

The path to the root directory containing the Aspect Model file(s).

String

${basedir}/src/main/resources/aspects

outputDirectory

The path to the directory where the generated AsyncAPI Specification will be written to.

String

none

applicationId

Sets the application id, e.g. an identifying URL

String

none

channelAddress

Sets the channel address (i.e., for MQTT, the topic’s name)

String

none

useSemanticApiVersion

Use the complete semantic version of the Aspect Model as the version of the Aspect API.

Boolean

false

outputFormat

The format of the resulting AsyncAPI Specification. May be either JSON or YAML.

String

none

separateFiles

Create separate files for each schema.

Boolean

false

language

The language from the model for which an AsyncAPI specification should be generated.

String

en

Generate an SQL script from an Aspect Model

The generateSql goal generates an SQL table creation script for a given Aspect Model. The default life cycle phase for the goal is generate-resources.

Usage:

<build>
  <plugins>
     <plugin>
        <artifactId>esmf-aspect-model-maven-plugin</artifactId>
        <executions>
           <execution>
              <id>generate-sql</id>
              <goals>
                 <goal>generateSql</goal>
              </goals>
           </execution>
        </executions>
        <configuration>
           <modelsRootDirectory>${path-to-models-root}</modelsRootDirectory>
           <includes>
              <include>${urn-of-aspect-model-to-be-included}</include>
           </includes>
           <outputDirectory>${directory-for-generated-source-files}</outputDirectory>
        </configuration>
     </plugin>
  </plugins>
</build>

Configuration Properties:

Property Description Type Default Value Required

modelsRootDirectory

The path to the root directory containing the Aspect Model file(s).

String

${basedir}/src/main/resources/aspects

outputDirectory

The path to the directory where the generated SQL script will be written to.

String

none

dialect

The SQL dialect to generate for.

String

databricks

strategy

The mapping strategy to use.

String

denormalized

language

The language from the model to use for generated comments.

String

en

includeTableComment

Include table comment in the generated SQL script.

Boolean

true

includeColumnComments

Include column comments in the generated SQL script.

Boolean

true

tableCommandPrefix

The prefix to use for Databricks table creation commands.

String

CREATE TABLE IF NOT EXISTS

decimalPrecision

The precision to use for Databricks decimal columns, between 1 and 38. See also notes in the Databricks type mapping.

Integer

10

customColumns

Contains <column> elements, each of which defines a custom column to add. Column defintions follow the pattern column_name DATATYPE [NOT NULL] [COMMENT 'custom'].

<column>…​

Generate Documentation for an Aspect Model

Generating HTML Documentation

The generateDocumentation goal generates HTML reference documentation for a given Aspect Model. The default life cycle phase for the goal is generate-resources.

Usage:

<build>
  <plugins>
     <plugin>
        <artifactId>esmf-aspect-model-maven-plugin</artifactId>
        <executions>
           <execution>
              <id>generate-html-doc</id>
              <goals>
                 <goal>generateDocumentation</goal>
              </goals>
           </execution>
        </executions>
        <configuration>
           <modelsRootDirectory>${path-to-models-root}</modelsRootDirectory>
           <includes>
              <include>${urn-of-aspect-model-to-be-included}</include>
           </includes>
           <outputDirectory>${directory-for-generated-source-files}</outputDirectory>
        </configuration>
     </plugin>
  </plugins>
</build>

Configuration Properties:

Property Description Type Default Value Required

detailedValidationMessages

Detailed validation messages if the model can not be loaded

Boolean

false

modelsRootDirectory

The path to the root directory containing the Aspect Model file(s).

String

${basedir}/src/main/resources/aspects

includes

A list of Aspect Model URNs identifying the Aspect Models to be included in the plugin execution.

String

none

outputDirectory

The path to the directory where the generated HTML document will be written to.

String

none

htmlCustomCSSFilePath

Path to a CSS file with custom styles to be included in the generated HTML documentation.

String

none

Generating SVG or PNG Diagrams

The generateDiagram goal generates an automatically layouted diagram for a given Aspect Model in SVG or PNG. The default life cycle phase for the goal is generate-resources.

Usage:

<build>
  <plugins>
     <plugin>
        <artifactId>esmf-aspect-model-maven-plugin</artifactId>
        <executions>
           <execution>
              <id>generate-aspect-model-diagram</id>
              <goals>
                 <goal>generateDiagram</goal>
              </goals>
           </execution>
        </executions>
        <configuration>
           <modelsRootDirectory>${path-to-models-root}</modelsRootDirectory>
           <includes>
              <include>${urn-of-aspect-model-to-be-included}</include>
           </includes>
           <outputDirectory>${directory-for-generated-source-files}</outputDirectory>
           <targetFormats>
              <targetFormat>png</targetFormat>
           </targetFormats>
        </configuration>
     </plugin>
  </plugins>
</build>

Configuration Properties:

Property Description Type Default Value Required

detailedValidationMessages

Detailed validation messages if the model can not be loaded

Boolean

false

modelsRootDirectory

The path to the root directory containing the Aspect Model file(s).

String

${basedir}/src/main/resources/aspects

includes

A list of Aspect Model URNs identifying the Aspect Models to be included in the plugin execution.

String

none

outputDirectory

The path to the directory where the generated diagrams will be written to.

String

none

targetFormats

A list formats in which the diagram(s) will be created. A diagram will be generated for each specified format.

String

none

Generating Sample JSON Payload

The generateJsonPayload goal generates a valid sample JSON payload for a given Aspect Model as it could be returned by an Aspect that implements that Aspect Model. The default life cycle phase for the goal is generate-resources.

Usage:

<build>
  <plugins>
     <plugin>
        <artifactId>esmf-aspect-model-maven-plugin</artifactId>
        <executions>
           <execution>
              <id>generate-json-payload</id>
              <goals>
                 <goal>generateJsonPayload</goal>
              </goals>
           </execution>
        </executions>
        <configuration>
           <modelsRootDirectory>${path-to-models-root}</modelsRootDirectory>
           <includes>
              <include>${urn-of-aspect-model-to-be-included}</include>
           </includes>
           <outputDirectory>${directory-for-generated-source-files}</outputDirectory>
        </configuration>
     </plugin>
  </plugins>
</build>

Configuration Properties:

Property Description Type Default Value Required

detailedValidationMessages

Detailed validation messages if the model can not be loaded

Boolean

false

modelsRootDirectory

The path to the root directory containing the Aspect Model file(s).

String

${basedir}/src/main/resources/aspects

includes

A list of Aspect Model URNs identifying the Aspect Models to be included in the plugin execution.

String

none

outputDirectory

The path to the directory where the generated JSON payload will be written to.

String

none

Generating JSON-LD representation of an Aspect Model

The generateJsonLd goal generates a JSON-LD represention of a given Aspect Model. The default life cycle phase for the goal is generate-resources.

Usage:

<build>
  <plugins>
     <plugin>
        <artifactId>esmf-aspect-model-maven-plugin</artifactId>
        <executions>
           <execution>
              <id>generate-jsonld</id>
              <goals>
                 <goal>generateJsonLd</goal>
              </goals>
           </execution>
        </executions>
        <configuration>
           <modelsRootDirectory>${path-to-models-root}</modelsRootDirectory>
           <includes>
              <include>${urn-of-aspect-model-to-be-included}</include>
           </includes>
           <outputDirectory>${directory-for-generated-source-files}</outputDirectory>
        </configuration>
     </plugin>
  </plugins>
</build>

Configuration Properties:

Property Description Type Default Value Required

detailedValidationMessages

Detailed validation messages if the model can not be loaded

Boolean

false

modelsRootDirectory

The path to the root directory containing the Aspect Model file(s).

String

${basedir}/src/main/resources/aspects

includes

A list of Aspect Model URNs identifying the Aspect Models to be included in the plugin execution.

String

none

outputDirectory

The path to the directory where the generated JSON-LD will be written to.

String

none

Pretty Print

The prettyPrint goal formats the given Aspect Model. The formatted file is written to the location specified in the outputDirectory property. The default life cycle phase for the goal is generate-resources. Note that the prettyPrint goal can also be used as a substitute of the now-removed migrate goal, since it implies loading and automatically migrating a model to the latest meta model version before it is pretty-printed.

Usage:

<build>
  <plugins>
     <plugin>
        <artifactId>esmf-aspect-model-maven-plugin</artifactId>
        <executions>
           <execution>
              <id>pretty-print-aspect-model</id>
              <goals>
                 <goal>prettyPrint</goal>
              </goals>
           </execution>
        </executions>
        <configuration>
           <modelsRootDirectory>${path-to-models-root}</modelsRootDirectory>
           <includes>
              <include>${urn-of-aspect-model-to-be-included}</include>
           </includes>
           <outputDirectory>${directory-for-generated-source-files}</outputDirectory>
        </configuration>
     </plugin>
  </plugins>
</build>

Configuration Properties:

Property Description Type Default Value Required

detailedValidationMessages

Detailed validation messages if the model can not be loaded

Boolean

false

modelsRootDirectory

The path to the root directory containing the Aspect Model file(s).

String

${basedir}/src/main/resources/aspects

includes

A list of Aspect Model URNs identifying the Aspect Models to be included in the plugin execution.

String

none

outputDirectory

The path to the directory containing the pretty printed Aspect Model.

String

none

Conversion to and from AAS

Generate an AAS file from an Aspect Model

The generateAas goal generates a file containing an Asset Administration Shell (AAS) environment with a submodel template that corresponds to a given input Aspect Model. The output file can be written in either AASX, XML or JSON formats. The default life cycle phase for the goal is generate-resources.

Usage:

<build>
  <plugins>
     <plugin>
        <artifactId>esmf-aspect-model-maven-plugin</artifactId>
        <executions>
           <execution>
              <id>generate-aas</id>
              <goals>
                 <goal>generateAas</goal>
              </goals>
           </execution>
        </executions>
        <configuration>
           <modelsRootDirectory>${path-to-models-root}</modelsRootDirectory>
           <includes>
              <include>${urn-of-aspect-model-to-be-included}</include>
           </includes>
           <outputDirectory>${directory-for-generated-source-files}</outputDirectory>
           <targetFormat>aasx</targetFormat>
        </configuration>
     </plugin>
  </plugins>
</build>

Configuration Properties:

Property Description Type Default Value Required

detailedValidationMessages

Detailed validation messages if the model can not be loaded

Boolean

false

modelsRootDirectory

The path to the root directory containing the Aspect Model file(s).

String

${basedir}/src/main/resources/aspects

includes

A list of Aspect Model URNs identifying the Aspect Models to be included in the plugin execution.

String

none

outputDirectory

The path to the directory where the generated AAS file will be written to.

String

none

targetFormat

The format to write, one of aasx, xml or json.

String

none

Generate an Aspect Model from an AAS file

The generateAspectFromAas goal generates one Aspect Model for each of the AAS submodel templates defined in a given input AAS file. The input file can be given in either AASX, XML or JSON formats. The output files are written to a directory in the models directory structure. The default life cycle phase for the goal is generate-resources.

Usage:

<build>
  <plugins>
     <plugin>
        <artifactId>esmf-aspect-model-maven-plugin</artifactId>
        <executions>
           <execution>
              <id>generate-aspect-model-from-aas</id>
              <goals>
                 <goal>generateAspectFromAas</goal>
              </goals>
           </execution>
        </executions>
        <configuration>
           <includes>
              <include>${aas-file-path}</include>
           </includes>
           <outputDirectory>${directory-for-generated-aspect-models}</outputDirectory>
        </configuration>
     </plugin>
  </plugins>
</build>

Configuration Properties:

Property Description Type Default Value Required

detailedValidationMessages

Detailed validation messages if the model can not be loaded

Boolean

false

includes

A list of AAS files to convert.

String

none

outputDirectory

The path to the directory where the generated Aspect Models will be written to.

String

none