- The "Problem"
The problem is that different systems have different levels of support for the concept, or have different semantics for the concept. Most of these differences can be abstracted away, however there are costs associated with such abstractions. Even worse, sometimes the way in which they support the concept, can have a radical impact on other areas of the API. In particular, one area of major difference between different solutions is how individual items are given an id. Some have calendar-unique ids, while others have datastore-unique ids.
Currently, in the repository, our API assumes that a QOrganizerItem is identified by a QOrganizerItemId (which consists of a URI which identifies a QOrganizerItemManager, and a QOrganizerItemLocalId which is a manager-unique id for that item). That is, we currently assume datastore-unique ids. This means that to fetch an item, you only need to know its QOrganizerItemLocalId, since it uniquely identifies an item in a manager, regardless of which collection it is saved in. Similarly, to remove an item you need only specify its local id.
On platforms where item ids are only calendar-unique, however, the QOrganizerItemManagerEngine plugin would have to store some extra data in order to support the current model: it would have to create a map from QOrganizerItemLocalId to QPair<QOrganizerCollectionId, calendar_unique_id> -- which is prone to problems (performance, memory overhead, persistence of collection ids, and has a higher maintenance burden).
If we changed our API's semantics so that the QOrganizerItemLocalId is per-collection (that is, calendar-unique rather than manager-unique), we'd have to change the semantics of the fetch and remove functions (since a QOrganizerItemLocalId no longer uniquely identifies an item in a manager; but rather it only uniquely identifies an item in a collection in a manager which may have multiple collections). This in turn would be less consistent with other APIs in mobility (such as the Contacts API, the Landmarks API, and so on).
So, that's the "problem".
- Proposed Solutions
a) Current solution: QOrganizerItemLocalId uniquely identifies an item in a manager.
(plus) consistent with Contacts API
(plus) simple semantics for developers
(plus) QOrganizerItemLocalId is very light-weight (just an int)
(minus) greatly increased maintenance burden on backend developers
(minus) reduced performance (speed and memory) of applications using most common backends
b) Modified current solution: QOrganizerItemLocalId becomes a compound type which consists of both the CollectionId and a CollectionLocalId. Thus, a QOrganizerItemLocalId still uniquely identifies an item in a manager.
(plus) similar semantics to Contacts API
(plus) simple semantics for developers, with some caveats
(minus) QOrganizerItemLocalId is not light weight (class with setters/accessors, compound type)
(minus) slightly increased maintenance burden on backend developers (persistence of collectionIds, etc)
(minus) reduced performance (speed and memory) of some operations due to the heavier nature of the local id
c) Alternative solution: change the semantic of QOrganizerItemLocalId so that it is Collection-unique rather than manager-unique
(plus) reduced maintenance burden on backend developers
(plus) performance will not be negatively impacted
(plus) QOrganizerItemLocalId remains light-weight, but in order for this positive to be realised, the API will have to be changed so that all operations take a single collectionId along with a list of collection-local QOrganizerItemLocalIds.
(minus) Not consistent with Contacts API
(minus) May be slightly confusing semantics for developers if they're used to Contacts/Landmarks
Obviously, we want clients to be able to persistently store an id (or a <collectionid, itemid> pair) which uniquely identifies an item in a manager, and have that id be valid after a reboot. We also want the best performance and lowest maintenance burden possible. And of course, we want the APIs to be as consistent and intuitive as possible.
In this particular case, these goals are in conflict, so we thought we'd open it up to the community for discussion and feedback, before making a decision (which, by necessity, must be made shortly - so don't delay).