[Kde-pim] Re: How Resources and Collections play together

[Stephen Kelly]

At the risk of adding to the confusion I'm going to add my piece here.

There are several angles that you need to think in when you create an 
Akonadi based application. There are resources, the akonadi server in the 
middle which controls the resources, and the applications, which interact 
with the server only, not directly with the resources.

Usually, applications work with the akonadi server and collections and 
items, not directly with resources. Applications will create, configure and 
remove resources, but not directly tell them to do anything with collections 
or items. If applications want to use an ical file, it asks the server to 
create a new ical resource for it, and configures it to point to the file. 
The resource will then create a top level collection and notify Akonadi 
about that, and then Akonadi notifies applications about that through a 
Monitor notification. 

The resource will also populate the top-level collection with any items in 
the file. In more complicated resources like maildir there can be a 
heirarchy of collections each of which have items. The resource will create 
the collections and tell the akonadi server about them.

>From the application point of view it doesn't matter which resource the 
collections and items come from. Application get a list of collections with 
a CollectionFetchJob which will return all relevant collections based on the 
filter. The CollectionFetchJob filters based on whether you want all 
collections, or child collections of a particular collection, only top level 
collections, only collections which can contain items of particular 
mimetypes etc. 

Once you have a collection from the Akonadi server you can fetch the items 
in it. If there are two applications running, one of them might change an 
item or collection in some way. In that case, they send a modify job to 
Akonadi for the item or collection. Akonadi forwards that to the resource, 
which might report (to Akonadi) that the change was successful. At that 
point Akonadi notifies each listening application that the item was changed.

That much is probably all obvious already, but I wanted to make clear that 
applications generally deal with collections and items, and resources are 
responsible for executing the things the application requests.

The EntityTreeModel encapsulates a lot of that interaction for you.

Thomas McGuire wrote:

> Hi,
> 
> let me try to answer some questions I know about, others can fill in the
> blanks.
> 
> On Friday 14 January 2011 13:04:07 Christian Mollekopf wrote:
>> I'm a bit confused how akonadi resources and collections play together
>> exactly.
>> 
>> As far as I understand it, a collection is the akonadi internal
>> container. While the collection doesn't need a resource to exist

Actually it does. The resource manages the collections. There are a small 
number of special cases, such as search collections.

>> , a
>> resource is needed to make the link to the storage backend (filesystem,
>> google, etc.).

Yes, if an application asks Akonadi to create a collection (with an 
Akonadi::CollectionCreateJob), Akonadi delegates that work to the relevant 
resource, which might report that it can't create a new collection.

>> 
>> So if i want a new calendar I create a new calendar resource (not a
>> collection), which will in turn generate a new collection, associated
>> with the resource.
> 
> Yep.
> 
>> So I assume normally there is 1 resource with 1 associated collection,
>> but there can be special resources which have several collections.
> 
> Yes, correct. Quite a lot of resources have multiple collections.

Indeed. I don't think the ical file scheme of one file and one collection is 
the normal case. Akonadi is designed to handle heirarchies of collections 
with items. Usually resources only have one top-level collection though.

> 
>> What I need to know:
>> 
>> Is the resource responsible for creating/deleting the collections?

Yes. When an application runs a CollectionCreateJob (for example if the user 
clicks the 'New folder' button) it is interacting with Akonadi, which 
forwards the work to the responsible resource.

Here's what resources are responsible for:

* Listing collections - When a resource is created, akonadi might ask it 
what collectinos it has.
* Listing items in collections - Akonadi might ask a resource what items are 
in a collection.
* Notification of new items/collections - Resources need to notify about new 
stuff. That might happen 'spontaneously' inside the resource, for example if 
a filesystem watcher controlled by a maildir resource tells it that an item 
was deleted on the filesystem.
* Reacting to requests to create/remove/change items and collections - These 
requests come from Akonadi usually forwarded from an application. The 
resource attempts to complete the work and then reports success or failure 
to Akonadi. The result of that is that Akonadi will make the result 
available through the Job result (available to the application that started 
the job), and it will notify all applications though the Monitor API, if the 
monitor is configured to listen to such notifications. Because all changes 
are available through the Monitor, usually the EntityTreeModel ignores the 
result of the job (except for listing Jobs of course), and simply listens to 
Monitor notifications. That way it doesn't matter whether the ETM is in the 
calling application or any other.

> 
> Yes, the collections need to be created in
> ResourceBase::retrieveCollections()
> 
>> So as an application developer, do I always work with resources not
>> collections (speaking of creating/deleting toplevel
>> collections(respectively storage locations))?

For top-level collections, yes, you deal with resources. For everything not 
top level, you deal with collections through jobs. That's the plumbing at 
least. ETM provides some porcelain on top of that.

> 
> Not sure what you mean here. The API for applications can deal with
> collections and resources. Applications in general deal with collections
> more than with resources.
> 
>> If I want to make a dialog where the user can choose, where to store his
>> calendar files, is it ok to display a list of collections with the
>> mimetype which i need? Or should I somehow list the resources?
> 
> Listing the collections should be enough. There is
> Akonadi::CollectionDialog and Akonadi::CollectionComboBox for this
> already, btw.

Storing an item in a collections requires that the collection holds items of 
the right mimetype, that the collection is not hidden, that the user has the 
write right to add the item etc. As Thomas writes there are classes for  
presenting a listing of those to the user already.

> 
>> In the ChangeRecorder for the EntityTreemodel, should I rather watch the
>> collections or the resources? Whats the difference?

As I wrote above, the ETM listens to the ChangeRecorder (is-a Monitor) for 
changes to collections and items reported by Akonadi. The high level concept 
is that the ETM displays whatever the Monitor is monitoring. The Monitor is 
capable of monitoring groups of individual collections, groups of individual 
resources, all collections containing items of particular mimetypes, and 
also some Item related filtering.

So far in the KDE PIM applications the ChangeRecorder used by the ETM is 
always monitoring a particular mimetype, so collections matching that 
mimetype become part of the Model. The applications are generally interested 
in all available collections of that mimetype. Usually applications don't 
have to do anything other than configure the ChangeRecorder to monitor a 
particular mimetype.

A special case (used by the akonotes plasmoid) is to monitor a mimetype and 
a collection. That way, collections which match the mimetype AND are below 
the specified collection are part of the Model. That way you get a model of 
some sub-tree, and all the rest is ignored. Currently only one monitored 
top-level collection works. I saw you have a patch about that, but I haven't 
reviewed it yet.

Another special case is adding a resource explicitly to the ChangeRecorder. 
Some resources are hidden (search for example), but if explicitly monitored 
it will show up in the model.

So, to answer your question, you probably want to monitor particular 
mimetypes and Collection::root().

Something to keep in mind is that if you do that in your application you 
will get all available resources/collections/items matching notes and ical 
mimetypes, even those created/managed by kjots/korganizer. If you want some 
behaviour different to that there may be some work involved.

<snip trash talk>

All the best,

Steve.


_______________________________________________
KDE PIM mailing list kde-pim at kde.org
https://mail.kde.org/mailman/listinfo/kde-pim
KDE PIM home page at http://pim.kde.org/