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 ()
DataAccessError	error () const
bool	hasError () const
QVariant	load (const QString &filePath)
QVariant	load (QIODevice *ioDevice)
QVariant	loadFromBuffer (const QByteArray &buffer)
QVariant	loadFromBuffer (const QString &buffer)
void	save (const QVariant &data, const QString &filePath)
void	save (const QVariant &data, QIODevice *ioDevice)
void	saveToBuffer (const QVariant &data, QByteArray *buffer)
void	saveToBuffer (const QVariant &data, QString *buffer)

Public Functions

JsonDataAccess (
QObject *parent)

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 (
const QString &filePath)

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 (
QIODevice *ioDevice)

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 (
const QByteArray &buffer)

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

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 (
const QString &buffer)

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

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 (
const QVariant &data,
const QString &filePath )

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 (
const QVariant &data,
QIODevice *ioDevice )

Saves JSON data to the specified I/O device.

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 (
const QVariant &data,
QByteArray *buffer )

Saves JSON data to the specified QByteArray buffer.

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 (
const QVariant &data,
QString *buffer )

Saves JSON data to the specified QString buffer.

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

JsonDataAccess

Loading data

Unicode

Overview

Public Functions Index

Public Functions

JsonDataAccess (
QObject *parent)

virtual~JsonDataAccess ()

DataAccessError error ()

bool hasError ()

QVariant load (
const QString &filePath)

QVariant load (
QIODevice *ioDevice)

QVariant loadFromBuffer (
const QByteArray &buffer)

QVariant loadFromBuffer (
const QString &buffer)

void save (
const QVariant &data,
const QString &filePath )

void save (
const QVariant &data,
QIODevice *ioDevice )

void saveToBuffer (
const QVariant &data,
QByteArray *buffer )

void saveToBuffer (
const QVariant &data,
QString *buffer )

1. Choose your focus

2. Download the tools

3. Try the sample apps

4. Educate yourself

5. Start developing

JsonDataAccess

Loading data

Unicode

Overview

Public Functions Index

Public Functions

JsonDataAccess (QObject *parent)

virtual~JsonDataAccess ()

DataAccessError error ()

bool hasError ()

QVariant load (const QString &filePath)

QVariant load (QIODevice *ioDevice)

QVariant loadFromBuffer (const QByteArray &buffer)

QVariant loadFromBuffer (const QString &buffer)

void save (const QVariant &data, const QString &filePath )

void save (const QVariant &data, QIODevice *ioDevice )

void saveToBuffer (const QVariant &data, QByteArray *buffer )

void saveToBuffer (const QVariant &data, QString *buffer )

1. Choose your focus

2. Download the tools

3. Try the sample apps

4. Educate yourself

5. Start developing

JsonDataAccess (
QObject *parent)

QVariant load (
const QString &filePath)

QVariant load (
QIODevice *ioDevice)

QVariant loadFromBuffer (
const QByteArray &buffer)

QVariant loadFromBuffer (
const QString &buffer)

void save (
const QVariant &data,
const QString &filePath )

void save (
const QVariant &data,
QIODevice *ioDevice )

void saveToBuffer (
const QVariant &data,
QByteArray *buffer )

void saveToBuffer (
const QVariant &data,
QString *buffer )