[Kde-pim] Akonadi::ResourceBase - API questions

[Volker Krause]

On Sunday 13 May 2007 13:20:59 Brad Hards wrote:
> I've been looking at Akonadi with the view to making a microsoft exchange
> resource (based on http://www.openchange.org) - no promises though...
>
> I have a few comments/questions that others may be able to help me with.
> These are in relation to ResourceBase, which is the class I guess I'm meant
> to inherit from.

I have updated the API docs during the last days to hopefully better address 
your points.

> 1. It seems a bit strange for Akonadi::ResourceBase to inherit from
> Akonadi::Resource. What is the rationale for this?

As Tobias already noted, renaming Resource to ResourceInterface might be a 
good idea. I'm not sure if we want to keep the inheritance to avoid having 
the external interface in ResourceBase which is confusing, see below.

> 2. The method naming seems a bit strange in a couple of places. For
> example, I expected that the method to add an Item to a Collection would be
> called addItem(). If I'm understanding the code correctly, it is called
> itemAdded(), which feels like a signal that would be emitted. I think I
> understand the logic, but the name should still be with respect to the
> resource, not Akonadi as a whole. Same issue for itemChanged, itemRemoved,
> collectionAdded, collectionChanged, collectionRemoved.

clarified in the docs:
http://www.englishbreakfastnetwork.org/apidocs/apidox-kde-4.0/kdepim-apidocs/akonadi/libakonadi/html/classAkonadi_1_1ResourceBase.html

> 3. changeProgress() and changeStatus() are unexpected - should be
> setProgress() and setStatus().

agreed

> 4. enableChangeRecording() sounds like something that turns on revision
> recording. From the API documentation it is meant to temporarily queue up
> changes to the backend - if so, it should be called something
> enableChangeQueuing() or deferChanges(). I'm still not sure how this
> differs from the online/offline idea?

this should not be in the public API at all I think

> 5. I'm not sure what the "partIdentifiers" argument to itemChanged() is
> intended to do. Any suggestions?

added to the docs:
http://www.englishbreakfastnetwork.org/apidocs/apidox-kde-4.0/kdepim-apidocs/akonadi/html/akonadi_concepts.html#akonadi_concepts_items

> 6.. status() returns an int. The apidox says the possible return values are
> 0, 1 or 2. If so, why does it not return the Status enum type?
>
> 7. collectionAdded(), collectionChanged() and collectionRemoved() are
> inline and virtual, which looks a bit strange.

I guess they should be pure virtual instead and there should be a convenience 
base class for collection-less resources which implements those to emit an 
error.

> 8. Noting my concerns about how to tell the difference between
> enableChangeRecording() and setOnline(), why isn't setOnline a slot?

Right, I guess it has to be a slot as it's part of the DBus interface.

> 9. the knut resource has this function:
> virtual bool requestItemDelivery( const Akonadi::DataReference &ref, int
> type, const QDBusMessage &msg )
> while the ResourceBase has this:
> virtual bool requestItemDelivery( int uid, const QString &remoteId, int
> type );
> Are these related?

That's the problem with mixing the external interface and the internal 
interface in ResourceBase, see above.
requestITemDelivery( DataReference, int, QDBusMessage ) needs to be 
reimplemented to fetch the actual data in case it's not yet cached in the 
Akonadi server.
This still need to be clarified in the docs. Also, the int type parameter 
should rather be QString partIdentifier.

Thanks for the feedback, it really helps to make sure we have an easy to use 
API :)

regards
Volker

-------------- next part --------------
A non-text attachment was scrubbed...
Name: signature.asc
Type: application/pgp-signature
Size: 189 bytes
Desc: This is a digitally signed message part.
URL: <http://mail.kde.org/pipermail/kde-pim/attachments/20070521/cedb5f72/attachment.sig>
-------------- next part --------------
_______________________________________________
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/