PushTechnology.ClientInterface.Data.JSON.IJSON Interface Reference

The immutable JSON data value. More...

Inheritance diagram for PushTechnology.ClientInterface.Data.JSON.IJSON:

Public Member Functions
IBinaryDelta	BinaryDiff (IJSON original)
	Compares this JSON value with an earlier version to create a binary delta. More...
IJSON	Apply (IBinaryDelta delta)
	Applies a binary delta to this JSON value to create a new value. More...
IJSON	Validate ()
	Checks whether this instance is valid. More...
string	ToJSONString ()
	Returns this JSON value as a JSON-formatted string. More...
Public Member Functions inherited from PushTechnology.ClientInterface.Data.IBytes
Stream	AsInputStream ()
	Returns the data as a read-only stream. More...
byte[]	ToByteArray ()
	Returns a copy of the data as a byte array. More...
void	CopyTo (Stream outputStream)
	Writes the data to an output stream. More...

Additional Inherited Members
Properties inherited from PushTechnology.ClientInterface.Data.IBytes
int	Length [get]
	Returns the length of the data in bytes. More...

Detailed Description

The immutable JSON data value.

JSON is "JavaScript Object Notation", a lightweight data-interchange format. See www.json.org.

To create an instance from a JSON string, obtain a IJSONDataType implementation from Diffusion.DataTypes.JSON and call IJSONDataType.FromJSONString(string).

The ToJSONString() method can be used to retrieve this value as a JSON string. Applications can use a JSON library to create and interpret the JSON data represented as a string.

CBOR representation

Internally the value is stored and transmitted not as a JSON string, but in CBOR format to reduce memory and network overhead. CBOR (Concise Binary Object Representation) is a standardized format for binary representation of structured data defined by RFC 7049. See www.cbor.io.

Rather than working with JSON strings it is possible, and usually preferable, for applications to work directly with the underlying CBOR-format binary representation. This avoids creating intermediate JSON strings, and allows access to CBOR features such as the byte string data type.

Each JSON value is represented as a single CBOR data item. CBOR supports composite data types just like JSON, so this data item can be an array or a map of other data items. The JSON null value is represented by the CBOR Null value.

A particular advantage of working directly with the CBOR-format data is that binary data can be written to the value as a data item using the CBOR byte string type. The data item will be stored as part of the JSON value in binary form and transmitted without further conversion.

Working with CBOR data

To create an instance from a CBOR-format byte array, call IDataType{IJSON}.ReadValue(byte[]). The byte array must contain a single CBOR data item, otherwise, an InvalidDataException will be thrown when the data is first parsed. To convert an instance to CBOR format, use IBytes.AsInputStream() or IJSONDataType.WriteValue(IJSON,OutputStream).

To read or write CBOR we recommend using our own basic CBORReader and CBORWriter classes, or some other library of your choice.

CBOR limitations

The mapping from a JSON string to and from CBOR-format binary data is mostly straightforward, but there are a few limitations. In particular:

• Non-string keys are not supported.
• Precision may be lost converting numbers from JSON to CBOR.

Since 5.8

Member Function Documentation

IJSON PushTechnology.ClientInterface.Data.JSON.IJSON.Apply

(

IBinaryDelta

delta

)

Applies a binary delta to this JSON value to create a new value.

Convenient equivalent to Diffusion.DataTypes.JSON.BinaryDeltaType.Apply(this, delta) .

Parameters

delta

The binary delta to apply to this JSON value.

Returns

The new JSON value.

IBinaryDelta PushTechnology.ClientInterface.Data.JSON.IJSON.BinaryDiff

(

IJSON

original

)

Compares this JSON value with an earlier version to create a binary delta.

Convenient equivalent to Diffusion.DataTypes.JSON.BinaryDeltaType.Diff(original, this) .

Parameters

original

The original JSON value.

Returns

The delta representing the difference between original and this JSON.

string PushTechnology.ClientInterface.Data.JSON.IJSON.ToJSONString

(

)

Returns this JSON value as a JSON-formatted string.

Returns

This JSON value as a JSON-formatted string.

IJSON PushTechnology.ClientInterface.Data.JSON.IJSON.Validate

(

)

Checks whether this instance is valid.

Convenient equivalent to Diffusion.DataTypes.JSON.Validate(this) .

Returns

The current IJSON instance to allow fluent chaining.

---

The documentation for this interface was generated from the following file:

• Data.Public/JSON/IJSONDataType.cs