Page MenuHomePhorge
Files F16569654

Mainpage.dox
No OneTemporary
Actions

Mainpage.dox
View Options

/**
\mainpage Akonadi, the KDE PIM storage framework
These pages are a combination of design and api documentation. If you are
looking for general information go to the Overview section.
For detailed information and/or api-dox on any of the packages go to the
package main page, either from the menu on the left or from the Building
blocks section below.
\section akonadi_overview Overview
- \ref akonadi_history
- Design and Concepts
- \ref akonadi_design_basic
- \ref akonadi_concepts
- \ref akonadi_design
- \ref akonadi_design_communication
- \ref akonadi_usage
- <a href="http://pim.kde.org/akonadi">Website</a>
- <a href="http://techbase.kde.org/index.php?title=Projects/PIM/Akonadi">Wiki</a>
- \ref akonadi_todos
\section akonadi_building_blocks Building Blocks
- Domain-specific libraries:
- <a href="../../kdepimlibs-apidocs/kabc/html/index.html">Contacts (KABC)</a>
- <a href="../../kdepimlibs-apidocs/kmime/html/index.html">MIME Messages (KMime)</a>
- <a href="../../kdepimlibs-apidocs/kcal/html/index.html">Events, todo items and journal entries (KCal)</a>
- <a href="../../kdepimlibs-apidocs/akonadi/html/index.html">Core library (libakonadi)</a>
\authors Tobias König <tokoe@kde.org>, Volker Krause <vkrause@kde.org>
\licenses \lgpl
*/
/**
\page akonadi_history Historical Background
\section akonadi_history_general General
During the last 5 years, after the release of KDE 3.0, the requirements of our users
have constantly increased. While it was sufficient that our PIM solution was able to handle 100 contacts,
300 events and maybe 1000 mails in 2001, nowadays users expect the software to be able to
handle a multiple of that. Over the years, the KDE PIM developers tried to catch up with the new
requirements; however, since KDE 3.x had to stay binary compatible, they were limited in their
efforts.
With the new major release KDE 4.0 it's possible to completely redesign the PIM libraries from
the ground up and use new concepts to face the requirements of 2006 and beyond.
After some discussion at the annual KDE PIM meeting in Osnabrück in January 2006, the PIM developers
came to the conclusion that a service is needed which acts as a local cache on the user's desktop
and provides search facilities. The name Akonadi comes from a divinity from Ghana and was chosen since
all other nice names were already used by other projects on the Internet ;)
\section akonadi_history_problems Problems with the implementation of KDE 3.x
Before digging into the internals of Akonadi, we want to take a look at the implementation of the
old KDE PIM libraries to understand the problems and conceptual shortcomings.
The main PIM libraries libkabc (contacts) and libkcal (events) where designed at a time when the
address book and calendar were files on the local file system, so there was no reason to think
about access time and mode. The libraries accessed the files synchronously and loaded all data of the
file into memory to be able to perform search queries on the data set. It worked well for local files,
but over time plug-ins for loading data from groupware servers were written, so the synchronous access blocked
applications which used libkabc/libkcal, and loading all 2000 contacts from a server is not only
time consuming but also needs a lot of memory to store them locally. The KDE PIM developers tried to
address the first issue by adding an asynchronous API, but it was not well implemented and was difficult to use.
In the end, the design decisions caused the following problems:
\li Bad Performance
\li High Memory Consumption
Another important but missing thing in the libraries was support for notifications and locking.
The former was partly implemented (at least reflected by the API) but only implemented in the local
file plug-in, so it was in practice unusable. The latter was also partly implemented but never really tested and
lead to deadlocks sometimes, so the following problems appeared as well:
\li Missing Notifications
\li Missing Locking
The main aim of Akonadi is to solve these issues and make use of the goodies which the new design brings.
*/
/**
\page akonadi_design_basic Basic Thoughts
To solve the \ref akonadi_history "problems of KDE 3" and make Akonadi ready for the requirements of the KDE 4 release
cycle, some considerations had been made which had a deep influence on the design:
\li <em>Functionality is spread over different processes.</em><br>
This separation has the big advantage that if one process crashes because of
a programming error it doesn't affect the other components. That results in
robustness of the whole system. A disadvantage might be that there is an additional
overhead due to inter-process communication.
\li <em>Communication protocol is split into data and control channel.</em><br>
When doing communication between processes you have to differentiate between the type of data
that is being transferred. For a large amount of data a high-performance
protocol should be used and for control data a low-latency protocol.
Matching both requirements in one protocol is mostly impossible and hard to
achieve with currently available software.
\li <em>Separate logic from storage.</em><br>
By separating the logic from the storage, the storage can be used to store data
of any type. In this case, the storage is a kind of service, which is available for
other components of the system. The logic is located in separated components and so
3rd-party developers can extend the system by providing their own components.
\li <em>Keep communication asynchronous.</em><br>
To allow a non-blocking GUI, all the communication with the back-end and within the
back-end itself must be asynchronous. You can easily provide a synchronous convenience
for the application developer; the back-end, however, must communicate asynchronously.
Keep these considerations in mind when you read \ref akonadi_design
*/
/**
\page akonadi_design Akonadi Design
The main components are:
- \ref akonadi_design_libakonadi (libakonadi)
- \ref akonadi_design_server
- \ref akonadi_design_control
- \ref akonadi_design_agents (resources)
- \ref akonadi_design_storage
In the diagram below you can see a rough schematic view of Akonadi:
\image latex concept.eps "Akonadi Components" height=5cm
\image html concept.png "Akonadi Components"
For a more technical view go to \ref akonadi_overview_uml
\section akonadi_design_libakonadi The Client Library
Every client application can access the Akonadi service directly via the D-Bus and an IMAP-alike
protocol; however, for easier implementation and a better abstraction the library libakonadi is
provided, which handles all the low level stuff and provides a Qt based API for all the
functionality Akonadi provides.
libakonadi works on all kinds of data and knows nothing about the type of the data.
For the type specific tasks libkabc and libkcal should be used, which are positioned above
libakonadi, and perform the conversion from the raw storage format to convenient Qt/KDE objects.
\section akonadi_design_server Server
The Server is a process which provides an API to store arbitrary data over
an IMAP interface into a relational database. The advantage of IMAP is the mature state of the protocol
and its capability to handle large quantities of data.
Whenever items are added to or removed from the Storage, the Server will
emit a signal over its D-Bus interface to inform other components.
Also, as defined in the IMAP standard, a simple type of search is supported,
so you can query for all items of a special mime type or for email-specific fields.
For more complex search queries, another component, the SearchProvider, is included.
\subsection akonadi_design_agents Agents
Agents are processes which are controlled by the Akonadi server itself and which
are able to work on the cache of the Storage. In the current design there are two
types of Agents:
\li Autonomous Agents
\li Resources
Autonomous Agents are processes which only work on the cache of the Storage
and the user will (probably) never see them at work.
Resources are processes which load data from an external data source, store them
in the cache of the Storage and keep track of changes on both sides to keep
the external data source and the cache synchronized.
Resources can be grouped into profiles, where one Resource can belong to different
profiles. Profiles are useful in use cases like this:
You have configured a local Resource and a groupware server Resource. You want both
to be shown in the address book application but for synchronization with your mobile
phone only the data from the local Resource is of interest. So the easy solution
is to create a profile 'view' which both the local Resource and the groupware server
Resource belong to, and a profile 'synchronize' to which only the local Resource is
assigned. Now you just have to tell the application which profile it should use to
access the data.
\subsection akonadi_design_control The Control
The Control process is the 'brain' of the system. It starts the Storage and Resource
processes and monitors them, so that if one of these processes crashes, it restarts them immediately.
Furthermore it provides a D-Bus API with the following functionality:
\li Managing Resources
\li Managing Profiles
\li Notifications when the state of Resources or Profiles have changed
The Control should be started in the startkde script and terminated at the end of the session.
\subsection akonadi_design_storage Storage
The Storage is part of the Akonadi Server and is responsible for managing the cache of \ref akonadi_concepts_items.
In other words, create the database schema and perform read/write operations on the database.
*/
/**
\page akonadi_design_communication Communication Schemas
\section akonadi_design_communication_search Search
The sequence diagrams below show how general communication is done:
<div id='akonadi_client_search_small.png' onClick="document.getElementById('akonadi_client_search_small.png').style.display='none';document.getElementById(' akonadi_client_search.png').style.display='inline';" title="Click to enlarge" >
\image html akonadi_client_search_small.png "Akonadi Communication Schema"
</div>
<div id=' akonadi_client_search.png' onClick="document.getElementById(' akonadi_client_search.png').style.display='none';document.getElementById('akonadi_client_search_small.png').style.display='inline';" style="display:none" >
\image html akonadi_client_search.png "Akonadi Communication Schema"
</div>
\image latex akonadi_client_search.eps "Akonadi Communication Schema" height=5cm
The item search request is probably the call which is used most often
by the clients (components or applications). This call enables the client
to search for a list of items of a given mime type which match a
given search criterion.
In this case the client will contact the SearchProvider responsible for
the mime type, in order to retrieve the list of matching UIDs. The SearchProvider
already has a list of all available items of this mime type in its memory, so it
can search fast and use indices for optimization.
To communicate mime type constraints in FETCH and LIST and their responses the
IMAP flags mechanism is used. Unknown flags should be ignored by non-Akonadi
IMAP clients, which keeps compatibility with mutt and regular KMail.
Examples:
- List
\verbatim
0x8053c68 8 LIST "" "res1/foo/%"
0x8053c68 * LIST (\MimeTypes[text/calendar,directory/inode]) "/" "res1/foo/bar"
\endverbatim
- Fetch
\verbatim
0x8056310 7 UID FETCH 22 (UID RFC822.SIZE FLAGS BODY.PEEK[])
0x8056310 * 1 FETCH (FLAGS (\Seen \MimeTypes[message/rfc822]) RFC822 {2450} From: Till Adam To: ...
\endverbatim
\section akonadi_design_communication_profile Profile Handling
<div id=' akonadi_profile_handling_small.png' onClick="document.getElementById(' akonadi_profile_handling_small.png').style.display='none';document.getElementById(' akonadi_profile_handling.png').style.display='inline';" title="Click to enlarge" >
\image html akonadi_profile_handling_small.png "Akonadi Profile Handling"
</div>
<div id=' akonadi_profile_handling.png' onClick="document.getElementById(' akonadi_profile_handling.png').style.display='none';document.getElementById(' akonadi_profile_handling_small.png').style.display='inline';" style="display:none" >
\image html akonadi_profile_handling.png "Akonadi Profile Handling"
</div>
\image latex akonadi_profile_handling.eps "Akonadi Profile Handling" height=2.5cm
\section akonadi_design_communication_agent Agent Handling
<div id=' akonadi_agent_handling_small.png' onClick="document.getElementById(' akonadi_agent_handling_small.png').style.display='none';document.getElementById(' akonadi_agent_handling.png').style.display='inline';" title="Click to enlarge" >
\image html akonadi_agent_handling_small.png "Akonadi Agent Handling"
</div>
<div id=' akonadi_agent_handling.png' onClick="document.getElementById(' akonadi_agent_handling.png').style.display='none';document.getElementById(' akonadi_agent_handling_small.png').style.display='inline';" style="display:none" >
\image html akonadi_agent_handling.png "Akonadi Agent Handling"
</div>
\image latex akonadi_agent_handling.eps "Akonadi Agent Handling" height=4cm
*/
/**
\page akonadi_overview_uml Akonadi Overview
This overview does not show a complete class or collaboration diagram, it is rather meant to show the
big picture.
<div id=' akonadi_overview_uml_small.png' onClick="document.getElementById(' akonadi_overview_uml_small.png').style.display='none';document.getElementById(' akonadi_overview_uml.png').style.display='inline';" title="Click to enlarge" >
\image html akonadi_overview_uml_small.png "Akonadi Overview"
</div>
<div id=' akonadi_overview_uml.png' onClick="document.getElementById(' akonadi_overview_uml.png').style.display='none';document.getElementById(' akonadi_overview_uml_small.png').style.display='inline';" style="display:none" >
\image html akonadi_overview_uml.png "Akonadi Overview"
</div>
*/
/**
\page akonadi_concepts Concepts
This page describes the basic concepts of Akonadi.
- \ref akonadi_concepts_collections
- \ref akonadi_concepts_items
- \ref akonadi_concepts_identification
@todo complete this page: eg. cache policies/management, search
\section akonadi_concepts_collections Collections
\subsection akonadi_conectps_collections_concept Concept
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.
\subsection akonadi_concepts_collections_akonadi 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.
\subsection akonadi_concepts_collections_tree 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:
\verbatim
+-+ resource-folder1
| +- sub-folder1
| +- sub-folder2
| ...
+-+ resource-folder2
| ...
|
+-+ Searches
+- search-folder1
+- search-folder2
...
\endverbatim
\section akonadi_concepts_items 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.
\subsection akonadi_concepts_items_parts 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).
\subsection akonadi_concepts_items_serializer 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).
\section akonadi_concepts_identification Object Identification
\subsection akonadi_concepts_identification_uid 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.
\subsection akonadi_concepts_identification_rid 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.
*/
/**
\page akonadi_usage Usage
\section akonadi_usage_start How to get started
To start Akonadi, you need to start the \ref akonadi_design_control "Control" process.
This can be done by calling \c akonadi_control, on the command line.
\section akonadi_usage_debugging Debugging Tools
From time to time it is necessary to debug the Akonadi system. For this purpose \c akonadiconsole
is available.
It is a management tool which provides user interfaces for the following tasks:
<ul>
<li>Agent Management<ul>
<li>Creation</li>
<li>Deletion</li>
<li>Configuration</li>
<li>Synchronization</li>
</ul></li>
<li>Profile Management<ul>
<li>Creation</li>
<li>Deletion</li>
</ul></li>
<li>Content Browsing<ul>
<li>Viewing and manipulation of collections</li>
<li>Viewing of PIM items</li>
</ul></li>
<li>Error Management<ul>
<li>Signal and Data monitoring</li>
</ul></li>
</ul>
*/
// DOXYGEN_SET_INPUT += @topdir@/akonadi/doc
// DOXYGEN_EXCLUDE = server libakonadi resources clients kioslave kabc kmime plugins kcal

File Metadata

Mime Type
text/x-tex
Expires
Fri, Nov 1, 8:39 AM (1 d, 10 h)
Storage Engine
blob
Storage Format
Raw Data
Storage Handle
10075167
Default Alt Text
Mainpage.dox (19 KB)

Event Timeline