Skip to main content

Configuring an Expansion Resource

A typical expansion resource project follows the standard Maven directory structure:

expansion-resource-project/
├── pom.xml (with expanders-maven-plugin)
├── src/
│   └── main/
│       ├── java/             # Custom expansion steps (Java)
│       └── resources/        # Expanders, features, and data resources
└── description.md           # Optional: Human-readable documentation

Plugin Setup​

The expanders-maven-plugin has an expansionResource goal that will generate the expansion resource .jar and a expansionResource.xml manifest file. This manifest file will list all components used by the expander framework (e.g. location of expander files, resource files, dependencies).

The expanders-maven-plugin is executed during the build and is thus configured within the build tag.

Plugin configuration:

  • The expansion-resource name will be defined as ${groupId}:${artifactId}.
  • Add a title and sortName to provide better integration with tooling.
  • Add labels to filtering and give visual hints towards the content.
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>2026.0.0</version>
      <executions>
        <execution>
          <goals>
            <goal>expansionResource</goal>
          </goals>
          <configuration>
            <details>
              <title>Example expanders</title><!-- Human-friendly name -->
              <sortName>my-expanders,net.demo</sortName><!-- Used in sorting/filtering -->
              <labels><!-- Attach labels for visual cues and filtering -->
                <label>expanders</label>
                <label>experimental</label>
                <label>jee</label>
              </labels>
            </details>
          </configuration>
        </execution>
      </executions>
    </plugin>
  </plugins>
</build>
</project>

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 this example manifest.

tip

If a resource (e.g., an expander) is missing from target/classes/expansionResource.xml after a build, verify that the file follows the naming conventions and is correctly located in src/main.

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>9.2.0</version>
</dependency>

will result in the dependency being added to your manifest:

<expansionResourceDependencys>
<expansionResourceDependency name="">
  <dependsOn name="net.democritus:Expanders" version="9.2.0"/>
</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​