SDK best practices

Dependency management

Your plugin can handle third-party dependencies in one of two ways:

Option 1: Shade the dependency into your jar

If the server library might not stay stable, or if you need a specific library version to be isolated from other plugins' choices. use Maven’s shade plugin to bundle it to your jar under a relocated packaged namespace. This ensures your plugin works identically across server versions, but at the cost of larger jars and more complex shade configuration.

The notification-publisher example demonstrates this patterns. It needs specific versions of Jackson, which it shades into the jar under com.pingidentity.notification.publisher.shade.*:

<dependency>
    <groupId>com.fasterxml.jackson.core</groupId>
    <artifactId>jackson-databind</artifactId>
    <version>2.21.1</version>
    <scope>compile</scope>
</dependency>

<plugin>
    <groupId>org.apache.maven.plugins</groupId>
    <artifactId>maven-shade-plugin</artifactId>
    <version>3.5.3</version>
    <executions>
        <execution>
            <phase>package</phase>
            <goals>
                <goal>shade</goal>
            </goals>
            <configuration>
                <artifactSet>
                    <includes>
                        <include>com.fasterxml.jackson.core:jackson-databind</include>
                        <include>com.fasterxml.jackson.core:jackson-core</include>
                        <include>com.fasterxml.jackson.core:jackson-annotations</include>
                    </includes>
                </artifactSet>
                <relocations>
                    <relocation>
                        <pattern>com.fasterxml</pattern>
                        <shadedPattern>com.pingidentity.notification.publisher.shade.com.fasterxml</shadedPattern>
                    </relocation>
                </relocations>
            </configuration>
        </execution>
    </executions>
</plugin>

Refer to the notification-publisher/pom.xml for a complete example.

Option 2: rely on the server

If PingFederate already includes the library you need, declare it using the provided scope rather than bundling it with your plugin. This reduces your jar size and avoids conflicts with other plugins. The catch is, if the server upgrades or removes that library in a future version, you’ll need to test and potentially upgrade your plugin to prevent it from breaking.

<!-- Libraries PingFederate already ships; don't bundle them -->
<dependency>
    <groupId>org.apache.commons</groupId>
    <artifactId>commons-lang3</artifactId>
    <version>3.18.0</version>
    <scope>provided</scope>
</dependency>

When to use each method

Use provided for small, stable libraries that the server is guaranteed to include, like slf4j-api, commons-logging, and jakarta.servlet-api.
Shade dependencies that you own the version of, or that aren’t bundled by PingFederate, or where version conflicts with other plugins are a risk.
Never shade pingfederate-sdk itself. Always use provided.

Versioning and manifests

Plugins can report their version to PingFederate at runtime using the jar manifest. To enable this, configure maven-jar-plugin to embed version information:

<plugin>
    <groupId>org.apache.maven.plugins</groupId>
    <artifactId>maven-jar-plugin</artifactId>
    <version>3.4.1</version>
    <configuration>
        <archive>
            <manifest>
                <addDefaultImplementationEntries>true</addDefaultImplementationEntries>
            </manifest>
        </archive>
    </configuration>
</plugin>

Then retrieve it in your plugin at runtime:

public String getVersion() {
    return getClass().getPackage().getImplementationVersion();
}

This is a convention most plugins in the examples follow. It lets admins and logs verify which version of your plugin is deployed.

SDK versioning and compatibility

The PingFederate SDK maintains backwards compatibility. If you build against version 13.0.0.4, your plugin will run on versions 13.1 or 13.2 without requiring a rebuild. The SDK doesn’t remove or break existing interfaces.

New releases can change which Java versions PingFederate is compiled with. When this happens, your plugin might need to be recompiled with the same or later version of the Java Development Kit (JDK). These changes are documented in Installing Java.

New features are added: When new SDK interfaces and methods are introduced, they’re marked with a @Since annotation in the Javadoc, indicating which SDK version introduced them.
Features are deprecated: When an interface or method is scheduled for removal, it’s marked @Deprecated in the Javadoc with a note about what to use instead.

Deprecated items remain available for several major versions, giving you time to migrate. The SDK won’t break your plugin just because you’re using a deprecated method. It will log warnings while compiling your plugin, but the plugin will continue to work. When you see these compile warnings, start planning to upgrade to the supported methods.

You can update your pingfederate-sdk.version confidently, and you can build plugins against newer SDK versions and deploy them to older servers, as long as you don’t use methods newer than what the server includes.

PingFederate Server