All About Catalogue IDs
Anatomy of a Catalogue ID
Using Catalogue IDs in Plug-in
Bundles
Using Catalogue IDs in a Catalogue
Tweaking IDs by Hand
If you want your plug-in to appear in the catalogue, you will need to know about catalogue IDs. Every plug-in bundle that is listed in a catalogue needs to have its own ID. Strange Eons uses this ID to tell two things about the bundle: what plug-in it contains, and which version of that plug-in.
The ID has to appear in two places: in the root file (eons-plugin) in the plug-in bundle, and in the catalogue listing. When you open the catalogue, the IDs in all of the bundles that you have installed are compared to the IDs listed in the catalogue. When two catalogue IDs refer to the same plug-in but one in the catalogue file has a newer version code, Strange Eons knows that the plug-in has been updated.
A catalogue ID has consists of three parts. The first is an outer wrapper that helps SE determine that a block of text contains an ID. It consists of the text CATALOGUEID and a matched pair of braces. (The US spelling CATALOGID is also accepted.) Inside the braces are two strings of letters and numbers separated by a colon. The first string identifies the particular plug-in bundle. It consists of a UUID (Universally Unique Identifier). This is a number that is generated in such a way that the probability of two UUIDs ever being the same is very, very, very low. The second string encodes a time and date, in UTC time, measured with millisecond precision.
Here is what one looks like (the colon divides the UUID from the date):
CATALOGUEID{0ecbf2f7-d140-43d4-965b-38ec4228e91f:2010-0-25-1-16-26-595}
| |:| |
| UUID Part | | Date Part |
Catalogue IDs are set in one of two ways. When you first create a new plug-in, you should generate a new ID for it. The ID should be placed in a comment line in the plug-in's root file. It usually appears in the first line, but this is not required. Second, when you want to publish a new version of the plug-in, you need to update just the date part of the ID without changing the UUID part. This is called touching the ID.
There are tools available in the project system that make this easier. The root file editor (double click the eon-plugin file) can generate and touch IDs with the click of a button, creating (or changing) the comment line in the script automatically:
If needed, you can also generate an ID from the command line. From the same directory as the Strange Eons JAR file, run:
java -cp strange-eons.jar ca.cgjennings.apps.arkham.plugins.catalog.CatalogID
This tool accepts the following command line options:
CatalogID [--d] [--xfile] [--tfile] [n...] [existing ID]
--d to generate just the date part of an ID (manually update an existing ID)
--xfile will extract and print the ID from plug-in bundle 'file'
--tfile will generate or touch the ID in plug-in bundle 'file'
a series of one or more integers will generate a group of that many IDs
using an existing ID will touch the ID (make the date current)
Another way to create and edit IDs is with the Catalogue Tools plug-in.
On the catalogue listing side of the equation, each catalogue listing must include an ID for the bundle it represents. This is done by adding an id = CATALOGUEID{...} entry to the listing. When a new version of the plug-in is published, the ID in the listing must be updated with the new date from the ID of the updated bundle.
If you use the Catalogue Tools plug-in to help manage your catalogue listings, then you don't need to copy ID information manually. You simply copy the plug-in bundles (new or updated) into a catalogue task folder, and use the Update command on the task. The plug-in will scan your catalogue folder and create entries for newly added bundles (adding an ID to the bundle if needed), update the date part of the the IDs for existing bundles, and update the size and MD5 fields of the listing to match the bundle.
The UUID part of a catalogue ID must never be edited by hand. There are certain checks that are performed on IDs to ensure that they are valid, and editing it by hand could cause it to be rejected. More importantly, though, generating your own ID defeats the entire purpose of using a UUID because there is no longer a strong probability that two IDs are unique.
The date part of an ID can be updated manually. It consists of the following digit parts, separated by hyphens: the year, the month (0=January), the day within the month, the hour since midnight (0-23), the minute within the hour (0-59), the second within the minute (0-59), and the millisecond within the second (0-999).
Strange Eons does not rely on dates being accurate. It uses them only to establish a total ordering over plug-in versions: it only needs to know what order the the plug-ins are published in, not whether they were really published 1 ms apart. However, if you edit a date by hand it is good practice to match it at least to the correct day, as that much is presented to the user as the publication date.