Skip to content

Getting started with developing an NPL Contributor Library

New feature (added in 2024.1.4)

An NPL contributor library lets you package NPL constructs such as types and functions and share them with your NPL community. Referencing and declaring protocols is currently unsupported. Consider developing an NPL contributor library when several projects share similar NPL constructs.

Writing an NPL Contributor Library and general guidelines

The general components/layout of such a project are:

  1. the src/main/npl/sample and src/test/npl/sample directories
  2. the src/main/resources/config.json file
  3. usage of the maven-assembly-plugin and its assembly file src/main/resources/assembly.xml

sample should be replaced with an appropriate name for your project. All your NPL source files should be contained under 1 main directory.

The config.json for now only supports specifying a platform minimum version. This version is not checked while developing and testing but is checked when running a final release version of engine. SNAPSHOT and RC versions of engine will not check this platform minimum version. Such a config.json should be structured as following:

{
  "platform": {
    "minimum_version": "2024.1.1"
  }
}

The maven-assembly-plugin is responsible for packaging the config.json and your NPL source files into a single NPL contrib zip file. Its configuration file src/main/resources/assembly.xml contains parameters for assembling it. The assembly.xml should be configured as following:

<assembly xmlns="http://maven.apache.org/ASSEMBLY/2.2.0"
          xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
          xsi:schemaLocation="http://maven.apache.org/ASSEMBLY/2.2.0 http://maven.apache.org/xsd/assembly-2.2.0.xsd">

    <id>zip</id>
    <includeBaseDirectory>true</includeBaseDirectory>

    <formats>
        <format>zip</format>
    </formats>
    <fileSets>
        <fileSet>
            <directory>${project.basedir}/src/main/npl/sample</directory>
            <outputDirectory>/sample</outputDirectory>
        </fileSet>
    </fileSets>
    <files>
        <file>
            <source>${project.basedir}/src/main/resources/config.json</source>
            <outputDirectory>/</outputDirectory>
        </file>
    </files>
</assembly>

Versioning

You are free to choose how to version your NPL contributor library source files and your produced zip file. However, we recommend to version your NPL source files using a major version namespace & directories such as v1 and v2. This should make your life easier for patch & minor releases.

All versions of your NPL contributor library source files should be present in a single zip file for every release. Clients using your NPL contributor library defined NPL constructs must continue to use it once they use it in production, otherwise their environment will break.

Packaging

After executing mvn package or mvn install a zip file named npl-contrib-sample-0.0.1-SNAPSHOT.zip will be available. This zip file can then be used as a dependency in any NPL project.

Deployment

You are free to choose where & how to publish your zip artifact as long as it supports Maven.

Integrating an NPL Contributor Library into an NPL project and in IntelliJ

To see a working example, git checkout our npl-integrations project and peruse its npl/pom.xml. If you can't, continue reading.

To your NPL project pom.xml:

  1. Add the published, or locally installed SNAPSHOT, NPL contrib as a zip dependency

  2. Add the maven-dependency-plugin before the npl-maven-plugin in the plugins section and specify where to copy the zip dependency. The outputDirectory should be the location where all your NPL contrib libraries are located for your NPL project. This is the same directory as your configured nplContribPath of the npl-maven-plugin, which defaults to ${project.basedir}/npl-contrib.

  3. Add the maven-clean-plugin to the plugin section. In the configuration section, specify the outputDirectory location in the directory property element. This will ensure that the npl-contrib library stays up to date and avoid version conflicts.

  4. Add the npl-contrib goal of the npl-maven-plugin. It will create an npl-contrib.properties file at the root of your project to make the all zip files in npl-contrib discoverable for development using IntelliJ and the npl-idea-plugin. It is safe to add this npl-contrib.properties to your .gitignore.

<project>

    <dependency>
        <groupId>com.noumenadigital.platform</groupId>
        <artifactId>npl-contrib-sample</artifactId>
        <version>${platform.version}</version>
        <type>zip</type>
    </dependency>

   <properties>
      <nplContribDir>${project.basedir}/npl-contrib</nplContribDir>
   </properties>

    <build>
        <plugins>
            <plugin>
                <groupId>org.apache.maven.plugins</groupId>
                <artifactId>maven-dependency-plugin</artifactId>
                <executions>
                    <execution>
                        <id>copy-npl-contrib</id>
                        <goals>
                            <goal>copy-dependencies</goal>
                        </goals>
                        <!-- important step: the phase should be `generate-sources` -->
                        <phase>generate-sources</phase>
                        <configuration>
                            <!-- important step: `outputDirectory` should match `nplContribPath` of `npl-maven-plugin` -->
                            <outputDirectory>${nplContribDir}</outputDirectory>
                            <includeGroupIds>com.noumenadigital.platform</includeGroupIds>
                            <includeArtifactIds>npl-contrib-sample</includeArtifactIds>
                            <overWriteIfNewer>true</overWriteIfNewer>
                        </configuration>
                    </execution>
                </executions>
            </plugin>
            <plugin>
              <groupId>org.apache.maven.plugins</groupId>
              <artifactId>maven-clean-plugin</artifactId>
              <version>3.4.0</version>
              <configuration>
                 <filesets>
                    <fileset>
                       <directory>${nplContribDir}</directory>
                    </fileset>
                 </filesets>
              </configuration>
            </plugin>
            <plugin>
                <groupId>com.noumenadigital.platform</groupId>
                <artifactId>npl-maven-plugin</artifactId>
                <version>${platform.version}</version>
                <executions>
                    <execution>
                        <goals>
                            <goal>npl-contrib</goal> <!-- important step: this goal must be included -->
                            <goal>npl-compile</goal>
                            <goal>npl-test-compile</goal>
                            <goal>npl-test</goal>
                        </goals>
                    </execution>
                    <configuration>
                        <!-- important step: should match the `outputDirectory` of the `copy-npl-contrib` execution of `maven-dependency-plugin` -->
                        <nplContribPath>${nplContribDir}</nplContribPath>
                    </configuration>
                </executions>
            </plugin>
        </plugins>
    </build>
</project>

Before the npl-contrib files can be discoverable in IntelliJ, mvn generate-sources or mvn compile will need to be executed. Alternatively, IntelliJ's Build can be configured to execute mvn compile before a Build and before a Rebuild by using the Maven lifecycle configuration window pane in IntelliJ. Removing the npl-contrib files is necessary to prevent errors during compile. The clean step before the generate-sources will do this as a part of the clean phase.