KDE PIM/Akonadi/Architecture

Here's a high level overview of the most important classes:

For akonadi to do something useful you typically have at least three processes (if we ignore akonadictl) involved;

• The client process (you application)
• The akonadiserver process (the database)
• The resource process (the backend that i.e. talks to your IMAP server)

Of course a typical session consists of many client processes and many resource processes.

The individual processes communicate using the following protocols with the server:

• dbus for notifications and function calls
• the IMAP like ASAP protocol via a local socket for the bulk data transfer

Client Libraries

The client libraries provide helper classes that implement the DBUS/ASAP communication. Note that the client and the resource implementation share a lot of common code.

Akonadi::Job

A job represents a single action that is executed by the client/resource and implements the required commands to execute the task. A typical example is the ItemFetchJob, that retrieves an Item from the Server.

Akonadi::Session

The session represents the connection (socket) to the akonadi server. All ASAP communication goes through the session. The session is responsible for scheduling the queued Job objects that need to be executed.

Akonadi::Monitor

The monitor can be used to listen for changes. The server emits change notifications over DBUS. The monitor listens to these change notifications and automatically retrieves the new/changed items via it's session. A client/resource can use the monitor to be notified over all changes happening in the akonadi store.

Akonadi::ChangeRecorder

The change recorder is a monitor, that additionally records changes to a file and allows the client to replay them. This can be used to ensure that a client doesn't loose any notifications even if it is not able to process all notifications immediately.

Akonadi::EntityTreeModel

The EntityTreeModel (ETM) provides a QAbstractItemModel (tree model) exposing the Collection/Item tree. It does all the caching and on-demand information retrieval. It is therefore the preferred access mechanism whenever a list/tree view needs to be displayed.

Resource Libraries

Resources use the same client libraries, but have a couple of additional helper classes.

Akoandi::AgentBase

The base class for every agent/resource. The AgentBase provides the interface for all agents/resources. It is responsible for receiving change notifications via Akonadi::ChangeRecorder. The change notifications are delivered via the Akonadi::Observer interface.

Akonadi::Observer

The interface for agents/resources that require change notifications. AgentBase delivers notifications through functions like itemAdded/itemChanged that can be implemented by the resource.

Akonadi::Resource

The interface for all resources that are responsible for synchronizing a portion of the data to a backend. This class implements the interface that is called by the server to schedule the synchronization to the backend. E.g. the retrieveItems(Akonadi::Collection) call, tells the resource that it should now fetch all items from that collection.