sop-java/external-sop/README.md

External-SOP

Access an external SOP binary from within your Java/Kotlin application.

This module implements a backend for sop-java that binds to external SOP binaries (such as sqop, python-sop etc.). SOP operation calls will be delegated to the external binary, and the results are parsed back, so that you can access them from your Java application as usual.

Example

Let's say you are using ExampleSOP which is a binary installed in /usr/bin/example-sop. Instantiating a SOP object is as simple as this:

SOP sop = new ExternalSOP("/usr/bin/example-sop");

This SOP object can now be used as usual (see here).

Keep in mind the license of the external SOP binary when integrating one with your project!

Some SOP binaries might require additional configuration, e.g. a Java based SOP might need to know which JAVA_HOME to use. For this purpose, additional environment variables can be passed in using a Properties object:

Properties properties = new Properties();
properties.put("JAVA_HOME", "/usr/lib/jvm/[...]");
SOP sop = new ExternalSOP("/usr/bin/example-sop", properties);

Most results of SOP operations are communicated via standard-out, standard-in. However, some operations rely on writing results to additional output files. To handle such results, we need to provide a temporary directory, to which those results can be written by the SOP, and from which External-SOP reads them back. The default implementation relies on Files.createTempDirectory() to provide a temporary directory. It is however possible to overwrite this behavior, in order to specify a custom, perhaps more private directory:

ExternalSOP.TempDirProvider provider = new ExternalSOP.TempDirProvider() {
    @Override
    public File provideTempDirectory() throws IOException {
        File myTempDir = new File("/path/to/directory");
        myTempDir.mkdirs();
        return myTempDir;
    }
};
SOP sop = new ExternalSOP("/usr/bin/example-sop", provider);

Testing

The external-sop module comes with a growing test suite, which tests SOP binaries against the expectations of the SOP specification.
To configure one or multiple backends for use with the test suite, just provide a custom config.json file in src/main/resources/sop/external. An example configuration file with the required file format is available as config.json.example.