Akonadi::ItemModifyJob Class Reference

#include <itemmodifyjob.h>

Inheritance diagram for Akonadi::ItemModifyJob:

Public Member Functions
	ItemModifyJob (const Item &item, QObject *parent=0)
	ItemModifyJob (const Item::List &items, QObject *parent=0)
virtual	~ItemModifyJob ()
void	disableAutomaticConflictHandling ()
void	disableRevisionCheck ()
bool	ignorePayload () const
Item	item () const
Item::List	items () const
void	setIgnorePayload (bool ignore)
void	setUpdateGid (bool update)
bool	updateGid () const
Public Member Functions inherited from Akonadi::Job
	Job (QObject *parent=0)
virtual	~Job ()
virtual QString	errorString () const
void	start ()

Protected Member Functions
virtual void	doHandleResponse (const QByteArray &tag, const QByteArray &data)
virtual void	doStart ()
Protected Member Functions inherited from Akonadi::Job
virtual bool	addSubjob (KJob *job)
virtual bool	doKill ()
void	emitWriteFinished ()
virtual bool	removeSubjob (KJob *job)

Additional Inherited Members
Public Types inherited from Akonadi::Job
enum	Error {   ConnectionFailed = UserDefinedError, ProtocolVersionMismatch, UserCanceled, Unknown,   UserError = UserDefinedError + 42 }
typedef QList< Job * >	List
Signals inherited from Akonadi::Job
void	aboutToStart (Akonadi::Job *job)
void	writeFinished (Akonadi::Job *job)
Protected Slots inherited from Akonadi::Job
virtual void	slotResult (KJob *job)

Detailed Description

Job that modifies an existing item in the Akonadi storage.

This job is used to writing back items to the Akonadi storage, after the user has changed them in any way. For performance reasons either the full item (including the full payload) can written back or only the meta data of the item.

Example:

// Fetch item with unique id 125
Akonadi::ItemFetchJob *fetchJob = new Akonadi::ItemFetchJob( Akonadi::Item( 125 ) );
connect( fetchJob, SIGNAL(result(KJob*)), SLOT(fetchFinished(KJob*)) );

...

MyClass::fetchFinished( KJob *job )
{
  if ( job->error() )
    return;

  Akonadi::ItemFetchJob *fetchJob = qobject_cast<Akonadi::ItemFetchJob*>( job );

  Akonadi::Item item = fetchJob->items().first();

  // Set a custom flag
  item.setFlag( "\GotIt" );

  // Store back modified item
  Akonadi::ItemModifyJob *modifyJob = new Akonadi::ItemModifyJob( item );
  connect( modifyJob, SIGNAL(result(KJob*)), SLOT(modifyFinished(KJob*)) );
}

MyClass::modifyFinished( KJob *job )
{
  if ( job->error() )
    qDebug() << "Error occurred";
  else
    qDebug() << "Item modified successfully";
}

Conflict Resolution

When the job is executed, a check is made to ensure that the Item contained in the job is not older than the version of the Item already held in the Akonadi database. If it is older, a conflict resolution dialog is displayed for the user to choose which version of the Item to use, unless disableAutomaticConflictHandling() has been called to disable the dialog, or disableRevisionCheck() has been called to disable version checking altogether.

The item version is checked by comparing the Item::revision() values in the job and in the database. To ensure that two successive ItemModifyJobs for the same Item work correctly, the revision number of the Item supplied to the second ItemModifyJob should be set equal to the Item's revision number on completion of the first ItemModifyJob. This can be obtained by, for example, calling item().revision() in the job's result slot.

Author

Volker Krause vkrau.nosp@m.se@k.nosp@m.de.or.nosp@m.g

Definition at line 97 of file itemmodifyjob.h.

Constructor & Destructor Documentation

ItemModifyJob::ItemModifyJob ( const Item &  item, QObject *  parent = 0  )

explicit

Creates a new item modify job.

Parameters

item	The modified item object to store.
parent	The parent object.

Definition at line 160 of file itemmodifyjob.cpp.

Akonadi::ItemModifyJob::ItemModifyJob ( const Item::List &  items, QObject *  parent = 0  )

explicit

Creates a new item modify job for bulk modifications.

Using this is different from running a modification job per item. Use this when applying the same change to a set of items, such as a mass-change of item flags, not if you just want to store a bunch of randomly modified items.

Currently the following modifications are supported:

• flag changes

Note

Since this does not do payload modifications, it implies setIgnorePayload( true ) and disableRevisionCheck().

Parameters

items

The list of items to modify, must not be empty.

Since

4.6

ItemModifyJob::~ItemModifyJob ( )

virtual

Destroys the item modify job.

Definition at line 190 of file itemmodifyjob.cpp.

Member Function Documentation

void ItemModifyJob::disableAutomaticConflictHandling

(

)

Disables the automatic handling of conflicts.

By default the item modify job will bring up a dialog to resolve a conflict that might happen when modifying an item. Calling this method will avoid that and the job returns with an error in case of a conflict.

Since

4.6

Definition at line 458 of file itemmodifyjob.cpp.

void ItemModifyJob::disableRevisionCheck

(

)

Disables the check of the revision number.

Note

If disabled, no conflict detection is available.

Definition at line 451 of file itemmodifyjob.cpp.

void ItemModifyJob::doHandleResponse ( const QByteArray &  tag, const QByteArray &  data  )

protectedvirtual

This method should be reimplemented in the concrete jobs in case you want to handle incoming data.

It will be called on received data from the backend. The default implementation does nothing.

Parameters

tag	The tag of the corresponding command, empty if this is an untagged response.
data	The received data.

Reimplemented from Akonadi::Job.

Definition at line 321 of file itemmodifyjob.cpp.

void ItemModifyJob::doStart ( )

protectedvirtual

This method must be reimplemented in the concrete jobs.

It will be called after the job has been started and a connection to the Akonadi backend has been established.

Implements Akonadi::Job.

Definition at line 294 of file itemmodifyjob.cpp.

bool ItemModifyJob::ignorePayload

(

)

const

Returns whether the payload of the modified item shall be omitted from transmission to the Akonadi storage.

Definition at line 428 of file itemmodifyjob.cpp.

Item ItemModifyJob::item

(

)

const

Returns the modified and stored item including the changed revision number.

Note

Use this method only when using the single item constructor.

Definition at line 465 of file itemmodifyjob.cpp.

Item::List ItemModifyJob::items

(

)

const

Returns the modified and stored items including the changed revision number.

Since

4.6

Definition at line 473 of file itemmodifyjob.cpp.

void ItemModifyJob::setIgnorePayload

(

bool

ignore

)

Sets whether the payload of the modified item shall be omitted from transmission to the Akonadi storage.

The default is false, however it can be set for performance reasons.

Parameters

ignore

ignores payload if set as true

Definition at line 411 of file itemmodifyjob.cpp.

void ItemModifyJob::setUpdateGid

(

bool

update

)

Sets whether the GID shall be updated either from the gid parameter or by extracting it from the payload.

The default is false to avoid unecessarily update the GID, as it should never change once set, and the ItemCreateJob already sets it.

Parameters

update

update the GID if set as true

Note

If disabled the GID will not be updated, but still be used for identification of the item.

Since

4.12

Definition at line 435 of file itemmodifyjob.cpp.

bool ItemModifyJob::updateGid

(

)

const

Returns wheter the GID should be updated.

Since

4.12

Definition at line 445 of file itemmodifyjob.cpp.

---

The documentation for this class was generated from the following files:

• itemmodifyjob.h
• itemmodifyjob.cpp