[Kde-pim] Moving Entities in Akonadi

[Volker Krause]

On Tuesday 03 March 2009 14:38:49 Stephen Kelly wrote:
> Volker Krause wrote:
> > On Friday 27 February 2009 10:29:03 Stephen Kelly wrote:
> >> One of the pending features needed to build Akonadi applications is
> >> support for moving Entities between collections on the server, in
> >> resources, notifying other classes with the correct signals and
> >> providing Jobs to allow consumers of libakonadi to perform moves.
> >>
> >> Here's a list of things that are outstanding to get this finished. I
> >> think it's complete, but please add to it if you think of anything else.
> >
> > Excellent list about this problem!
> >
> >> 1) Jobs
> >> Applications need to be able to notify the server that an Entity is to
> >> be moved. This can be  achieved by using setParent and a EntityUpdateJob
> >> in the case of Collections. Reordering also needs to be updated with
> >> CollectionChildOrderAttribute. All this can possibly be encapsulated in
> >> an EntityMoveJob.
> >
> > There is a ItemMoveJob already, which is basically a convenience wrapper
> > around ItemModifyJob. I agree that we probably want the same for
> > collections.
>
> Oh yeah. I remember that now. Just need a CollectionMoveJob then,
>
> >> 2) Entity Ancestors
> >> As discussed in an earlier thread and at Osnabruck, Entities will need
> >> to have a list of the remoteIds of their ancestors in order to handle
> >> moves between collections correctly and reliably.
> >
> > This is probably the trickiest part to implement, as this touches quite
> > some places where we have to keep compatibility. Still, I think it's
> > possible and needed beyond just moving.
> >
> >> 3) Monitor Signals
> >> The server needs to emit signals through Monitor that a move has
> >> occurred. There are several different cases here. If an entity is moved
> >> within the
> >> same resource, the resource should  be able to react to the move. If an
> >> entity is moved between collections in different resources, one resource
> >> must react as if a remove operation occurred, and the other must react
> >> as if an insert occurred. Application-side classes listening to the
> >> Monitor should always consider moves as moves. Considering a move to
> >> always be separate insert and remove operations would break selections
> >> and persistent indexes in models for example.
> >
> > Makes sense, but breaks my current idea of solving this by emitting
> > add/delete signals for inter-resource moves and a move signal only for
> > intra-resource moves.
>
> Hmm, well I think resources should be invisible to applications, right? If
> your current idea remains, applications would have to be more aware that
> resources exist, and sometimes they get signals which are the result of a
> move, and sometimes it looks like a insert+delete, but is really a move
> between resources. I think that applications shouldn't have to be aware of
> resources at all. They should only be aware of a tree of Collections and
> Items. I think it would make it easier for applications if a move was
> always a move.

Right, splitting up move into add/delete on the resource side if necessary is 
indeed the better solution.

> >> To account for these, the signal emitted should contain a parameter for
> >> the identifiers of the source and destination resources. They would most
> >> likely be ignored by application side classes, but resources would have
> >> something like:
> >>
> >> @code
> >>
> >> void SomeResource::entityMoved(Entity entity, Collection src, Collection
> >> dest, const QString &srcResource, const QString &destResource)
> >> {
> >>   if (this->identifier() == srcResource)
> >>   {
> >>     if (this->identifier() == destResource)
> >>     {
> >>       // Handle the move within this resource
> >>       return;
> >>     }
> >>     // Handle removing entity from this resource.
> >>   } else if (this->identifier() == destResource)
> >>   {
> >>     // Handle inserting entity into this resource.
> >>   }
> >> }
> >>
> >> @endcode
> >
> > We might want to put that into ObserverV2 instead of into every resource.
>
> Good point. we could put it into a slotEntityMoved and call the virtual
> entity{Inserted,Removed,Moved} methods.
>
> >> As discussed in an earlier thread and at Osnabruck, Entities need to
> >> know a list of the remoteIds of their ancestors.
> >>
> >>
> >> 4) AgentBase::ObserverV2
> >> In order for resources to be able to react to the signals, we'll
> >> probably need to have an ObserverV2 to add virtual methods for concrete
> >> resources to override. I tried to do this before with a mixin class, but
> >> it didn't work for a reason I don't remember. An ObserverV2 would be a
> >> better solution anyway, because some parameters in existing signals (eg,
> >> Collection in ### TODO ) will probably not be necessary when Entity
> >> knows a list of its ancestors.
> >
> > The reason why we lack parent parameters for quite some signals, as well
> > as a parent() method in Item is that an item can be in multiple
> > collections, one "physical" one, owned by a resource, and many virtual
> > ones.
>
> Right. It looks like I never filled that TODO there :). My point was that
> in some signals, additional Collections are given as metadata.
>
> http://api.kde.org/4.x-api/kdepimlibs-
> apidocs/akonadi/html/classAkonadi_1_1AgentBase_1_1Observer.html
>
> For example, itemAdded has a collection in the signal. That might not be
> necessary if Item knows the remoteIds of its ancestor collections. It might
> be better API to remove them, seeing as we're adding an ObserverV2 anyway.
> Just something to review.

Right.

> > On the resource side this doesn't matter, which is why the remote id
> > ancestors solve all our problems there. I'm still unsure on what we need
> > API wise on the application side. There we have use cases like "monitor a
> > virtual collection for changes", for which we need to know all physical
> > and virtual parents of an item.
>
> Are you sure? I think all we'd need is to listen to the itemLinked and
> itemUnlinked signals from the monitor.

item[Un]Linked are the equivalent of itemAdded/Removed for non-virtual 
collections, that still leaves itemChanged() which so far comes without a 
collection context.

> I've been thinking a bit about virtual collections too. I'll post about it
> soon, because I have several questions from an application point of view.
>
> >> 5) Doing it in a branch?
> >> I might have missed something regarding moves, and there may be other
> >> missing pieces in Akonadi API that we'll only know about as we build
> >> real applications on top of it. I think we need some prototype
> >> applications which between them use all of the features of akonadi, so
> >> we don't end up needing an ObserverV3 or other virtual methods in
> >> another class. I know that KAddressManager is around somewhere, but I
> >> don't think it handles moves for example.
> >
> > I so far used akonadiconsole as a test application for stuff like this.
> > We can eg. easily add additional browser tabs with different models if
> > that helps. KContactManager might be able to do cut/paste already, thanks
> > to StandardActions, similar probably for dnd and the models. If not, we
> > should fix those I guess.
>
> Sure, I think dnd works, but what I mean is that we're still not certain
> what an akonadi application looks like and what it needs to react to etc.
> For now we know it would be hard for an application to react to a move
> because akonadi doesn't report moves yet. There may be other things that
> need BiC changes.

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/20090309/bed4fe3b/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/