Inherits from NSObject
Declared in JPAsyncJsonParser.h
JPAsyncJsonParser.mm

Overview

While a JPJsonParser can only parse input which contains one or more JSON documents that is provided in one buffer which is a contiguous sequence of bytes in memory, a JPAsyncJsonParser is capable to parse input which is partitioned into a contiguous set of data buffers. The concatenated content may comprise one or more JSON documents.

When downloading a resource from the net, the underlaying network layer will usually provide the content in chunks, each contained in a data buffer. For example, NSURLConnection delivers the content as a sequence of NSData objects to its delegate. The sequence of data buffers make up the complete input which may contain one or more JSON documents.

JPAsyncJsonParser provides an interface where a sequence of NSData buffers can be sent via the message parseBuffer: to a JPAsyncJsonParser object. This makes JPAsyncJsonParser especially suited to receive partial input which will be received as a sequence of data buffers, e.g. from a NSURLConnection delegate or through a NSStream interface.

A JPAsyncJsonParser instance will invoke the underlaying parser asynchronously. That is, when an JPAsyncJsonParser instance receives the start message, the underlaying JSON parser will be executed on a different thread and the method start returns immediately. The underlaying JSON parser will then wait for incoming data buffer to become available for parsing.

The client is responsible to provide the sequence of NSData objects which will be sent by message parserBuffer: to the JPAsyncJsonParser instance. The underlaying JSON parser in turn will consume this data buffer and start parsing it. As a result it will send parse events to the semantic actions object as long as there is data available, or until the parser receives an EOF from the input. If there is no data available and the parser expects yet more input, the parser’s thread will be blocked until data is available again.

A client of an asynchronous parser will be notified about the result of a semantic actions object and other events through the means of handler blocks which will be assigned the semantic actions object via properties. The exact behavior depends on the concrete semantic actions class. For more information on semantic actions see JPSemanticActionsProtocol, JPSemanticActionsBase, JPRepresentationGenerator and JPStreamSemanticActions.

A JPAsyncJsonParser object can only be used once for parsing the input. That is, once the message start has been sent, it cannot be invoked again. In order to parse another input, a new parser object must be created. The input can consist of many JSON documents however, and the total length of the input stream can be virtually infinitive.

Tasks

Initialization

Properties

Starting the Parser Asynchronously

  • – start

    Start the parser asynchronously. The parser will wait for data buffers to become available provided by method parseBuffer:. Once the first buffer is available, the parser will try to determine the encoding of the input. If any error occurs while detecting the encoding, the parser will issue an error which will cause the error handler to be called (if it is not NULL). Otherwise, the parser will continue to parse the input from the buffers, until no more buffers are available.

Providing Data Buffers

  • – parseBuffer:

    Push a data buffer to the parser’s internal buffer queue which the parser will start to process when it becomes ready.

Canceling an Asynchronously Running Parser

  • – cancel

    Synchronously cancels the parser which forces it to exit as soon as possible. After returning from cancel, it is guaranteed that no blocks will be invoked and no delegate will receive any messages. cancel will block until the parser’s worker thread has been exited. After canceling the parser’s result and error state is undefined.

Check if a Parser is Running

  • – isRunning

    Returns YES if the parser has been started and is currently running.

Properties

semanticActions

Returns the semantic actions object.

@property (nonatomic, readonly, strong) JPSemanticActionsBase *semanticActions

Declared In

JPAsyncJsonParser.h

Instance Methods

cancel

Synchronously cancels the parser which forces it to exit as soon as possible. After returning from cancel, it is guaranteed that no blocks will be invoked and no delegate will receive any messages. cancel will block until the parser’s worker thread has been exited. After canceling the parser’s result and error state is undefined.

- (void)cancel

Declared In

JPAsyncJsonParser.h

init

Invokes the designated initializer with parameter semanticActions set to nil and workerQueue set to NULL.

- (id)init

See Also

Declared In

JPAsyncJsonParser.h

initWithSemanticActions:workerDispatchQueue:

Designated Initializer

- (id)initWithSemanticActions:(JPSemanticActionsBase *)semanticActions workerDispatchQueue:(dispatch_queue_t)workerQueue

Parameters

semanticActions

A semantic actions object or nil.

workerQueue

A dispatch queue or NULL.

Discussion

If object semanticActions equals nil an instance of class JPRepresentationGenerator will be created and initialized with default properties. The default values which will be set are documented in class JPRepresentationGenerator.

If parameter workerQueue equals NULL the parsing routines will be scheduled on the global dispatch queue. This is usually a good choice.

The semantic actions handler dispatch queue and the parser’s worker dispatch queue must not be the same, unless the semantic actions object property parseMultipleDocumentsAsynchronously equals YES.

Declared In

JPAsyncJsonParser.h

isRunning

Returns YES if the parser has been started and is currently running.

- (BOOL)isRunning

Declared In

JPAsyncJsonParser.h

parseBuffer:

Push a data buffer to the parser’s internal buffer queue which the parser will start to process when it becomes ready.

- (BOOL)parseBuffer:(NSData *)buffer

Parameters

buffer

A NSData object possibly containing a partial input. If buffer equals nil the parser treats it as EOF and stops parsing.

Return Value

Returns YES if the parser will consume this buffer. Returns NO if a timeout occurred, or if the parser is in cancel or error state.

Discussion

The content of buffer may contain partial JSON text in which case subsequent invocations of parseBuffer: will be required in order to finish parsing of one or more JSON texts.

The method will block until after the parser is ready to consume this buffer, that is, when it has finished the previous buffer or when it is idle. It does not block however for the time it takes to process this buffer.

buffer will be retained for the duration of use and then released again.

Warning: Caution: The buffer’s byte sequence MUST start or end only at complete Unicode code unites. That is, for instance, UTF-8 encoded text may start and end at any byte boundary, while UTF-16 and UTF-32 requires to start and end at their respective code units (two bytes and four bytes).

Declared In

JPAsyncJsonParser.h

start

Start the parser asynchronously. The parser will wait for data buffers to become available provided by method parseBuffer:. Once the first buffer is available, the parser will try to determine the encoding of the input. If any error occurs while detecting the encoding, the parser will issue an error which will cause the error handler to be called (if it is not NULL). Otherwise, the parser will continue to parse the input from the buffers, until no more buffers are available.

- (BOOL)start

Return Value

Returns YES if the parser has not yet been started previously.

Discussion

Depending on the actual semantic actions object, their handlers may be called whenever the start of a JSON document was found in the input stream and whenever a JSON document has been created. Finally, if the end of the data is detected a completion handler may be called.

Declared In

JPAsyncJsonParser.h