Akonadi
Table of Contents
- Akonadi Objects
- Collection retrieval and manipulation
- PIM item retrieval and manipulation
- Low-level access to the Akonadi server
- Change notifications (Monitor)
- PIM item serializer
- Agents and Resources
- Integration in your Application
- Jobs and Monitors
- Tricky details
- Resources
- Serializers
- Implementation details
Akonadi client libraries consist of three libraries that provide tools to access the Akonadi PIM data server: AkonadiCore, AkonadiWidgets and AkonadiAgentBase. All processes accessing Akonadi, including those which communicate with a remote server agents, are considered clients.
Akonadi Objects
Akonadi works on two basic object types: collections and items.
Collections are comparable to folders in a file system and are represented by the class Akonadi::Collection. Every collection has an associated cache policy represented by the class Akonadi::CachePolicy which defines what part of its content is cached for how long. All available ways to work with collections are listed in the "[Collections](#collections)" section.
Akonadi items are comparable to files in a file system and are represented by the class Akonadi::Item. Each item represents a single PIM object such as a mail or a contact. The actual object it represents is its so-called payload. All available ways to work with items are listed in the "[Items](#items)" section.
Both items and collections are identified by a persistent unique identifier. Also, they can contain arbitrary attributes (derived from Akonadi::Attribute) to attach general or application specific meta data to them.
Collection retrieval and manipulation
A collection is represented by the Akonadi::Collection class.
Classes to retrieve information about collections:
Classes to manipulate collections:
- Akonadi::CollectionCreateJob
- Akonadi::CollectionCopyJob
- Akonadi::CollectionModifyJob
- Akonadi::CollectionDeleteJob
There is also Akonadi::CollectionModel, which is a self-updating model class which can be used in combination with Akonadi::CollectionView. Akonadi::CollectionFilterProxyModel can be used to limit a displayed collection tree to collections supporting a certain type of PIM items. Akonadi::CollectionPropertiesDialog provides an extensible properties dialog for collections. Often needed QAction for collection operations are provided by Akonadi::StandardActionManager.
PIM item retrieval and manipulation
PIM items are represented by classes derived from Akonadi::Item. Items can be retrieved using Akonadi::ItemFetchJob.
The following classes are provided to manipulate PIM items:
Akonadi::ItemModel provides a self-updating model class which can be used to display the content of a collection. Akonadi::ItemView is the base class for a corresponding view. Often needed QAction for item operations are provided by Akonadi::StandardActionManager.
Low-level access to the Akonadi server
Accessing the Akonadi server is done using job classes derived from Akonadi::Job. The communication channel with the server is provided by Akonadi::Session.
To use server-side transactions, the following jobs are provided:
There also is Akonadi::TransactionSequence which can be used to automatically group a set of jobs into a single transaction.
Change notifications (Monitor)
The Akonadi::Monitor class allows you to monitor specific resources, collections and PIM items for changes. Akonadi::ChangeRecorder augments this by providing a way to record and replay change notifications.
PIM item serializer
The class Akonadi::ItemSerializer is responsible for converting between the stored (binary) representation of a PIM item and the objects used to handle these items provided by the corresponding libraries (kabc, kcal, etc.).
Serializer plugins allow you to add support for new kinds of PIM items to Akonadi. Akonadi::ItemSerializerPlugin can be used as a base class for such a plugin.
Agents and Resources
Agents are independent processes that watch the Akonadi store for changes and react to them if necessary. Example: The Akonadi Indexing Agent is an agent that watches Akonadi for new emails, calendar events, etc., retrieves the new items and indexes them into a special database.
The class Akonadi::AgentBase is the common base class for all agents. It provides commonly needed functionality such as change monitoring and recording.
Resources are a special kind of agents. They are used as the actual backend for whatever data the resource represents. In this situation the akonadi server acts more like a proxy service. It caches data on behalf of its clients (client here being the Resource), not permanently storing it. The Akonadi server forwards item retrieval requests to the corresponding resource, if the item is not in the cache. Example: The imap resource is responsible for storing and fetching emails from an imap server.
Akonadi::ResourceBase is the base class for them. It provides the necessary interfaces to the server as well as many convenience functions to make implementing a new resource as easy as possible. Note that a collection contains items belonging to a single resource, although there are plans in the future for 'virtual' collections which will contain the results of a search query spanning multiple resources.
A resource can support multiple mimetypes. There are two places where a resource can specify mimetypes: in its desktop files, and in the content mimetypes field of collections created by it. The ones in the desktop file are used for filtering agent types, e.g. in the resource creation dialogs. The collection content mimetypes specify what you can actually put into a collection, which is not necessarily the same (e.g. the Kolab resource supports contacts and events, but not in the same folder).
Integration in your Application
Akonadi::Control provides ways to ensure that the Akonadi server is running, to monitor its availability and provide help on server-side errors. A more low-level interface to the Akonadi server is provided by Akonadi::ServerManager.
A set of standard actions is provided by Akonadi::StandardActionManager. These provide consistent look and feel across applications.
This library provides classes for KDE applications to communicate with the Akonadi server. The most high-level interface to Akonadi is the Models and Views provided in this library. Ready to use models are provided for use with views to interact with a tree of collections, a list of items in a collection, or a combined tree of Collections and items.
Collections and Items
In the Akonadi concept, Items are individual objects of PIM data, e.g. emails, contacts, events, notes etc. The data in an item is stored in a typed payload. For example, if an Akonadi Item holds a contact, the contact is available as a KABC::Addressee:
Additionally, an Item must have a mimetype which corresponds to the type of payload it holds.
Collections are simply containers of Items. A Collection has a name and a list of mimetypes that it may contain. A collection may for example contain events if it can contain the mimetype 'text/calendar'. A Collection itself (as opposed to its contents) has a mimetype, which is the same for all Collections. A Collection which can itself contain Collections must be able to contain the Collection mimetype.
This system makes it simple to create PIM applications. For example, to create an application for viewing and editing events, you simply need to tell Akonadi to retrieve all items matching the mimetype 'text/calendar'.
Convenience Mimetype Accessors
In order to avoid typos, improve readability, and to encapsulate the correct mimetypes for particular pim items, many of the standard classes have an accessor for the kind of mimetype the can handle. For example, you can use KMime::Message::mimeType() for emails, KABC::Addressee::mimeType() for contacts etc. It makes sense to define a similar static function in your own types.
Models and Views
Akonadi models and views are a high level way to interact with the Akonadi server. Most applications will use these classes. See the EntityTreeModel documentation for more information.
Models provide an interface for viewing, deleting and moving Items and Collections. New Items can also be created by dropping data of the appropriate type on a model. Additionally, the models are updated automatically if another application changes the data or inserts or deletes items etc.
Akonadi provides several models for particular uses, e.g. the MailModel is used for emails and the ContactsModel is used for showing contacts. Additional specific models can be implemented using EntityTreeModel as a base class.
A typical use of these would be to create a model and use proxy models to make the view show different parts of the model. For example, show a collection tree in on one side and show items in a selected collection in another view.
The content of the model is determined by the configuration of the Monitor passed into it. The examples below show a use of the EntityTreeModel and some proxy models for a simple hierarchical note collection. As the model is generic, the configuration and proxy models will also work with any other mimetype.
The EntityTreeModel can be further configured for certain behaviours such as fetching of collections and items.
To create a model of only a collection tree and no items, set that in the model. This is just like CollectionModel:
Or, create a model of only items and not child collections. This is just like ItemModel:
Or, to create a model which includes items and first level collections:
The items in the model can also be inserted lazily for performance reasons. The Collection tree is always built immediately.
Additionally, a KDescendantsProxyModel may be used to alter how the items in the tree are presented.
KDescendantsProxyModel can also display ancestors of each Entity in the list.
This proxy can be combined with a filter to for example remove collections.
It is also possible to show the root item as part of the selectable model:
By default the displayed name of the root collection is '[*]', because it doesn't require i18n, and is generic. It can be changed too.
These can of course be combined to create an application which uses one EntityTreeModel along with several proxies and views.
Or to also show items of child collections in the list:
Note that it is important in this case to use the DescendantEntitesProxyModel before the EntityMimeTypeFilterModel. Otherwise, by filtering out the collections first, you would also be filtering out their child items.
A SelectionProxyModel can be used to simplify managing selection in one view through multiple proxy models to a representation in another view. The selectionModel of the initial view is used to create a proxied model which includes only the selected indexes and their children.
The SelectionProxyModel can handle complex selections.
If an index and one or more of its descendants are selected, only the top-most selected index (including all of its descendants) are included in the proxy model. (Though this is configurable. See below)
SelectionProxyModel allows configuration using the methods setStartWithChildTrees, setOmitDescendants, setIncludeAllSelected. See testapp/proxymodeltestapp to try out the 5 valid configurations.
Obviously, the SelectionProxyModel may be used in a view, or further processed with other proxy models. See the example_contacts application for example which uses a further KDescendantsProxyModel and EntityMimeTypeFilterModel on top of a SelectionProxyModel.
The SelectionProxyModel orders its items in the same top-to-bottom order as they appear in the source model. Note that this order may be different to the order in the selection model if there is a QSortFilterProxyModel between the selection and the source model.
Details on the actual implementation of lazy population are described on this page.
Jobs and Monitors
The lower level way to interact with Akonadi is to use Jobs and Monitors (This is what models use internally). Jobs are used to make changes to akonadi, and in some cases (e.g., a fetch job) emit a signal with data resulting from the job. A Monitor reports changes made to the data stored in Akonadi (e.g., creating, updating, deleting or moving an item or collection ) via signals.
Typically, an application will configure a monitor to report changes to a particular Collection, mimetype or resource, and then connect to the signals it emits.
Most applications will use some of the low level api for actions unrelated to a model-tree view, such as creating new items and collections.
Tricky details
Change Conflicts
It is possible that while an application is editing an item, that item gets updated in akonadi. Akonadi will notify the application that that item has changed via a Monitor signal. It is the responsibility of the application to handle the conflict by for example offering the user a dialog to resolve it. Alternatively, the application could ignore the dataChanged signal for that item, and will get another chance to resolve the conflict when trying to save the result back to akonadi. In that case, the ItemModifyJob will fail and report that the revision number of the item on the server differs from its revision number as reported by the job. Again, it is up to the application to handle this case.
This is something that every application using akonadi will have to handle.
Using Item::Id or Collection::Id as an identifier
Items and Collections have a id() member which is a unique identifier used by akonadi. It can be useful to use the id() as an identifier when storing Collections or Items.
However, as an item and a collection can have the same id(), if you need to store both Collections and Items together by a simple identifier, conflicts can occur.
In this case, it makes more sense to use a normal qint64 as the internal identifier, and use the sign bit to determine if the identifier refers to a Collection or an Item. This is done in the implementation of EntityTreeModel to tell Collections and Items apart.
Unordered Lists
Collection and Item both provide a ::List to represent groups of objects. However the objects in the list are usually not ordered in any particular way, even though the API provides methods to work with an ordered list. It makes more sense to think of it as a Set instead of a list in most cases.
For example, when using an ItemFetchJob to fetch the items in a collection, the items could be in any order when returned from the job. The order that a Monitor emits notices of changes is also indeterminate. By using a Transaction however, it is sometimes possible to retrieve objects in order. Additionally, using s constructor overload in the CollectionFetchJob it is possible to retrieve collections in a particular order.
Resources
The KDEPIM module includes resources for handling many types of PIM data, such as imap email, vcard files and vcard directories, ical event files etc. These cover many of the sources for your PIM data, but in the case that you need to use data from another source (for example a website providing a contacts storage service and an api), you simply have to write a new resource.
https://techbase.kde.org/Development/Tutorials/Akonadi/Resources
Serializers
Serializers provide the functionality of converting raw data, for example from a file, to a strongly typed object of PIM data. For example, the addressee serializer reads data from a file and creates a KABC::Addressee object.
New serializers can also easily be written if the data you are dealing with is not one of the standard PIM data types.
Implementation details
Updating Akonadi Models
NOTE: The details here are only relevant if you are writing a new view using EntityTreeModel, or writing a new model.
Because communication with Akonadi happens asynchronously, and the models only hold a cached copy of the data on the akonadi server, some typical behaviours of models are not followed by Akonadi models.
For example, when setting data on a model via a view, most models synchronously update their internal store and notify akonadi to update its view of the data by returning true.
Akonadi models only cache data from the Akonadi server. To update data on an Akonadi::Entity stored in a model, the model makes a request to the Akonadi server to update the model data. At that point the data cached internally in the model is not updated, so false is always returned from setData. If the request to update data on the Akonadi server is successful, an Akonadi::Monitor notifies the model that the data on that item has changed. The model then updates its internal data store and notifies the view that the data has changed. The details of how the Monitor communicates with akonadi are omitted for clarity.
Similarly, in drag and drop operations, most models would update an internal data store and return true from dropMimeData if the drop is successful.
Documentation copyright © 1996-2024 The KDE developers.
Generated on Tue Mar 26 2024 11:13:38 by doxygen 1.10.0 written by Dimitri van Heesch, © 1997-2006
KDE's Doxygen guidelines are available online.