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 class 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.

To implement this class, you must decide how to handle error conditions. If there are SQL or other expected or unexpected runtime errors, you 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 error() signal

  • Query issues an error signal and returns false

  • The application detects that the error is unrecoverable

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

  • The 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 also depend on whether retries might be effective, either immediately, after a certain time has elapsed, or when the user wishes to trigger a retry.

For recoverable errors handled by Query, 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

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

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

For recoverable errors handled by the application, the steps may look like this:
  • Connect the application to the error() signal

  • Query issues an error signal and returns false

  • The application detects that the error is recoverable

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

  • The 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:


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 (

Constructs a DataQuery.

Parameters
parent

The parent owner or 0. Optional and defaults 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 preceded by the query emitting an error signal. This signal should be handled at the application level, 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. This pointer must not be null.

totalCount

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

results

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

Return:

True if the data is successfully retrieved, false otherwise.

Since:

BlackBerry 10.2.0

bool getDataForRevision (

Fetch the data items from the data source if the data source is at the requested 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 preceded by the query emitting an error signal. This signal should be handled at the application level, leading to some appropriate action.

Note:

The return of false by this method is always expected and not a catastrophic error since false is returned when the data source doesn't 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 returns false.

results

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

Return:

True if the data could be successfully retrieved at the requested revision, false otherwise.

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 (

Emitted when the data changes.

Parameters
revision

The revision of the latest source data.

Since:

BlackBerry 10.2.0

void error (

Emitted when an error occurs when executing the query.

Parameters
code

The error code.

message

The error message.

Since:

BlackBerry 10.2.0

Last modified: 2014-09-30



Got questions about leaving a comment? Get answers from our Disqus FAQ.

comments powered by Disqus