Metamodels 2024.3.9

Resources

This version introduces a new expansion-resource ontology-metamodel-expanders, which is included in the metamodel stack.

Resource	Version
nsx-metamodel-stack	2024.3.9

Changes

Expanders 2024.3.x introduce the ontology-metamodel-expanders. These expanders have been to made to replace the metamodel-expanders. They use the ontology-based metamodel directly instead of first requiring the GenerateMetamodelApplication transmuter.

Different Project Structure

The new expanders generate a simplified project.

• The different submodules for each component/ontology have been merged. There is now a single {ontology}-model submodule for each ontology
• The onion-spec classes have been moved to the test-support module.
• Harvesting ext files works differently. There are no ext/gen directories. Instead, the expanders harvest every file that was not expanded. The project contains a number of .harvestInclude files, which contain glob patterns for which files to harvest.
• The expanders module has been removed. Instead, expanders should be implemented in a separate project similar to regular expander projects.

Merged with CompositeBuilder Expanders

Before, it was necessary to expand with model-builder-expanders in a separate project to generate helper classes for transmuters. These expanders have now been merged into the ontology-metamodel-expanders so that this is no longer needed.

Profiles

The new expanders make use of profiles to configure cross-cutting concerns. The Standard Metamodel enables every feature, but it is possible to create new profiles if necessary.

<dataResource type="expansionControl::ExpansionProfile">
  <profile name="Standard Metamodel">
    <tags>
      <tag>#meta.maven</tag>
      <tag>#meta.xml</tag>
      <tag>#meta.transmutation</tag>
    </tags>
  </profile>
</dataResource>

XML and XSD

The expanders generate XSD files to describe the ElementClass XML files. The default namespace is https://schemas.normalizedsystems.org/xsd/${ontology}/${version}, which can be modified with the meta.xml.namespace option on ontology. If it contains ${version}, this will be replaced with the actual version.

There are also some changes to the XML representation.

• References are represented as text-content with the full functional key.
• Exported XML files have one or more xmlns attributes. In case of mixed metamodels, the XML tags can contain prefixes.

The XMLReaders are implemented to be backwards compatible (they can read both old and new formats).

Miscellaneous

• MappingContext: Now uses Optional instead of Option. There is an option meta.compatibility.mappingContext.option for backwards compatibility.
• Dropped support for valueFieldTypes. Attributes now only support DataTypes with String, Boolean or Integer.
• Dropped DataRefConverter. Keys can be parsed with a method on the {element}DataRef class.
• Dropped CompositeRegistrar. This was not used.
• Dropped OptionConverter.
• CompositeScanner now also scans aggregate relations, e.g. Application -> Component.
• SpecBuilders no longer support embedding parent specs into the child spec.
• Now uses dataResource notation instead of _data.xml for most DataResources.
• expansion directory uses expansionMetamodel name
• Ontologies now have versions, and imported ontologies without versions are interpreted as being expanded with older expanders.

Migration guide

1. Migrate your metamodel to ontology representation

Make sure your metamodel is up to date with DataElement representation. You can run the MigrateMetamodelApplication transmuter to convert the DataElements to ElementClasses.

There are also some options for backwards compatibility which you might consider:

• meta.compatibility.xml.legacyRefs (on Ontology or ElementClass): Adds backwards compatibility for DataRef changes in XMLReader. This ensures compatibility with older file formats. Recommended if the model files are already in use.
• meta.compatibility.mappingContext.option (on Ontology or ElementClass): Adds backwards compatible methods to TreeToCompositeMappingContext based on Option. This ensures compatibility for metamodels compiled against older versions. Recommended if there are any other metamodels depending on this one.

2. Change expansionSettings

To activate the new Expanders, you'll need to change the program type in the expansionSettings.

before

<expansionSettings>
  <modelDirectory>..</modelDirectory>
  <expansionDirectory>../expansions</expansionDirectory>
  <expansionResources>
    <expansionResource name="net.democritus.metamodel:nsx-metamodel-stack"
                       version="2024.1.0"/>
  </expansionResources>
  <expansions>
    <expansion>
      <type component="metamodel" name="ExpandableMetamodel"/>
      <target>scriptModel::_</target>
      <variant>scriptModel</variant>
    </expansion>
    <expansion>
      <type component="metamodels" name="Metamodel"/>
      <target>scriptMetamodel</target>
    </expansion>
  </expansions>
</expansionSettings>

after

<expansionSettings>
  <modelDirectory>..</modelDirectory>
  <expansionDirectory>../expansions</expansionDirectory>
  <expansionResources>
    <expansionResource name="net.democritus.metamodel:nsx-metamodel-stack"
                       version="2024.3.8"/>
  </expansionResources>
  <expansions>
    <expansion>
      <type component="metamodels.v3" name="Metamodel"/>
      <target>scriptMetamodel</target>
      <profile name="Standard Metamodel"/>
    </expansion>
  </expansions>
</expansionSettings>

3. Expand once to migrate harvest

Because of the changes in the project structure and the switch to ontologies, the harvest files and ext files need to be relocated. The expanders have an ExpansionStep, which does a best effort relocation of these customizations.

• It's best to commit your changes at this point to have a clean work directory.
• Run the expansion once to move the customizations.
• The customizations will have been copied. You can start removing the applications and components directory. Check your git changes to make sure that no customizations have been lost.
• Build the project to check for compilation issues.

Possible Issues

There are a number of changes that might not be automatically resolved

• Because the number of maven modules has been reduced, the harvest code in the pom.xml files might need to be migrated manually.
• The new CompositeBuilder classes might create compilation issues. You can disable them by creating a profile without #meta.transmutation if they are not needed. Otherwise, it might be necessary to add a dependency on prime-builders if you are missing classes from elements.

Customization to Expanders module

As noted earlier, the expanders module is no longer present in the metamodel project. If you had any customizations, like Expanders, in this module, you will need to create a separate expanders project to house them.

4. Update scripts

• The location of the expanded project will be slightly different because it uses the metamodel name instead of the application name as root directory (-Metamodel instead of -Model). You will need to update your Jenkinsfile and build scripts.
• The GenerateMetamodelApplication is no longer necessary. You can remove the prepare-metamodel.nss script. Also check for any uses of the transmuter in other scripts.