[Kde-pim] Tomboy resource: Questions to the usage of KIO::KJob

[Daniel Vrátil]

On Friday, June 3, 2016 4:37:05 PM CEST Stefan Staeglich wrote:
> Hello,

Hi,

> 
> I'm developing a Akonadi resource for Tomboy servers like Grauphel[1]. I
> understand the basic stuff now, but in detail it's still complicated.
> 
> Daniel Vrátil suggested to use the KIO::KJob stuff. I've  tried to study
> this, but at the moments it's very complex for me. For now I only want to
> implement the basic things. For this we have the necessary following
> actions: - Register at the server
> - Retrieve all items (I want to use only one collection)
> - Get a specific item (full item data!)
> - Add a new item
> - Delete a item
> - Modify a item
> 
> My idea was to use the following KJob-Classes:
> - TomboyJobBase:
>   it should provide the full OAuth stuff using the library o2
> - TomboyServerAuthenticateJob:
>   It's needed for the configuration it should do the OAuth registration
> process getting the client credentials
> - TomboyItemsDownloadJob:
>   It should retrieve all items
> - TomboyItemDownloadJob:
>   It should get the specific item
> - TomboyItemUploadJob
>  It should can add, delete and modify a item
> 
> Eventually the class TomboyItemsDownloadJob needs additional classes for
> adding, deleting and modifying items in the Akonadi cache. But I'm not sure
> about this.

Interaction with the Akonadi cache should not happen in the Jobs, but in your 
TomboyResource (Akonadi::ResourceBase subclass).

> So what do you think about this? What base class should I use? KJob
> directly?

You probably want to subclass KCompositeJob, because that allows you to run 
nested job (i.e. start new KJobs inside your KCompositeJob subclass).

> What features I should use from KJob? So that I can add necessary data,
> start the job and can get the result?

The main feature that KJob gives you is simplification of the code as it does 
lots of work for you behind the scenes.  The only thing you need to care about 
is to reimplement start(), which is called automatically by KJob when the job 
starts, and when you want the job to finish, you just call emitResult(), which 
causes the KJob to emit result(KJob*) signal that you listen to elsewhere. 
There's also setError() and setErrorText() to report errors that occured in 
the job.

A supersimplified example of one of your jobs (without the OAuth 
authentication, error handling etc.)

class TomboyItemsDownloadJob : public TomboyJobBase
{
public
	// ctor
	TomboyItemsDownloadJob(QObject *parent);
	 // returns the parsed results wrapped in Akonadi::Item, see bellow
	Akonadi::Item::List items() const;
protected:
	// automatically called by KJob, here you start the HTTP request using
	// KIO::get (or KIO::stored_get) (see [0]) and connect onResult() (see 
	// bellow) to its result() signal
	void start() override;

private Q_SLOTS:
	// called when the KJob your created above via KIO::get finishes.
	// Read the data from the job, parse them, store the results and
	// call emitResult(), which will....well, emit result() signal
	void onResult(KJob *kjob);
};


The way you use the jobs in your Resource then would be

class TomboyResource : public Akonadi::ResourceBase
{
	void retrieveItems(const Collection &c)
	{
		// create the job
		auto job = new TomboyItemsDownloadJob(c.id(), this);
		// connect to its result() signal
		connect(job, &KJob::result,
			        this, &TomboyResource::onDownloadFinished);
	}

	void onDownloadFinished(KJob *kjob)
	{
		// get the job
		auto job = qobject_cast<TomboyItemsDownloadJob*>(kjob);
		// pass the items you retrieved to Akonadi
		itemsRetrieved(job->items());
	}
}

Passing the Items to ResourceBase (via itemsRetrived, or 
itemsRetrievedIncremental, if Tomboy has a way to perform incremental sync) is 
all you have to do, the ResourceBase will take care to store the 
Akonadi::Items in the Akonadi cache.

I recommend that you take a look at Google Contacts resource [1], which uses 
the Job pattern heavily, and at LibKGAPI [2], which implements the jobs 
(LibKGAPI does not use KJob, but the thing is modelled very closely after 
KJob, so you will get the idea. I will hopefully one day get off my lazy butt 
and port it to KJob....). 

Hope it helps,

Daniel

[0] https://api.kde.org/frameworks/kio/html/namespaceKIO.html
[1] https://quickgit.kde.org/?p=kdepim-runtime.git&a=blob&f=resources%2Fgoogle
%2Fcontacts%2Fcontactsresource.cpp
[2] https://quickgit.kde.org/?p=libkgapi.git&a=tree&f=src%2Fcontacts

> 
> Thanks,
> Stefan
> 
> [1] https://bugs.kde.org/show_bug.cgi?id=362938
> _______________________________________________
> 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/


-- 
Daniel Vrátil
www.dvratil.cz | dvratil at kde.org
IRC: dvratil on Freenode (#kde, #kontact, #akonadi, #fedora-kde)

GPG Key: 0x4D69557AECB13683
Fingerprint: 0ABD FA55 A4E6 BEA9 9A83 EA97 4D69 557A ECB1 3683
-------------- next part --------------
A non-text attachment was scrubbed...
Name: signature.asc
Type: application/pgp-signature
Size: 819 bytes
Desc: This is a digitally signed message part.
URL: <http://mail.kde.org/pipermail/kde-pim/attachments/20160603/1774043a/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/