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

[Daniel Vrátil]

On Wednesday 19 of March 2014 14:26:36 David Jarvie wrote:
> 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.

Christian has added GID for exactly this purpose in KDE 4.12. In case of 
events GID == RID (because both GID and RID are iCal UIDs), but in  emails for 
example GID == Message-Id and RID == IMAP UID.  

> 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?

+1

Dan

> 
> Cheers,
> David.

-- 
Daniel Vrátil | dvratil at redhat.com | dvratil on #kde-devel, #kontact, #akonadi
KDE Desktop Team
Associate Software Engineer, Red Hat, Inc.

GPG Key: 0xC59D614F6F4AE348
Fingerprint: 4EC1 86E3 C54E 0B39 5FDD B5FB C59D 614F 6F4A E348
-------------- next part --------------
A non-text attachment was scrubbed...
Name: signature.asc
Type: application/pgp-signature
Size: 490 bytes
Desc: This is a digitally signed message part.
URL: <http://mail.kde.org/pipermail/kde-pim/attachments/20140319/3b0d381e/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/