Commit cc5c9631 authored by Volker Krause's avatar Volker Krause
Browse files

Recover and update some of the Akonadi documentation that was forgotten in

kdepim/runtime (former kdepim/akonadi, the place where it all started)
when the various components were moved out of there.

svn path=/trunk/KDE/kdepim/runtime/; revision=1186454
parent 58650b7c
......@@ -10,10 +10,8 @@ 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
......@@ -35,57 +33,6 @@ blocks section below.
*/
/**
\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.
*/
/**
......@@ -183,7 +130,7 @@ Furthermore it provides a D-Bus API with the following functionality:
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.
The Storage is part of the Akonadi Server and is responsible for managing the cache of %Akonadi items.
In other words, create the database schema and perform read/write operations on the database.
*/
......@@ -256,166 +203,6 @@ big picture.
*/
/**
\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_NAME=kdepim-runtime
// DOXYGEN_ENABLE=YES
Markdown is supported
0% or .
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment