KDE PIM/Akonadi/Trashhandling
The akonadi trashhandling are a couple of convenience classes, to make it easy for developers building on akonadi, to provide a trashbin in their application. It's also meant to standardize the way trashed items are handled among several applications using the same akonadi resources.
The uniform handling opens possibilities (which are not yet realized), like mapping the flags used to mark trash to remote locations (i.e. IMAP server), or creating a janitor agent which does automatic cleaning in a configured interval.
The trashhandling consists of the following parts:
TrashJob
Mark entity as trash with the EntityDeletedAttribute and moves it to a configured trash collection (if configured).
The default behaviour is to move the item to the trash collection which is configured in TrashSettings. If this trash collection is not available, the entity is kept in place.
All sub entites of a collection which is marked as trash are also marked as trash, and get the parent collection of the collection which was marked as trash as restore collection. This ensures that it is possible to restore items from trash, which were originally moved to trash together with the parent collection.
The job has also an option to automatically delete items which are already marked as trash.
RestoreJob
Restore the entity from the trash collection to the original collection and remove the EntityDeletedAttribute.
By default the RestoreJob tries to move the entity back to the original location, which is saved in the EntityDeletedAttribute. If this collection is not available anymore, it tries the original resource root as fallback, if also not available it aborts.
For this case it is possible to configure a special restore collection on the job, to which the item is restored.
If the move was successful the EntityDeletedAttribute is removed from the entity (and from all subentities).
EntityDeletedAttribute
Marks the entity as deleted and stores the restore collection/resource. Resources could map this flag to an appropriate flag as the MarkAsDeleted flag in IMAP.
TrashSettings
Store a trashcollection for a resource.
In the future further trash related settings, as the time before the janitor agent deletes items could be stored here.
TODO: atm. the settings are never removed. Even if the configured resource or trash collection is removed.
TrashFilterProxyModel
Either shows all items with the EntityDeletedAttribute or hides all entities with the EntityDeletedAttribute. It is using a KRecursiveProxyModel, so also trash items which are in a non trash collection are shown in the trash.
StandardActions
Provides 6 standard actions:
- MoveItemToTrash
- MoveCollectionToTrash
- RestoreItemFromTrash
- RestoreCollectionFromTrash
- MoveToTrashRestoreCollection
- MoveToTrashRestoreItem
While the first 4 are trivial, the last two provide a single action, which changes its behaviour depending if the EntityDeletedAttribute is set or not. As it doesn't make sense to restore entites which are not in trash or move entities to trash which are in trash, I believe it is the most common usecase and is what I use myself. All new actions need the EntityDeletedAttribute fetched in order to work properly. I had to add some bits to the internal structure of the standardactionmanager to make it possible to change description/icon/etc. for a single action, everything existing should continue to work as expected though.
Trash Janitor Agent (TODO)
Goes trough all collections, and deletes items after a configured period of time, if they are marked as trash. This configuration is in TrashSettings on a per resource basis, but could be overridden by a configuration in the EntityDeletedAttribute
This is not work in progress atm. but more a concept. I also don't plan to add this anytime soon, so feel free to do it if you need it now.