tree: 92f7eb0d73a6b72f8274c060cf030c811643c8a0 [path history] [tgz]
  1. src/
  2. pom.xml
  3. README.md
taverna-robundle/README.md

RO bundle API

API for building researchobject.org RO bundles.

Complies with RO bundle specification version 1.0.

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

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

This API is the basis for the Taverna Data Bundles API.

Usage

If you use Maven 3, then add to your pom.xml:

<dependencies>
    <dependency>
        <groupId>org.apache.taverna.language</groupId>
        <artifactId>taverna-robundle</artifactId>
        <version>0.15.1-incubating</version>
    </dependency>
</dependencies>

To find the latest <version> to use above (this README might not have been updated), see the Apache Taverna Language downloads.

Supported bundle formats

The Bundles API will load a bundle in any of the formats above, converging them to a Research Object Bundle, while still maintaining the manifests of the other formats, if they exist within the bundle.

Thus, if you open say a COMBINE Archive and add a couple of resources, indicating their mediatype using bundle.getManifest().getAggregation(path).setMediaType("a/b"), then when closing this bundle, the API will generate both an RO Bundle manifest and a COMBINE manifest that reflect this.

Example of use

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

		// Create a new (temporary) RO bundle
		Bundle bundle = Bundles.createBundle();

		// Get the inputs
		Path inputs = bundle.getRoot().resolve("inputs");
		Files.createDirectory(inputs);

		// Get an input port:
		Path in1 = inputs.resolve("in1");

		// Setting a string value for the input port:
		Bundles.setStringValue(in1, "Hello");

		// And retrieving it
		if (Bundles.isValue(in1)) {
			System.out.println(Bundles.getStringValue(in1));
		}

		// Or just use the regular Files methods:
		for (String line : Files.readAllLines(in1, Charset.forName("UTF-8"))) {
			System.out.println(line);
		}

		// Binaries and large files are done through the Files API
		try (OutputStream out = Files.newOutputStream(in1,
				StandardOpenOption.APPEND)) {
			out.write(32);
		}
		// Or Java 7 style
		Path localFile = Files.createTempFile("", ".txt");
		Files.copy(in1, localFile, StandardCopyOption.REPLACE_EXISTING);
		System.out.println("Written to: " + localFile);

		Files.copy(localFile, bundle.getRoot().resolve("out1"));

		// Representing references
		URI ref = URI.create("http://example.com/external.txt");
		Path out3 = bundle.getRoot().resolve("out3");
		System.out.println(Bundles.setReference(out3, ref));
		if (Bundles.isReference(out3)) {
			URI resolved = Bundles.getReference(out3);
			System.out.println(resolved);
		}

		// Saving a bundle:
		Path zip = Files.createTempFile("bundle", ".zip");
		Bundles.closeAndSaveBundle(bundle, zip);
		// NOTE: From now "bundle" and its Path's are CLOSED
		// and can no longer be accessed

		System.out.println("Saved to " + zip);

		// Loading a bundle back from disk
		try (Bundle bundle2 = Bundles.openBundle(zip)) {
			assertEquals(zip, bundle2.getSource());
		}