JsonDataAccess

Since: BlackBerry 10.0.0

#include <bb/data/JsonDataAccess>

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

Provides load and save operations for JSON data.

The JsonDataAccess class converts data from JSON format to Qt C++ value objects or from Qt C++ value objects to JSON format. You can use this class to provide JSON data to a ListView to display the data in your application.

Load operations read and parse JSON (JavaScript Object Notation) data coming from a file or memory buffer into a tree of Qt value objects. Save operations convert Qt value objects into JSON format, which are written to a file or returned in a memory buffer.

The topmost (root) JSON element must be either an array or an object. See http://www.json.org/ for the JSON format description.

The Qt value data must always be a QVariant that contains either a QVariantList or QVariantMap.

Both formats support unlimited nesting of hierarchical data.

The JSON element types are mapped to Qt values as follows:
   JSON Type         QT Type
   ---------         -----------------
   null              empty QVariant
   int               QVariant(Int64)
   uint              QVariant(UInt64)
   real              QVariant(double)
   string            QVariant(const char*)
   boolean           QVariant(bool)
   array             QVariant(QVariantList)
   object            QVariant(QVariantMap)

Loading data

Here's an example of how to load JSON data from a file (called contacts.json) and insert the data into a data model. The data model is then used to provide data for a ListView.

The contacts.json file contains the following JSON data:
[
{ "id":1, "firstname": "Mike", "lastname": "Chepesky", "title": "Sr. Editor",
  "image": "images/data/mike_chepesky.png", "active": true, "gender": "m" },
{ "id":2, "firstname": "Westlee", "lastname": "Barichak", "title": "Talent Scout",
  "image": "images/data/westlee_barichak.png", "active": true, "gender": "m" },
...
]
C++:
// Create a data model with sorting keys for firstname and lastname
GroupDataModel *model =
  new GroupDataModel(QStringList() << "firstname" << "lastname");

// Load the JSON data
JsonDataAccess jda;
QVariant list = jda.load("contacts.json");

// Add the data to the model
model->insertList(list.value<QVariantList>());

// Create a ListView control and add the model to the list
ListView *listView = new ListView();
listView->setDataModel(model);
QML:
import bb.cascades 1.0
import bb.data 1.0
Page {
  content: ListView {
    id: listView
    dataModel: dataModel
    //...
  }
  attachedObjects: [
    GroupDataModel {
      id: dataModel
    },
    DataSource {
      id: dataSource
      source: "contacts.json"
      onDataLoaded: {
        dataModel.insertList(data)
      }
    }
  ]
  onCreationCompleted: {
      dataSource.load(); 
  }
}

Unicode

JSON data, in general, is encoded in Unicode. The default encoding is UTF-8 but external data in UTF-16 formats can also be loaded and parsed. The The various load and save methods in this class will indicate what assumptions and restrictions they have regarding decoding and encoding.


Overview

Public Functions Index

JsonDataAccess (QObject *parent=0)
virtual ~JsonDataAccess ()
DataAccessErrorerror () const
boolhasError () const
QVariantload (const QString &filePath)
QVariantload (QIODevice *ioDevice)
QVariantloadFromBuffer (const QByteArray &buffer)
QVariantloadFromBuffer (const QString &buffer)
voidsave (const QVariant &data, const QString &filePath)
voidsave (const QVariant &data, QIODevice *ioDevice)
voidsaveToBuffer (const QVariant &data, QByteArray *buffer)
voidsaveToBuffer (const QVariant &data, QString *buffer)

Public Functions

