[prev in list] [next in list] [prev in thread] [next in thread] 

List:       kde-pim
Subject:    Re: [Kde-pim] Akonadi::ResourceSelectJob - why is it private?
From:       David Jarvie <djarvie () kde ! org>
Date:       2014-03-19 14:26:36
Message-ID: 201403191426.41465.djarvie () kde ! org
[Download RAW message or body]

On Wednesday 19 Mar 2014 11:43:27 Daniel Vr=E1til 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 f=
irst
> > 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 I=
D is
> > specified.
> =

> Server permits operations with RID sets only to Resources. Client applica=
tions =

> 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 i=
s =

> 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 tak=
e 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 e=
vent is deleted in KAlarm, the KOrganizer copy is also deleted. The only wa=
y that KAlarm can identify KOrganizer's copy of the event is by the fact th=
at its UID (which is used as the RID) has a known relationship to the UID o=
f KAlarm's event. If RIDs are hidden from clients, this operation will as f=
ar 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 swit=
ched =

> into sort of a "privileged' mode on the server, which changes behavior of =

> certain operations a little, like permitting RID operations, etc. that ar=
e =

> specific to resources. You don't want to switch your application's sessio=
n =

> into this mode.

Ok.

> So the documentation should be updated not to mention the Select jobs  an=
d =

> 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 comme=
nts, but unfortunately the @internal doxygen tag has no effect when the onl=
ine API documentation is generated. Ideally this would highlight the releva=
nt 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 gen=
erated documentation. Perhaps the references could be retained, but text ad=
ded 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@kde.org
https://mail.kde.org/mailman/listinfo/kde-pim
KDE PIM home page at http://pim.kde.org/
[prev in list] [next in list] [prev in thread] [next in thread]