Skip to content

Dependency Management

A vast assortment of third-party Java libraries are available, expanding the set of ready-to-use functionality well beyond what is already a rich standard library. Plugins for the Delphix Masking engine are able to make use of external libraries, but a number of guidelines should be followed to ensure proper function and compatibility. Note that the plugin classloader uses a plugin-first loading strategy for dependencies.

How to Properly Use and Embed External Libraries

When using an external library in a plugin for the Delphix Masking engine, consider these guidelines:

  • The plugin JAR should contain all external libraries. This is commonly referred to as a "fat JAR". This prevents the plugin code from inadvertently linking with copies of the same library that might happen to be part of the Masking Engine's codebase, leading to potential version conflicts and unpredictable behavior across upgrades.
  • However, a small set of packages defining the interface between plugins and the Delphix Masking Engine must not be embedded in the JAR. It is critical that, for these packages, the plugin code link against the same classes already loaded by the engine. These packages are:
    • com.delphix.masking:masking-algorithm-api
    • com.fasterxml.jackson.core:jackson-annotations
    • com.google.code.findbugs:jsr305
    • junit:junit

If the externally created plugin uses any of the mentioned libraries, the exact same libraries versions should be used by the plugin author, as the ones used by the SDK. The way to find those versions is:

- in the installed SDK find the following gradle file under `samples` directory:
    * gradle.properties

It contains the versions of the SDK provided external libraries, for example:

        googleGuavaVer=28.0-jre
        maskingAlgoVer=1.3.0
        jacksonVer=2.9.5
        junitVer=4.12

Looking to those versions author should decide what version of corresponding library to use (if it is required by their design).

  • Plugins consuming third-party libraries should be thoroughly tested, as it is not uncommon that library code will attempt to use permissions not granted by the plugin sandbox. If this is the case, there is currently no way to modify the constraints under which the plugin code is executed.
  • The plugin author, not Delphix, is responsible for ensuring that any license files or other forms of attribution required by any embedded software are handled properly.
  • The entity deploying the plugin, not Delphix, is responsible for ensuring the organization operating the Masking Engine has obtained the necessary licenses or rights to use any embedded software.

Example Build File

The following fragments, derived from the sample algorithm build.gradle file, illustrate how to correctly build a plugin using the gradle build system:

jar {
    from {
        configurations.runtimeClasspath.collect { it.isDirectory() ? it : zipTree(it) }
    }
    includeEmptyDirs = false

    manifest {
        attributes(
                (PluginMetadata.PLUGIN_NAME_KEY)       : "SampleAlgorithms",
                (PluginMetadata.AUTHOR_NAME_KEY)       : "Sample Author,
                (PluginMetadata.PLUGIN_VERSION_KEY)    : "1.0.0 ${getGitHash}",
                (PluginMetadata.ALGORITHM_API_VERSION_KEY): maskingAlgoVer,
                'Build-Timestamp': new java.text.SimpleDateFormat("yyyy-MM-dd'T'HH:mm:ss.SSSZ").format(new Date()),
                'Created-By'     : "Gradle ${gradle.gradleVersion}",
                'Build-Jdk'      : "${System.properties['java.version']} (${System.properties['java.vendor']} ${System.properties['java.vm.version']})",
                'Build-OS'       : "${System.properties['os.name']} ${System.properties['os.arch']} ${System.properties['os.version']}",
        )
    }
}

dependencies {
    compileOnly ('com.google.code.findbugs:jsr305:3.0.2')
    compileOnly ('com.delphix.masking:masking-algorithm-api:' + maskingAlgoVer)
    compileOnly ('com.fasterxml.jackson.core:jackson-annotations:' + jacksonVer)

    compile 'com.google.guava:guava:' + googleGuavaVer

    testImplementation 'com.google.code.findbugs:jsr305:3.0.2'
    testImplementation 'com.delphix.masking:masking-algorithm-api:' + maskingAlgoVer
    testImplementation 'com.fasterxml.jackson.core:jackson-annotations:' + jacksonVer
    testImplementation 'junit:junit:' + junitVer
    testImplementation "com.google.truth:truth:" + googleTruthVer
}

How this works:

  • The "from { ... }" property of the jar section instructs gradle to included all classed need at runtime in the plugin JAR file.
  • In the dependencies section, packages comprising the interface between the plugin and Masking Engine are listed as compileOnly. This excludes them from the runtime environment and causes them to be omitted from the plugin JAR file.
  • The third-party code dependency on the popular Google Guava library is listed as compile, causing it to be included in the plugin JAR file.

Note

Variables defining the package dependency versions are typically read from the gradle.properties file.