1# Akonadi Server # {#server} 2 3[TOC] 4 5This is the API documentation for the Akonadi server. If you are using Akonadi 6from within KDE, you almost certainly want the [client library documentation][client_libs_documentation]. 7This API reference is more useful to people implementing client libraries or 8working on the Akonadi server itself. 9 10For additional information, see the <a href="https://community.kde.org/KDE_PIM/Akonadi">Akonadi website</a>. 11 12## Architecture ## 13 14<img src="https://community.kde.org/images.community/8/8e/Akonadi_Architecture.png"/> 15 16The Akonadi framework uses a client/server architecture. The Akonadi server has the following primary tasks: 17* Abstract access to data from arbitrary sources, using toolkit-agnostic protocols and data formats 18* Provide a data cache shared among several clients 19* Provide change notifications and conflict detection 20* Support offline change recording and change replay for remote data 21 22## Design Principles ## 23 24The Akonadi architecture is based on the following four design principles: 25 26* _Functionality is spread over different processes._ 27 This separation has the big advantage that if one process crashes because of 28 a programming error it doesn't affect the other components. That results in 29 robustness of the whole system. A disadvantage might be that there is an additional 30 overhead due to inter-process communication. 31* _Communication protocol is split into data and control channel._ 32 When doing communication between processes you have to differentiate between the type of data 33 that is being transferred. For a large amount of data a high-performance 34 protocol should be used and for control data a low-latency protocol. 35 Matching both requirements in one protocol is mostly impossible and hard to 36 achieve with currently available software. 37* _Separate logic from storage._ 38 By separating the logic from the storage, the storage can be used to store data 39 of any type. In this case, the storage is a kind of service, which is available for 40 other components of the system. The logic is located in separated components and so 41 3rd-party developers can extend the system by providing their own components. 42* _Keep communication asynchronous._ 43 To allow a non-blocking GUI, all the communication with the back-end and within the 44 back-end itself must be asynchronous. You can easily provide a synchronous convenience 45 for the application developer; the back-end, however, must communicate asynchronously. 46 47## Components ## 48The Akonadi server itself consists of a number of components: 49* The Akonadi control process (`akonadi_control`). It is responsible for managing all other server components and Akonadi agents. 50* The Akonadi server process (`akonadiserver`). The actual data access and caching server. 51* The Akonadi agent server (`akonadi_agent_server`). Allows running of multiple Akonadi agents in one process. 52* The Akonadi agent launcher (`akonadi_agent_launcher`). A helper process for running Akonadi agents. 53* The Akonadi control tool (`akonadictl`). A tool to start/stop/restart the Akonadi server system and query its status. 54 This is the only program of these listed here you should ever run manually. 55* The Akonadi protocol library (`libakonadiprotocolinternals`), Contains protocol definitions and protocol parsing methods 56 useful for client implementations. 57 58### The Akonadi server process ### 59 60The Akonadi server process (`akonadiserver`) has the following tasks: 61* Provide a transaction-safe data store. 62* Provide operations to add/modify/delete items and collections in the local store, implementing the server side of the ASAP protocol. 63* Cache management of cached remote contents. 64* Manage virtual collections representing search results. 65* Provide change notifications for all known Akonadi objects over D-Bus. 66 67### The Akonadi server control process ### 68 69The Akondi control process (\c akonadi_control) has the following tasks: 70* Manage and monitor the other server processes. 71* Lifecycle management of agent instances using the various supported agent launch methods. 72* Monitor agent instances and provide crash recovery. 73* Provide D-Bus API to manage agents. 74* Provide change notifications on agent types and agent instances. 75 76## Objects and Data Types ## 77 78The Akonadi server operates on two basic object types, called items and collections. They are comparable to files and directories 79and are described in more detail in this section. 80 81## Akonadi Items ## 82 83An item is a generic container for whatever you want to store in Akonadi (eg. mails, 84events, contacts, etc.). An item consists of some generic information (such as identifier, 85mimetype, change date, flags, etc.) and a set of data fields, the item parts. Items 86are independent of the type of stored data, the semantics of the actual content is only 87known on the client side. 88 89## Items Parts ## 90 91Akonadi items can have one or more parts, e.g. an email message consists of the 92envelope, the body and possible one or more attachments. Item parts are identified 93by an identifier string. There are a few special pre-defined part identifiers (ALL, 94ENVELOPE, etc.), but in general the part identifiers are defined by the type specific 95extensions (ie. resource, serializer plugin, type specific client library). 96 97## Item Tags ## 98 99Tags are self-contained entities stored in separate database table. A tag is a 100relation between multiple items. Tags can have different types (PLAIN, ...) and applications 101can define their own type to describe application-specific relations. Tags can also have 102attributes to store additional metadata about the relation the tag describes. 103 104## Payload Data Serialization ## 105 106Item payload data is typically serialized in a standard format to ensure interoperability between different 107client library implementations. However, the %Akonadi server does not enforce any format, 108payload data is handled as an opaque binary blob. 109 110## Collections ## 111 112Collections are sets of items. Every item is stored in exactly one 113collection, this is sometimes also referred to as the "physical" storage location of the item. 114An item might also be visible in several other collections - so called "virtual collections" - 115which are defined as the result set of a search query. 116 117Collections are organized hierarchically, i.e. a collection can have child 118collections, thus defining a collection tree. 119 120Collections are uniquely identified by their identifier in 121contrast to their path, which is more robust with regard to renaming and moving. 122 123## Collection Properties ## 124 125Every collection has a set of supported content types. 126These are the mimetypes of items the collection can contain. 127Example: A collection of a folder-less iCal file resource would only support 128"text/calendar" items, a folder on an IMAP server "message/rfc822" but also 129"inode/directory" if it can contain sub-folders. 130 131There is a cache policy associated with every collection which defines how much 132of its content should be kept in the local cache and for how long. 133 134Additionally, collections can contain an arbitrary set of attributes to represent 135various other collection properties such as ACLs, quotas or backend-specific data 136used for incremental synchronization. Evaluation of such attributes is the responsibility 137of client implementations, the %Akonadi server does not interpret properties 138other than content types and cache policies. 139 140## Collection Tree ## 141 142There is a single collection tree in Akonadi, consisting of several parts: 143 144* A root node, id 0 145* One or more top-level collections for each resource. Think of these as mount-points 146 for the resource. The resources must put their items and sub-collections into their 147 corresponding top-level collection. 148* Resource-dependent sub-collections below the resource top-level collections. 149 If the resource represents data that is organized in folders (e.g. an IMAP 150 resource), it can create additional collections below its top-level 151 collection. These have to be synched with the corresponding backend by the 152 resource. 153 Resources which represent folder-less data (e.g. an iCal file) don't need 154 any sub-collections and put their items directly into the top-level collection. 155* A top-level collection containing virtual collections. 156 157Example: 158 159 +-+ resource-folder1 160 | +- sub-folder1 161 | +- sub-folder2 162 | ... 163 +-+ resource-folder2 164 | ... 165 | 166 +-+ Searches 167 +- search-folder1 168 +- search-folder2 169 ... 170 171 172## Object Identification ## 173 174### Unique Identifier ### 175 176Every object stored in %Akonadi (collections and items) has a unique 177identifier in the form of an integer value. This identifier cannot be changed in 178any way and will stay the same, regardless of any modifications to the referred 179object. A unique identifier will never be used twice and is globally unique, 180therefore it is possible to retrieve an item without knowing the collection it belongs to. 181 182### Remote Identifier ### 183 184Every object can also have an optional so-called remote identifier. This is an 185identifier used by the corresponding resource to identify the object on its 186backend (e.g., a groupware server). 187 188The remote identifier can be changed by the owning resource agent only. 189 190Special case applies for Tags, where each tag can have multiple remote IDs. This fact is 191however opaque to resources as each resource is shown only the remote ID that it had 192provided when inserting the tag into Akonadi. 193 194### Global Identifier ### 195 196Every item can has also so called GID, an identifier specific to the content (payload) 197of the item. The GID is extracted from the payload by client serializer when storing the 198item in Akonadi. For example, contacts have vCard "UID" field as their GID, emails can 199use value of "Message-Id" header. 200 201## Communication Protocols ### 202 203For communication within the Akonadi server infrastructure and for communication with Akonadi clients, two communication technologies are used: 204* D-Bus Used for management tasks and change notifications. 205* ASAP (Akonadi Server Access Protocol), used for high-throughput data transfer. ASAP is based on the well-known IMAP protocol (RFC 3501) which has been proven it's ability to handle large quantities of data in practice already. 206 207## Interacting with Akonadi ## 208 209There are various possibilities to interact with Akonadi. 210 211### Akonadi Client Libraries ### 212 213Accessing the Akonadi server using the ASAP and D-Bus interfaces directly is cumbersome. 214Therefore you'd usually use a client library implementing the low-level protocol handling 215and providing convenient high-level APIs for Akonadi operations. 216 217### Akonadi Agents ### 218 219Akonadi agents are processes which are controlled by the Akonadi server itself. Agents typically 220operate autonomously (ie. without much user interaction) on the objects handled by Akonadi, mostly 221by reacting to change notifications sent by the Akonadi server. 222 223Agents can implement specialized interfaces to provide additional functionality. 224The most important ones are the so-called resource agents. 225 226Resource agents are connectors that provide access to data from an external source, and replay local changes 227back to their corresponding backend. 228 229## Implementation Details ## 230 231### Data and Metadata Storage ### 232 233The Akonadi server uses two mechanisms for data storage: 234* A SQL databases for metadata and small payload data 235* Plain files for large payload data 236 237More details on the SQL database layout can be found here: \ref akonadi_server_database. 238 239The following SQL databases are supported by the Akonadi server: 240* MySQL using the default QtSQL driver shipped with Qt 241* Sqlite using the improved QtSQL driver shipped with the Akonadi server 242* PostgreSQL using the default QtSQL driver shipped with Qt 243 244For details on how to configure the various backends, see Akonadi::DataStore. 245
