Skip to main content

Create a new Expansion Resource Project

What is an Expansion Resource?​

An expansion-resource or expansion-resource bundle is a jar which can contain:

  • Expanders, which will generate new artifacts
  • Features, which can insert content into artifacts from expanders of this expansion resource or expansion resources the project depends on
  • Additional expansion steps, which can perform tasks before, during or after expansion

And if you really feel fancy, you can add the following:

  • Data resources, which contain metadata like technologies, layerImplementations etc.
  • Model resources, which provide components for expansion

This section will use maven to build the expansion-resource with the help of the expanders-maven-plugin.

Setup​

The expanders-maven-plugin has an expansionResource goal that will generate an expansionResource.xml file. This file is a manifest which describes all resources included in the expansion-resource jar.

Create a new project with maven and add the expanders-maven-plugin to the build:

pom.xml
<?xml version="1.0" encoding="UTF-8"?>
<project xmlns="http://maven.apache.org/POM/4.0.0"
         xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
         xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/xsd/maven-4.0.0.xsd">

  <modelVersion>4.0.0</modelVersion>

  <groupId>org.example</groupId>
  <artifactId>example-expanders</artifactId>
  <version>1.0.0-SNAPSHOT</version>

  <build>
    <plugins>
      <plugin>
        <groupId>net.democritus.maven.plugins</groupId>
        <artifactId>expanders-maven-plugin</artifactId>
        <version>2024.6.0</version>
        <executions>
          <execution>
            <goals>
              <goal>expansionResource</goal>
            </goals>
          </execution>
        </executions>
      </plugin>
    </plugins>
  </build>
</project>

You can find the latest version of the plugin on expanders-maven-plugin.

This will generate a manifest:

<expansionResource name="org.example:example-expanders">
  <version>1.0.0-SNAPSHOT</version>
  <expanders/>
  <features/>
  <additionalExpansionSteps/>
  <dataResources/>
  <modelResources/>
  <expansionResourceDependencys/>
  <classPathDependencys/>
</expansionResource>

The manifest defines the name and version of the expansion-resource. Because the project does not contain any resources yet, none are defined in the manifest.

tip

If at any point your expanders or other resources are not included in the expansion, the manifest is the first place to check, since resources not included in the manifest will not be used during expansion!

Providing Expanders, Features and Additional Expansion Steps​

When building, the plugin will search for expanders, features and additional expansion steps in a specific source directory. By default, this directory is src/main. It is possible to override this by configuring the rootDirectory in the plugin.

The plugin recognizes the resources based on some characteristics:

  • Expanders: ends with Expander.xml, contains a root tag <expander> and has <active value="true"/> defined.
  • Features: ends with .xml and contains a root tag <feature>
  • Additional Expansion Steps: ends with Step.xml and contains root tag additionalExpansionStep.

Adding dependencies​

The plugin will also look for any dependencies of the project that are expansion-resources. These dependencies will be added to the expansion-resource manifest:

E.g. adding the following dependency to your pom.xml:

<dependency>
  <groupId>net.democritus</groupId>
  <artifactId>Expanders</artifactId>
  <version>7.8.2</version>
</dependency>

will result in the dependency being added to your manifest:

<expansionResourceDependencys>
  <expansionResourceDependency name="">
    <dependsOn name="net.democritus:Expanders" version="7.8.2"/>
  </expansionResourceDependency>
</expansionResourceDependencys>

If this information is defined, nsx-prime will do the following when running an expansion with this resource:

  • If the current expander version is older than the version in the dependency, nsx-prime will complain about a version mismatch
  • If the dependency references another expansion-resource that is not present, it will be fetched and added to the expansion

If you require non-expansion-resource libraries, you can enable ClassPathDependencies.

More advanced usage​