CombineArchive

Java library to read/write/create/manipulate/... CombineArchives

View the Project on GitHub

HowTo use CombineArchive

Using the our CombineArchive library is not very complicated and can be separated in the sollowing steps:

In addition, a complete example is available in Example.java.

Opening or Creating a CombineArchive

To open a CombineArchive just pass the path to the archive to the CombineArchive constructor (source, JavaDoc):

CombineArchive ca = new CombineArchive (new File ("/path/to/archive.omex"));

If /path/to/archive.omex does not exist an empty CombineArchive aill be created.

Reading the contents of a CombineArchive

In addition to the methods described in the following these functions provide some information about the entries stored in a CombineArchive:

Iterate over all Entries in an Archive

The method getEntries () (JavaDoc) returns a list of files stored in the archive. To iterate over all entries you could use the following snippet:

for (ArchiveEntry entry : ca.getEntries ())
{
	System.out.println (">>> file name in archive: " + entry.getFileName ()
		+ "  -- apparently of format: " + entry.getFormat ());
}

Get an Entry by Location

Passing a path to getEntry (String location) (JavaDoc) you can retrieve the file that is stored at this location:

ArchiveEntry myEntry = ca.getEntry ("/path/to/entry");

Paths should always start with a / and, thus, start absolute from the root of the archive.

Receive the Meta Data describing an Entry

To iterate over the meta data descriptions stored for an entry entry in the archive you might want to use the getDescriptions () (JavaDoc) method:

for (MetaDataObject description : entry.getDescriptions ())
{
	System.out.println ("+ found some meta data about "
		+ description.getAbout ());
}

To learn more about meta data have a look at MetaDataObjects.

Extract a File from the CombineArchive

Given an entry in entry you can extract it using extractFile(File target) (JavaDoc):

File tmpEntryExtract = new File ("/path/to/desired/destination");
entry.extractFile (tmpEntryExtract);

Afterwards, you’ll find the fill in /path/to/desired/destination.

Read a File from the CombineArchive without extracting it

To read a file you do not have to extract it. Instead, you can access its input stream directly:

InputStream myReader = Files.newInputStream (entry.getPath (), StandardOpenOption.READ);
// do whatever you want with the stream
myReader.close ();

This of course will on the fly decompress it from the ZIP container. Thus, it is fine for just taking a small look into a file, but not the best way to open all files repeatedly.

Extract the whole CombineArchive

The archive can be extracted by passing the destination to the extractTo(File destination) (JavaDoc) method:

File destination = new File ("/path/to/myDestination");
ca.extractTo (destination);

This will extract all files stored in the archive to /path/to/myDestination.

Updating the CombineArchive

It is of course also possible to manipulate archives.

Adding a File to an Archive

There are multiple options to add another file to a CombineArchive. The following two sections will cover the main methods.

Specifying the Target Name

This is the simplest method. Just pass a file and a target location to addEntry(File toInsert, String targetName, URI format) (JavaDoc):

ArchiveEntry CellMLFile = ca.addEntry (
	new File ("/tmp/base/path/subdir/file.cellml"),
	"/target/dir/file.cellml", 
	new URI ("http://identifiers.org/combine.specifications/cellml.1.0"));

After doing so you’ll find the CellML file in /target/dir/file.cellml of the CombineArchive.

(To learn more about formats see combine-ext:wiki, especially http://sems.uni-rostock.de/trac/combine-ext/wiki/CombineFormatizer)

Providing a Base Path

The function addEntry(File baseDir, File file, URI format) (JavaDoc will add an entry stored in file from the subtree starting in baseDir. For example:

ArchiveEntry SBMLFile = ca.addEntry (
	new File ("/tmp/base/path"),
	new File ("/tmp/base/path/sub/dir/file.sbml"),
	new URI ("http://identifiers.org/combine.specifications/sbml"));

will add an SBML file which is located in /tmp/base/path/sub/dir/file.sbml. The base path is set to /tmp/base/path, that means the entry can afterwards be found in /sub/dir/file.sbml in the CombineArchive.

While this method seems to be more complicated and less useful, there are cases when it eases your work. Imagine you want to create an archive of all files in /home/user/latest/research recursively. Using this method you could simply iterate through all files and directories always passing /home/user/latest/research as base path to the creation of entries. This way, you can quickly zip subtree on your file system.

(To learn more about formats see Combine-Ext, especially CombineFormatizer)

Setting the Main Entry

You can immediately define the main entry of an archive when you add it. There are versions of the previously described addEntry (...) functions which take another boolean to specify if it’s the main entry.

In addition, you can set a main entry afterwards by calling the setMainEntry (ArchiveEntry mainEntry) (JavaDoc) method, passing the main entry:

ca.setMainEntry (entry);

Removing a File from an Archive

You can remove a file from an archive by specifying its location in removeEntry(String location) (JavaDoc):

ca.removeEntry("/path/to/the/entry");

Additionally, you can simply pass the ArchiveEntry to removeEntry(ArchiveEntry entry) (JavaDoc):

ca.removeEntry(entry);

Adding Meta Data to an Entry in the Archive

To describe an entry in the archive simply pass a MetaDataObject to the addDescription(MetaDataObject description) (JavaDoc) function:

entry.addDescription (someMetaData);

Read more about MetaDataObjects.

If you have a file containing multiple description elements for a single archive entry you may just pass the file to the addAllDescriptions (File metaDataFile) (JavaDoc) function:

entry.addAllDescriptions (new File ("/path/to/rdf/file"));

This will read the file /path/to/rdf/file and add all rdf:Description subtrees to entry.

Removing Meta Data of an Entry in the Archive

You can of course also delete some meta data for an entry in the archive. Just pass the description to the removeDescription (MetaDataObject toDelete) (JavaDoc) function:

entry.removeDescription (someMetaData);

Read more about MetaDataObjects.

Finalising the CombineArchive

While we are working directly in the CombineArchive you need to finalise the archive after you finished working with it. That means, you need to call the following functions:

ca.pack ();
ca.close ();

Full Example

A complete example is available at Example.java.