akonadi

Concepts

This page describes the basic concepts of Akonadi.

Todo:: complete this page: eg. cache policies/management, search

Collections are sets of PIM items. Every PIM item is stored in exactly one collection (the server calls these "Locations" internally). An item might also be visible in several other collections - so called "virtual collections" - which are defined as the result set of a query.

Collections are organized hierarchically, i.e. every collection can have child collections, thus defining a collection tree.

The concept is comparable to KMail's (search-)folders or to some extent (sub-)resources.

Akonadi Collections

In Akonadi, collections are uniquely identified by their identifier in contrast to their path, which is more robust wrt. to renaming.

Collections can contain an arbitrary set of attributes (inherited from the CollectionAttribute class) to represent various collection properties such as ACLs, quotas or backend-specific data used for incremental synchronization.

Every collection has a set of supported content types. These are the mimetypes of items the collection can contain. Example: A collection of a folder-less iCal file resource would only support "text/calendar" items, a folder on an IMAP server "message/rfc822" but also "inode/directory" if it can contain sub-folders.

There is a cache policy associated with every collection which defines how much of its content should be kept in the local cache and for how long.

Akonadi Collection Tree

There is a single collection tree in Akonadi, consisting of several parts:

A root node, id 0
A top-level collection for every resource. Think of these as mount-points for the resource. They are automatically created and removed by the storage server whenever a resource is created or removed. The resources must put their items and sub-collections into their corresponding top-level collection.
Resource-dependent sub-collections below the resource top-level collections. If the resource represents data that is organized in folders (e.g. an IMAP resource), it can create additional collections below its top-level collection. These have to be synched with the corresponding backend by the resource. Resources which represent folder-less data (e.g. an iCal file) don't need any sub-collections and put their items directly into the top-level collection.
A top-level collection containing virtual collections.

Example:

+-+ resource-folder1
| +- sub-folder1
| +- sub-folder2
|  ...
+-+ resource-folder2
| ...
|
+-+ Searches
  +- search-folder1
  +- search-folder2
  ...

PIM Items

A PIM item is a generic container for whatever you want to store in Akonadi (eg. mails, events, contacts, etc.). A PIM item consists of some generic information (such as identifier, mimetype, change date, flags, etc.) and a set of data fields, the item parts. PIM items are independent of the type of stored data, the semantics of the actual content is only known on the client side.

Item Parts

PIM items can have one or more parts, e.g. an email message consists of the envelope, the body and possible one or more attachments. Item parts are identified by an identifier string. There are a few special pre-defined part identifiers (ALL, ENVELOPE, etc.), but in general the part identifiers are definied by the type specific extensions (ie. resource, serializer plugin, type specific client library).

Serializer Plugins

Serializer plugins are used by libakonadi to convert between the binary representation stored in the server and type-specific objects used by client applications (eg. iCal and KCal::Event).

Object Identification

Unique Identifier

Every object stored in Akonadi (collections and PIM items) has a unique identifier in the form of an integer value. This identifier cannot be changed in any way and will stay the same, regardless of any modifications to the referred object. A unique identifier will never be used twice and is globally unique, therefore it is possible to retrieve an item without knowing the folder it belongs to.

Remote Identifier

Every object can also have an optional so-called remote identifier. This is an identifier used by the corresponding resource to identify the object on its backend (e.g., a groupware server).

The remote identifier can be changed arbitrarily, but should only be changed by the corresponding resource.

akonadi

akonadi

kdepim