taverna-databundle

Data bundles API

API for Taverna Data Bundles.

See also the structure of the data bundle.

This API is built on the Java NIO Files and the RO Bundle API, which uses the Java ZIP file provider to generate the Data Bundle.

The class org.apache.taverna.databundle.DataBundles complements the Java java.nio.Files API with more specific helper methods to work with Data Bundles.

Example of use

Example in full is at org.apache.taverna.databundle.TestExample

Create a new (temporary) data bundle:

        Bundle dataBundle = DataBundles.createBundle();

Get the input ports and the port "in1":

        Path inputs = DataBundles.getInputs(dataBundle);
        Path portIn1 = DataBundles.getPort(inputs, "in1");

Setting a string value for the input port:

        DataBundles.setStringValue(portIn1, "Hello");

And retrieving it:

        if (DataBundles.isValue(portIn1)) {
            System.out.println(DataBundles.getStringValue(portIn1));
        }

Hello

Alternatively, use the regular Files methods:

        for (String line : Files
                .readAllLines(portIn1, Charset.forName("UTF-8"))) {
            System.out.println(line);
        }

Binaries and large files are done through the Files API:

        try (OutputStream out = Files.newOutputStream(portIn1,
                StandardOpenOption.APPEND)) {
            out.write(32);
        }

Or using NIO:

        Path localFile = Files.createTempFile("", ".txt");
        Files.copy(portIn1, localFile, StandardCopyOption.REPLACE_EXISTING);
        System.out.println("Written to: " + localFile);

Written to: C:\Users\stain\AppData\Local\Temp\2009921746200670789.txt

Either direction of copy works, of course:

        Files.copy(localFile,
                DataBundles.getPort(DataBundles.getOutputs(dataBundle), "out1"));

When you get a port, it can become either a value or a list:

        Path port2 = DataBundles.getPort(inputs, "port2");
        DataBundles.createList(port2); // empty list
        List<Path> list = DataBundles.getList(port2);
        assertTrue(list.isEmpty());

Adding items sequentially:

        Path item0 = DataBundles.newListItem(port2);
        DataBundles.setStringValue(item0, "item 0");
        DataBundles.setStringValue(DataBundles.newListItem(port2), "item 1");
        DataBundles.setStringValue(DataBundles.newListItem(port2), "item 2");

Set and get by explicit position:

        DataBundles.setStringValue(DataBundles.getListItem(port2, 12), "item 12");
        System.out.println(DataBundles.getStringValue(DataBundles.getListItem(port2, 2)));

item 2

The list is sorted numerically (e.g. 2, 5, 10) and will contain nulls for empty slots:

        System.out.println(DataBundles.getList(port2));

[/inputs/port2/0, /inputs/port2/1, /inputs/port2/2, null, null, null, null, null,
 null, null, null, null, /inputs/port2/12]

Ports can be browsed as a map by port name:

        NavigableMap<String, Path> ports = DataBundles.getPorts(inputs);
        System.out.println(ports.keySet());

[in1, port2]

Saving a data bundle:

        Path zip = Files.createTempFile("databundle", ".zip");
        DataBundles.closeAndSaveBundle(dataBundle, zip);
        // NOTE: From now dataBundle and its Path's are CLOSED
        // and can no longer be accessed
        System.out.println("Saved to " + zip);

Saved to C:\Users\stain\AppData\Local\Temp\databundle6905894602121718151.zip

Inspecting the zip:

        if (Desktop.isDesktopSupported()) {
            // Open ZIP file for browsing
            Desktop.getDesktop().open(zip.toFile());
        }

Loading a data bundle back from disk:

        try (Bundle dataBundle2 = DataBundles.openBundle(zip)) {
            // Any modifications here will be saved on (here automatic) close
        }