[Kde-pim] Akonadi::ResourceSelectJob - why is it private?

[David Jarvie]

On Wednesday 19 Mar 2014 11:43:27 Daniel Vrátil wrote:
> On Tuesday 18 of March 2014 14:27:51 David Jarvie wrote:
> > The API documentation for ItemDeleteJob says that if a remote ID is
> > specified, ResourceSelectJob or CollectionSelectJob need to be called first
> > to set the context for the ItemDeleteJob. Unfortunately, both of those
> > SelectJob classes are private, and therefore aren't available to
> > applications, so the documentation is somewhat misleading.
> 
> ItemDeleteJob uses CollectionSelectJob internally when you use the 
> ItemDeleteJob(const Akonadi::Collection &) ctor, but see below.
> 
> > Is there a good reason for this (e.g. could it unintentionally set the
> > context for internal library functions)? It effectively means that
> > ItemDeleteJob can't be used in applications if only the item's remote ID is
> > specified.
> 
> Server permits operations with RID sets only to Resources. Client applications 
> are not allowed to use RIDs. in Frameworks I want to change the behavior so 
> that RID is only exposed to resources and is  not exposed to client 
> applications at all. This answers your question why CollectionSelectJob is 
> private - it has no use outside ItemFetchJob and ItemDeleteJob, which use it 
> when appropriate (i.e.e Collection-wide or RID-based operations).

Thanks. I would question the desirability of prohibiting clients from using RID operations, though. The RID is the only identifier in an event (to take one example) which is fixed, and won't change if the Akonadi database is rebuilt. I have a particular use case in KAlarm where the RID is needed. A KAlarm event can optionally be copied to KOrganizer's calendar. When that event is deleted in KAlarm, the KOrganizer copy is also deleted. The only way that KAlarm can identify KOrganizer's copy of the event is by the fact that its UID (which is used as the RID) has a known relationship to the UID of KAlarm's event. If RIDs are hidden from clients, this operation will as far as I can see become impossible.

Essentially this use of UIDs/RIDs is an extension of the standard iCalendar features which allow linkage of events within an individual calendar, and instead allows linkage across different calendars.

> ResourceSelectJob is private because when you use it, the session is switched 
> into sort of a "privileged' mode on the server, which changes behavior of 
> certain operations a little, like permitting RID operations, etc. that are 
> specific to resources. You don't want to switch your application's session 
> into this mode.

Ok.

> So the documentation should be updated not to mention the Select jobs  and 
> instead explain that RID-based fetch and removal can only be used from 
> Resources. 

I'd like to put these references into an @internal section of the API comments, but unfortunately the @internal doxygen tag has no effect when the online API documentation is generated. Ideally this would highlight the relevant parts of the documentation as being for internal use, but it looks as if doxygen only provides the option to exclude internal comments from the generated documentation. Perhaps the references could be retained, but text added to mention that they are for internal use only?

Cheers,
David.

-- 
David Jarvie.
KDE developer.
KAlarm author -- http://www.astrojar.org.uk/kalarm
_______________________________________________
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/