[maven-release-plugin]  copy for tag 0.2.1
[maven-release-plugin] prepare release 0.2.1
1 file changed
tree: b72e5a73948878a30b588eca794b327e975593c5
  1. .gitignore
  2. README.md
  3. pom.xml
  4. src/
README.md

Data bundles API

API for Taverna Data Bundles

Work in progress.

See Data bundle requirements and TestDataBundles.java

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

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

Building

mvn clean install

should normally work, given a recent version of Maven 3 and Java 7 SDK.

myGrid's Jenkins installation has automated builds of both databundles and robundle, which snapshots are deployed to myGrid's snapshot repository.

Maven should download the latest snapshot of robundle from myGrid's snapshot repository, but in some cases you might have to build robundle locally before building this project.

Example of use

Example in full is at uk.org.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 Java 7 style:

        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            
        }