Overview

There is currently one curnit archive file format (dev20050513). We might call these ".car" files. Let's see if that catches on.

When I put together the file format, I didn't expect it to persist so long. It was a hack to get something going. I had in mind that curnits would be generated on the fly from a database of pods. We're not there yet, so we have the curnit archive format. This file ties a bunch of pods together within a single archive.

Structurally, it is a JAR with these files:

META-INF/MANIFEST.MF
curnit.xml
podsReferenced.properties
a number of POD_<PODID>.xml files
optional pod archive subdirectories for binary resources attached to those pods

META-INF/MANIFEST.MF

This is the manifest for the jar, as specified in the Java JAR specification. Basically it encodes metadata of the jar. Here is the curnit.xml generated by BuildPas0007, with comments.

# this is fixed across all JAR manifests
Manifest-Version: 1.0
# this is not important
Created-By: SAIL Curnit Builder 0.1
# the goal of this was that you could double-click on the jar,
# but it's not very practical since those classes will never be on the classpath
Main-Class: net.sf.sail.common.apps.PreviewCurnit
# this is the title of the curnit (title being a name that is for display and not authoritative)
Curnit-Title: WISE_0007
# this is the id for the format in which this curnit archive is encoded
Curnit-Format: dev20050513

Notice that the format identifier isn't "1.0". It's just the format at an arbitrary date from which the format has yet to change: June 13, 2005. It's there so that if the format does change, code can be written to be backwards-compatible with curnits written in this format.

curnit.xml

This is the a net.sf.sail.core.curnit.Curnit bean marshalled by java.beans.XMLEncoder. Example generated by BuildPas0007.

<?xml version="1.0" encoding="UTF-8"?> 
<java version="1.5.0_08" class="java.beans.XMLDecoder"> 
 <object class="net.sf.sail.core.curnit.Curnit"> 
  <void property="curnitId"> 
   <object class="net.sf.sail.core.uuid.CurnitUuid"> 
    <string>cccccccc-0002-0000-0000-000000000000</string> 
   </object> 
  </void> 
  <void property="rootPodId"> 
   <object class="net.sf.sail.core.uuid.PodUuid"> 
    <string>dddddddd-0002-0000-0000-000000000000</string> 
   </object> 
  </void> 
  <void property="title"> 
   <string>WISE_0007</string> 
  </void> 
 </object> 
</java>

The title property matches the Curnit-Title metadata. The curntiId is the SAIL UUID of the curnit. The rootPodId is the SAIL UUID of the pod that is the root of the curnit's pod tree.

podsReferenced.properties

This is a simple property list of the pods referenced in this curnit and their respective binary resource archives. Example from BuildPas0001,

#pod dependencies
#Wed Sep 20 10:31:18 EDT 2006
dddddddd-0001-0002-0000-000000000000=
dddddddd-0001-0001-0000-000000000000=withincurnit\:/tmp/wise1.jar
dddddddd-0101-0000-0000-000000000000=
dddddddd-0101-0001-0000-000000000000=

The "0001-0001" pod has an archive associated with it and the source of the archive is given by a URL on the right side of the equals sign. In this case, the URL is our custom withincurnit: protocol that specifies a file in the curnit archive at that path.

POD_<PODID>.xml

For the format of this file, see Pod XMLEncoder format.

Putting it all together

Basically, the loader (see loadPods()) reads the pod UUIDs from podsReferenced.properties and then looks for an XML marshalling of each pod. It unmarshalls those into pod objects (child of BeanContext), resolves access to the binary resources, then assembles them all up into a runtime version of the curnit.

That's pretty much it. Comment on this page or write SAIL-Dev with any questions.

Curnit archive file format