Creating external expanders with a separate meta-model

Requirements

If you wish to model the application in the PrimeRadiant or modeller, you will need to also import the elements and foundation component. You can find the sources of these components in the primeRadiant-model jar.

Generating the project structure

Generate project based on maven archetype (net.democritus:expander-metamodel-bundle-archetype). Add extra property metaComponent to define the name of the component. Otherwise, it will default to model.

This will generate the basic setup of the project.

The project will have the following structure:

<projectDirectory>
    \-- src
        |-- main
        |   |-- config        // expansionResource.xml will be generated here
        |   |-- gen           // expansion-control classes will be generate here
        |   |-- java          // extra helper classes can be added here
        |   \-- resources     // expander resources will be added here
        |-- model  
        |   |-- applications  // defines application to be able to expand
        |   |-- components    // contains component with meta-elements
        |   \-- conf          // contains expansionSettings.xml
        \-- test
            |-- java          // will contain the tests for expanders etc.
            \-- resources

Modelling elements

For expandable elements, it is best to add the following options:

  • isExpandableElement : This will generate the *ExpansionContext and *ExpansionRunner classes and others needed to run expanders that have this element as elementType.
  • hasParentElement : Defines under which parent element the element should be expanded. In most cases this will be elements::Component.
  • generateExpansionHook : This generate a *ExpansionStep that will hook into the expansion based on the defined parent (see option hasParentElement)
  • functionalKey : Defining a functional key allows you to refer to a specific element by it’s key. E.g. for DataElement, the functionalKey is defined as component_name and so DataElements can be referred to as <component.name>::<dataElement.name>. This is used in tests or in references to the element from other elements.

Note that in order for an Element to have a parentElement, it should also have a link to that element

These options will make sure the necessary files are generated to expand the elements.

Child elements

If the expandable elements contains child elements, the option agregation should be added to the linkFields of the parent with the value composite.

Look at the DataElement-_Field_ relation to see an example.

If these options are missing, the child elements will not be read from the model and will not appear in the Tree projection.

Building the jar

When running mvn package, the build will take the following steps:

  • It will extract the components of the Prime Radiant into the target/model folder
  • It will also copy the src/model directory to the target/model folder so that it is merged with the components of the previous step
  • Then it will run an expansion based on the src/model/conf/expansionSettings.xml file, which will expand the required artifacts into the src/main/gen directory
  • Before packaging, the ExpansionResourceXmlGenerator class is used to generate a expansionResource.xml descriptor file. It searches recursively for expander, feature and additionalExpansionStep files in the rootDirectory, now defined as src/main
  • When all is done, it will add everything to the .jar file, which can then be used in the expansion.

Adding the expansionResource to expansion

To add you expander-bundle to the expansion, add it to the expansionResources tag in either expansionSettings.xml or nsfInstallation.xml.

You can do this through the cli by typing:

nsf config add-resource --name <groupId>:<artifactId> --version <version>

Add the --global option to add it to nsfInstallation.xml so that it applies to all projects.

Location of the element xml files

The expanders will look for the model files in a specific directory under components/<component>/model/. In case the parentElement is defined as elements::Component, this will be components/<component>/model/<elementName>s. You can consult the *ModelReader class to find out where to place them or to customize it.

Issues

This chapter lists known issues of the tools for each version.

expander-metamodel-bundle-archetype

Version 1.0

  • The pom.xml file contains the following:

    <plugin>
          <groupId>org.codehaus.mojo</groupId>
          <artifactId>exec-maven-plugin</artifactId>
           ...
          <configuration>
            <classpathScope>compile</classpathScope>
            <mainClass>net.democritus.expander.setup.ExpansionResourceXmlGenerator</mainClass>
            <arguments>
               ...
              <argument>--rootDirectory</argument>
              <argument>${project.basedir}/src/main/resources</argument>
              ...
            </arguments>
          </configuration>
        </plugin>
    

    This should be :

              ...
              <argument>--rootDirectory</argument>
              <argument>${project.basedir}/src/main</argument>
              ...
    
  • The pom.xml also does not define any java compile version. This can be solved by adding the following properties to the properties tag:

    <maven.compiler.target>1.8</maven.compiler.target>
    <maven.compiler.source>1.8</maven.compiler.source>
    
  • In this version, the archetype does not generate a .gitignore file, which for now has to be added manually. The content could be something like:

    .idea
    *.iml
    target
    src/main/gen
    src/main/config
    

nsx-prime

Version 2019.5.3.1

Nsx-prime will attempt to fetch the resources required to expand from a maven repository. By default, however, it will use settings that refer to the nexus managed by nsx, and if failing to reach, fall back to maven central.

However, those repositories are not always available and so the expansion will fail. Currently, the only solution here is to overwrite the settings.xml file that is extracted under target/repositories/nsx/maven with settings that go to the correct server.

This will need to be adjusted so that nsx-prime prefers the settings under the user root.