JsonDataAccess (

Constructs a JsonDataAccess object with the specified parent.

If the specified parent is not 0, the ownership of this object will be transferred to the parent.

Parameters
parent

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

Since:

BlackBerry 10.0.0

virtual~JsonDataAccess ()

Destructor.

Since:

BlackBerry 10.0.0

DataAccessError error ()

Returns an error object for the most recent operation.

Return:

DataAccessError with error type and error message.

Since:

BlackBerry 10.0.0

bool hasError ()

Returns indication of whether or not most recent operation ended with an error.

Return:

true if current error or false if none.

Since:

BlackBerry 10.0.0

QVariant load (

Loads JSON data from specified file and returns it as a hierarchy of Qt value objects.

The data returned is a QVariant with a type that matches the type of the root JSON object (see table of types in the class description of JsonDataAccess). Unless the data is a single primitive JSON value, the returned data will be either a QVariantList (if root JSON node is array) or a QVariantMap (if root JSON node is an object), cast as a QVariant.

You can use DataAccess::hasError() to determine if the most recent operation resulted in an error, and you can use DataAccess::error() to retrieve information about the error that occurred.

The file data can be encoded as UTF-8 (with or without byte-order-mark) or as UTF-16 (must have a byte-order-mark to indicate little endian or big endian).

Parameters
filePath

The path to the JSON file.

Return:

A QVariant containing a hierarchy of QT value objects.

Since:

BlackBerry 10.0.0

QVariant load (

Loads JSON data from the specified I/O device and returns it as a hierarchy of Qt value objects.

An I/O device is used to read or write data from various sources. A QIODevice can represent several useful types, including QBuffer and QFile.

The data returned is a QVariant with a type that matches the type of the root JSON object (see the table of types in the class description of JsonDataAccess). Unless the data is a single primitive JSON value, the returned data will be either a QVariantList (if the root JSON node is an array) or a QVariantMap (if root JSON node is an object), cast as a QVariant.

You can use DataAccess::hasError() to determine if the most recent operation resulted in an error, and you can use DataAccess::error() to retrieve information about the error that occurred.

The input data can be encoded as UTF-8 (with or without byte-order-mark) or as UTF-16 (must have a byte-order-mark to indicate little endian or big endian).

Parameters
ioDevice

The I/O device that is used to read and write data.

Return:

A QVariant containing a hierarchy of Qt value objects.

Since:

BlackBerry 10.0.0

QVariant loadFromBuffer (

Parses the specified JSON byte array buffer and returns it as a hierarchy of Qt value objects.

The data returned is a QVariant with a type that matches the type of the root JSON object (see the table of types in the class description of JsonDataAccess). Unless the data is a single primitive JSON value, the returned data will be either a QVariantList (if the root JSON node is an array) or a QVariantMap (if root JSON node is an object), cast as a QVariant.

You can use DataAccess::hasError() to determine if the most recent operation resulted in an error, and you can use DataAccess::error() to retrieve information about the error that occurred.

Parameters
buffer

An in-memory byte array containing JSON data encoded as UTF-8.

Return:

A QVariant containing a hierarchy of Qt value objects.

Since:

BlackBerry 10.0.0

QVariant loadFromBuffer (

Parses the specified JSON string buffer and returns it as a hierarchy of Qt value objects.

The data returned is a QVariant with a type that matches the type of the root JSON object (see the table of types in the class description of JsonDataAccess). Unless the data is a single primitive JSON value, the returned data will be either a QVariantList (if the root JSON node is an array) or a QVariantMap (if root JSON node is an object), cast as a QVariant.

You can use DataAccess::hasError() to determine if the most recent operation resulted in an error, and you can use DataAccess::error() to retrieve information about the error that occurred.

Parameters
buffer

An in-memory string containing JSON unicode data.

Return:

A QVariant containing a hierarchy of Qt value objects.

Since:

BlackBerry 10.0.0

void save (

Saves JSON data to the specified file.

The data parameter is a QVariant (see the table of types in the class description of JsonDataAccess). Unless the data is a single primitive JSON value, the data should be either a QVariantList (if the root JSON node is an array) or a QVariantMap (if root JSON node is an object), cast as a QVariant.

You can use DataAccess::hasError() to determine if the most recent operation resulted in an error, and you can use DataAccess::error() to retrieve information about the error that occurred.

Parameters
data

The data to be converted to JSON format.

filePath

The path to the JSON file to be written as UTF-8 (with no byte-order-mark).

Since:

BlackBerry 10.0.0

void save (

Saves JSON data to the specified I/O device.

The data parameter is a QVariant (see the table of types in the class description of JsonDataAccess). Unless the data is a single primitive JSON value, the data should be either a QVariantList (if the root JSON node is an array) or a QVariantMap (if root JSON node is an object), cast as a QVariant.

You can use DataAccess::hasError() to determine if the most recent operation resulted in an error, and you can use DataAccess::error() to retrieve information about the error that occurred.

An I/O device is used to read or write data from various sources. A QIODevice can represent several useful types, including QBuffer and QFile.

Parameters
data

The data to be converted to JSON format.

ioDevice

The I/O device that is used to write JSON data as UTF-8 (no byte order mark).

Since:

BlackBerry 10.0.0

void saveToBuffer (

Saves JSON data to the specified QByteArray buffer.

The data parameter is a QVariant (see the table of types in the class description of JsonDataAccess). Unless the data is a single primitive JSON value, the data should be either a QVariantList (if the root JSON node is an array) or a QVariantMap (if root JSON node is an object), cast as a QVariant.

You can use DataAccess::hasError() to determine if the most recent operation resulted in an error, and you can use DataAccess::error() to retrieve information about the error that occurred.

Parameters
data

The data to be converted to JSON format.

buffer

An output parameter that is updated with JSON-formatted data in UTF-8 format.

Since:

BlackBerry 10.0.0

void saveToBuffer (

Saves JSON data to the specified QString buffer.

The data parameter is a QVariant (see the table of types in the class description of JsonDataAccess). Unless the data is a single primitive JSON value, the data should be either a QVariantList (if the root JSON node is an array) or a QVariantMap (if root JSON node is an object), cast as a QVariant.

You can use DataAccess::hasError() to determine if the most recent operation resulted in an error, and you can use DataAccess::error() to retrieve information about the error that occurred.

Parameters
data

The data to be converted to JSON format.

buffer

An output parameter that is updated with JSON-formatted Unicode data.

Since:

BlackBerry 10.0.0

Last modified: 2014-03-13

comments powered by Disqus