KDE PIM/Akonadi: Difference between revisions

    From KDE TechBase
    m (Update links)
    (61 intermediate revisions by 18 users not shown)
    Line 3: Line 3:


    Note: The person noted in the "Contact" column is not necessarily the one implementing that feature, but the one who can tell you what to do and how to help, i.e. you can also contribute to those tasks ;-)
    Note: The person noted in the "Contact" column is not necessarily the one implementing that feature, but the one who can tell you what to do and how to help, i.e. you can also contribute to those tasks ;-)
    There is also a more detailed page about bugs and missing features of things that are currently ported [[Projects/PIM/Akonadi/PortingStatus|here]].


    === Core ===
    === Core ===
    Line 46: Line 48:
    |}
    |}


    ==== Scheduled for KDE 4.3 / Akonadi 1.2 ====
    ==== KDE 4.3 / Akonadi 1.2 ====


    Stuff we want to do for KDE 4.3, scheduled to be released in June 2009. The list is not completed yet, will be discussed during the [[Projects/PIM/Meetings/Osnabrueck_7|Osnabrueck 7]] meeting.
    Stuff that went into KDE 4.3 and Akonadi server 1.2.


    {| class="sortable" border="1" cellpadding="5" cellspacing="0" style="border: gray solid 1px; border-collapse: collapse; text-align: left; width: 100%;"
    {| class="sortable" border="1" cellpadding="5" cellspacing="0" style="border: gray solid 1px; border-collapse: collapse; text-align: left; width: 100%;"
    Line 54: Line 56:
    ! Status !! Item !! Description !! Contact
    ! Status !! Item !! Description !! Contact
    {{FeatureDone|Fix unit tests|Make unittests work without destroying the production database|Igor/Volker}}
    {{FeatureDone|Fix unit tests|Make unittests work without destroying the production database|Igor/Volker}}
    {{FeatureInProgress|Resource testing framework|Automated, shareable tests for resources|Igor/Volker}}
    {{FeatureTodo|Review change notifications|See the various discussions about shortcomings in that area|}}
    {{FeatureDone|Filesystem Backend|Store content data in files instead of the database, transfer filehandles instead of data to the client|Andras}}
    {{FeatureDone|Filesystem Backend|Store content data in files instead of the database, transfer filehandles instead of data to the client|Andras}}
    {{FeatureDone|IMAP resource||Kevin}}
    {{FeatureDone|Kolab proxy resource||Andras}}
    {{FeatureDone|RID based operations|Item/collection retrieval and modification based on remote identifiers|Volker}}
    {{FeatureDone|Microblog Support|Type library, serializer plugin, identi.ca/twitter resources|Tom}}
    {{FeatureDone|ResourceBase::collectionsRetrievalDone is missing|I'm working around by calling collectionsRetrievedIncremental() with empty collection lists|Volker}}
    |}
    ==== KDE 4.4 / Akonadi 1.3 ====
    The following is being worked on for KDE 4.4 and Akonadi server 1.3.
    {| 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
    {{FeatureDone|Port KAddressBook|Replace with KContactManager|Tobias}}
    {{FeatureDone|Resource testing framework|Automated, shareable tests for resources|Igor/Volker}}
    {{FeatureInProgress|Review change notifications|See the various discussions about shortcomings in that area|Volker,Steve}}
    {{FeatureDone|Collection statistics for sub-trees|Provide a CollectionStatus object covering the full sub-tree in the model, allowing accumulated unread counts etc.|Kevin}}
    {{FeatureDone|Favorite Folder Model|see current KMail|Kevin}}
    {{FeatureDone|Batch jobs for modifying/deleting collections/items|it would be great to have jobs which perform operations on several entities in one go|Volker}}
    {{FeatureDone|Collection streaming support in ResourceBase/CollectionSync|Similar to what is available for items already|Volker}}
    {{FeatureDone|MBox resource||Bertjan}}
    |}
    ==== Scheduled for KDE 4.5 / Akonadi 1.4 ====
    Stuff that is planned for inclusion in 4.5, partly already available in the akonadi-ports branch.
    {| 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|Port KOrganizer|Port from KResource to Akonadi|Frank/Sebastian}}
    {{FeatureInProgress|Port KOrganizer|Port from KResource to Akonadi|Frank/Sebastian}}
    {{FeatureInProgress|Port KAddressBook|Replace with KContactManager|Tobias}}
    {{FeatureDone|Account creation wizard|as discussed in Berlin, see below|Volker,Laurent,Tom}}
    {{FeatureInProgress|IMAP/Kolab resource||Kevin}}
    {{FeatureInProgress|KMail port|KMail using Akonadi|everyone}}
    {{FeatureInProgress|Port KNotes|File resource, serializer plugin, KNotes application, Kontact plugin|Jesper}}
    {{FeatureInProgress|Remote Search|Delegating searches to resources, see below|Volker}}
    {{FeatureInProgress|RID based operations|Item/collection retrieval and modification based on remote identifiers|Volker}}
    {{FeatureDone|Microblog Support|Type library, serializer plugin, identi.ca/twitter resources|Tom}}
    |}
    |}


    ==== Post KDE 4.3 / Akonadi 1.2 ====
    ==== Post KDE 4.5 /Akonadi 1.4 ====


    This stuff is currently not considered for 4.3 due to lack of resources. Of course it will be added nevertheless if someone implements it. The list is completely unsorted.
    This stuff is currently not considered for 4.5 due to lack of resources. Of course it will be added nevertheless if someone implements it. The list is completely unsorted.


    {| class="sortable" border="1" cellpadding="5" cellspacing="0" style="border: gray solid 1px; border-collapse: collapse; text-align: left; width: 100%;"
    {| class="sortable" border="1" cellpadding="5" cellspacing="0" style="border: gray solid 1px; border-collapse: collapse; text-align: left; width: 100%;"
    Line 73: Line 102:
    ! Status !! Item !! Description !! Contact
    ! Status !! Item !! Description !! Contact
    {{FeatureTodo|Error reporting|Akonadi::Job basically has only one error code: Unknown|Tobias}}
    {{FeatureTodo|Error reporting|Akonadi::Job basically has only one error code: Unknown|Tobias}}
    {{FeatureInProgress|Finish collection model/view|see below|[email protected]}}
    {{FeatureInProgress|Port KNotes|File resource, serializer plugin, KNotes application, Kontact plugin|}}
    {{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|Batch jobs for modifying/deleting collections/items|it would be great to have jobs which perform operations on several entities in one sitting (a use-case: mark all as read).|}}
    {{FeatureTodo|Batch job to retrieve a set of items from Akonadi|Those items don't belong to the same collection, rather they are located in different collections|}}
    {{FeatureTodo|Batch job to retrieve a set of items from Akonadi|Those items don't belong to the same collection, rather they are located in different collections|}}
    {{FeatureTodo|CollectionFetchJob/ItemFetchJob should be able to retrieve entities by remote id/mimetype|
    {{FeatureTodo|CollectionFetchJob/ItemFetchJob should be able to retrieve entities by flags/mimetype|
    This is problematic with change notifications, as they have to know about the filtering with the \Seen flag as well.
    This is problematic with change notifications, as they have to know about the filtering with the \Seen flag as well.
    This type of filtering would be possible with full Nepomuk interface though. We don't want yet another query language here. The plan is to fix the nepomuk agent and use that as semi-public interface for now.|}}
    This type of filtering would be possible with full Nepomuk interface though. We don't want yet another query language here. The plan is to fix the nepomuk agent and use that as semi-public interface for now.|}}
    {{FeatureTodo|ResourceBase::collectionsRetrievalDone is missing|I'm working around by calling collectionsRetrievedIncremental() with empty collection lists|}}
    {{FeatureTodo|Nepomuk integration|Generic Item tag/rate/comment, etc.|Tom}}
    {{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|Sync collection tree after creating setting up a resource|see AgentInstanceCreateJob|}}
    {{FeatureTodo|Support standard commands for QUndo framework||}}
    {{FeatureTodo|Support standard commands for QUndo framework||}}
    Line 88: Line 113:
    {{FeatureInProgress|Action framework|see below|[email protected]|Volker}}
    {{FeatureInProgress|Action framework|see below|[email protected]|Volker}}
    {{FeatureInProgress|Fix API docs|The libakonadi move as well as the huge API changes following it broke lots of the docs technical and content-wise, see below|Tobias}}
    {{FeatureInProgress|Fix API docs|The libakonadi move as well as the huge API changes following it broke lots of the docs technical and content-wise, see below|Tobias}}
    {{FeatureTodo|Migration|Data and settings from pre-Akonadi times, see below|}}
    {{FeatureInProgress|Migration|Data and settings from pre-Akonadi times, see below|}}
    {{FeatureTodo|Remote Search|Delegating searches to resources, see below|}}
    {{FeatureInProgress|Extended notifications|Item change notification do not yet include their source collections (real and virtual)|}}
    {{FeatureTodo|Extended notifications|Item change notification do not yet include their source collections (real and virtual)|}}
    {{FeatureTodo|Alternative for Akonadi::ResourceBase|Not using the scheduler to avoid the serialization of operations, see RSS resource. (This will get very complicated. Maybe use a proxy ResourceBase for this, which is thread-pooled?)|}}
    {{FeatureTodo|Alternative for Akonadi::ResourceBase|Not using the scheduler to avoid the serialization of operations, see RSS resource. (This will get very complicated. Maybe use a proxy ResourceBase for this, which is thread-pooled?)|}}
    {{FeatureTodo|Collection parameter for Monitor::itemChanged() and Monitor::itemRemoved()|
    If the item resides in several collections (normal + virtual collections) then emit those signals for each collection. Adding this would mean changing it in many places (Monitor, Observer, ...), this is lots of work but probably the right thing to do.
    Related to virtual collections, since with them, items can be in multiple collections. Better wait until the Nepomuk stuff is finished?|}}
    |}
    |}


    Line 127: Line 148:
    |- style="background: #ececec; white-space:nowrap;"
    |- style="background: #ececec; white-space:nowrap;"
    ! Status !! Item !! Description !! Contact
    ! 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|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||}}
    |}
    |}


    Line 139: Line 157:
    ! Status !! Item !! Description !! Contact
    ! Status !! Item !! Description !! Contact
    {{FeatureTodo|Todo proxy model|See KOrganizers To-Do view|Bruno?}}
    {{FeatureTodo|Todo proxy model|See KOrganizers To-Do view|Bruno?}}
    {{FeatureInProgress|Subtype identification|See discussion on kde-pim mailinglist|Kevin?}}
    {{FeatureDone|Subtype identification|See discussion on kde-pim mailinglist|Kevin}}
    {{FeatureTodo|Agenda view|KOrganizer agenda view based on Akonadi|Bruno?}}
    {{FeatureInProgress|Agenda view|KOrganizer agenda view based on Akonadi|Sergio,Kevin}}
    {{FeatureTodo|Month view|KOrganizer month view based on Akonadi|Bruno?}}
    {{FeatureTodo|Month view|KOrganizer month view based on Akonadi|Bruno?}}
    {{FeatureTodo|Timeline view|KOrganizer timeline view based on Akonadi|}}
    {{FeatureTodo|Timeline view|KOrganizer timeline view based on Akonadi|}}
    Line 153: Line 171:
    {{FeatureDone|Akonadi KResource bridge|for data accessed through KCal or KABC resources|[email protected]|Kevin}}
    {{FeatureDone|Akonadi KResource bridge|for data accessed through KCal or KABC resources|[email protected]|Kevin}}
    {{FeatureTodo|Expire Agent||}}
    {{FeatureTodo|Expire Agent||}}
    {{FeatureTodo|MBOX Resource||Thomas}}
    {{FeatureDone|MBOX Resource||Bertjan}}
    {{FeatureTodo|Extend IMAP Resource||}}
    {{FeatureDone|Extend IMAP Resource||Kevin/Andras}}
    {{FeatureTodo|POP3 Resource||Thomas}}
    {{FeatureInProgress|POP3 Resource||Thomas}}
    {{FeatureInProgress|RSS Resource|GSoC in playground/pim ([[Projects/PIM/RSS_framework_for_Akonadi|Details]])|Dmitry}}
    {{FeatureInProgress|RSS Resource|in akregator_port branch ([[Projects/PIM/RSS_framework_for_Akonadi|Details]])|Frank}}
    {{FeatureTodo|Filter Agent||}}
    {{FeatureInProgress|Filter Agent||Szymon}}
    {{FeatureTodo|Search||}}
    {{FeatureTodo|Search||}}
    {{FeatureTodo| History resource||}}
    {{FeatureTodo| History resource||}}
    {{FeatureTodo|Filter Rule GUI|Used by filters and searches|}}
    {{FeatureInProgress|Filter Rule GUI|Used by filters and searches|Szymon}}
    |}
    |}


    Line 178: Line 196:
    |-
    |-
    |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?
    |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
    |NNTP||yes (4)||yes (2)||n/a||n/a||yes||Needs support for local collection names and collection hierarchy
    Line 207: Line 223:


    Everything without migration support is implicitly converted to use the compat bridge currently.
    Everything without migration support is implicitly converted to use the compat bridge currently.
    [[Image:Akonadi-Kres.png]]


    ==== KABC migration status ====
    ==== KABC migration status ====
    Line 313: Line 332:
    * Enable/disable status columns
    * Enable/disable status columns
    * Show status after the name (see KMail)
    * Show status after the name (see KMail)
    * Size column
    * <s>Size column</s>
    * Save/restore layout
    * Save/restore layout
    * <s>Custom collection icons (see KMail, also needed for resource defined special folders (eg. Inbox)</s>
    * <s>Custom collection icons (see KMail, also needed for resource defined special folders (eg. Inbox)</s>
    * Status tooltips (see KMail in 3.5.9)
    * Status tooltips (see KMail in 3.5.9) [still missing quota info]
    * Quick search
    * Quick search
    * Favorite folder view as proxy model on top of the normal collection model (FlatCollectionProxyModel might be helpful for there)
    * <s>Favorite folder view as proxy model on top of the normal collection model (FlatCollectionProxyModel might be helpful for there)</s>
    * Accumulated statistics (unread, total, size)
    * Accumulated statistics (unread, total, size)
    * Fix dnd: move/copy/cancel menu always shows up and never has any effect
    * Fix dnd: move/copy/cancel menu always shows up and never has any effect
    Line 370: Line 389:
    * Store Account -> Resources information to offer deletion of depending resources
    * Store Account -> Resources information to offer deletion of depending resources


    === PostgreSQL datastore support ===
    === PostgreSQL Support ===
     
    First review of the akonadi code reveals PGSQL Qt driver is already supported, but the code is not totally ready for it. Some first reading comments about where to patch for supporting PostgreSQL too:
     
    ==== akonadi/server/src/storage/dbinitializer.cpp ====
     
    * line 201..., ALTER TABLE ADD [UNIQUE] INDEX syntax is MySQL only, better use the common one CREATE [UNIQUE] INDEX ... one [done with revision 789899]
    * line 303, QString DbInitializer::sqlType(const QString & type), LONGBLOB is the MySQL type, PostgreSQL will use BYTEA.
    * line 362, qFatal("Implement index support for your database!");
      mysql: SHOW INDEXES FROM %1
      pgsql: SELECT c2.relname, i.indisprimary, i.indisunique, i.indisclustered, i.indisvalid, pg_catalog.pg_get_indexdef(i.indexrelid, 0, true), c2.reltablespace
      FROM pg_catalog.pg_class c, pg_catalog.pg_class c2, pg_catalog.pg_index i
      WHERE c.oid = '16713' AND c.oid = i.indrelid AND i.indexrelid = c2.oid
      ORDER BY i.indisprimary DESC, i.indisunique DESC, c2.relname
     
        relname    | indisprimary | indisunique | indisclustered | indisvalid |                      pg_get_indexdef                        | reltablespace
      --------------+--------------+-------------+----------------+------------+--------------------------------------------------------------+---------------
      foo_pkey    | t            | t          | f              | t          | CREATE UNIQUE INDEX foo_pkey ON foo USING btree (id)        |            0
      foo_time_key | f            | t          | f              | t          | CREATE UNIQUE INDEX foo_time_key ON foo USING btree ("time") |            0
      (2 lignes)
     
    ==== akonadi/server/src/storage/datastore.cpp ====


    * line 700, qint64 DataStore::highestPimItemId() const, seems wrong for a concurrent program (SELECT MAX(col) FROM table; is not reliable if another thread is inserting at the same time) : check the callers
    Has been merged for Akonadi server 1.3. We still need a volunteer for continuous testing and maintenance though.
    * line 794, qint64 DataStore::lastInsertId( const QSqlQuery & query ), PostgreSQL doesn't provide concurrent-bogus last_insert_id, but from 8.2 accepts the syntax INSERT INTO ... RETURNING col1, col2, ...;
    * line 806, QString DataStore::dateTimeFromQDateTime( const QDateTime & dateTime ), use PostgreSQL to_char() formatting function for date rather than having Qt do it


    === Documentation ===
    === Documentation ===
    Line 401: Line 397:
    * Avoid examples using KJob::exec() due to its problematic side-effects.
    * 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
    * 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
    * Resurrect the server API docs (now at http://api.kde.org/kdesupport-api/kdesupport-apidocs/akonadi/server/html/index.html ).
    * Content of http://api.kde.org/4.x-api/kdepim-apidocs/akonadi/html/index.html should probably be moved to server or client lib docs


    === Migration of pre-Akonadi data and settings ===
    === Migration of pre-Akonadi data and settings ===
    Line 423: Line 418:
    * Akregator
    * Akregator


    === Search ===
    === Search & Virtual Collections ===
     
    Got their own page by now:
    * [[Projects/PIM/Akonadi/VirtualCollections]]
    * [[Projects/PIM/Akonadi/SearchInfrastructure]]
    * [[Projects/PIM/Akonadi/SearchPolishing]]
     
    === 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.


    * Delegation to resources still completely missing
    * Agent monitoring and control
    ** Requires query transformation
    * Enable/disable logging?
    ** Requires management for live searches
    * Plasma applet for notes / sticky notes
    ** Requires the ability to report search results (needs protocol extension)
    * Resource progress, e.g. like KIO progress
    * Query language still undecided, current options: XESAM, SPARQL
    * Drag&Drop of Akonadi items: drop target should be able to retrieve payload
    * Backend still undecided, current options: XESAM, Nepomuk


    == KMail Breakdown Plan ==
    == KMail Breakdown Plan ==
    Line 440: Line 452:
    ! Status !! Item !! Description !! Contact
    ! Status !! Item !! Description !! Contact
    {{FeatureTodo|Bodypart formatters||}}
    {{FeatureTodo|Bodypart formatters||}}
    {{FeatureTodo|Reader Window||}}
    {{FeatureDone|Reader Window||Andris}}
    {{FeatureTodo|Composer: Editor||}}
    {{FeatureDone|Composer: Message Composer||Constantin,Leo}}
    {{FeatureTodo|Composer: Message Composer||}}
    {{FeatureInProgress|Composer: GUI Window||Constantin}}
    {{FeatureTodo|Composer: GUI Window||}}
    {{FeatureDone|Queue Manager for mailtransport||Constantin}}
    {{FeatureTodo|Queue Manager for mailtransport||}}
    {{FeatureInProgress|Templates: Core||Leo}}
    {{FeatureTodo|Templates: Core||}}
    {{FeatureTodo|Templates: GUI||}}
    {{FeatureTodo|Templates: GUI||}}
    {{FeatureTodo|Port KMCommands||}}
    {{FeatureTodo|Port KMCommands||}}
    {{FeatureTodo|Port away from KMMessage and KMFolder* everywhere it is left|An idea might be: wrap KMMsgBase/KMMessage inside a reference counted Message class. Insulate everything else from it by wrapper functions. KMFolder should be easier...|}}
    {{FeatureDone|Port away from KMMessage and KMFolder* everywhere it is left|An idea might be: wrap KMMsgBase/KMMessage inside a reference counted Message class. Insulate everything else from it by wrapper functions. KMFolder should be easier...|all}}
    {{FeatureTodo|Migration application for index and other config||}}
    {{FeatureInProgress|Migration application for index and other config||Casey}}
    {{FeatureTodo|Port MDNs||}}
    {{FeatureTodo|Port MDNs||}}
    |}
    |}


    == The Road to World Domination ==
    == The Road to World Domination ==
    Line 462: Line 472:
    ! Status !! Item !! Description !! Contact
    ! Status !! Item !! Description !! Contact
    {{FeatureTodo|Share identity config GUI parts|eg. the signature configuration widget|}}
    {{FeatureTodo|Share identity config GUI parts|eg. the signature configuration widget|}}
    {{FeatureTodo|Mailtransport Agent|Global shared outbox, central mail sending instance|}}
    {{FeatureDone|Mailtransport Agent|Global shared outbox, central mail sending instance|Constantin}}
    {{FeatureTodo|Recently sent to support in mailtransport|related to above, based on Akonadi/Nepomuk|}}
    {{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.|}}
    {{FeatureInProgress|Composer engine|Shared stuff for KMail/KNode/Mailody: Crypto, editor, editor actions, attachment model, message assembly, etc.|Constantin,Leo}}
    |}
    |}


    Line 489: Line 499:


    There are three different parts of source code:
    There are three different parts of source code:
    * The Akonadi server, which is KDE-independent. Currently, the code can be found at [http://websvn.kde.org/trunk/kdesupport/akonadi/ kdesupport/akonadi]. The server code will likely move to the [http://www.freedesktop.org/wiki/ freedesktop.org project] in the future, the move has already been [https://bugs.freedesktop.org/show_bug.cgi?id=15711 requested].
    * The Akonadi server, which is KDE-independent. Currently, the code can be found at [https://projects.kde.org/projects/kdesupport/akonadi/ kdesupport/akonadi]. The server code will likely move to the [http://www.freedesktop.org/wiki/ freedesktop.org project] in the future, the move has already been [https://bugs.freedesktop.org/show_bug.cgi?id=15711 requested].
    * The Akonadi KDE client libraries are in [http://websvn.kde.org/trunk/KDE/kdepimlibs/akonadi/ kdepimlibs/akonadi].
    * The Akonadi KDE client libraries are in [https://projects.kde.org/projects/kde/kdepimlibs/repository/revisions/master/show/akonadi kdepimlibs/akonadi].
    * Various agents, resources, the Akonadi console and much other misc stuff is in [http://websvn.kde.org/trunk/KDE/kdepim/akonadi/ kdepim/akonadi]
    * Various agents, resources, the Akonadi console and much other misc stuff is in [https://projects.kde.org/projects/kde/kdepim/repository kdepim]


    === Where can I find documentation? ===
    === Where can I find documentation? ===
    Line 498: Line 508:
    You can find the generated documentation on [api.kde.org api.kde.org], for example:
    You can find the generated documentation on [api.kde.org api.kde.org], for example:


    * General documentation, including a design overview, is [http://api.kde.org/4.x-api/kdepim-apidocs/akonadi/html/index.html here]
    * General documentation, including a design overview, is [http://api.kde.org/kdesupport-api/kdesupport-apidocs/akonadi-git/html/ here]


    : Note that some links in the above documentation which point to the server or the KDE client libraries are currently broken, use the links below to access that documentation.
    : Note that some links in the above documentation which point to the server or the KDE client libraries are currently broken, use the links below to access that documentation.
    * Documentation for the KDE Akonadi client library is [http://api.kde.org/4.x-api/kdepimlibs-apidocs/akonadi/html/index.html here]
    * Documentation for the KDE Akonadi client library is [http://api.kde.org/4.x-api/kdepimlibs-apidocs/akonadi/html/index.html here]
    * Documentation about the server is [http://api.kde.org/kdesupport-api/kdesupport-apidocs/akonadi/server/html/index.html here]
    * Documentation about the server is [http://api.kde.org/kdesupport-api/kdesupport-apidocs/akonadi-git/html/ here]


    === Which DBMS does Akonadi use? ===
    === Which DBMS does Akonadi use? ===
    Line 510: Line 520:
    === Why not use sqlite? ===
    === Why not use sqlite? ===


    We tried. Really. It can't handle the concurrent access very well, in the best case this means ''very'' slow operations, but we've also seen deadlocks and failing transactions. Once that's fixed in sqlite, adjusting Akonadi to use it again instead of MySQL is no problem.
    We tried. Really. It just can't handle the concurrent access very well.
     
    Please refer to [http://techbase.kde.org/Projects/PIM/Akonadi/Database#Sqlite] for more information on this subject.


    === Why not use MySQL/Embedded? ===
    === Why not use MySQL/Embedded? ===
    Line 523: Line 535:


    Yes, it can. You find the corresponding settings in ''~/.config/akonadi/akonadiserverrc''.
    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. ===
    === I don't like a database server because of backups/running on NFS/etc. ===
    Line 536: Line 554:


    === What's the differences between Akonadi and EDS? ===
    === What's the differences between Akonadi and EDS? ===
    EDS 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).
    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? ===
    === How do I create a collection? ===
    Line 556: Line 574:
    ''kwriteconfig --file kres-migratorrc --group Migration --key Enabled --type bool false''
    ''kwriteconfig --file kres-migratorrc --group Migration --key Enabled --type bool false''


    Please note that at some point KDE applications such as Kontact, KOrganizer, KMail, KAddressBook will be using Akonadi directly, at which point migration either has to be enabled or performed manually.
    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? ===
    === How do I completely disable Akonadi startup? ===


    If you already have applications natively using Akonadi, you of course can't disable Akonadi startup. <i>Mailody</i> and <i>KPilot</i> are applications that are already based on Akonadi, for example.
    {{warning|If you already have applications natively using Akonadi, you of course can't disable Akonadi startup. <i>KAddressBook</i> (as of KDE 4.4 and its test versions), <i>Mailody</i>, <i>KMail</i> (as of KDE 4.4 and its test versions for address book related things) and <i>KPilot</i> are applications that are already based on Akonadi.}}


    Other applications, like <i>KAddressbook</i> and <i>KOrganizer</i>, are not based on Akonadi yet, at the time of writing. Instead, they use the old KResource framework for storing contacts, calendars and notes.
    Other applications, like <i>KOrganizer</i>, are not based on Akonadi yet, at the time of writing. Instead, they use the old KResource framework for storing contacts, calendars and notes.
    During the KDE 4.2 beta time, these KResources were automatically migrated to Akonadi-based KResources, the so-called Akonadi compatibility resources. Therefore, applications like KAddressbook and KOrganizer would use Akonadi indirectly through KResources, and therefore would start the Akonadi server when being started. Note that the same situation applies for KMail, which uses addressbook functionality also based on KResources.
    During the KDE 4.2 beta time, these KResources were automatically migrated to Akonadi-based KResources, the so-called Akonadi compatibility resources. Therefore, applications like KOrganizer would use Akonadi indirectly through KResources, and therefore would start the Akonadi server when being started.


    If Akonadi doesn't start up correctly for you, the following should help you to disable Akonadi startup and use your old KResources again.
    If Akonadi doesn't start up correctly for you, the following should help you to disable Akonadi startup and use your old KResources again.
    Line 600: Line 620:
    An alternative approach especially for multi-user systems might be the use of a single, global MySQL server instance.
    An alternative approach especially for multi-user systems might be the use of a single, global MySQL server instance.


    [[Category:PIM]]
    === 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]]


    == Links ==
    === Documentation ===


    * [[Projects/PIM/Akonadi/Testing|Akonadi Testing Framework]]
    * [[Projects/PIM/Akonadi/Testing|Akonadi Testing Framework]]
    * [[Projects/PIM/Akonadi/Development_Tools|Akonadi Development Tools]]
    * [[Projects/PIM/Akonadi/Development_Tools|Akonadi Development Tools]]
    * Tutorials:
    * [[Projects/PIM/Akonadi/Firstrun|Akonadi Firstrun]]
    ** [[Development/Tutorials/Akonadi/Application|Application Development]]
    * [[Projects/PIM/Akonadi/Trashhandling|Akonadi Trashhandling]]
    ** [[Development/Tutorials/Akonadi/Resources|Resource Development]]
    * [[Projects/PIM/Akonadi/Debug_IMAP|Debugging Akonadi IMAP Resource]]
    ** [[Development/Tutorials/Akonadi/SerializerPlugin|Serializer Plugin Development]]
    * [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 ===
     
    * [[Projects/PIM/Akonadi/Bookmarks|Bookmark support based on Akonadi]]
    * [[Projects/PIM/Akonadi/Bookmarks|Bookmark support based on Akonadi]]
    * [[Projects/PIM/Akonadi/PortingStatus|Akonadi Port - List of Bugs and Features]]
    === Contact & Getting Involved ===
    * #akonadi IRC channel on freenode
    * [email protected] mailing-list
    * Google Summer of Code
    ** [[Projects/Summer of Code/2009/Ideas#KDE_PIM|Google Summer of Code 2009 Ideas]]
    ** TODO: add links for other years
    === Links ===
    * [http://pim.kde.org/akonadi/ http://pim.kde.org/akonadi/]
    * [http://pim.kde.org/akonadi/ http://pim.kde.org/akonadi/]
    * API docs
     
    ** [http://api.kde.org/4.x-api/kdepimlibs-apidocs/akonadi/html/index.html Client library]
     
    ** [http://api.kde.org/kdesupport-api/kdesupport-apidocs/akonadi/html/ Server]
    == Akonadi Internals ==
    * #akonadi IRC channel on freenode
     
    * Meetings
    References to information for developers of Akonadi itself (the above section is of course also relevant for you).
    ** [[Projects/PIM/Akonadi/Meeting2008-11|Halloween Sprint 2008]]
     
    ** [[Projects/PIM/Meetings/Osnabrueck_7|Osnabrueck 7]]
    === Documentation ===
    ** [[Projects/PIM/Akonadi/Meeting2009-04|Akonadi April Sprint 2009]]
     
    * [[Projects/Summer of Code/2009/Ideas#KDE_PIM|Google Summer of Code 2009 Ideas]]
    * [[Projects/PIM/Akonadi/Release_Howto|Akonadi Release Howto]]
    * [[Projects/PIM/Akonadi/Database|Akonadi Database Internals]]
    * [http://api.kde.org/kdesupport-api/kdesupport-apidocs/akonadi/html/ Akonadi Server API documentation]
     
    === Meeting Notes ===
     
    * [[Projects/PIM/Akonadi/Meeting2008-11|Halloween Sprint 2008]]
    * [http://community.kde.org/KDE_PIM/Meetings/Osnabrueck_7 Osnabrueck 7]
    * [[Projects/PIM/Akonadi/Meeting2009-04|Akonadi April Sprint 2009]]
    * [[Projects/PIM/Meetings/GCDS_2009|GCDS/aKademy 2009]]
    * [[Projects/PIM/Akonadi/Meeting2009-10|Akonadi October Sprint 2009]]
    * [http://community.kde.org/KDE_PIM/Meetings/Osnabrueck_8 Osnabrueck 8]
    * [http://community.kde.org/KDE_PIM/Meetings/Akonadi-2010-05 Akonadi/KDE PIM pre45 sprint 2010]
     
    [[Category:PIM]]

    Revision as of 16:39, 16 October 2012

    Akonadi TODO

    The following list contains the things which need to be done for Akonadi.

    Note: The person noted in the "Contact" column is not necessarily the one implementing that feature, but the one who can tell you what to do and how to help, i.e. you can also contribute to those tasks ;-)

    There is also a more detailed page about bugs and missing features of things that are currently ported here.

    Core

    KDE 4.1 / Akonadi 1.0

    Urgent tasks that need to be finished for the KDE 4.1 release (May 19th):

    Status Item Description Contact
    DONE Item streaming in ItemSync/ResourceBase As discussed in Osnabrueck <Tom/Volker>
    DONE Payload serialization format versioning see below

    [email protected]

    <Tobias>
    DONE API for additional item parts As discussed in Osnabruck <Volker/Tobias>
    DONE Infrastructure for showing additional dialogs from agents/resources As discussed in Osnabrueck <Tom>
    DONE Allow to limit ItemFetchJob to current cache content Prevents search index feeder agents from downloading all remote data Volker <[email protected]>
    DONE Fix API for item/collection modifications See Osnabrueck meeting notes for details Volker <[email protected]>
    DONE Plugin Versioning For serializer plugins, also check using Qt plugin stuff instead of the libkdepim plugin framework Tobias <[email protected]>
    DONE Tray app small app to control the server and have a something that can report errors Toma <[email protected]>
    DONE Backup support Dump & Restore database contents, also useful when upgrading to a newer database version <[email protected]>
    DONE Akonadi Artwork Icon for the tray app Toma <[email protected]>

    KDE 4.2 / Akonadi 1.1

    That's the stuff we want to have in 4.2, very roughly ordered by priority. Releases are scheduled for early January 2009.

    Status Item Description Contact
    DONE Server error reporting Helpful error message when the server cannot be started or if there is some other problem communicating with it. Volker <[email protected]>
    DONE KResource migration tool For KABC and KCal resources, setting up Akonadi <-> KResource bridges where needed <Volker>
    DONE KResource bridges Basically finished, needs more testing <Kevin>
    DONE Distribution Lists Serializer Plugin and resource support <Tobias,Kevin>
    DONE Complete iCal resource error handling, robustness, legacy formats, file montitoring <Volker>
    DONE Complete vCard resource same as iCal + binary legacy format <Bertjan>
    DONE Item size Needed by Mailody <[email protected]>
    DONE LINK/UNLINK commands Managing item references in virtual collections Volker <[email protected]>
    DONE Akonadi Testrunner Running tests in a self contained Akonadi setup Igor <[email protected]>
    DONE Remote file support for iCal/vCard resources Replaces net/remote KRes resources <Bertjan>
    DONE Solid integration Switch online/offline state in ResourceBase automatically <Bertjan>

    KDE 4.3 / Akonadi 1.2

    Stuff that went into KDE 4.3 and Akonadi server 1.2.

    Status Item Description Contact
    DONE Fix unit tests Make unittests work without destroying the production database <Igor/Volker>
    DONE Filesystem Backend Store content data in files instead of the database, transfer filehandles instead of data to the client <Andras>
    DONE IMAP resource <Kevin>
    DONE Kolab proxy resource <Andras>
    DONE RID based operations Item/collection retrieval and modification based on remote identifiers <Volker>
    DONE Microblog Support Type library, serializer plugin, identi.ca/twitter resources <Tom>
    DONE ResourceBase::collectionsRetrievalDone is missing I'm working around by calling collectionsRetrievedIncremental() with empty collection lists <Volker>

    KDE 4.4 / Akonadi 1.3

    The following is being worked on for KDE 4.4 and Akonadi server 1.3.

    Status Item Description Contact
    DONE Port KAddressBook Replace with KContactManager <Tobias>
    DONE Resource testing framework Automated, shareable tests for resources <Igor/Volker>
    IN PROGRESS Review change notifications See the various discussions about shortcomings in that area <Volker,Steve>
    DONE Collection statistics for sub-trees Provide a CollectionStatus object covering the full sub-tree in the model, allowing accumulated unread counts etc. <Kevin>
    DONE Favorite Folder Model see current KMail <Kevin>
    DONE Batch jobs for modifying/deleting collections/items it would be great to have jobs which perform operations on several entities in one go <Volker>
    DONE Collection streaming support in ResourceBase/CollectionSync Similar to what is available for items already <Volker>
    DONE MBox resource <Bertjan>

    Scheduled for KDE 4.5 / Akonadi 1.4

    Stuff that is planned for inclusion in 4.5, partly already available in the akonadi-ports branch.

    Status Item Description Contact
    IN PROGRESS Port KOrganizer Port from KResource to Akonadi <Frank/Sebastian>
    DONE Account creation wizard as discussed in Berlin, see below <Volker,Laurent,Tom>
    IN PROGRESS KMail port KMail using Akonadi <everyone>
    IN PROGRESS Remote Search Delegating searches to resources, see below <Volker>

    Post KDE 4.5 /Akonadi 1.4

    This stuff is currently not considered for 4.5 due to lack of resources. Of course it will be added nevertheless if someone implements it. The list is completely unsorted.

    Status Item Description Contact
    TO DO Error reporting Akonadi::Job basically has only one error code: Unknown <Tobias>
    IN PROGRESS Port KNotes File resource, serializer plugin, KNotes application, Kontact plugin [mailto: <>]
    TO DO Batch job to retrieve a set of items from Akonadi Those items don't belong to the same collection, rather they are located in different collections [mailto: <>]
    TO DO CollectionFetchJob/ItemFetchJob should be able to retrieve entities by flags/mimetype

    This is problematic with change notifications, as they have to know about the filtering with the \Seen flag as well. This type of filtering would be possible with full Nepomuk interface though. We don't want yet another query language here. The plan is to fix the nepomuk agent and use that as semi-public interface for now.

    [mailto: <>]
    TO DO Nepomuk integration Generic Item tag/rate/comment, etc. <Tom>
    TO DO Sync collection tree after creating setting up a resource see AgentInstanceCreateJob [mailto: <>]
    TO DO Support standard commands for QUndo framework [mailto: <>]
    TO DO Conflict detection in resources See Osnabrueck meeting notes for details [mailto: <>]
    IN PROGRESS Action framework see below Volker <[email protected]>
    IN PROGRESS Fix API docs The libakonadi move as well as the huge API changes following it broke lots of the docs technical and content-wise, see below <Tobias>
    IN PROGRESS Migration Data and settings from pre-Akonadi times, see below [mailto: <>]
    IN PROGRESS Extended notifications Item change notification do not yet include their source collections (real and virtual) [mailto: <>]
    TO DO Alternative for Akonadi::ResourceBase Not using the scheduler to avoid the serialization of operations, see RSS resource. (This will get very complicated. Maybe use a proxy ResourceBase for this, which is thread-pooled?) [mailto: <>]

    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 yes no Feeds, Items ? OPML GSoC in playground/pim
    Bookmarks yes no - - local bookmarks, del.icio.us

    (1) see Email

    Mail specific extensions

    Status Item Description Contact
    TO DO Share mail flag code Standard actions, standard flag enum/constants, Nepomuk interaction [mailto: <>]

    Event/Todo/Journal specific extensions

    Status Item Description Contact
    TO DO Todo proxy model See KOrganizers To-Do view <Bruno?>
    DONE Subtype identification See discussion on kde-pim mailinglist <Kevin>
    IN PROGRESS Agenda view KOrganizer agenda view based on Akonadi <Sergio,Kevin>
    TO DO Month view KOrganizer month view based on Akonadi <Bruno?>
    TO DO Timeline view KOrganizer timeline view based on Akonadi [mailto: <>]

    Resources, Agents and others

    Status Item Description Contact
    DONE KResource Akonadi bridge for applications using KCal or KABC Kevin <[email protected]>
    DONE Akonadi KResource bridge for data accessed through KCal or KABC resources Kevin <[email protected]>
    TO DO Expire Agent [mailto: <>]
    DONE MBOX Resource <Bertjan>
    DONE Extend IMAP Resource <Kevin/Andras>
    IN PROGRESS POP3 Resource <Thomas>
    IN PROGRESS RSS Resource in akregator_port branch (Details) <Frank>
    IN PROGRESS Filter Agent <Szymon>
    TO DO Search [mailto: <>]
    TO DO History resource [mailto: <>]
    IN PROGRESS Filter Rule GUI Used by filters and searches <Szymon>

    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 yes remote file support, file watching with conflict handling
    vCard yes (4) yes (1) (2) no yes yes remote file support, file watching with conflict handling
    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?
    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 yes(6) yes no yes yes
    KCal yes(6) yes yes(7) 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
    6. availability of child collections depend on whether the KResource plugin has subresources
    7. child collections can be added or removed if the KCal plugin can have subresources

    KResource Migration Status

    Everything without migration support is implicitly converted to use the compat bridge currently.


    KABC migration status

    KResource Feature equivalent agent Migration support Notes
    directory vCard dir in development
    file vCard file 4.2 binary format no longer supported, migrated to compat bridge instead
    groupdav
    groupwise
    kolab
    ldapkio
    net vCard file TODO
    scalix
    slox
    xmlrpc

    KCal Migration Status

    KResource Feature equivalent agent Migration support Notes
    blog
    bugzilla
    groupdav
    groupwise
    kabc (birthday) birthdays 4.3
    kolab
    localdir
    local iCal file 4.2
    remote iCal file TODO remote supports different URLs for upload and download, the iCal file agent doesn't, is this needed at all?
    featureplan probably obsolete since we don't use the XML featureplan anymore
    scalix
    slox
    xmlrpc

    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.

    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) [still missing quota info]
    • 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

    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.

    Account Creation Wizard

    Notes on the resource configuration wizard discussion.

    • WizardBase class
    • Wizard discovery via .desktop files
    • 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

    PostgreSQL Support

    Has been merged for Akonadi server 1.3. We still need a volunteer for continuous testing and maintenance though.

    Documentation

    Migration of pre-Akonadi data and settings

    • KCal/KABC
      • switch KRes resources to Akonadi KRes compat resources, use KRes Akonadi compat resource, basically injecting Akonadi inbetween
      • Replace Akonadi KRes compat resources with their ported equivalent
      • Application side does not need migration code, "only" port to Akonadi
    • KMail
      • Should migrate to one resource per account + one for previous local folders
      • Problem: local folders are mixed mbox/maildir
        • Dedicated KMail compat resource?
        • Convert everything to maildir first?
      • Flags are stored in proprietary binary format
    • KNode
      • Migrate every account to NNTP resource
      • Local flags should be preserved, stored in proprietary binary format
      • Local subscription state should be preserved (where is that stored?)
      • Local folders using MBOX format + proprietary binary index
    • Akregator

    Search & Virtual Collections

    Got their own page by now:

    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

    KMail Breakdown Plan

    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.

    Status Item Description Contact
    TO DO Bodypart formatters [mailto: <>]
    DONE Reader Window <Andris>
    DONE Composer: Message Composer <Constantin,Leo>
    IN PROGRESS Composer: GUI Window <Constantin>
    DONE Queue Manager for mailtransport <Constantin>
    IN PROGRESS Templates: Core <Leo>
    TO DO Templates: GUI [mailto: <>]
    TO DO Port KMCommands [mailto: <>]
    DONE Port away from KMMessage and KMFolder* everywhere it is left An idea might be: wrap KMMsgBase/KMMessage inside a reference counted Message class. Insulate everything else from it by wrapper functions. KMFolder should be easier... <all>
    IN PROGRESS Migration application for index and other config <Casey>
    TO DO Port MDNs [mailto: <>]

    The Road to World Domination

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

    Status Item Description Contact
    TO DO Share identity config GUI parts eg. the signature configuration widget [mailto: <>]
    DONE Mailtransport Agent Global shared outbox, central mail sending instance <Constantin>
    TO DO Recently sent to support in mailtransport related to above, based on Akonadi/Nepomuk [mailto: <>]
    IN PROGRESS Composer engine Shared stuff for KMail/KNode/Mailody: Crypto, editor, editor actions, attachment model, message assembly, etc. <Constantin,Leo>

    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?

    There are three different parts of source code:

    Where can I find documentation?

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

    • General documentation, including a design overview, is here
    Note that some links in the above documentation which point to the server or the KDE client libraries are currently broken, use the links below to access that documentation.
    • Documentation for the KDE Akonadi client library is here
    • Documentation about the server is here

    Which DBMS does Akonadi use?

    So far only MySQL. There is some work on PostgreSQL support going on though. 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 two questions).

    Why not use sqlite?

    We tried. Really. It just can't handle the concurrent access very well.

    Please refer to [2] for more information on this subject.

    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?

    Warning
    If you already have applications natively using Akonadi, you of course can't disable Akonadi startup. KAddressBook (as of KDE 4.4 and its test versions), Mailody, KMail (as of KDE 4.4 and its test versions for address book related things) and KPilot are applications that are already based on Akonadi.


    Other applications, like KOrganizer, are not based on Akonadi yet, at the time of writing. Instead, they use the old KResource framework for storing contacts, calendars and notes. During the KDE 4.2 beta time, these KResources were automatically migrated to Akonadi-based KResources, the so-called Akonadi compatibility resources. Therefore, applications like KOrganizer would use Akonadi indirectly through KResources, and therefore would start the Akonadi server when being started.

    If Akonadi doesn't start up correctly for you, the following should help you to disable Akonadi startup and use your old KResources again.

    First, disable automatic migration like described in the above FAQ entry. Then, open System Settings, go to the Advanced tab and open the KDE Resources config panel. There, you can configure which type of KResources are used for contacts, calendars and notes. If the migration to Akonadi was successful, you'll probably only see the Akonadi Compatibility Resource as an active resource, and all others disabled.

    To disable Akonadi startup, enable your old resources again, then disable and delete the Akonadi compatibility resource.

    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

    Projects

    Contact & Getting Involved

    Links


    Akonadi Internals

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

    Documentation

    Meeting Notes