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
orInteger
. - 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.
<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>
<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.
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 onprime-builders
if you are missing classes fromelements
.
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 theprepare-metamodel.nss
script. Also check for any uses of the transmuter in other scripts.