GPA Tool Extension Development Guide

This guide is intended for users who wish to build GPA models using SuperMap iServer Geoprocessing Modeler or SuperMap iDesktopX toolbox, but find existing tools insufficient for their functional requirements. Follow this guide to complete custom extensions of GPA tools and learn deployment steps in SuperMap iServer Geoprocessing Modeler or SuperMap iDesktopX toolbox. Prerequisites include:

Prior knowledge of Maven repository usage, Scala/Java code development, and JAR file construction is required before using this guide.
Extension development is implemented through SuperMap SPS extension mechanism. Spatial analysis algorithms from SuperMap iObjects Java or SuperMap iObjects for Spark can be utilized during custom tool implementation.
Extended tools can be discovered in visual interfaces of SuperMap iServer Geoprocessing Modeler or SuperMap iDesktopX toolbox with automatically generated parameter interfaces. They can connect with other GPA tools for model building, eliminating UI development and lowering custom tool usage barriers.
This guide can be used with sample code sps-geocoder, which provides geocoding functionality to convert address text files into spatial files with coordinate information. Sample code locations:
- %SuperMap iServer_HOME%\samples\code\sps\samplecode\sps-geocoder
- %SuperMap iDesktopX_HOME%\template\sps\samplecode\sps-geocoder

Click here to download Sample Code and Data.

1. Extension Development Steps

1.1. Add Maven Project Dependencies

https://maven.supermap.io is SuperMap's official Maven repository for developers, facilitating extension development with SuperMap products.

The repository contains JAR files and third-party dependencies for SuperMap iServer and SuperMap iObjects. By adding SuperMap Maven repository in pom files, required dependencies can be directly added to Maven projects, resolving third-party dependency issues when using SuperMap products.

Add following <repositories> node in pom.xml:

<repositories>
    <repository>
        <id>iserver</id>
        <name>iserver</name>
        <url>https://maven.supermap.io/</url>
        <snapshots>
            <enabled>true</enabled>
        </snapshots>
        <releases>
            <enabled>true</enabled>
        </releases>
    </repository>
</repositories>

Add required dependencies for extension development in pom.xml. sps-core is the main dependency available in SuperMap Maven repository. Add a <dependency> node:

<dependency>
    <groupId>com.supermap.sps</groupId>
    <artifactId>sps-core</artifactId>
    <version>1.0</version>
</dependency>

Note: When Spark distributed computing is required, add dependency for bdt-processing from SuperMap iObjects for Spark:

<dependency>
    <groupId>com.supermap.bdt</groupId>
    <artifactId>bdt-processing</artifactId>
    <version>10.1.0-SNAPSHOT</version>
</dependency>

1.2. Create Custom Tool Related Types

New custom tool classes must inherit from com.supermap.sps.impl.annotated.AnnotatedProcessBean.

Note: For Spark distributed computing, inherit from com.supermap.bdt.processing.sps.BDTAnnotatedBean to use SuperMap iObjects for Spark APIs in execute function (refer to 《SuperMap iObjects for Spark Programming Guide》). Supports setting cluster parameters in GPA interface.

First create a base class inheriting AnnotatedProcessBean, e.g. DemoProcess class:

Create implementation class inheriting from DemoProcess. Implement tool functionality in execute function.

Use annotations defined in GPA extension framework to describe tool basic info, outputs, and parameters for UI discovery. Common annotations:

@ProcessDef: Basic info, caption parameter sets tool display name in GPA interface:

@OutputDef: Output
@InputDef: Input parameter
@NamespaceDef: Namespace for multi-level directory organization:

Detailed annotation parameters are described in Chapter 2.

1.3. Create Custom Factory

Create custom factory class inheriting from com.supermap.sps.impl.annotated.AbstractAnnotatedProcessFactory to load custom tools.

Note: For Spark distributed computing, inherit from com.supermap.bdt.processing.sps.AbstractBDTProcessFactory

Example: GeocoderFactory class loading geocoding tools:

Constructor parameters:

Factory name (ID, unchangeable)
Factory namespace (display name, editable first-level directory in GPA interface):

Factory description
Base classes of custom tools (e.g. A.class,B.class)

1.4. Register Custom Tool

Use SPI to register relationship between custom tool and base class. Create META-INF/services/com.supermap.geocode.DemoProcess file and register GeoCodeProcess:

1.5. Register Custom Factory

Register factory via SPI in META-INF/service/com.supermap.sps.core.workflow.IProcessFactory. Example: Register GeocoderFactory:

Code-level extension development completes after this step.

1.6. Add to iServer Geoprocessing Modeler

To use extended tools in iServer Geoprocessing Modeler:

Package extension as JAR file and place in %SuperMap iServer_HOME%\support\geoprocessing\lib. Restart iServer and access Geoprocessing Modeler to find custom tools in left panel.

Note: For Spark distributed computing, append "withbdt" to JAR filename to ensure automatic distribution to clusters:

1.7. Add to SuperMap iDesktopX GPA Toolbox

To use extended tools in SuperMap iDesktopX toolbox:

Place custom tool JAR in %SuperMap iDesktop_HOME%\lib. Restart SuperMap iDesktopX to find tools in toolbox.

Note: For Spark distributed computing, also copy JAR to %SuperMap iDesktop_HOME%\support\bdtJars for cluster distribution.

2. Annotation Specifications

Annotation system in GPA extension framework (provided by sps-core-*.jar) supports Chinese parameter names, optional parameters, default values, etc.

Annotation System in GPA Extension Framework

Key annotations for custom tool development:

@ProcessDef

Describes tool basic info for methods/classes

name(): Tool name (analogous to Maven artifactId)
caption(): Display name (defaults to name)
description(): Tool description
version(): Version info (default 1.0)
compatibleVersion(): Compatible version (default 1.0)

@NamespaceDef

namespace(): Namespace ID (analogous to Maven groupId), supports multi-level directories with "." separator
title(): Namespace display name
description(): Namespace description

@InputDef

Binds process input parameters

name(): Unique input name
caption(): Display name (defaults to name)
description(): Input description
isRequired(): Mandatory flag (default true)
defaultValue(): Default value (ignored for collections)
meta(): Additional metadata (e.g., value ranges, connection types)
dataType(): Explicit data type specification (required for generics/BDTParameterBuilder)

Supported metadata types:

Numeric types (auto-matched):
- minValue: Minimum value
- maxValue: Maximum value
- left: Range left boundary {open, close}
- right: Range right boundary {open, close}
String types:
- stringType: {connection, FieldType}
- connection.mode: {SELECT, CREATE}
- supportType: FieldType enumerations
DatasetVector types:
- supportType: DatasetType enumerations