Diffusion Apple API  6.3.0
Unified Client Library for iOS, tvOS and OS X / macOS
 All Classes Functions Variables Properties Pages
Class Methods | Properties | Instance Methods | List of all members
PTDiffusionJSON Class Reference

Introduction

An immutable JSON value with support for both binary and JSON deltas.

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

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.

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 null value is represented by the CBOR Null value.

Since
5.9
Inheritance diagram for PTDiffusionJSON:
PTDiffusionBytes

Class Methods

(PTDiffusionValueStream *) + valueStreamWithDelegate:
 
(PTDiffusionValueStream *) + timeSeriesEventValueStreamWithDelegate:
 
(PTDiffusionRequestHandler *) + requestHandlerWithDelegate:
 
(PTDiffusionRequestStream *) + requestStreamWithDelegate:
 
(PTDiffusionSessionResponseStream *) + sessionResponseStreamWithDelegate:
 

Properties

PTDiffusionRequestrequest
 
PTDiffusionResponseresponse
 
PTDiffusionUpdateConstraintupdateConstraint
 
- Properties inherited from PTDiffusionBytes
NSData * data
 

Instance Methods

(nullable instancetype) - initWithObject:error:
 
(nullable instancetype) - initWithJSONData:error:
 
(nullable instancetype) - initWithJSONString:error:
 
(nullable PTDiffusionBinaryDelta *) - binaryDiffFromJSON:error:
 
(nullable PTDiffusionJSON *) - applyDelta:error:
 
(BOOL) - validateWithError:
 
(nullable id) - objectWithError:
 
(nullable NSData *) - JSONDataWithError:
 
(BOOL) - isEqualToJSON:
 
- Instance Methods inherited from PTDiffusionBytes
(instancetype) - initWithData:
 
(BOOL) - isEqualToBytes:
 

Method Documentation

- (nullable PTDiffusionJSON *) applyDelta: (PTDiffusionBinaryDelta *)  delta
error: (NSError **)  error 

Apply a binary delta to the receiver's JSON value to create a new value.

Parameters
deltaThe delta describing the changes to be applied to the receiver's value in order to create the value to be returned.
errorIf an error occurs, upon return contains an NSError object that describes the problem.
Returns
The new JSON value, or nil if there was an error (e.g. the receiver does not represent a valid JSON value).
Exceptions
NSInvalidArgumentExceptionRaised if the delta argument is nil.
Since
5.9
- (nullable PTDiffusionBinaryDelta *) binaryDiffFromJSON: (PTDiffusionJSON *)  json
error: (NSError **)  error 

Compare the receiver's JSON value with another (e.g. an earlier version) to create a binary delta.

