KDE PIM/Akonadi: Difference between revisions

From KDE TechBase
(remove done items)
(Remove "Why not use SQLite" section which contained obsolete information (already in the title))
 
(187 intermediate revisions by 28 users not shown)
Line 1: Line 1:
== Akonadi TODO ==
== Status ==
The following list contains the things which need to be done for Akonadi.


=== Core ===
* [[Projects/PIM/Akonadi/Supported__Types|Supported Payload Types]]
 
 
{| class="sortable" border="1" cellpadding="5" cellspacing="0" style="border: gray solid 1px; border-collapse: collapse; text-align: left; width: 100%;"
|- style="background: #ececec; white-space:nowrap;"
! Status !! Item !! Description !! Contact
{{FeatureInProgress|Item size|Needed by Mailody|[email protected]}}
{{FeatureTodo|Payload serialization format versioning|see below|}}
{{FeatureTodo|Item streaming in ItemSync/ResourceBase|As discussed in Osnabrueck|}}
{{FeatureInProgress|API for additional item parts|As discussed in Osnabruck|Volker/Tobias}}
{{FeatureInProgress|Infrastructure for showing additional dialogs from agents/resources|As discussed in Osnabrueck|Tom}}
{{FeatureTodo|Allow to limit ItemFetchJob to current cache content|Prevents search index feeder agents from downloading all remote data|[email protected]}}
{{FeatureInProgress|Fix API for item/collection modifications|See Osnabrueck meeting notes for details|Volker}}
{{FeatureInProgress|Tray app|small app to control the server and have a something that can report errors|[email protected]|Toma}}
{{FeatureInProgress|Finish collection model/view|see below|[email protected]}}
{{FeatureTodo|Error reporting|Akonadi::Job basically has only one error code: Unknown|Tobias}}
{{FeatureTodo|Backup support|Dump & Restore database contents, also useful when upgrading to a newer database version|[email protected]}}
{{FeatureInProgress|Collection statistics for sub-trees|Provide a CollectionStatus object covering the full sub-tree in the model, allowing accumulated unread counts etc.|Thomas}}
{{FeatureTodo|Nepomuk integration|Generic Item tag/rate/comment, etc.|Tom}}
{{FeatureTodo|Account creation wizard|as discussed in Berlin, see below|}}
{{FeatureTodo|Sync collection tree after creating setting up a resource|see AgentInstanceCreateJob|}}
{{FeatureTodo|Support standard commands for QUndo framework||}}
{{FeatureTodo|Conflict detection in resources|See Osnabrueck meeting notes for details|}}
{{FeatureInProgress|Action framework|see below|[email protected]|Volker}}
{{FeatureTodo|Solid integration|Switch online/offline state in ResourceBase automatically|}}
{{FeatureTodo|Make unittests work without destroying the production database||}}
|}
 
=== Supported Types ===
 
Overview on the current state of support for various types:
 
{|
|-
! Type !! Serializer !! Multipart Support !! Models !! Views !! Resources !! Notes
|-
|Email||yes||partial||MessageModel, MessageCollectionModel, threading proxy model||?||maildir, IMAP||threading agent
|-
|News||yes (1)||partial (1)||(1)||(1)||NNTP||
|-
|Contact||yes||no||ContactModel||-||vCard, facebook, KRes||
|-
|Events||yes||no||EventModel||-||iCal, KRes||
|-
|Notes||no||no||-||-||-||not started yet
|-
|Feeds||no||no||-||-||-||not started yet
|-
|Bookmarks||yes||no||-||-||local bookmarks, del.icio.us||
|}
 
(1) see Email
 
=== Mail specific extensions ===
 
{| class="sortable" border="1" cellpadding="5" cellspacing="0" style="border: gray solid 1px; border-collapse: collapse; text-align: left; width: 100%;"
|- style="background: #ececec; white-space:nowrap;"
! Status !! Item !! Description !! Contact
{{FeatureTodo|Extend Message Model|Add all required columns, save/restore layout, flag delegate, configurable columns, etc.|}}
{{FeatureTodo|Share mail flag code|Standard actions, standard flag enum/constants, Nepomuk interaction|}}
{{FeatureTodo|Extend ENVELOPE|Add more information to the envelope payload part in the serializer plugin, eg. trheading information is missing|}}
{{FeatureTodo|Fix/finish threading||}}
|}
 
=== Event/Todo/Journal specific extensions ===
 
{| class="sortable" border="1" cellpadding="5" cellspacing="0" style="border: gray solid 1px; border-collapse: collapse; text-align: left; width: 100%;"
|- style="background: #ececec; white-space:nowrap;"
! Status !! Item !! Description !! Contact
{{FeatureTodo|Todo proxy model|See KOrganizers To-Do view|Bruno?}}
{{FeatureInProgress|Subtype identification|See discussion on kde-pim mailinglist|Kevin?}}
{{FeatureTodo|Agenda view|KOrganizer agenda view based on Akonadi|Bruno?}}
{{FeatureTodo|Month view|KOrganizer month view based on Akonadi|Bruno?}}
{{FeatureTodo|Timeline view|KOrganizer timeline view based on Akonadi|}}
|}
 
=== Resources, Agents and others ===
 
