From bd7f23f3473637f4ab4b9a96d003f7a3968dce6e Mon Sep 17 00:00:00 2001 From: Jaishree Vyas Date: Fri, 9 Sep 2022 14:24:01 +0200 Subject: [PATCH] Doc: Document Qt Serialization with use cases MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Added some background about Serialization with the classes and used cases. Fixes: QTBUG-103951 Change-Id: I3ff179b814fc5d424f2ac2ffaf3237b90ddd7e2b Reviewed-by: Vladimir Minenko Reviewed-by: Cristian Maureira-Fredes Reviewed-by: Kai Köhne (cherry picked from commit 57a4c0d73c3521a0855ce597204b096928c43117) Reviewed-by: Qt Cherry-pick Bot --- src/corelib/doc/src/qtserialization.qdoc | 138 ++++++++++++++++++ src/corelib/serialization/qcborarray.cpp | 1 + src/corelib/serialization/qcborcommon.cpp | 1 + src/corelib/serialization/qcbormap.cpp | 1 + .../serialization/qcborstreamreader.cpp | 1 + .../serialization/qcborstreamwriter.cpp | 1 + src/corelib/serialization/qcborvalue.cpp | 1 + src/corelib/serialization/qdatastream.cpp | 1 + src/corelib/serialization/qjsonarray.cpp | 1 + src/corelib/serialization/qjsondocument.cpp | 1 + src/corelib/serialization/qjsonobject.cpp | 1 + src/corelib/serialization/qjsonparser.cpp | 1 + src/corelib/serialization/qjsonvalue.cpp | 1 + src/corelib/serialization/qtextstream.cpp | 1 + src/corelib/serialization/qxmlstream.cpp | 3 + 15 files changed, 154 insertions(+) create mode 100644 src/corelib/doc/src/qtserialization.qdoc diff --git a/src/corelib/doc/src/qtserialization.qdoc b/src/corelib/doc/src/qtserialization.qdoc new file mode 100644 index 00000000000..dfceed55f2d --- /dev/null +++ b/src/corelib/doc/src/qtserialization.qdoc @@ -0,0 +1,138 @@ +// Copyright (C) 2022 The Qt Company Ltd. +// SPDX-License-Identifier: LicenseRef-Qt-Commercial OR GFDL-1.3-no-invariants-only + +/*! + \page qtserialization.html + \title Qt Serialization + \brief Serializations provided by Qt API + + The purpose of serialization is to save the state of an object to be able to + recreate it when needed. It allows you to perform actions like: + + \list + \li Sending the object to a remote application by using a web service + \li Passing the object as a JSON or XML string + \li Saving and restoring user information or sharing it across applications + \endlist + + The Qt API provides support for serialization for several use cases: + + \list + \li \l JSON support in Qt provides an easy to use C++ API to parse, modify + and save JSON data. \l {CBOR} {CBOR Support in Qt} is a compact form + of binary data encoding that is a superset of JSON. + \li \l QDataStream provides serialization of binary data to a QIODevice + \li \l {Qt XML C++ Classes} provide C++ implementations of the \l XML Streaming + and DOM standards for XML + \li \l CBOR is Qt's implementation for the CBOR serialization format. + \li \l QSettings provides a way of serializing and storing platform independent + application settings. + \endlist + + \section1 Advantages of JSON and CBOR + + When you use \l JSON information is stored in a QJsonObject and a QJsonDocument + takes care to stream values into a QByteArray. + + For example + \code + QJsonObject jobject; + jobject["SensorID"] = m_id; + jobject["AmbientTemperature"] = m_ambientTemperature; + jobject["ObjectTemperature"] = m_objectTemperature; + jobject["AccelerometerX"] = m_accelerometerX; + jobject["AccelerometerY"] = m_accelerometerY; + jobject["AccelerometerZ"] = m_accelerometerZ; + jobject["Altitude"] = m_altitude; + jobject["Light"] = m_light; + jobject["Humidity"] = m_humidity; + QJsonDocument doc( jobject ); + + return doc.toJson(); + \endcode + + JSON has several advantages: + + \list + \li Textual JSON is declarative, which makes it readable to humans + \li The information is structured + \li Exchanging generic information is easy + \li JSON allows extending messages with additional values + \li Many solutions exist to receive and parse JSON in cloud-based solutions + \endlist + + \l CBOR is the Concise Binary Object Representation, a very compact form of + binary data encoding that is a superset of JSON. It was created by the IETF + Constrained RESTful Environments (CoRE) WG, which has been used in many new + RFCs. CBOR shares many of the advantages of JSON, but sacrifices human + readability for compactness. + + \section1 Advantages of QDataStream Classes + + \l QDataStream is a viable option when the whole flow of data is determined + and not about to change. In addition, both the reader and the writer of the + data must be written in Qt. + + Adding support for this to a class requires two additional operators. + For example, for a class named SensorInformation: + + \code + QDataStream &operator<<(QDataStream &, const SensorInformation &); + QDataStream &operator>>(QDataStream &, SensorInformation &); + \endcode + + The implementation for the serialization is shown below: + + \code + QDataStream &operator<<(QDataStream &out, const SensorInformation &item) + { + QDataStream::FloatingPointPrecision prev = out.floatingPointPrecision(); + out.setFloatingPointPrecision(QDataStream::DoublePrecision); + out << item.m_id + << item.m_ambientTemperature + << item.m_objectTemperature + << item.m_accelerometerX + << item.m_accelerometerY + << item.m_accelerometerZ + << item.m_altitude + << item.m_light + << item.m_humidity; + out.setFloatingPointPrecision(prev); + return out; + } + \endcode + + Deserialization works similarly, but using the \c {>>} operator. + For example, \c {out >> item.m_id}, and so on. + + Usually, using QDataStream is faster than using textual JSON. + + \section1 Advantages of Qt XML C++ Classes + + Qt provides the QDomDocument class that represents the XML document and + two classes for reading and writing the XML through a simple streaming API: + QXmlStreamReader and QXmlStreamWriter. + + QDomDocument class represents the entire XML document. It is the root of the + document tree and provides primary access to the document's data. + + A stream reader reports an XML document as a stream of tokens. This differs + from SAX as SAX applications provide handlers to receive XML events from the + parser, whereas the QXmlStreamReader drives the loop, pulling tokens from the + reader when they are needed. This pulling approach makes it possible to build + recursive descent parsers, allowing XML parsing code to be split into + different methods or classes. + + QXmlStreamReader a parser for well-formed XML 1.0, excluding external parsed + entities. Hence, data provided to the stream reader adheres to the + W3C's criteria for well-formed XML, or an error will be raised. Functions + such as \c atEnd(), \c error(), and \c hasError() can be used to test for + such errors and obtain a description of them. + + The QXmlStreamWriter is a streaming API that takes care of prefixing namespaces, + when the namespaceUri is specified when writing elements or attributes. + + \section1 Classes that provide serialization + + \annotatedlist qtserialization +*/ diff --git a/src/corelib/serialization/qcborarray.cpp b/src/corelib/serialization/qcborarray.cpp index 91644fe2ea9..2d9cb711127 100644 --- a/src/corelib/serialization/qcborarray.cpp +++ b/src/corelib/serialization/qcborarray.cpp @@ -13,6 +13,7 @@ using namespace QtCbor; \class QCborArray \inmodule QtCore \ingroup cbor + \ingroup qtserialization \reentrant \since 5.12 diff --git a/src/corelib/serialization/qcborcommon.cpp b/src/corelib/serialization/qcborcommon.cpp index 844bcef4af2..66d6dcd6850 100644 --- a/src/corelib/serialization/qcborcommon.cpp +++ b/src/corelib/serialization/qcborcommon.cpp @@ -17,6 +17,7 @@ QT_IMPL_METATYPE_EXTERN(QCborTag) /*! \headerfile \inmodule QtCore + \ingroup qtserialization \brief The header contains definitions common to both the streaming classes (QCborStreamReader and QCborStreamWriter) and to QCborValue. diff --git a/src/corelib/serialization/qcbormap.cpp b/src/corelib/serialization/qcbormap.cpp index dcb4299027d..3eda1e82cf0 100644 --- a/src/corelib/serialization/qcbormap.cpp +++ b/src/corelib/serialization/qcbormap.cpp @@ -12,6 +12,7 @@ using namespace QtCbor; \class QCborMap \inmodule QtCore \ingroup cbor + \ingroup qtserialization \reentrant \since 5.12 diff --git a/src/corelib/serialization/qcborstreamreader.cpp b/src/corelib/serialization/qcborstreamreader.cpp index 5f6c0feb49b..c0a32c303ba 100644 --- a/src/corelib/serialization/qcborstreamreader.cpp +++ b/src/corelib/serialization/qcborstreamreader.cpp @@ -62,6 +62,7 @@ static_assert(int(QCborStreamReader::Invalid) == CborInvalidType); \class QCborStreamReader \inmodule QtCore \ingroup cbor + \ingroup qtserialization \reentrant \since 5.12 diff --git a/src/corelib/serialization/qcborstreamwriter.cpp b/src/corelib/serialization/qcborstreamwriter.cpp index 0e445451bc2..696f55b0b06 100644 --- a/src/corelib/serialization/qcborstreamwriter.cpp +++ b/src/corelib/serialization/qcborstreamwriter.cpp @@ -45,6 +45,7 @@ Q_DECLARE_TYPEINFO(CborEncoder, Q_PRIMITIVE_TYPE); \class QCborStreamWriter \inmodule QtCore \ingroup cbor + \ingroup qtserialization \reentrant \since 5.12 diff --git a/src/corelib/serialization/qcborvalue.cpp b/src/corelib/serialization/qcborvalue.cpp index b2a89f067f6..0d11aa86dc4 100644 --- a/src/corelib/serialization/qcborvalue.cpp +++ b/src/corelib/serialization/qcborvalue.cpp @@ -44,6 +44,7 @@ Q_DECL_UNUSED static constexpr quint64 MaximumPreallocatedElementCount = \class QCborValue \inmodule QtCore \ingroup cbor + \ingroup qtserialization \reentrant \since 5.12 diff --git a/src/corelib/serialization/qdatastream.cpp b/src/corelib/serialization/qdatastream.cpp index 59a2a4c53f7..05691885a40 100644 --- a/src/corelib/serialization/qdatastream.cpp +++ b/src/corelib/serialization/qdatastream.cpp @@ -18,6 +18,7 @@ QT_BEGIN_NAMESPACE /*! \class QDataStream \inmodule QtCore + \ingroup qtserialization \reentrant \brief The QDataStream class provides serialization of binary data to a QIODevice. diff --git a/src/corelib/serialization/qjsonarray.cpp b/src/corelib/serialization/qjsonarray.cpp index 85e73af06bf..f3b1f671a65 100644 --- a/src/corelib/serialization/qjsonarray.cpp +++ b/src/corelib/serialization/qjsonarray.cpp @@ -22,6 +22,7 @@ QT_BEGIN_NAMESPACE \inmodule QtCore \ingroup json \ingroup shared + \ingroup qtserialization \reentrant \since 5.0 diff --git a/src/corelib/serialization/qjsondocument.cpp b/src/corelib/serialization/qjsondocument.cpp index a77aab38953..446cfcd303b 100644 --- a/src/corelib/serialization/qjsondocument.cpp +++ b/src/corelib/serialization/qjsondocument.cpp @@ -24,6 +24,7 @@ QT_BEGIN_NAMESPACE \inmodule QtCore \ingroup json \ingroup shared + \ingroup qtserialization \reentrant \since 5.0 diff --git a/src/corelib/serialization/qjsonobject.cpp b/src/corelib/serialization/qjsonobject.cpp index e87f46a5508..589bbfeebac 100644 --- a/src/corelib/serialization/qjsonobject.cpp +++ b/src/corelib/serialization/qjsonobject.cpp @@ -25,6 +25,7 @@ QT_BEGIN_NAMESPACE \inmodule QtCore \ingroup json \ingroup shared + \ingroup qtserialization \reentrant \since 5.0 diff --git a/src/corelib/serialization/qjsonparser.cpp b/src/corelib/serialization/qjsonparser.cpp index acc2bc383f3..b11ae3a9d2e 100644 --- a/src/corelib/serialization/qjsonparser.cpp +++ b/src/corelib/serialization/qjsonparser.cpp @@ -50,6 +50,7 @@ QT_BEGIN_NAMESPACE \inmodule QtCore \ingroup json \ingroup shared + \ingroup qtserialization \reentrant \since 5.0 diff --git a/src/corelib/serialization/qjsonvalue.cpp b/src/corelib/serialization/qjsonvalue.cpp index ef07dcdc3b8..8b5f3cd243e 100644 --- a/src/corelib/serialization/qjsonvalue.cpp +++ b/src/corelib/serialization/qjsonvalue.cpp @@ -53,6 +53,7 @@ static QJsonValue::Type convertFromCborType(QCborValue::Type type) noexcept \inmodule QtCore \ingroup json \ingroup shared + \ingroup qtserialization \reentrant \since 5.0 diff --git a/src/corelib/serialization/qtextstream.cpp b/src/corelib/serialization/qtextstream.cpp index 2a2536aeee5..a268002dc68 100644 --- a/src/corelib/serialization/qtextstream.cpp +++ b/src/corelib/serialization/qtextstream.cpp @@ -14,6 +14,7 @@ static const int QTEXTSTREAM_BUFFERSIZE = 16384; \ingroup io \ingroup string-processing + \ingroup qtserialization \reentrant QTextStream can operate on a QIODevice, a QByteArray or a diff --git a/src/corelib/serialization/qxmlstream.cpp b/src/corelib/serialization/qxmlstream.cpp index b76243c1760..70e65df9957 100644 --- a/src/corelib/serialization/qxmlstream.cpp +++ b/src/corelib/serialization/qxmlstream.cpp @@ -229,6 +229,8 @@ QXmlStreamEntityResolver *QXmlStreamReader::entityResolver() const \ingroup xml-tools + \ingroup qtserialization + QXmlStreamReader provides a simple streaming API to parse well-formed XML. It is an alternative to first loading the complete XML into a DOM tree (see \l QDomDocument). QXmlStreamReader reads data either @@ -2735,6 +2737,7 @@ QStringView QXmlStreamReader::documentEncoding() const simple streaming API. \ingroup xml-tools + \ingroup qtserialization QXmlStreamWriter is the counterpart to QXmlStreamReader for writing XML. Like its related class, it operates on a QIODevice specified