kde-playground/kdepim/akonadi_next/Mainpage.dox

/** @mainpage akonadi_next

Some classes to be merged into akonadi when finished. This doc will also need to be merged.

<h1>How to use Akonadi in your application</h1>

This library provides classes for KDE applications to communicate with the akonadi server. The most high-level interface to Akonadi is the Models and Views provided in this library. Ready to use models are provided for use with views to interact with a tree of collections, a list of items in a collection, or a combined tree of Collections and items.

<h2>Collections and Items</h2>

In the Akonadi concept, Items are individual objects of PIM data, eg emails, contacts, events, notes etc. The data in an item is stored in it a typed payload. For example, if an Akonadi Item holds a contact, the contact is available as a KABC::Addressee:

@code
  if (item.hasPayload<KABC::Addressee>())
  {
    KABC::Addressee addr = item.payload<KABC::Addressee>();
    // use addr in some way...
  }
@endcode

Additionally, an Item must have a mimetype which corresponds to the type of payload it holds.

Collections are simply containers of Items. A Collection has a name and a list of mimetypes that it may contain. If a collection may contain events if it can contain the mimetype 'text/calendar'. All Collections have the same mimetype. A Collection which can itself contain Collections must be able to contain the Collection mimetype.

@code
  Collection col;
  // This collection can contain events and nested collections.
  col.setContentMimetypes( QStringList() << Collection::mimeType() << "text/calendar" );
@endcode

This systems makes it simple to create PIM applications. For example, to create an application for viewing and editing events, you simply need to tell akonadi to retrieve all items matching the mimetype 'text/calendar'.

<h2> Models and Views</h2>
Akonadi models and views are a high level way to interact with the akonadi server. Most applications will use these classes.

Models provide an interface for viewing, deleting and moving Items and Collections. New Items can also be created by dropping data of the appropriate type on a model. Additionally, the models are updated automatically if another application changes the data or inserts of deletes items etc.

Akonadi provides several models for particular uses, eg the MailModel is used for emails and the ContactsModel is used for showing contacts. Additional specific models can be implemented using EntityTreeModel as a base class.

A typical use of these would be to create a model and use proxy models to make the view show different parts of the model. For example, show a collection tree in on one side and show items in a selected collection in another view.

@code
  mailModel = new MailModel( session, monitor, this);

  collectionTree = new MimeTypeFilterProxyModel(this);
  collectionTree->setSourceModel(mailModel);
  // Filter out everything that is not a collection.
  collectionTree->addMimeTypeInclusionFilter( Collection::mimeType() );
  collectionTree->setHeaderSet(EntityTreeModel::CollectionTreeHeaders);

  collectionView = new EntityTreeView(this);
  collectionView->setModel(collectionTree);

  itemList = new MimeTypeFilterProxyModel(this);
  itemList->setSourceModel(mailModel);
  // Filter out collections
  itemList->addMimeTypeExclusionFilter( Collection::mimeType() );
  itemList->setHeaderSet(EntityTreeModel::ItemListHeaders);

  itemView = new EntityTreeView(this);
  itemView->setModel(itemList);
@endcode

\image html mailmodelapp.png "An email application using MailModel"

@warning Some of the features in the examples below are not fully implemented yet. See entitytreemodel.h for a list of remaining issues with the api and implementation of these classes.

The content of the model is determined by the configuration of the Monitor passed into it. The examples below show a use of the EntityTreeModel and some proxy models for a simple heirarchical note collection. As the model is generic, the configuration and proxy models will also work with any other mimetype.

@code

// Configure what should be shown in the model:
Monitor *monitor = new Monitor( this );
monitor->fetchCollection( true );
monitor->setItemFetchScope( scope );
monitor->setCollectionMonitored( Collection::root() );
monitor->setMimeTypeMonitored( MyEntity::mimeType() );

Session *session = new Session( QByteArray( "MyEmailApp-" ) + QByteArray::number( qrand() ), this );

EntityTreeModel *entityTree = new Akonadi::EntityTreeModel(session, monitor, this);
@endcode

\image html entitytreemodel.png "A plain EntityTreeModel in a view"

The EntityTreeModel can be further configured for certain behaviours such as fetching of collections and items.

To create a model of only a collection tree and no items, set that in the model. This is just like CollectionModel:

@code
entityTree->setItemPopulationStrategy(EntityTreeModel::NoItemPopulation);
@endcode


\image html entitytreemodel-collections.png "A plain EntityTreeModel which does not fetch items."

Or, create a model of only items and not child collections. This is just like ItemModel:

@code
entityTree->setRootCollection(myCollection);
entityTree->setCollectionFetchStrategy(EntityTreeModel::FetchNoCollections);
@endcode

The CollectionModel-like and ItemModel-like configurations will probably not be used much. Usually, a full tree of collections and items will be created and proxy models will be used to filter collections or items as needed.

Or, to create a model which includes items and first level collections:

@code
entityTree->setCollectionFetchStrategy(EntityTreeModel::FetchFirstLevelCollections);
@endcode

The items in the model can also be inserted lazily for performance reasons. The Collection tree is always built immediately.

Additionally, a DescendantEntitiesProxyModel may be used to alter how the items in the tree are presented.

@code
// ... Create an entityTreeModel
DescendantEntitiesProxyModel *descProxy = new DescendantEntitiesProxyModel(this);
descProxy->setSourceModel(entityTree);
view->setModel(descProxy);
@endcode

\image html descendantentitiesproxymodel.png "A DescendantEntitiesProxyModel wrapping an EntityTreeModel"

DescendantEntitiesProxyModel can also display the same data as FlatCollectionProxyModel, but optionally for the entire entity tree, not just collections.

@code
// ... Create an entityTreeModel
DescendantEntitiesProxyModel *descProxy = new DescendantEntitiesProxyModel(this);
descProxy->setSourceModel(entityTree);

// #### This is new
descProxy->setDisplayAncestorData(true, QString(" / "));

view->setModel(descProxy);

@endcode

\image html descendantentitiesproxymodel-withansecnames.png "A DescendantEntitiesProxyModel with ancestor names."


This proxy can be combined with a filter to for example remove collections.

@code
// ... Create an entityTreeModel
DescendantEntitiesProxyModel *descProxy = new DescendantEntitiesProxyModel(this);
descProxy->setSourceModel(entityTree);

// #### This is new.
MimeTypeFilterProxyModel *filterModel = new MimeTypeFilterProxyModel(this);
filterModel->setSourceModel(descProxy);
filterModel->setExclusionFilter(QStringList() << Collection::mimeType());

view->setModel(filterModel);
@endcode

\image html descendantentitiesproxymodel-colfilter.png "An MimeTypeFilterProxyModel wrapping a DescendantEntitiesProxyModel wrapping an EntityTreeModel"

It is also possible to show the root item as part of the selectable model:

@code

entityTree->setIncludeRootCollection(true);

@endcode

\image html entitytreemodel-showroot.png "An EntityTreeModel showing Collection::root"

By default the displayed name of the root collection is '[*]', because it doesn't require i18n, and is generic. It can be changed too.

@code
entityTree->setIncludeRootCollection(true);
entityTree->setRootCollectionDisplayName(i18nc("Name of top level for all collections in the application", "[All]"))
@endcode

\image html entitytreemodel-showrootwithname.png "An EntityTreeModel showing Collection::root with an application specific name."

These can of course be combined to create an application which uses one EntityTreeModel along with several proxies and views.

@code
// ... create an EntityTreeModel.
MimeTypeFilterProxyModel *collectionTree = new MimeTypeFilterProxyModel(this);
collectionTree->setSourceModel(entityTree);
// Filter to include collections only:
collectionTree->setInclusionFilter(QStringList() << Collection::mimeType());
EntityTreeView *treeView = new EntityTreeView(this);
treeView->setModel(collectionTree);

MimeTypeFilterProxyModel *itemList = new MimeTypeFilterProxyModel(this);
itemList->setSourceModel(entityTree);
// Filter *out* collections
itemList->setExclusionFilter(QStringList() << Collection::mimeType());
EntityTreeView *listView = new EntityTreeView(this);
listView->setModel(itemList);
@endcode


\image html treeandlistapp.png "A single EntityTreeModel with several views and proxies."

Or to also show items of child collections in the list:

@code
  collectionTree = new MimeTypeFilterProxyModel(this);
  collectionTree->setSourceModel(entityTree);

  // Include only collections in this proxy model.
  collectionTree->addMimeTypeInclusionFilter( Collection::mimeType() );

  treeview->setModel(collectionTree);

  descendedList = new DescendantEntitiesProxyModel(this);
  descendedList->setSourceModel(entityTree);

  itemList = new MimeTypeFilterProxyModel(this);
  itemList->setSourceModel(descendedList);

  // Exclude collections from the list view.
  itemList->addMimeTypeExclusionFilter( Collection::mimeType() );

  listView = new EntityTreeView(this);
  listView->setModel(itemList);
@endcode

\image html treeandlistappwithdesclist.png "Showing descendants of all Collections in the list"

Note that it is important in this case to use the DescendantEntitesProxyModel before the MimeTypeFilterProxyModel. Otherwise, by filtering out the collections first, you would also be filtering out their child items.

A SelectionProxyModel can be used to simplify managing selection in one view through multiple proxy models to a representation in another view. The selectionModel of the initial view is used to create a proxied model which includes only the selected indexes and their children.

@code
  collectionTree = new MimeTypeFilterProxyModel(this);
  collectionTree->setSourceModel(entityTree);

  // Include only collections in this proxy model.
  collectionTree->addMimeTypeInclusionFilter( Collection::mimeType() );

  treeview->setModel(collectionTree);

  // SelectionProxyModel can handle complex selections:
  treeview->setSelectionMode(QAbstractItemView::ExtendedSelection);

  SelectionProxyModel *selProxy = new SelectionProxyModel(treeview->selectionModel(), this);
  selProxy->setSourceModel(etm);

  EntityTreeView *selView = new EntityTreeView(splitter);
  selView->setModel(selProxy);
@endcode

\image html selectionproxymodelsimpleselection.png "A Selection in one view creating a model for use with another view."

The SelectionProxyModel can handle complex selections.

\image html selectionproxymodelmultipleselection.png "Non-contiguous selection creating a new simple model in a second view."

If an index and one or more of its descendants are selected, only the top-most selected index (including all of its descendants) are included in the proxy model. (Though this is configurable. See below)

\image html selectionproxymodelmultipleselection-withdescendant.png "Selecting an item and its descendant."

SelectionProxyModel allows configuration using the methods setStartWithChildTrees, setOmitDescendants, setIncludeAllSelected. See testapp/proxymodeltestapp to try out the 5 valid configurations.

Obviously, the SelectionProxyModel may be used in a view, or further processed with other proxy models. See the example_contacts application for example which uses a further DescendantEntitiesProxyModel and MimeTypeFilterProxyModel on top of a SelectionProxyModel.

The SelectionProxyModel orders its items in the same top-to-bottom order as they appear in the source model. Note that this order may be different to the order in the selection model if there is a QSortFilterProxyModel between the selection and the source model.

\image html selectionproxymodel-ordered.png "Ordered items in the SelectionProxyModel"

A different view can also be used with the model, such as a QColumnView. However this does not work because QColumnView does not listen to signals from the model (http://www.qtsoftware.com/developer/task-tracker/index_html?id=246999&method=entry).

@code
// ... Create an EntityTreeModel
view = new QColumnView(this);
view->setModel(entityTree);
@endcode

Work is also started on time based proxy models so that Items containing calendar data can be represented in a table.

<h2>Jobs and Monitors</h2>

The lower level way to interact with Akonadi is to use Jobs and Monitors (This is what models use internally). Jobs are used to make changes to akonadi, and in some cases (eg, a fetch job) emit a signal with data resulting from the job. A Monitor reports changes made to the data stored in Akonadi (eg, creating, updating, deleting or moving an item or collection ) via signals.

Typically, an application will configure a monitor to report changes to a particular Collection, mimetype or resource, and then connect to the signals it emits.

Most applications will use some of the low level api for actions unrelated to a model-tree view, such as creating new items and collections.

<h2>Tricky details</h2>

<h3>Change Conflicts</h3>
It is possible that while an application is editing an item, that item gets updated in akonadi. Akonadi will notify the application that that item has changed via a Monitor signal. It is the responsibility of the application to handle the conflict by for example offering the user a dialog to resolve it. Alternatively, the application could ignore the dataChanged signal for that item, and will get another chance to resolve the conflict when trying to save the result back to akonadi. In that case, the ItemModifyJob will fail and report that the revision number of the item on the server differs from its revision number as reported by the job. Again, it is up to the application to handle this case.

This is something that every application using akonadi will have to handle.

<h3>Using Entity::Id as an identifier</h3>

Items and Collections have a id() member which is a unique identifier used by akonadi. It can be useful to use the id() as an identifier when storing Collections or Items.

However, as an item and a collection can have the same id(), if you need to store both Collections and Items together by a simple identifier, conflicts can occur.

@code
  QString getRemoteIdById( Entity::Id id )
  {
    // Note:
    // m_items is QHash<Entity::Id, Item>
    // m_collections is QHash<Entity::Id, Collection>
    if ( m_items.contains( id ) )
    {
      // Oops, we could accidentally match a collection here.
      return m_items.value( id ).remoteId();
    } else if ( m_collections.contains( id ) )
    {
      return m_collections.value( id ).remoteId();
    }
    return QString();
  }
@endcode

In this case, it makes more sense to use a normal qint64 as the internal identifier, and use the sign bit to determine if the identifier refers to a Collection or an Item. This is done in the implementation of EntityTreeModel to tell Collections and Items apart.

@code
  QString getRemoteIdByInternalIdentifier( qint64 internalIdentifier )
  {
    // Note:
    // m_items is QHash<Entity::Id, Item>
    // m_collections is QHash<Entity::Id, Collection>

    // If the id is negative, it refers to an Item
    // Otherwise it refers to a Collection.

    if ( internalIdentifier < 0 )
    {
      // Reverse the sign of the id before using it.
      return m_items.value( internalIdentifier * -1 ).remoteId();
    } else
    {
      return m_collections.value( internalIdentifier ).remoteId();
    }
  }
@endcode

<h3>Unordered Lists</h3>
Collection and Item both provide a ::List to represent groups of objects. However the objects in the list are usually not ordered in any particular way, even though the API provides methods to work with an ordered list. It makes more sense to think of it as a Set instead of a list in most cases.

For example, when using an ItemFetchJob to fetch the items in a collection, the items could be in any order when returned from the job. The order that a Monitor emits notices of changes is also indeterminate. By using a Transaction however, it is sometimes possible to retrieve objects in order. Additionally, using s constructor overload in the CollectionFetchJob it is possible to retrieve collections in a particular order.

@code
  Collection::List getCollections(QList<Collection::Id> idsToGet)
  {
    Collection::List getList;
    foreach(Collection::Id id, idsToGet)
    {
      getList << Collection(id);
    }
    CollectionFetchJob *job = CollectionFetchJob(getList);
    if (job->exec())
    {
       // job->collections() is in the same order as the ids in idsToGet.
    }
  }

@endcode


<h3>Be careful when fetching collections recursively</h3>
Collections could be returned in multiple signal calls and out of order.

@TODO: more info.


<h2>Resources</h2>
The KDEPIM module includes resources for handling many types of PIM data, such as imap email, vcard files and vcard directories, ical event files etc. These cover many of the sources for your PIM data, but in the case that you need to use data from another source (for example a website providing a contacts storage service and an api), you simply have to write a new resource.

http://techbase.kde.org/Development/Tutorials/Akonadi/Resources

<h2>Serializers</h2>
Serializers provide the functionality of converting raw data, for example from a file, to a strongly typed object of PIM data. For example, the addressee serializer reads data from a file and creates a KABC::Addressee object.

New serializers can also easily be written if the data you are dealing with is not one of the standard PIM data types.

<h1>Implementation details</h1>

<h3>Updating Akonadi Models</h3>

@note The details here are only relevant if you are writing a new view using EntityTreeModel, or writing a new model.

Because communication with akonadi happens asynchronously, and the models only hold a cached copy of the data on the akonadi server, some typical behaviours of models are not followed by Akonadi models.

For example, when setting data on a model via a view, most models syncronously update their internal store and notify akonadi to update its view of the data by returning <tt>true</tt>.

@dot
digraph utmg {
    rankdir = LR;
    { node [label="",style=invis, height=0, width=0 ];
      V_Set_Data; V_Result; V_Data_Changed;
      M_Set_Data; M_Result;
    }
    { node [shape=box, fillcolor=lightyellow, style=filled,fontsize=26];
      View [label=":View"]; Model [label=":Model"];
    }
    { node [style=invis];
      View_EOL; Model_EOL;
    }
    {
      V_Set_Data -> M_Set_Data [label="Set Data"];
      M_Result -> V_Result [label="Success",arrowhead="vee", style="dashed"];
      V_Result -> V_Data_Changed [label="Update View \n[ Success = True ]"];
    }

    // Dashed Vertical lines for object lifetimes.
    edge [style=dashed, arrowhead=none];
    { rank = same; View -> V_Set_Data -> V_Result -> V_Data_Changed -> View_EOL; }
    { rank = same; Model -> M_Set_Data -> M_Result -> Model_EOL; }

    // Make sure top nodes are in a straight line.
    { View -> Model [style=invis]; }
    // And the bottom nodes.
    { View_EOL -> Model_EOL [style=invis]; }
}
@enddot

Akonadi models only cache data from the akonadi server. To update data on an Akonadi::Entity stored in a model, the model makes a request to the akonadi server to update the model data. At that point the data cached internally in the model is not updated, so <tt>false</tt> is always returned from setData. If the request to update data on the akonadi server is successful, an Akonadi::Monitor notifies the model that the data on that item has changed. The model then updates its internal data store and notifies the view that the data has changed. The details of how the Monitor communicates with akonadi are omitted for clarity.

@dot
digraph utmg {
    rankdir = LR;
    { node [label="",style=invis, height=0, width=0 ];
      ETV_Set_Data; ETV_Result; ETV_Data_Changed;
      ETM_Set_Data; ETM_Result; ETM_Changed;
      M_Dummy_1; M_Changed;
      AS_Modify;
    }
    { node [shape=box, fillcolor=lightyellow, style=filled,fontsize=26];
      EntityTreeView [label=":View"]; EntityTreeModel [label=":Model"]; Monitor [label=":Monitor"]; Akonadi_Server [label=":Akonadi"];
    }
    { node [style=invis];
      EntityTreeView_EOL; EntityTreeModel_EOL; Monitor_EOL; Akonadi_Server_EOL;
    }
    {
      { rank = same; ETV_Set_Data -> ETM_Set_Data [label="Set Data"]; }
      { rank = same; ETM_Result -> ETV_Result [label="False",arrowhead="vee", style="dashed"]; }
      { rank = same; ETM_Result -> M_Dummy_1 [style=invis]; }
      { rank = same; ETM_Set_Data -> AS_Modify [arrowhead="vee",taillabel="Modify Item", labeldistance=14.0, labelangle=10]; }
      { rank = same; M_Changed -> ETM_Changed [arrowhead="vee",label="Item Changed"]; }
      { rank = same; ETM_Changed -> ETV_Data_Changed [arrowhead="vee",label="Update View"]; }
    }

    // Dashed Vertical lines for object lifetimes.
    edge [style=dashed, arrowhead=none];
    { rank = same; EntityTreeView -> ETV_Set_Data -> ETV_Result -> ETV_Data_Changed -> EntityTreeView_EOL; }
    { rank = same; EntityTreeModel -> ETM_Set_Data -> ETM_Result -> ETM_Changed -> EntityTreeModel_EOL; }
    { rank = same; Monitor -> M_Dummy_1 -> M_Changed -> Monitor_EOL; }
    { rank = same; Akonadi_Server -> AS_Modify -> Akonadi_Server_EOL; }

    // Make sure top nodes are in a straight line.
    { EntityTreeView -> EntityTreeModel -> Monitor -> Akonadi_Server [style=invis]; }
    // And the bottom nodes.
    { EntityTreeView_EOL -> EntityTreeModel_EOL -> Monitor_EOL -> Akonadi_Server_EOL [style=invis]; }
}
@enddot

Similarly, in drag and drop operations, most models would update an internal data store and return <tt>true</tt> from dropMimeData if the drop is successful.

@dot
digraph utmg {
    rankdir = LR;
    { node [label="",style=invis, height=0, width=0 ];
      Left_Phantom; Left_Phantom_DropEvent;
      V_DropEvent; V_Result; V_Data_Changed; V_Dummy_1;
      M_DropMimeData; M_Result;
    }
    { node [shape=box, fillcolor=lightyellow, style=filled,fontsize=26];
      View [label=":View"]; Model [label=":Model"];
    }
    { node [style=invis];
       Left_Phantom_EOL;
       View_EOL; Model_EOL;
    }
    {
      Left_Phantom_DropEvent -> V_DropEvent [label="DropEvent"];
      V_DropEvent -> M_DropMimeData [label="DropMimeData"];
      M_Result -> V_Result [label="Success",arrowhead="vee", style="dashed"];
      V_Result -> V_Data_Changed [label="Update View \n[Success = True]"];
    }

    // Dashed Vertical lines for object lifetimes.
    edge [style=dashed, arrowhead=none];
    { rank = same; View -> V_DropEvent -> V_Result -> V_Dummy_1 -> V_Data_Changed -> View_EOL; }
    { rank = same; Model -> M_DropMimeData -> M_Result -> Model_EOL; }

    //Phantom line
    { rank= same; Left_Phantom -> Left_Phantom_DropEvent -> Left_Phantom_EOL [style=invis]; }

    // Make sure top nodes are in a straight line.
    {  Left_Phantom -> View -> Model [style=invis]; }
    // And the bottom nodes.
    {  Left_Phantom_EOL ->  View_EOL -> Model_EOL [style=invis]; }
}

@enddot

Akonadi models, for the same reason as above, always return false from dropMimeData. At the same time a suitable request is sent to the akonadi server to make the changes resulting from the drop (for example, moving or copying an entity, or adding a new entity to a collection etc). If that request is successful, the Akonadi::Monitor notifies the model that the data is changed and the model updates its internal store and notifies the view that the model data is changed.

@dot

digraph utmg {
    rankdir = LR;
    { node [label="",style=invis, height=0, width=0 ];
      Left_Phantom; Left_Phantom_DropEvent;
      ETV_DropEvent; ETV_Result; ETV_Data_Changed;
      ETM_DropMimeData; ETM_Result; ETM_Changed;
      M_Dummy_1; M_Changed;
      AS_Modify;
    }
    { node [shape=box, fillcolor=lightyellow, style=filled,fontsize=26];
      EntityTreeView [label=":View"];
      EntityTreeModel [label=":Model"];
      Monitor [label=":Monitor"];
      Akonadi_Server [label=":Akonadi"];
    }
    { node [style=invis];
      Left_Phantom_EOL;
      EntityTreeView_EOL; EntityTreeModel_EOL; Monitor_EOL; Akonadi_Server_EOL;
    }

    {
      { rank = same; Left_Phantom_DropEvent -> ETV_DropEvent [label="DropEvent"]; }
      { rank = same; ETV_DropEvent -> ETM_DropMimeData [label="Drop MimeData"]; }
      { rank = same; ETM_Result -> ETV_Result [label="False",arrowhead="vee", style="dashed"]; }
      { rank = same; ETM_Result -> M_Dummy_1 [style=invis]; }
      { rank = same; ETM_DropMimeData -> AS_Modify [arrowhead="vee",taillabel="Action", labeldistance=14.0, labelangle=10]; }
      { rank = same; M_Changed -> ETM_Changed [arrowhead="vee",label="Item Changed"]; }
      { rank = same; ETM_Changed -> ETV_Data_Changed [arrowhead="vee",label="Update View"]; }
    }

    // Dashed Vertical lines for object lifetimes.
    edge [style=dashed, arrowhead=none];
    { rank = same; EntityTreeView -> ETV_DropEvent -> ETV_Result -> ETV_Data_Changed -> EntityTreeView_EOL; }
    { rank = same; EntityTreeModel -> ETM_DropMimeData -> ETM_Result -> ETM_Changed -> EntityTreeModel_EOL; }
    { rank = same; Monitor -> M_Dummy_1 -> M_Changed -> Monitor_EOL; }
    { rank = same; Akonadi_Server -> AS_Modify -> Akonadi_Server_EOL; }

    //Phantom line
    { rank= same; Left_Phantom -> Left_Phantom_DropEvent -> Left_Phantom_EOL [style=invis]; }

    // Make sure top nodes are in a straight line.
    { Left_Phantom -> EntityTreeView -> EntityTreeModel -> Monitor -> Akonadi_Server [style=invis]; }
    // And the bottom nodes.
    { Left_Phantom_EOL -> EntityTreeView_EOL -> EntityTreeModel_EOL -> Monitor_EOL -> Akonadi_Server_EOL [style=invis]; }
}


@enddot


*/