{| class="sortable" border="1" cellpadding="5" cellspacing="0" style="border: gray solid 1px; border-collapse: collapse; text-align: left; width: 100%;"
|- style="background: #ececec; white-space:nowrap;"
! Status !! Item !! Description !! Contact
{{FeatureInProgress|KResource Akonadi bridge|for applications using KCal or KABC|[email protected]|Kevin}}
{{FeatureInProgress|Akonadi KResource bridge|for data accessed through KCal or KABC resources|[email protected]|Kevin}}
{{FeatureTodo|Expire Agent||}}
{{FeatureTodo|MBOX Resource||Thomas}}
{{FeatureTodo|Extend IMAP Resource||}}
{{FeatureTodo|POP3 Resource||Thomas}}
{{FeatureTodo|RSS Resource||}}
{{FeatureTodo|Filter Agent||}}
{{FeatureTodo|Search||}}
{{FeatureTodo|Filter Rule GUI|Used by filters and searches|}}
|}
 
Resource status overview (this should list all resources existing in KDE3 or already under development for Akonadi):
 
{|
|-
! Resource !! Retrieve Collections !! Retrieve Items !! Change Collections !! Change Items !! Configuration !! Notes
|-
|iCal||yes (4)||yes (1) (2)||no||yes (5)||yes||does not yet watch for file changes
|-
|vCard||yes (4)||yes (1) (2)||no||?||yes||does not yet watch for file changes
|-
|maildir||yes (1) (4)||yes (1) (2)||?||?||yes||
|-
|mbox||no||no||no||no||no||not started yet, code exists in KMail
|-
|IMAP||yes (1) (4)?||yes (1) (2)||no||no||no||code exists in kio_imap4 and Mailody, support for extensions: quota, ACL, annotations missing, what about Kolab and Scalix?
|-
|POP3||no||no||no||no||no||not started yet,code exists in kio_pop3
|-
|NNTP||yes (4)||yes (2)||n/a||n/a||yes||Needs support for local collection names and collection hierarchy
|-
|Local Bookmarks||?||?||?||?||(3)||Code in akonadi/resources
|-
|OpenChange||?||?||?||?||?||Code in akonadi/resources
|-
|Facebook||?||?||?||?||?||Code in playground/pim
|-
|del.icio.us||?||?||?||yes||no||Code in playground/pim
|-
|KABC||no||yes||no||yes||yes||
|-
|KCal||no||yes||no||yes||yes||
|}
 
(1) only full sync supported currently, need optimization
(2) does not yet honor cache policy
(3) still relies on QSettings for configuration and/or doesn't provide configuration over D-Bus
(4) does not yet provide correct access control settings
(5) only adding new items, not changing existing ones


== Akonadi Braindump ==
== Akonadi Braindump ==
Line 172: Line 41:


The list is definitely long enough to make this worthwhile.
The list is definitely long enough to make this worthwhile.
=== Collection Model / Collection View ===
Ideas/missing features/bugs of the collection model/view:
* Enable/disable status columns
* Show status after the name (see KMail)
* Size column
* Save/restore layout
* Custom collection icons (see KMail, also needed for resource defined special folders (eg. Inbox)
* Status tooltips (see KMail in 3.5.9)
* Quick search
* Favorite folder view as proxy model on top of the normal collection model (FlatCollectionProxyModel might be helpful for there)
* Accumulated statistics (unread, total, size)
* Fix dnd: move/copy/cancel menu always shows up and never has any effect
=== Compatibility ===
Notes on how to keep long-term protocol, source and binary compatibility.
* Detect server version in Akonadi::Session, might be useful in case of protocol extensions/changes
* What about database server version updates?
* Versioning or any other kind of serialization format meta data, we'll need that in case of changes in serialization formats (see eg. Robert's compression patch where this is needed)
* We currently use 32 bit ids, probably hard to change later on, is that enough?
* Plugin versioning


=== Resource API issues ===
=== Resource API issues ===
Line 205: Line 49:
** Scheduler dead-locks when a requested operation is not correctly announced as finished, esp. a problem in error cases.
** Scheduler dead-locks when a requested operation is not correctly announced as finished, esp. a problem in error cases.
** Using the result methods multiple times or when not requested asserts
** Using the result methods multiple times or when not requested asserts
* Item streaming is missing, requiring all data to be in memory at once
* <s>Item streaming is missing, requiring all data to be in memory at once</s>
* Non-incremental updates need to know the results of ItemSync to not have to provide all data, even for already existing/unchanged items.
* Non-incremental updates need to know the results of ItemSync to not have to provide all data, even for already existing/unchanged items.


Line 215: Line 59:
* No mentioning of "IMAP" in the public API, we are not using IMAP
* No mentioning of "IMAP" in the public API, we are not using IMAP
* Naming and installed location of libraries, headers and executables (see discussion on kde-pim ML)
* Naming and installed location of libraries, headers and executables (see discussion on kde-pim ML)
* Payload part labels are QStrings, attribute types are QByteArray
* <s>Payload part labels are QStrings, attribute types are QByteArray</s>


=== Deployment issues ===
=== Deployment issues ===
Line 225: Line 69:
* Backup: MySQL data files should not be backed up without telling the mysqld process, otherwise a corrupt backup will be made.  LOCK TABLES and FLUSH TABLES at the least.  A dump can be made or mysqlhotbackup may be used in some circumstances. We should consider sysadmins' backup techniques when planning/promoting Akonadi, as a simple rsync cronjob with running Akonadi will not work. [http://dev.mysql.com/doc/refman/6.0/en/backup.html MySQL backup advice].
* Backup: MySQL data files should not be backed up without telling the mysqld process, otherwise a corrupt backup will be made.  LOCK TABLES and FLUSH TABLES at the least.  A dump can be made or mysqlhotbackup may be used in some circumstances. We should consider sysadmins' backup techniques when planning/promoting Akonadi, as a simple rsync cronjob with running Akonadi will not work. [http://dev.mysql.com/doc/refman/6.0/en/backup.html MySQL backup advice].


