New DOI
1 file changed
tree: 400cf6c48d06f55c63610a55d16d1291fa3e7279
  1. .gitignore
  2. .travis.yml
  3. LICENSE.md
  4. README.md
  5. pom.xml
  6. src/
README.md

RO bundle API

Build Status DOI

API for building researchobject.org RO bundles.

Complies with RO bundle specification version 1.0.

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

The class org.purl.wf4ever.robundle.Bundles complements the Java 7 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.

Slides

Slides

Slides 2014-04-24

Usage

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

<dependencies>
    <dependency>
       	<groupId>org.purl.wf4ever.robundle</groupId>
        <artifactId>robundle</artifactId>
        <version>0.5.0</version>
    </dependency>
</dependencies>
<repositories>
    <repository>
        <id>mygrid-repository</id>
        <name>myGrid Repository</name>
        <url>http://www.mygrid.org.uk/maven/repository</url>
        <releases />
        <snapshots>
            <enabled>false</enabled>
        </snapshots>
    </repository>
</repositories>

To find the latest <version> (in case the above has not been updated), see the list of robundle releases. To download a precompiled binary JAR, see the myGrid's Maven repository.

Building

If you are building from source (this repository), then:

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 robundle, which are deployed to myGrid's snapshot Maven repository.

To use a snapshot build, add this repository to pom.xml:

<repository>
    <id>mygrid-snapshot-repository</id>
    <name>myGrid Snapshot Repository</name>
    <url>http://www.mygrid.org.uk/maven/snapshot-repository</url>
    <releases>
        <enabled>false</enabled>
    </releases>
    <snapshots />
</repository>

Then change your <dependency> to match the -SNAPSHOT version in this project's pom.xml.

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.purl.wf4ever.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());
		}