Implementation of Stamping

This page is way out of date... Stamping now uses annotations.

Under the hood, when you change an Item's Kind you change its Python class and also its set of persistent attributes.

We refer to a bag of attributes as a "Mixin Kind". There are three Mixin Kinds currently supported: TaskMixin, MailMessageMixin, and CalendarEventMixin. A ContentItem without any of these three Mixin Kinds is a simple Note. Each Kind of ContentItem is built using Note and its Mixin, so a Task is built from a Note plus a TaskMixin. The various combinations of Mixins are also defined, so there exists a MailedTask Kind, a MailedEvent Kind, etc.

Because we have duplicate attributes in the form of the various "important" attributes listed above, we need to be careful how we combine the different Mixins. The Task-ness of an Item is supposed to take priority over the Event-ness of an item, so we should show the "dueDate" of a Task instead of the "startTime" of an Event in the "date" column of an EventTask. If we ignore the priority and just stamp Mixins, we'll find that stamping Task and then Event isn't the same as stamping Event and then Task. In one case the "date" for Event will win, in the other the "date" for Task will win. So I implemented a priority scheme. There are three different ways of implementing this that I considered:

1. Define a set of rules, either in code or XML that defines what happens when you stamp MixinA onto KindK.
2. Build a set of Kinds that define the ordering desired, and then search for a Kind match when stamping.
3. Associate a priority with each Mixin Kind, and when stamping place the Mixins in priority order.

I decided to implement scheme #2, since it gives us good control over the structure of our Kinds, and good diagnostic information. Under scheme #3 multi-Mixin Kinds are built on the fly instead of being hand built and don't have an easy to read name for the Kind. This is probably appropriate for stamping beyond the Items provided Out Of the Box, so we may implement this later. In 0.4 I have implemented a stamping system that uses scheme #2, but falls back onto simple on-the-fly Mixing of Kinds when an appropriate target Kind for the stamping can't be found in the set of predefined Kinds.

Stamping is complicated by a concept that I'm calling "Kind Synergy". Simply stated, sometimes the presence of multiple kinds takes on additional meaning, and so an extra bag of attributes is needed. We have this situation when we combine Task and CalendarEvent. The scheme I implemented under #2 (above) allows for some flexability when searching for a target Kind, in that it will accept one "extra" bag of attributes in the match. This requires that all of the synergy attributes be packaged up in one single Mixin Kind expressed as a superkind in the combined Item's Kind.

There are several ways that one could implement the Kind-matching scheme outlined in #2. I chose an implementation that uses the "superkind signature" of the kinds being stamped. This implementation works, but has some drawbacks. Basically, the way it works, it takes the current item's Kind and breaks it up into the set of fundimental superkinds that it is built from. The superkinds are considered the superkind signature, and need to be unique. When stamping it adds (or removes) the mixin kind being stamped to the superkind signature of the Item to get the superkind signature for the stamping result Kind. Then all known Kinds are considered to see if they match this target signature. If just one Kind is found that matches the signature then it is used. If no exact matches are found, and exactly one kind is found that has one additional superKind in the signature during addative stamping then it's considered a "Kind Synergy" situation and will be used. Similarly if one fewer superkind is found during unstamping then "Kind Synergy" is presumed and the Kind is used. Otherwise the search fails, and regular on-the-fly mixinKind conversion will be used, and a warning will be issued to the log file.

This Kind-Searching is fairly complicated and confusing, and it's unclear wheather we need this level of complexity. Here's the list of advantages and disadvantages as I currently see it with this implementation:

• + Handles the "kind synergy" issue. It's unclear how strong of a requirement this is - maybe we can make the other attributes optional attributes on Task
• + Handles the "kind ordering" issue. The ordering in which we mixin kinds is only important when conflicts occur. Right now, this happens only with the redirected attributes "who", "about", "date" etc. We could probably add a simple priority scheme to control the ordering.
• + Provides user-readable Kinds for stamped items. This is a bonus for debugging, but it's unclear if we'll really need it longer term. Will we continue to show the Kind name in the Detail View? Will a webDAV exported Item need a user-readable Kind?
• + It's somewhat flexible and extensible to third party stamping schemes.
• - The implementation is complicated, and requires predefinition of Kinds (implicit in the schema) which must have unique "superKind signatures" (see above) though you can build them any way you like.
• - The implementation is slow because it searches all Content Items in the repository for a match
• - Bad parcels can disrupt stamping by defining Kinds that have the same "superkind signature" as the an existing kind, like Note. See the section on Trouble Shooting below.

Trouble Shooting

---

Morgen discovered that creating a new Kind of Content Item in the natural way caused stamping to fail. A warning was issued to the log saying "Couldn't find suitable candidates for stamping...", and giving details about the Content Items that were ambiguous. We should be able to fix this problem for the next release. In the meantime Morgen refactored his schema using the mixin model to separate his attributes into a Mixin Kind, which fixed the problem. This refactoring also allows him to stamp other content items with his Kind.

Future Directions

It's likely that we'll simplify the stamping scheme to just use a simple priority ordering, as outlined in option #3 above, for the next release. We're not really using all the features of the current system, so if we decide they are not needed the code can be simplified and made more robust by removing the implementation of the super-kind signature matching.

-- DonnDenman - 20 Oct 2004