=== Account Creation Wizard ===
=== Documentation ===
 
* Avoid examples using KJob::exec() due to its problematic side-effects.
* Examples in the ItemCreateJob docs (and maybe others) operate on items in the root collection which does not work at all
* Resurrect the server API docs (now at https://api.kde.org/kdepim/akonadi/html/server.html ).
 
=== Range Queries, Sorting ===
 
Range queries require indexes on certain parts of the payload so it becomes i.e. possible to request only the events that are currently visible in the view. The same is required for server-side sorting so we can request the 200 latest emails sorted by date.
 
The feature could be implemented by creating temporary virtual collections containing the search result.
A calendar would i.e. "search" for all events of the current month, which would already solve things such as
not getting notifications for items we are not interested in.
This search folder would however have to be modified with a new query as the user scrolls in the view.
 
=== Workspace integration ===
 
* Email notifier, based on UI of LionMail [[http://vizzzion.org/blog/2010/09/getting-email-done-the-stack-and-the-heap-of-lion-mail/]], in more detail:
** Write (or lend from Kontact Touch) ProxyModels to display email collections: new / unread and important, combination thereof
** Plasma Quick widgets for individual emails and collections
** UI integration
*** Konfiguration
*** Drag and Drop (from Collection onto desktop)
*** Theming / Animations
*** Streamlined notifications (MUST NOT get in the way)
** Activity support (notify off for certain activities, only selected folders for a given activity, etc)
The current Lion Mail code uses a dataengine to retrieve data from AKonadi. This needs to be ported to using one of the AKonadi models which are also used in Kontact Touch.
 
* Agent monitoring and control
* Enable/disable logging?
* Plasma applet for notes / sticky notes
* Resource progress, e.g. like KIO progress
* Drag&Drop of Akonadi items: drop target should be able to retrieve payload
 
== Akonadi FAQ ==
 
This FAQ primarily deals with technical and design questions, if you have questions about using Akonadi (such as "I get error X when starting Akonadi"), please refer to [http://userbase.kde.org/Akonadi userbase.kde.org/Akonadi].
 
=== Where do I find the Akonadi config files? ===
 
''~/.config/akonadi/''
 
=== Where does Akonadi store my data? ===
 
Akonadi merely acts as a cache for your data, the actual content stays where it has always been, .ics/.vcf/MBOX files, local maildirs, IMAP- and groupware servers. There is only a limited amount of data stored exclusively in Akonadi:
* Data not supported by the corresponding backends, such as email flags in case of maildir/mbox. This is comparable to KMail's binary index files stored alongside these files in pre-Akonadi times.
* Internal meta-data used by application or resources, such as information about the last synchronization with a backend or translated folder names.
* Data that has been changed while the corresponding backend has been offline and has not yet been uploaded.
 
=== Where can I find the Akonadi database? ===
 
''~/.local/share/akonadi/''
 
=== Where can I find the source code? ===
 
Code for the respective parts of Akonadi is in multiple code repositories:
* The Akonadi server can be found at the [https://commits.kde.org/akonadi?path=src/server src/server subdir of the akonadi main code repo].
* The Akonadi client libraries are distributed over the [https://commits.kde.org/akonadi?path=src other subdirs of /src in the akonadi main code repo].
* Various agents, resources, and much other misc stuff is in [https://commits.kde.org/kdepim-runtime the kdepim-runtime code repo]
* the Akonadi console is in [https://commits.kde.org/akonadiconsole the akonadiconsole code repo]
 
More related repos can be found in https://invent.kde.org/pim list (TODO: list here)
 
=== Where can I find documentation? ===
General documentation, including a design overview, is on [http://community.kde.org/KDE_PIM/Akonadi KDE Community Wiki]
 
The documentation is mainly in the code itself, in the form of doxygen comments. You can find the generated documentation on [http://api.kde.org api.kde.org], for example:
* Documentation for the KDE Akonadi client library is [https://api.kde.org/kdepim/akonadi/html/client_libraries.html here]
* Documentation about the server is [https://api.kde.org/kdepim/akonadi/html/server.html here]
 
=== Which DBMS does Akonadi use? ===
Akonadi currently supports SQLite, MySQL and PostgreSQL. Basically, every database that is supported by QtSQL can be used, requiring minimal changes in the code at most. However, not all of them provide the features needed by Akonadi (see next questions).
 
=== Why not use MySQL/Embedded? ===
 
We tried that as well, there are two reasons for not using it: No support for the InnoDB engine (which we need for transaction support) and poor availability (only OpenSUSE provided usable packages, needed a patched QSQL driver).
 
=== Do I need a running MySQL server? ===
 
No. Akonadi starts its own local MySQL server (unless configured otherwise, see next question). All you need is having the 'mysqld' binary installed at runtime (usually found in the mysql-server package of your distribution).
 
=== Can Akonadi use a normal MySQL server running on my system? ===
 
Yes, it can. You find the corresponding settings in ''~/.config/akonadi/akonadiserverrc''.
 
=== Can I connect multiple Akonadi instances to the same database to share my data between different machines? ===
 
That does not work unfortunately. Akonadi does not store all relevant data in the database but also uses the file system for configuration and large payload data for example. Also, there is no mechanism to ensure multiple instances have exactly the same version and exactly the same agents and plug-ins installed etc., all of which would be necessary to work on the same database. Finally, there is no notification system to inform the other instances about changes which endangers consistency since the Akonadi server contains internal caches of data in the database. If you want multiple instances to synchronize, use a groupware server (not as bad as it sounds, Kolab for example works with many normal IMAP servers).
 
If you try this despite the warnings, be aware that there is no safety mechanism in place to prevent you from doing that and you will likely mess up your data in funny ways.
 
=== I don't like a database server because of backups/running on NFS/etc. ===
 
See section "Deployment Issues" above, we are aware of that and working on it. Some of these, like backup/restore are already implemented. But please be aware that most of this issues also existed before (eg. with KMail's custom binary indexes).
 
=== Can a single Akonadi instance be used by multiple users? ===
 
No. There has to be one Akonadi server instance per user. However, it is possible to use a shared database server.
 
=== Can I access the Akonadi server on a remote machine? ===
No. Akonadi is not a groupware server. It's a local cache only.
 
=== What's the differences between Akonadi and EDS? ===
EDS (Evolution Data Server) is limited to contacts and calendar data, Akonadi is type-independent. Especially, Akonadi is designed to also handle high-volume data such as email. Akonadi and EDS also differ largely in their access protocol on a technical level (Corba/D-Bus vs. local socket with IMAP-like protocol/D-Bus) and also on a protocol level (type specific vs. generic).
 
=== How do I create a collection? ===
 
From the developers point of view, there is Akonadi::CollectionCreateJob for that, from the users point of view, most applications allow that, eg. Mailody or akonadiconsole.
 
However, there is one limitation: Top-level collections can only be created by resources, not by normal applications. The reason for that is that every object (collection or item) is supposed to have an owning resource, that is a resource that is responsible for storing and retrieving that object. There is an ongoing discussion to remove this restriction though.
 
So, if you want to create a collection eg. for testing purposes, add a resource first. Most Akonadi applications offer an option to do that, a module for KControl is planned as well.
 
=== How do I disable automatic migration from KDE's traditional framework? ===
 
The migration tool is controlled by standard KDE configuration file called ''kres-migratorrc''.
 
Distributors or system administrators wanting to disable the automatism will probably want to that globally, e.g. by editing the installed default configuration file, or by using KDE's configuration hierachy and using a profile config between that and the user level.
 
The quickest way to deactivate it for one user account only is to use KDE's ''kwriteconfig'' tool to set the respective configration value with a simple copy&paste of the following command:
 
''kwriteconfig --file kres-migratorrc --group Migration --key Enabled --type bool false''
 
Please note that at some point KDE applications such as Kontact, KOrganizer, KMail will be using Akonadi directly, at which point migration either has to be enabled or performed manually.
 
As of KDE 4.4 (and its development releases and when building from SVN trunk) this already applies to KAddressBook and KMail's address book access.
 
=== How do I completely disable Akonadi startup? ===
 
Akonadi will be automatically started by any Akonadi-enabled application . If you don't want to start Akonadi at all, you can't use any of these applications (see the list of [http://userbase.kde.org/Akonadi#ApplicationTable Akonadi-enabled applications]). Also note, that some Plasma widgets, such as the "Digital Clock" applet uses Akonadi.
 
=== What is the relation between Akonadi and OpenSync? ===
 
Akonadi and OpenSync focus on different aspects and complement each other. Akonadi provides a unified way to access PIM data for applications and a framework to implement powerful connectors to varies data sources. OpenSync focus is on syncing two sets of PIM data.
 
An Akonadi plugin for OpenSync is currently under development, allowing to sync PIM data available through Akonadi with any other system supported by OpenSync, especially mobile phones.
 
=== When should I use Akonadi? ===
 
More precisely, when should you use for your application specific data instead of eg. just using a local file directly.
 
Akonadi is especially useful when you need one the following:
 
* Different backends for your data, like eg. a local file and a remote server. Akonadi provides a unified interface for application developers to access your data independent of the actual backend.
* Caching and change replay of remote data. Akonadi has support for that built in, giving you free offline support for any remote backend.
* Desktop-wide sharing of your data. As soon as more than one application (say your main applications and a plasmoid) accesses the same data you need to deal with locking, conflict detection, change notifications, etc. - or let Akonadi do that for you.
 
However, if you are just looking for a simple way to store your application data without needing one of the above, using Akonadi usually means more implementation work for relatively little gain.
 
=== Akonadi needs too much space in my home directory! ===
 
An empty, unused Akonadi database needs about 100 Mb of disk space. This is due to the MySQL InnoDB log files which work similar to a journal in a modern file system. These files are constant in size and independent of the actual data stored in Akonadi. The default size is optimized for performance on average desktop hardware where the use of 100 Mb of disk space is no problem. In other cases, such as multi-user systems or embedded devices, this default might not be optimal though.
 
The default size can be configured, globally or per-user. The global configuration file can be found in $PREFIX/share/config/akonadi/mysql-global.conf, the per-user file is in ~/.config/akonadi/mysql-local.conf and overwrites settings of the global file. In any of these files, you can change the settings '''innodb_log_file_size''' and assign it a smaller value than the default (64M).
 
For this setting to take effect you need to restart Akonadi. With older Akonadi versions (<=1.1.1) you might need to manually remove the InnoDB log files from ~/.local/share/akonadi/db_data for this change to take effect. The log files do not contain data after a clean shutdown and thus can safely be removed while Akonadi is not running.
 
An alternative approach especially for multi-user systems might be the use of a single, global MySQL server instance.
 
=== My Akonadi resource seems to randomly hang/stop working! ===
 
A very common problem of resources based on Akonadi::ResourceBase are "unguarded exit paths" from one of the methods you have reimplemented there. See the following example:
 
<syntaxhighlight lang="cpp">
void MyResource::retrieveItems( const Collection &collection )
{
  if ( someError )
    return;
  itemsRetrieved( myItems );
}
</syntaxhighlight>
 
In case of an error you leave retrieveItems() without telling Akonadi::ResourceBase that you are done with the task. Therefore, it is assumed the requested item retrieval takes a bit longer (which is not uncommon for resources for remote backends, results typically come in in a result slot connected to a job class for example) and waits until you announce the task is finished.
 
The following example does it correctly:
 
<syntaxhighlight lang="cpp">
void MyResource::itemAdded( const Akonadi::Item &item, const Akonadi::Collection &parent )
{
  if ( noNetwork ) { // transient error
    deferTask( i18n( "Offline, will retry later." ) );
  } else if ( item_not_valid ) { // permanent error
    cancelTaks( i18n( "Got invalid crap, can't store that." ) );
  } else {
    // store the item here
    Item newItem( item );
    newItem.setRemoteId( my_new_remote_id );
    changeCommitted( newItem );
  }
}
</syntaxhighlight>
 
The following methods require explicit notification that a task has been completed:
* retrieveX
* any method indicating changes, ie. itemAdded|Changed|Moved|Removed(), collectionAdded|Changed|Moved|Removed()
* any custom task scheduled with ResourceBase::scheduleCustomTask()
 
Refer to the API documentation of Akonadi::ResourceBase for the various ways to do that correctly, there are a few different ways, depending on the current task:
* Successful completion with convenience features, eg. changeCommitted(), itemsRetrieved() etc.
* Error cases with convenience features, eg. cancelTask(), deferTask()
* Only indicate completion, with everything else done manually, eg. changeProcessed(), taskDone()
 
To confirm a resource is affected by this problem, the "Resource Schedulers" tab of akonadiconsole is very useful (needs to be enabled in the context menu first, causes too much slowdown otherwise). It shows the state of the internal task scheduler of your resource, allowing you to spot stuck tasks.
 
== Information for Developers using Akonadi ==
 
References to information for developers using or extending Akonadi.
 
=== Tutorials ===
* [[Development/Tutorials/Akonadi/Application|Application Development]]
* [[Development/Tutorials/Akonadi/Resources|Resource Development]]
* [[Development/Tutorials/Akonadi/SerializerPlugin|Serializer Plugin Development]]
* [[Development/Tutorials/Akonadi/CreatingAccountWizardPackages|Creating accountwizard packages]]
* [[Development/AkonadiPorting|Application Porting]]
 
=== Documentation ===
 
* [[Projects/PIM/Akonadi/Testing|Akonadi Testing Framework]]
* [[Projects/PIM/Akonadi/Development_Tools|Akonadi Development Tools]]
* [[Projects/PIM/Akonadi/Firstrun|Akonadi Firstrun]]
* [[Projects/PIM/Akonadi/Trashhandling|Akonadi Trashhandling]]
* [[Projects/PIM/Akonadi/Debug_IMAP|Debugging Akonadi IMAP Resource]]
* [http://api.kde.org/4.x-api/kdepimlibs-apidocs/akonadi/html/index.html Client Library API documentation]
* [[Projects/PIM/Akonadi/Multi-Instance|Akonadi Multi-Instance Setup]]
* [[Projects/PIM/Akonadi/Architecture]]


Notes on the resource configuration wizard discussion.
=== Contact & Getting Involved ===


* WizardBase class
* [irc://irc.libera.chat/akonadi #akonadi] IRC channel on Libera Chat
* Wizard discovery via .desktop files
* [https://mail.kde.org/mailman/listinfo/kde-pim [email protected]] mailing-list
* A wizard can configure multiple resources (eg. IMAP + LDAP for Kolab) and non-resources (mailtransport)
* Optionally hide resources completely covered by wizards in the Add Account dialog
* List wizards in the Add Account dialog
* Store Account -> Resources information to offer deletion of depending resources


== KMail Breakdown Plan ==
== Akonadi Internals ==
The current plan is to put some parts of KMail into a stand-alone
library, independent of KMail. This increases code reuse (for example, the message composer could be shared with Mailody) and makes the code a lot easier to maintain and to port to Akonadi.


{| class="sortable" border="1" cellpadding="5" cellspacing="0" style="border: gray solid 1px; border-collapse: collapse; text-align: left; width: 100%;"
References to information for developers of Akonadi itself (the above section is of course also relevant for you).
|- style="background: #ececec; white-space:nowrap;"
! Status !! Item !! Description !! Contact
{{FeatureTodo|Bodypart formatters||}}
{{FeatureTodo|Reader Window||}}
{{FeatureTodo|Composer: Editor||}}
{{FeatureTodo|Composer: Message Composer||}}
{{FeatureTodo|Composer: GUI Window||}}
{{FeatureTodo|Queue Manager for mailtransport||}}
{{FeatureTodo|Templates: Core||}}
{{FeatureTodo|Templates: GUI||}}
{{FeatureTodo|Port KMCommands||}}
{{FeatureTodo|Port away from KMMessage and KMFolder* everywhere it is left||}}
{{FeatureTodo|Migration application for index and other config||}}
{{FeatureTodo|Port MDNs||}}
|}


=== Documentation ===


== The Road to World Domination ==
* [[Projects/PIM/Akonadi/Release_Howto|Akonadi Release Howto]]
* [[Projects/PIM/Akonadi/Database|Akonadi Database Internals]]
* [http://api.kde.org/kdesupport-api/akonadi-apidocs/ Akonadi Server API documentation]


Sort of related so the stuff above but with a scope for all of KDE PIM and beyond.
=== Meeting Notes ===


{| class="sortable" border="1" cellpadding="5" cellspacing="0" style="border: gray solid 1px; border-collapse: collapse; text-align: left; width: 100%;"
* [http://community.kde.org/KDE_PIM/Meetings/Osnabrueck_7 Osnabrueck 7]
|- style="background: #ececec; white-space:nowrap;"
* [http://community.kde.org/KDE_PIM/Meetings/Osnabrueck_8 Osnabrueck 8]
! Status !! Item !! Description !! Contact
* [http://community.kde.org/KDE_PIM/Meetings/Akonadi-2010-05 Akonadi/KDE PIM pre45 sprint 2010]
{{FeatureTodo|Share identity config GUI parts|eg. the signature configuration widget|}}
* [https://notes.kde.org/p/kdepim-sprint-2014 PIM Sprint 2014]
{{FeatureTodo|Mailtransport Agent|Global shared outbox, central mail sending instance|}}
{{FeatureTodo|Recently sent to support in mailtransport|related to above, based on Akonadi/Nepomuk|}}
{{FeatureTodo|Composer engine|Shared stuff for KMail/KNode/Mailody: Crypto, editor, editor actions, attachment model, message assembly, etc.|}}
|}


[[Category:PIM]]
[[Category:PIM]]

Latest revision as of 07:49, 13 April 2023

Status

Akonadi Braindump

Ideas/notes etc. on various open issues in Akonadi.

Akonadi Standard Actions

Idea: Have something like KStandardAction for Akonadi that not only includes the representation of the action but also its state management and the actual operations. Like libakonadi that should be splitted into a generic, type-independent part and be extensible for type-specific actions. This will enable code sharing among many applications and guarantee consistent actions everywhere.

State management: watch selection models of a collection and/or item model.

Use KXMLGUI for context menus in standard views to allow easy extensibility with custom actions.

Generic actions:

  • new collection [done]
  • new virtual collection
  • delete collection [done for single selection]
  • copy collection [done]
  • cut collection
  • paste collection [done]
  • synchronize collection [done for single selection]
  • synchronize resource
  • synchronize everything
  • show collection properties dialog [done]
  • delete item(s) [done]
  • copy item(s) [done]
  • cut item(s)
  • paste item(s) [done]
  • paste native data
  • tag item(s)
  • comment item
  • rate item(s)
  • configure resource
  • add resource? (would need a type parameter, etc.)
  • delete resource
  • manage local subscriptions [done]
  • move to submenu
  • copy to submenu

The list is definitely long enough to make this worthwhile.

Resource API issues

Notes/ideas/complaints about the Akonadi::ResourceBase API:

  • Extremely error prone:
    • Scheduler dead-locks when a requested operation is not correctly announced as finished, esp. a problem in error cases.
    • Using the result methods multiple times or when not requested asserts
  • Item streaming is missing, requiring all data to be in memory at once
  • Non-incremental updates need to know the results of ItemSync to not have to provide all data, even for already existing/unchanged items.

API / BC issues

Smaller stuff that should be fixed before the ABI freeze and is not yet listed above:

  • Cleanup the D-Bus format used by NotificationMessage
  • No mentioning of "IMAP" in the public API, we are not using IMAP
  • Naming and installed location of libraries, headers and executables (see discussion on kde-pim ML)
  • Payload part labels are QStrings, attribute types are QByteArray

Deployment issues

  • Multiple access: Should multiple Akonadi instances' mysqlds access a single set of data files the mysql will likely corrupt the data. This can happen in any NFS+YP installation where users can log onto any machine and access shared homes. MySQL relies on filesystem locking to prevent multiple access. MySQL multiple instance docu.
  • InnoDB tables should not be used on NFS.
  • NFS speed: MySQL documentation recommends against locating its data files on network shares.
  • AppArmor: Distros' AppArmor profiles prevent MySQL from writing outside its defined data directory (usually /var/lib/mysql). This is a problem at least with *buntu and openSUSE. These will need to be adapted. It is possible to daisy-chain profiles so that MySQL started by Akonadi receives a different profile to MySQL running standalone. An empty profile has all rights. Another possibility is to adapt the general MySQL profile so it can write to ${XDG_DATA_HOME}/akonadi(usually ${HOME/}.local/share/akonadi). Both support for profile chaining and ${HOME} may depend on the version of AppArmor installed. What about SELinux?
  • Backup: MySQL data files should not be backed up without telling the mysqld process, otherwise a corrupt backup will be made. LOCK TABLES and FLUSH TABLES at the least. A dump can be made or mysqlhotbackup may be used in some circumstances. We should consider sysadmins' backup techniques when planning/promoting Akonadi, as a simple rsync cronjob with running Akonadi will not work. MySQL backup advice.

Documentation

  • Avoid examples using KJob::exec() due to its problematic side-effects.
  • Examples in the ItemCreateJob docs (and maybe others) operate on items in the root collection which does not work at all
  • Resurrect the server API docs (now at https://api.kde.org/kdepim/akonadi/html/server.html ).

Range Queries, Sorting

Range queries require indexes on certain parts of the payload so it becomes i.e. possible to request only the events that are currently visible in the view. The same is required for server-side sorting so we can request the 200 latest emails sorted by date.

The feature could be implemented by creating temporary virtual collections containing the search result. A calendar would i.e. "search" for all events of the current month, which would already solve things such as not getting notifications for items we are not interested in. This search folder would however have to be modified with a new query as the user scrolls in the view.

Workspace integration

  • Email notifier, based on UI of LionMail [[1]], in more detail:
    • Write (or lend from Kontact Touch) ProxyModels to display email collections: new / unread and important, combination thereof
    • Plasma Quick widgets for individual emails and collections
    • UI integration
      • Konfiguration
      • Drag and Drop (from Collection onto desktop)
      • Theming / Animations
      • Streamlined notifications (MUST NOT get in the way)
    • Activity support (notify off for certain activities, only selected folders for a given activity, etc)

The current Lion Mail code uses a dataengine to retrieve data from AKonadi. This needs to be ported to using one of the AKonadi models which are also used in Kontact Touch.

  • Agent monitoring and control
  • Enable/disable logging?
  • Plasma applet for notes / sticky notes
  • Resource progress, e.g. like KIO progress
  • Drag&Drop of Akonadi items: drop target should be able to retrieve payload

Akonadi FAQ

This FAQ primarily deals with technical and design questions, if you have questions about using Akonadi (such as "I get error X when starting Akonadi"), please refer to userbase.kde.org/Akonadi.

Where do I find the Akonadi config files?

~/.config/akonadi/

Where does Akonadi store my data?

Akonadi merely acts as a cache for your data, the actual content stays where it has always been, .ics/.vcf/MBOX files, local maildirs, IMAP- and groupware servers. There is only a limited amount of data stored exclusively in Akonadi:

  • Data not supported by the corresponding backends, such as email flags in case of maildir/mbox. This is comparable to KMail's binary index files stored alongside these files in pre-Akonadi times.
  • Internal meta-data used by application or resources, such as information about the last synchronization with a backend or translated folder names.
  • Data that has been changed while the corresponding backend has been offline and has not yet been uploaded.

Where can I find the Akonadi database?

~/.local/share/akonadi/

Where can I find the source code?

Code for the respective parts of Akonadi is in multiple code repositories:

More related repos can be found in https://invent.kde.org/pim list (TODO: list here)

Where can I find documentation?

General documentation, including a design overview, is on KDE Community Wiki

The documentation is mainly in the code itself, in the form of doxygen comments. You can find the generated documentation on api.kde.org, for example:

  • Documentation for the KDE Akonadi client library is here
  • Documentation about the server is here

Which DBMS does Akonadi use?

Akonadi currently supports SQLite, MySQL and PostgreSQL. Basically, every database that is supported by QtSQL can be used, requiring minimal changes in the code at most. However, not all of them provide the features needed by Akonadi (see next questions).

Why not use MySQL/Embedded?

We tried that as well, there are two reasons for not using it: No support for the InnoDB engine (which we need for transaction support) and poor availability (only OpenSUSE provided usable packages, needed a patched QSQL driver).

Do I need a running MySQL server?

No. Akonadi starts its own local MySQL server (unless configured otherwise, see next question). All you need is having the 'mysqld' binary installed at runtime (usually found in the mysql-server package of your distribution).

Can Akonadi use a normal MySQL server running on my system?

Yes, it can. You find the corresponding settings in ~/.config/akonadi/akonadiserverrc.

Can I connect multiple Akonadi instances to the same database to share my data between different machines?

That does not work unfortunately. Akonadi does not store all relevant data in the database but also uses the file system for configuration and large payload data for example. Also, there is no mechanism to ensure multiple instances have exactly the same version and exactly the same agents and plug-ins installed etc., all of which would be necessary to work on the same database. Finally, there is no notification system to inform the other instances about changes which endangers consistency since the Akonadi server contains internal caches of data in the database. If you want multiple instances to synchronize, use a groupware server (not as bad as it sounds, Kolab for example works with many normal IMAP servers).

If you try this despite the warnings, be aware that there is no safety mechanism in place to prevent you from doing that and you will likely mess up your data in funny ways.

I don't like a database server because of backups/running on NFS/etc.

See section "Deployment Issues" above, we are aware of that and working on it. Some of these, like backup/restore are already implemented. But please be aware that most of this issues also existed before (eg. with KMail's custom binary indexes).

Can a single Akonadi instance be used by multiple users?

No. There has to be one Akonadi server instance per user. However, it is possible to use a shared database server.

Can I access the Akonadi server on a remote machine?

No. Akonadi is not a groupware server. It's a local cache only.

What's the differences between Akonadi and EDS?

EDS (Evolution Data Server) is limited to contacts and calendar data, Akonadi is type-independent. Especially, Akonadi is designed to also handle high-volume data such as email. Akonadi and EDS also differ largely in their access protocol on a technical level (Corba/D-Bus vs. local socket with IMAP-like protocol/D-Bus) and also on a protocol level (type specific vs. generic).

How do I create a collection?

From the developers point of view, there is Akonadi::CollectionCreateJob for that, from the users point of view, most applications allow that, eg. Mailody or akonadiconsole.

However, there is one limitation: Top-level collections can only be created by resources, not by normal applications. The reason for that is that every object (collection or item) is supposed to have an owning resource, that is a resource that is responsible for storing and retrieving that object. There is an ongoing discussion to remove this restriction though.

So, if you want to create a collection eg. for testing purposes, add a resource first. Most Akonadi applications offer an option to do that, a module for KControl is planned as well.

How do I disable automatic migration from KDE's traditional framework?

The migration tool is controlled by standard KDE configuration file called kres-migratorrc.

Distributors or system administrators wanting to disable the automatism will probably want to that globally, e.g. by editing the installed default configuration file, or by using KDE's configuration hierachy and using a profile config between that and the user level.

The quickest way to deactivate it for one user account only is to use KDE's kwriteconfig tool to set the respective configration value with a simple copy&paste of the following command:

kwriteconfig --file kres-migratorrc --group Migration --key Enabled --type bool false

Please note that at some point KDE applications such as Kontact, KOrganizer, KMail will be using Akonadi directly, at which point migration either has to be enabled or performed manually.

As of KDE 4.4 (and its development releases and when building from SVN trunk) this already applies to KAddressBook and KMail's address book access.

How do I completely disable Akonadi startup?

Akonadi will be automatically started by any Akonadi-enabled application . If you don't want to start Akonadi at all, you can't use any of these applications (see the list of Akonadi-enabled applications). Also note, that some Plasma widgets, such as the "Digital Clock" applet uses Akonadi.

What is the relation between Akonadi and OpenSync?

Akonadi and OpenSync focus on different aspects and complement each other. Akonadi provides a unified way to access PIM data for applications and a framework to implement powerful connectors to varies data sources. OpenSync focus is on syncing two sets of PIM data.

An Akonadi plugin for OpenSync is currently under development, allowing to sync PIM data available through Akonadi with any other system supported by OpenSync, especially mobile phones.

When should I use Akonadi?

More precisely, when should you use for your application specific data instead of eg. just using a local file directly.

Akonadi is especially useful when you need one the following:

  • Different backends for your data, like eg. a local file and a remote server. Akonadi provides a unified interface for application developers to access your data independent of the actual backend.
  • Caching and change replay of remote data. Akonadi has support for that built in, giving you free offline support for any remote backend.
  • Desktop-wide sharing of your data. As soon as more than one application (say your main applications and a plasmoid) accesses the same data you need to deal with locking, conflict detection, change notifications, etc. - or let Akonadi do that for you.

However, if you are just looking for a simple way to store your application data without needing one of the above, using Akonadi usually means more implementation work for relatively little gain.

Akonadi needs too much space in my home directory!

An empty, unused Akonadi database needs about 100 Mb of disk space. This is due to the MySQL InnoDB log files which work similar to a journal in a modern file system. These files are constant in size and independent of the actual data stored in Akonadi. The default size is optimized for performance on average desktop hardware where the use of 100 Mb of disk space is no problem. In other cases, such as multi-user systems or embedded devices, this default might not be optimal though.

The default size can be configured, globally or per-user. The global configuration file can be found in $PREFIX/share/config/akonadi/mysql-global.conf, the per-user file is in ~/.config/akonadi/mysql-local.conf and overwrites settings of the global file. In any of these files, you can change the settings innodb_log_file_size and assign it a smaller value than the default (64M).

For this setting to take effect you need to restart Akonadi. With older Akonadi versions (<=1.1.1) you might need to manually remove the InnoDB log files from ~/.local/share/akonadi/db_data for this change to take effect. The log files do not contain data after a clean shutdown and thus can safely be removed while Akonadi is not running.

An alternative approach especially for multi-user systems might be the use of a single, global MySQL server instance.

My Akonadi resource seems to randomly hang/stop working!

A very common problem of resources based on Akonadi::ResourceBase are "unguarded exit paths" from one of the methods you have reimplemented there. See the following example:

void MyResource::retrieveItems( const Collection &collection )
{
  if ( someError )
    return;
  itemsRetrieved( myItems );
}

In case of an error you leave retrieveItems() without telling Akonadi::ResourceBase that you are done with the task. Therefore, it is assumed the requested item retrieval takes a bit longer (which is not uncommon for resources for remote backends, results typically come in in a result slot connected to a job class for example) and waits until you announce the task is finished.

The following example does it correctly:

void MyResource::itemAdded( const Akonadi::Item &item, const Akonadi::Collection &parent )
{
  if ( noNetwork ) { // transient error
    deferTask( i18n( "Offline, will retry later." ) );
  } else if ( item_not_valid ) { // permanent error 
    cancelTaks( i18n( "Got invalid crap, can't store that." ) );
  } else {
    // store the item here
    Item newItem( item );
    newItem.setRemoteId( my_new_remote_id );
    changeCommitted( newItem );
  }
}

The following methods require explicit notification that a task has been completed:

  • retrieveX
  • any method indicating changes, ie. itemAdded|Changed|Moved|Removed(), collectionAdded|Changed|Moved|Removed()
  • any custom task scheduled with ResourceBase::scheduleCustomTask()

Refer to the API documentation of Akonadi::ResourceBase for the various ways to do that correctly, there are a few different ways, depending on the current task:

  • Successful completion with convenience features, eg. changeCommitted(), itemsRetrieved() etc.
  • Error cases with convenience features, eg. cancelTask(), deferTask()
  • Only indicate completion, with everything else done manually, eg. changeProcessed(), taskDone()

To confirm a resource is affected by this problem, the "Resource Schedulers" tab of akonadiconsole is very useful (needs to be enabled in the context menu first, causes too much slowdown otherwise). It shows the state of the internal task scheduler of your resource, allowing you to spot stuck tasks.

Information for Developers using Akonadi

References to information for developers using or extending Akonadi.

Tutorials

Documentation

Contact & Getting Involved

Akonadi Internals

References to information for developers of Akonadi itself (the above section is of course also relevant for you).

Documentation

Meeting Notes