New DOI
1 file changed
tree: 400cf6c48d06f55c63610a55d16d1291fa3e7279
  1. src/
  2. .gitignore
  3. .travis.yml
  4. LICENSE.md
  5. pom.xml
  6. README.md
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());
		}