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

[Stefan Staeglich]

Hello Dan,

I have now implemented the classes like you suggested. But the Jobs don't 
seems to be started. What could be the problem?

Thanks,
Stefan

Am Freitag, 3. Juni 2016, 17:19:48 schrieb 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/
_______________________________________________
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/