DataQuery

Since: BlackBerry 10.2.0

#include <bb/cascades/datamanager/DataQuery>

To link against this class, add the following line to your .pro file: LIBS += -lbbcascadesdatamanager

Retrieve data for a particular view of a data source.

This supports concepts like keys, overall revisions, item revisions and partial caching (using offset and limit) so that data models can use this to maintain a window of data in memory (the cache) consistent with a potentially much larger overall set of data in persistent storage.

In implementing this class, the developer must make decisions about how to handle error conditions. If there are SQL or other expected or unexpected runtime errors, the developer must determine which of these errors are catastrophic and which are recoverable.

Catastrophic errors can be dealt with by these steps:
  • Connect the application to the data query error signal

  • Query issues an error signal and returns false

  • Application detects that the error is unrecoverable

  • Application informs the users of the issue and remedies (if any)

  • User is instructed to terminate the application

Recoverable errors may be dealt with in a few ways. It may depend on whether the data is required or optional for the application to function. It may depend on whether retries might be effective, either immediately, after a certain elapsed timed or when the user wishes to trigger a retry.

For Query-handled recoverable errors, the steps may look like this:
  • Query detects an error and performs a finite number (N) of retries

  • If retry is successful then query returns true

  • If N retries fail then query emits an error and returns false

  • Application informs the users of the issue and remedies (if any)

  • User is instructed to ignore the error (if optional data) or to terminate the application

For Application-handled recoverable errors, the steps may look like this:
  • Connect the application to the data query error signal

  • Query issues an error signal and returns false

  • Application detects that the error is recoverable

  • Application informs the users of the issue and remedies (if any)

  • User is instructed to initiate retries or ignore the error (if optional data) or to terminate the application

To trigger a retry for a recoverable error use one of these methods:
  • Emit the DataQuery::dataChanged(Revision) signal.

  • Call the model load() method.


Overview

Public Functions Index

DataQuery (QObject *parent=0)
virtual ~DataQuery ()
boolgetData (int offset, int limit, DataRevision *revision, int *totalCount, QList< DataItem > *results)=0
boolgetDataForRevision (int offset, int limit, const DataRevision &requestedRevision, QList< DataItem > *results)=0
QStringtoString () const =0

Signals Index

voiddataChanged (DataRevision revision)
voiderror (int code, const QString &message)

Public Functions

DataQuery (

Constructor.

Parameters
parent

The parent owner or 0. Optional and will default to 0 if not specified.

Since:

BlackBerry 10.2.0

virtual~DataQuery ()

Destructor.

Since:

BlackBerry 10.2.0

bool getData (

Fetch the overall revision, total count and a range of data items from the data source.

This is a synchronous call, but it must be possible to safely call this method from any thread.

See the discussion about error handling in the class description. A return of false by this method should be both:
  • preceeded by the query emitting an error signal

  • application-level handling of the error signal leading to some appropriate action

Parameters
offset

The index offset within the view.

limit

The number of items to retrieve.

revision

the current revision of the data source. The revision value must match the state of the data items that are returned. Pointer must not be null.

totalCount

The total number of items in the view. Pointer must not be null.

results

The list of data items which is the return data. Pointer must not be null.

Return:

Returns true if the data could be successfully retrieved, else returns false.

Since:

BlackBerry 10.2.0

bool getDataForRevision (

Fetch the data items from the data source if the data source is at the request revision.

This is a synchronous call, but it must be safe to call this method from any thread.

See the discussion about error handling in the class description. A return of false by this method should be both:
  • preceeded by the query emitting an error signal

  • application-level handling of the error signal leading to some appropriate action

IMPORTANT NOTE: The return of false by this method is always expected and never a catastrophic error since false is returned when the data source does not match the requested revision. The error() signal should be emitted on database and query related errors only.

Parameters
offset

The index offset within the view.

limit

The number of items to retrieve.

requestedRevision

The requested revision id for the data source. If the data source does not match this revision, this method will return false.

results

The list of data items which is the return data. Pointer must not be null.

Return:

Returns true if the data could be successfully retrieved at the requested revision, else returns false.

Since:

BlackBerry 10.2.0

QString toString ()

Get a string representation of the query, for debugging purposes.

Return:

The string.

Since:

BlackBerry 10.2.0

Signals

void dataChanged (

Signal for data changes.

Parameters
revision

the revision of the latest source data.

Since:

BlackBerry 10.2.0

void error (

Signal for error when executing the query.

Parameters
code

the error code

message

the error message

Since:

BlackBerry 10.2.0

Last modified: 2014-03-13

comments powered by Disqus