InDefero Upload Archive Format

At the moment, this documentation is only available in English.

• Motivation
• The manifest format
• Final notes

Motivation

Adding multiple, individual downloads to a project for a release can be a tedious task if one has to select each file manually, and then has to fill in the summary and correct labels for each of these downloads individually.

InDefero therefore supports the upload of "archives" that contain multiple downloadable files. These archives are standard PKZIP files with only one special property - they contain an additional manifest file which describes the files that should be published.

Once such an archive has been uploaded and validated by InDefero, its files are extracted and individual downloads are created for each of them. If the archive contains files that should replace existing downloads, then InDefero takes care of this as well - automatically. Files that exist in the archive but are not listed in the manifest are not extracted.

An archive file and its manifest file can easily be compiled, either by hand with the help of a text editor, or through an automated build system with the help of your build tool of choice, such as Apache Ant.

The manifest format

The manifest is an XML file that follows a simple syntax. As it is always easier to look at an example, here you have one:

<?xml version="1.0" encoding="UTF-8" ?>
<manifest>
  <file>
    <name>foo-1.2.tar.gz</name>
    <summary>Tarball</summary>
    <replaces>foo-1.1.tar.gz</replaces>
    <labels>
       <label>Type:Archive</label>
    </labels>
  </file>
  <file>
    <name>foo-1.2-installer.exe</name>
    <summary>Windows MSI Installer</summary>
    <description>This installer needs Windows XP SP2 or later.</description>
    <labels>
       <label>Type:Installer</label>
       <label>OpSys:Windows</label>
    </labels>
  </file>
</manifest>

This is the DTD for the format:

<!DOCTYPE manifest [
<!ELEMENT manifest (file+)>
<!ELEMENT file (name,summary,replaces?,description?,tags?)>
<!ELEMENT name (#PCDATA)>
<!ELEMENT summary (#PCDATA)>
<!ELEMENT replaces (#PCDATA)>
<!ELEMENT description (#PCDATA)>
<!ELEMENT labels (label+)>
<!ELEMENT label (#PCDATA)>
]>

The format is more or less self-explaining, all fields map to properties of a single download. Note that there is a limit of six labels that you can attach to a download, similar to what the regular file upload functionality allows.

One special element has been introduced and this is named replaces. If this optional element is given, InDefero looks for a file with that name in the project and acts in one of the following two ways:

• If the new file's name is distinct from the file's name that is given in replaces, then the replaced file is marked as deprecated with the Other:Deprecated label (or any other label that is configured as the very last label in the download project configuration).
• If the new file's name is equal to the file's name that is given in replaces, then the replaced file is deleted before the new file is created. This happens because each file name has to be unique per project and a deprecated and a new file with the same name cannot coexist in InDefero. Note that while the filename-based URI of the download keeps intact, the download counter will be reset by this procedure.

If no existing file is found for the replaces tag, then this is completely ignored.

Final notes

Any file in the archive that is not enlisted in the manifest is ignored during the upload process, so ensure that your manifest.xml contains all the file names (case sensitive) you want to be processed.