How to develop an extension module

Owned by Former user (Deleted)
Last updated: 2023-05-30 by Marco Peters
5 min read

Warning

This is a very draft version.

  • TODO: think about providing Maven archetypes for the different extension module types


Table of Contents

System requirements 

  • Java IDE, e.g. IntelliJ IDEA
  • Python IDE, e.g. PyCharm
  • JDK 11
  • Maven 3

Java single module extension

my-module/
    .gitignore
    pom.xml
    src/main/
        java/<code-base>/*.java
        resources/<code-base>/*
    src/test/
        java/<code-base>/*.java
        resources/<code-base>/*
    target/
        classes/<code-base>/*.class
        nbm/netbeans/extra/*

See snap-desktop-basic-single code template.

Building the module

The plugin module can be build by calling the following maven command:

mvn clean package

After executing this command the .nbm plugin file can be found in the target directory.

This plugin can be provided to other SNAP users. How they can install it into their SNAP installation is explained in Install a Plugin (.nbm file) via Plugin Manager.

Python single module extension

TODO: describe how modules are configured that use the snap-python adapter

Arbitrary executable, single module extension

TODO: describe how modules are configured that use the stand-alone tools adapter

Java multi-module extensions

Each module is fully created as a single module with it's functionalities within the parent module.

my-parent-module/
    .gitignore
    pom.xml
    my-module-1/
	    pom.xml
        src/main/
            java/<code-base-1>/*.java
            resources/<code-base-1>/*
        src/test/
            java/<code-base-1>/*.java
            resources/<code-base-1>/*
        target/classes/<code-base-1>/*.class
    my-module-2/
    my-module-3/
    target/
        netbeans_clusters/extra/*
        netbeans_site/*.nbm

See snap-desktop-basic-multi code template.

You will need to aggregate the outputs of the sub-modules of your multi-module project for running and debugging with SNAP as well as for plugin and deployment. For this purpose, the Maven NBM Plugin provides the goals cluster and autoupdate. In your parent POM specify the the following:

pom.xml
<build>
    <plugin>
        <groupId>org.codehaus.mojo</groupId>
        <artifactId>nbm-maven-plugin</artifactId>
        <version>3.14</version>
        <inherited>false</inherited> 
        <executions>
            <execution>
                <phase>package</phase>
                <goals>
                    <goal>cluster</goal>
                    <goal>autoupdate</goal>
                </goals>
            </execution>
       </executions>
   </plugin>
    ...
</build>

Another option is to create a Kit Module as it is done for the various SNAP Toolboxes:

Debugging and Running your Extension in an IDE

There is a minor difference in the setup of the run/debug configurations whether you run/debug against a checked-out version of SNAP or if you use a binary installation.

Using a checked-out SNAP build

To build SNAP from sources check the guide How to build SNAP from sources. Assuming you have a checked-out and built <snap-desktop> source repository, then in the following sections the variable <snap-app> will refer to <snap-desktop>/snap-application/target/snap, which is the fully self-contained SNAP application directory.

Using an existing SNAP installation

Install a binary SNAP distribution whose version is compatible with the SNAP version stated in your project's pom.xml. In the following sections, the variable <snap-app> will refer to your SNAP installation directory. 

IntelliJ IDEA IDE

Debugging and Running with SNAP Desktop

Select File/Open and select your project's <my-module>/pom.xml file. To build your sources, open the Maven Projects tool window and run the lifecycle goals clean and package at once. After this first build, you can use CTRL+F9 to build your project. To run/debug your your extension module in SNAP, select Run/Edit Configurations and add a new configuration of type JAR Application (since IDEA 14) and give it a name, e.g. SNAP Desktop. Make sure to adjust the value of <snap-app> depending on whether you are using a checked-out version of SNAP or an installed SNAP:

  • Path to JAR: <snap-app>/snap/modules/ext/org.esa.snap.snap-rcp/org-esa-snap/snap-main.jar
  • VM options: -Dsun.java2d.noddraw=true -Dsun.awt.nopixfmt=true -Dsun.java2d.dpiaware=false -Dorg.netbeans.level=INFO -Xmx4G
  • Program arguments: --clusters "<my-module>/target/nbm/netbeans/<clusterName>" --patches "<my-module>/$/target/classes" --userdir "<my-module>/target/userdir"
  • Working directory: <snap-app>

The variable <clusterName> depends on the configuration of the nbm-maven-plugin in your <my-module>/pom.xml file. The configuration property cluster defines the name of the cluster. The default value is extra (i.e replace <clusterName> with extra). For multi-module projects let --clusters option point to the aggregation directory:

  • Program arguments: --clusters "<my-module>/target/netbeans_clusters/<clusterName>" --patches "<my-module>/$/target/classes" --userdir "<my-module>/target/userdir"

Debugging and Running with GPT of SNAP Engine

If you want to debug, run and test a processor extension (GPF operator) without the GUI but using the SNAP gpt command-line tool, create a new configuration of type JAR Application (since version 14) and give it a name, e.g. SNAP GPT. Again, make sure to set the path of <snap-app> depending on whether you are using a checked-out version of SNAP from https://github.com/senbox-org/snap-desktop or an installed SNAP:

  • Path to JAR: <snap-app>/snap/modules/ext/org.esa.snap.snap-core/org-esa-snap/snap-runtime.jar
  • VM options:  -Dsnap.mainClass=org.esa.snap.core.gpf.main.GPT -Dsnap.extraClusters=<my-module>/target/nbm/netbeans/<clusterName> -Dsnap.log.level=ALL -Xmx10G
  • Program arguments: <my-operator> ... (any GPT options and operator parameters here)
  • Working directory: <snap-app>

NetBeans IDE

Select File/Open Project and select the directory <my-module> which contains your project's pom.xml file. Build the project using Run/Build Project or use the toolbar button. In the Projects tool window, double-click Project Files/settings.xml (points to ~/.m2/settings.xml) and make sure it contains a profile defining a property netbeans.installation whose value points to the value of <snap-app>:


~/.m2/settings.xml
<settings>
    ...
    <profiles>
        ...
        <profile>
            <id>netbeans-snap</id>
            <properties>
                <netbeans.installation>Put the value of ${snap-app} in here</netbeans.installation>
            </properties>
        </profile>
    </profiles>
</settings>

Save the settings.xml file. A new entry netbeans-snap will appear in the Run Configuration drop-down list in the NetBeans toolbar and select the Run Project toolbar button next to it.