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
- 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.