Parameters
jsonThe original to which the delta should be able to be applied in order to generate the value represented by the receiver.
errorIf an error occurs, upon return contains an NSError object that describes the problem.
Returns
A delta representing the difference between json and the receiver, or nil if there was an error (e.g. either the original or the receiver don't represent a valid JSON value).
Exceptions
NSInvalidArgumentExceptionRaised if the json argument is nil.
Since
5.9
- (nullable instancetype) initWithJSONData: (NSData *)  jsonData
error: (NSError **)  error 

Convenience wrapper around initWithObject:error: that first uses NSJSONSerialization to generate the object to be serialized.

Parameters
jsonDataA data object containing JSON data. See Apple's NSJSONSerialization documentation for detailed information regarding supported encodings.
errorIf this method returns nil to indicate that an error occured then this will be populated with the reason for that failure.
Exceptions
NSInvalidArgumentExceptionRaised if the jsonData argument is nil.
Since
5.9
- (nullable instancetype) initWithJSONString: (NSString *)  jsonString
error: (NSError **)  error 

Convenience wrapper around initWithJSONData:error: that first encodes the given string as UTF-8 (NSUTF8StringEncoding), requiring lossless conversion.

Parameters
jsonStringA JSON string.
errorIf this method returns nil to indicate that an error occured then this will be populated with the reason for that failure.
Exceptions
NSInvalidArgumentExceptionRaised if the jsonString argument is nil.
Since
6.0
- (nullable instancetype) initWithObject: (id)  object
error: (NSError **)  error 

Return a JSON object initialised with the given object.

Object hierarchies passed to this method must be constructed from Foundation objects which can be logically encoded with CBOR. This provides flexibility above and beyond the basic capabilities of a 'pure JSON' encoding as well as being less restrictive than the capabilities of NSJSONSerialization.

This means:

  • All objects are instances of NSString, NSData, NSNumber, NSArray, NSDictionary or NSNull.
  • Dictionary keys may be instances of any supported type.
  • The top level object may be of any supported type.

Being more permissive than NSJSONSerialization in that:

  • NSData instances may be used.
  • Dictionary keys are not restricted to instances of NSString.
  • The top level object is not restricted to being a container (NSArray or NSDictionary).

Applications may take advantage of the more permissive nature of the underlying CBOR encoding by using these capabilities, assuming:

  1. Encoding to JSON string is not required.
  2. Other client applications, perhaps developed in a different language and against a different library, can also support the capabilities.
Parameters
objectThe object to be serialized to CBOR and stored internally to represent the receiver.
errorIf this method returns nil to indicate that an error occured then this will be populated with the reason for that failure.
Exceptions
NSInvalidArgumentExceptionRaised if the object argument is nil.
Since
5.9
- (BOOL) isEqualToJSON: (nullable PTDiffusionJSON *)  json

Compares the receiver to the given JSON.

Parameters
jsonThe JSON object with which to compare the receiver.
Returns
YES if the data in json is equal to the contents of the receiver, otherwise NO.
Note
Two JSON objects are equal if they are internally represented by the same CBOR encoding.
Since
5.9
- (nullable NSData*) JSONDataWithError: (NSError **)  error

Convenience wrapper around objectError: that then uses NSJSONSerialization to generate the JSON data.

Parameters
errorIf an error occurs, upon return contains an NSError object that describes the problem.
Returns
A data object containing JSON, or nil if there was an error (e.g. the receive doesn't represent a valid JSON value or cannot be converted to pure JSON).
Since
5.9
- (nullable id) objectWithError: (NSError **)  error

Creates a Foundation object from the receiver's JSON value.

Parameters
errorIf an error occurs, upon return contains an NSError object that describes the problem.
Returns
An object, or nil if there was an error (e.g. the receiver doesn't represent a valid JSON value).
Since
5.9
+ (PTDiffusionRequestHandler *) requestHandlerWithDelegate: (id< PTDiffusionJSONRequestDelegate >)  delegate

Creates a request handler capable of receiving JSON requests for a handler registered at the server.

Parameters
delegateThe object which will handle the incoming requests. A weak reference is maintained to this object by the returned handler.
Returns
An object reliant on the supplied delegate that can be registered at the server using the Messaging Control feature.
Exceptions
NSInvalidArgumentExceptionRaised if the delegate argument is nil.
See Also
PTDiffusionMessagingControlFeature
Since
6.0
+ (PTDiffusionRequestStream *) requestStreamWithDelegate: (id< PTDiffusionJSONRequestStreamDelegate >)  delegate

Creates a request stream capable of receiving JSON requests.

Parameters
delegateThe object which will handle the incoming requests. A weak reference is maintained to this object by the returned stream.
Returns
An object reliant on the supplied delegate that can be set as the receiver of requests using the Messaging feature.
Exceptions
NSInvalidArgumentExceptionRaised if the delegate argument is nil.
See Also
PTDiffusionMessagingFeature
Since
6.0
+ (PTDiffusionSessionResponseStream *) sessionResponseStreamWithDelegate: (id< PTDiffusionJSONSessionResponseStreamDelegate >)  delegate

Creates a response stream capable of receiving JSON responses from discrete sessions.

Parameters
delegateThe object which will handle the incoming responses. A weak reference is maintained to this object by the returned stream.
Returns
An object reliant on the supplied delegate that can be set as the receiver of requests using the Messaging Control feature.
Exceptions
NSInvalidArgumentExceptionRaised if the delegate argument is nil.
See Also
PTDiffusionMessagingControlFeature
Since
6.1
+ (PTDiffusionValueStream *) timeSeriesEventValueStreamWithDelegate: (id< PTDiffusionJSONTimeSeriesEventValueStreamDelegate >)  delegate

Creates a value stream capable of receiving JSON time series events.

Parameters
delegateThe object which will handle the incoming stream. A weak reference is maintained to this object by the returned stream.
Returns
An object reliant on the supplied delegate that can be added as a receiver of values using the Topics feature.
Exceptions
NSInvalidArgumentExceptionRaised if the delegate argument is nil.
See Also
PTDiffusionTopicsFeature
Since
6.0
- (BOOL) validateWithError: (NSError **)  error

Check whether the receiver is valid.

Parameters
errorIf not valid, upon return contains an NSError object that describes the problem.
Returns
YES if this instance is valid.
Since
5.9
+ (PTDiffusionValueStream *) valueStreamWithDelegate: (id< PTDiffusionJSONValueStreamDelegate >)  delegate

Creates a value stream capable of receiving JSON values.

Parameters
delegateThe object which will handle the incoming stream. A weak reference is maintained to this object by the returned stream.
Returns
An object reliant on the supplied delegate that can be added as a receiver of values using the Topics feature.
Exceptions
NSInvalidArgumentExceptionRaised if the delegate argument is nil.
See Also
PTDiffusionTopicsFeature
Since
5.9

Property Documentation

- (PTDiffusionRequest*) request
readnonatomicassign

A request that can be used to send this value using messaging.

Since
6.0
- (PTDiffusionResponse*) response
readnonatomicassign

A response that can be used to send this value using messaging.

Since
6.1
- (PTDiffusionUpdateConstraint*) updateConstraint
readnonatomicassign

An update constraint requiring the current value of a topic to match this value.

Use noValue (PTDiffusionUpdateConstraint) to check if the topic has no value.

This constraint is useful when changing the value of a topic. It is unsatisfied if no topic is present at the path, making it unsuitable for operations that try to add topics.

Since
6.3