Module: reverse-map-query

System-internal reverse maps are used to search backwards (upwards) in the ONE object tree. It is easy to follow the links in objects to find a leaf node, but to go the other way and find which higher level objects link to a (given) lower-level one is made possible by these maps. Each time a ONE object is written that links to another object the reverse map belonging to the linked (targeted) object is updated.

There is a reverse map

1. for each unversioned object, or for each ID object of a versioned object, and
2. for each type of object that links to the object.

The second point leads to having a variable number of reverse maps for each object, it is an optimization that assumes that there may be quite a lot of entries and that the most common use case probably is to look for links to a given object only from a certain type of object, so that having to sift through all links from all types of objects each time is unnecessary effort.

For example, if we have an app that stores the contents of a user's IMAP folder in ONE we may have ONE objects for Email and Mailbox. It is easy to find which Emails are in any given Mailbox object because the Email objects are directly linked from there. However, when given an Email object, to find out which Mailbox objects link to it - after all, any email is found in several IMAP mailboxes - we need to consult the reverse map for the given Email object which contains the map of Mailbox objects linking to it. It was updated each time a(ny) Mailbox object was written that contained a link to this Email object. There will be other reverse map files for other types of objects linking to the Email object.

Map name pattern:

${id-hash}.${type}

The "H" (for "Hash") indicates that this is a map for an unversioned (single) object, the "I" (for "ID hash") shows it is for a versioned object (with many objects).

We could of course find out if a given hash is the hash of a concrete object (unversioned) or of an ID-object (versioned object), but this requires additional effort (both I/O and CPU). By having this one letter as part of the name, and at a fixed position, we can use that information much more easily if we need it.

Similar for the type string at the end of the filename. We could read the hash we found in the map and find the type, but this comes at a cost. By having it in the name we can select the appropriate reverse map using this simple naming pattern without any effort.

Format:

targetObjHash,referencingObjIdHash,referencingObjHash
targetObjHash,referencingObjIdHash,referencingObjHash
targetObjHash,referencingObjIdHash,referencingObjHash
...