Supporting Transmutations

When creating a metamodel you might also want to author transmuters or allow others to write them. To support this the net.democritus.model:model-builder-expanders expansion resource is provided. Based on the metamodel it will generate various support classes to allow for integration with other parts of the model.

The following sample of a transmutation makes use of the DataElementCompositeBuilder. If you want to transmute a custom metamodel, you will need a builder project to support builders for this model.

DataElementCompositeBuilder.merge(dataElement, context, dataElementBuilder -> {
  dataElementBuilder.option("some.option.to.add", null);
});

Project setup

It is advised to put the model builders in a separate maven module, so transmuters can only depend on this builder module and don't need to include the metamodel directly.

The file structure of the builder directory should look like the following:

applications/
├─ yourBuilders/
│  ├─ model/
│  │  ├─ instances/
│  │  │  ├─ yourBuilders.xml
│  │  ├─ yourBuilders.xml
conf/
├─ expansionSettings.xml
expansions/   # add to git ignore
pom.xml

pom.xml

The root pom is only used for expansion and should not be published by itself. The expanded maven module (expansions/yourBuilders/pom.xml) has to be published. The pom.xml should at least contain the following pieces:

pom.xml

<!-- 1. A dependency to the used metamodels -->
 <dependencies>
   <dependency>
     <groupId>net.democritus.metamodel</groupId>
     <artifactId>prime-core</artifactId>
     <version>2024.1.1</version>
   </dependency>
   <dependency>
     <groupId>org.normalizedsystems.your.model</groupId>
     <artifactId>yourmodel-core</artifactId>
     <version>${your.model.version}</version>
   </dependency>
 </dependencies>
 
 <!-- 2. The expanders maven plugin -->
 <build>
   <plugins>
     <plugin>
       <groupId>net.democritus.maven.plugins</groupId>
       <artifactId>expanders-maven-plugin</artifactId>
       <version>2024.1.1</version>
     </plugin>
   </plugins>
 </build>

application.xml

Add all dependent metamodels as a component to the builder application

yourBuilders.xml

<application name="yourBuilders">
  <shortName>yourBuilders</shortName>
  <version>1.0.0</version>
  <components>
    <component name="elements"/>
    <component name="yourModel"/>
  </components>
</application>

application instance.xml

yourBuilders.xml

<applicationInstance name="yourBuilders">
  <shortName>yourBuilders</shortName>
  <version>1.0.0</version>
  <technologyStacks>
    <technologyStack name="ModelBuilder Maven Project"/>
  </technologyStacks>
  <options>
    <meta.packaging.useClassPathDependencies/>
    <meta.groupId>org.normalizedsystems.your.model</meta.groupId>
  </options>
</applicationInstance>

expansionSettings.xml

You will need to add a BuilderProject target and add the builder expanders as expansionResource.

expansionSettings.xml

  <expansionSettings>
    <modelDirectory>..</modelDirectory>
    <expansionDirectory>../expansions</expansionDirectory>
    <expansionResources>
      <expansionResource name="net.democritus:prime-data" version="2024.0.2"/>
      <expansionResource name="net.democritus.metamodel:prime-metamodel" version="2024.1.1"/>
      <expansionResource name="net.democritus.model:model-builder-expanders" version="2.3.3"/>
      <!-- Your model resource  -->
      <expansionResource name="org.normalizedsystems.your.model:your-metamodel" version="1.0.0"/>
    </expansionResources>
    <expansions>
      <expansion>
        <type component="builders" name="BuilderProject"/>
        <target>yourBuilders::1.0.0</target>
        <variant>yourBuilders</variant>
      </expansion>
    </expansions>
  </expansionSettings>

Building the project

Once your setup is ready you can simply expand and build to get your model builder library.

mvn expanders:expand

mvn -f expansions/yourBuilders/pom.xml clean install