Inherits from NSObject
Conforms to JPSemanticActionsProtocol
Declared in JPSemanticActionsBase.h
JPSemanticActionsBase.mm

Overview

Abstract Base Class for concrete Semantic Actions classes.

A Semantic Actions Object acts as an internal delegate of a JSON parser. It receives parse events sent from the parser and handles them in corresponding semantic actions. The class conforms to the protocol JPSemanticActionsProtocol and provides a default implementation for the following optional methods declared in JPSemanticActionsProtocol:

  • -parserFoundJsonBegin
  • -parserFoundJsonEnd
  • -parserFinished
  • -parserDetectedError

JPSemanticActionsBase is meant to be subclassed. Subclasses may override the methods mentioned above and may define the additional methods declared in protocol JPSemanticActionsProtocol.

There are two prominent subclasses: JPRepresentationGenerator and JPStreamSemanticActions. While JPRepresentationGenerator shall be used as is, JPStreamSemanticActions may be subclassed or alternatively used with a delegate.

The delegate methods will be invoked when the JSON parser successfully parsed a certain rule, that is when the parser detects the various JSON elements, or the start and the end of the document. For more information see JPSemanticActionsProtocol.

Using a Semantic Actions object

Each parser, that is an instance of JPJsonParser or and instance of JPAsyncJsonParser, needs to be associated to a Semantic Actions object. If none is specified when a parser is created, the parser itself creates a default one, which is a JPRepresentationGenerator.

Info: A parser sends parse events to the semantic actions object as they appear in the JSON text. The task of a semantic actions object is to handle these events appropriately.

All semantic actions classes shall inherit from . JPSemanticActionsBase implements all required common aspects for a semantic actions object.

Semantic actions classes shall conform to the protocol JPSemanticActionsProtocol.

There are two “built-in” semantic actions classes inheriting from JPSemanticActionsBase:

Setting Up Handler Blocks

An JPSemanticActions class provides four Blocks (callbacks) which handle principal events:

  • Notifying the start of a JSON text
  • Notifying the end of a JSON text
  • Notifying the completion of a semantic actions task
  • Notifying a possible error

These principal handlers are common to all semantic actions classes. They will be implemented using Blocks and the class provides properties to access them.

For a description of each, see section Handlers and Dispatch Queue.

Tasks

Initialization

Configuration

Parse Options

Set and Retrieve Error State

Handlers and Dispatch Queue

Retrieving Result

Properties

completionHandlerBlock

Sets or returns the completion handler block of type void (^)(void).

@property (nonatomic, copy) JPSemanticActions_CompletionHandlerBlockType completionHandlerBlock

Discussion

If the property is not NULL, the completion block is called when the JSON parser finished parsing, regardless if there has been a parse error signaled via the error handler block during parsing. The start of the JSON parser was previously signaled by calling the startJsonHandlerBlock block.

Note that the error handler may be possibly called before the JSON parser even started parsing, e.g. when JPJsonParser and JPAsyncJsonParser detect an error during determining the input encoding. In this case, the JSON parser will not be started, and consequently, startJsonHandlerBlock and completionHandlerBlock will not be called. completionBlock may be set to NULL.

Declared In

JPSemanticActionsBase.h

endJsonHandlerBlock

Sets or returns the endJson handler block of type void (^)(id result).

@property (nonatomic, copy) JPSemanticActions_EndJsonHandlerBlockType endJsonHandlerBlock

Discussion

The endJsonHandlerBlock is called when the parser has successfully parsed a JSON text and the semantic actions instance was able to create a result (e.g. a JSON representation created upon Foundation objects) from this JSON text. The result will be passed in parameter result. If property parseMultipleDocuments equals YES this block will be called for each result which will be created by the semantic actions instance.

If property parseMultipleDocumentsAsynchronously returns NO (the default) the parser’s thread is blocked until the handler finishes. This is a measurement to balance the process of generating result objects (e.g. JSON representations as Foundation objects) – which may tie up a large amount of system resources – with the actual processing of this result – which may free these resources again. Otherwise, if parseMultipleDocumentsAsynchronously returns YES, the parser will immediately continue to parse the input source on its own thread. Be carefully, when considering parseMultipleDocumentsAsynchronously set to YES.

endJsonHandlerBlock may be set to nil.

Declared In

JPSemanticActionsBase.h

error

Returns the error object from the receiver or nil if there is no error.

@property (weak, atomic, readonly) NSError *error

Declared In

JPSemanticActionsBase.h

errorHandlerBlock

Sets or retrieves the error handler block of type void (^)(NSError*).

@property (nonatomic, copy) JPSemanticActions_ErrorHandlerBlockType errorHandlerBlock

Discussion

The errorHandlerBlock will be called when an error has been detected by the JPJsonParser/JPAsyncJsonParser during determining the input encoding, by the JSON parser during parsing, or by the semantic actions instance while per- forming a semantic action. errorHandlerBlock may be set to NULL in which case no errors will be reported by this means.

Declared In

JPSemanticActionsBase.h

generateEncodedStrings

Sets or returns the option whether the receiver will get passed encoded JSON strings.

@property (nonatomic, assign) BOOL generateEncodedStrings

Discussion

Usually, a semantic actions object will require a properly decoded JSON string that matches the orginal source string. If this options is enabled however, the underlaying parser passes properly encoded JSON Strings in method -parserFoundKeyValuePairBeginWithKey:length:encoding:index: and -parserFoundString:length:hasMore:encoding:. That is, the string is encoded as required by RFC 4627.

Otherwise (the default), the parser passes properly decoded JSON strings to the receiver which match the original source string.

This option corresponds to JPJsonParserOptions flag JPJsonParserEncodedStrings.

Default: NO

Declared In

JPSemanticActionsBase.h

handlerDispatchQueue

Returns or sets the dispatch queue where handler blocks will be scheduled.

@property (nonatomic, assign) dispatch_queue_t handlerDispatchQueue

Discussion

The dispatch queue will be retained – with function dispatch_retain(). If the property is set to NULL, handler blocks will not be called. The dispatch queue must only be modified before a parser associated to the receiver is not yet started.

Warning: Setting a dispatch queue while a parser is started, may result in a crash.

The value shall be a concurrent or a serial dispatch queue or NULL.

Declared In

JPSemanticActionsBase.h

ignoreSpuriousTrailingBytes

Sets or returns the parse option “ignoreSpuriousTrailingBytes”.

@property (nonatomic, assign) BOOL ignoreSpuriousTrailingBytes

Discussion

If this options is set, the parser will not treat any additional characters which may occur after the last significant character of a valid JSON document as an error. Otherwise, any code units which can not be interpreted as white-space Unicode characters, except Unicode NULL (U+0000) and an EOF, following a JSON document will cause an error. Unicode NULL and EOF will issue a warning.

Default: NO

Declared In

JPSemanticActionsBase.h

logLevel

Sets or returns the log level of the semantic actions instance and the underlaying JSON parser.

@property (nonatomic, assign) JPSemanticActionsLogLevel logLevel

Discussion

Possible values are constants defined in enumeration JPSemanticActionsLogLevel:

  • JPSemanticActionsLogLevelDebug Verbose logging.
  • JPSemanticActionsLogLevelWarning Logs warning messages as well as errors.
  • JPSemanticActionsLogLevelError Logs only error messages.
  • JPSemanticActionsLogLevelNone Does not log anything.

Default: JPSemanticActionsLogLevelError

Declared In

JPSemanticActionsBase.h

nonConformanceOptions

Sets or returns the strictness of the underlaying JSON parser.

@property (nonatomic, assign) JPSemanticActionsNonConformanceOptions nonConformanceOptions

Discussion

Possible values are ored flags which are defined in enumeration JPSemanticActionsNonConformanceOptions:

  • JPSemanticActionsAllowNone
  • JPSemanticActionsAllowComments
  • JPSemanticActionsAllowControlCharacters
  • JPSemanticActionsAllowLeadingPlusInNumbers
  • JPSemanticActionsAllowLeadingZerosInIntegers

Default: JPSemanticActionsAllowNone

Declared In

JPSemanticActionsBase.h

parseMultipleDocuments

Sets or returns the parse option “parseMultipleDocuments”.

@property (nonatomic, assign) BOOL parseMultipleDocuments

Discussion

If this option is set, the parser parses more than one document from the input until it receives an EOF in the input data.

This flag becomes especially useful if the parser will be fed from a “stream” of JSON documents – possibly from input downloaded in a single network connection supporting a “Streaming API”.

Default: NO

Declared In

JPSemanticActionsBase.h

parseMultipleDocumentsAsynchronously

Sets or returns the parse option “parseMultipleDocumentsAsynchronously”.

@property (nonatomic, assign) BOOL parseMultipleDocumentsAsynchronously

Discussion

If this option is set, the parser invokes the jsonObjectHandlerBlock asynchronously and immediately processes the next JSON document within the input data. The JSON container is then retained in the dispatch queue till it is processed by the client. This may tie up a lot of system resources if the client processes frees the JSON containers slowly. If the flag is NO, the parser’s thread is blocked until the handler routine returns.

It is recommended to leave this flag disabled in systems where system resources are scarce or if the data input possibly contains many and large JSON documents. When downloading large data, this helps throttling the consumption of system resources by the underlaying network layer.

Default: NO

Declared In

JPSemanticActionsBase.h

result

Returns nil.

@property (nonatomic, readonly) id result

Return Value

An object if a result is available, otherwise nil.

Discussion

This method may be overridden by subclasses in order to return the result of the semantic actions.

Declared In

JPSemanticActionsBase.h

startJsonHandlerBlock

Sets or returns the startJson handler block of type void (^)(void).

@property (nonatomic, copy) JPSemanticActions_StartJsonHandlerBlockType startJsonHandlerBlock

Discussion

This handler block will be called when the JSON parser has found the start of a JSON root element within the input text. If property parseMultipleDocuments equals YES this block will be called each time a the parsers detects the start of a JSON root element.

Note, that this handler will only be called after the JSON parser actually has been started, which only happens after determining the input encoding, which possibly can fail.

startJsonHandlerBlock can be set to nil.

Declared In

JPSemanticActionsBase.h

unicodeNoncharacterHandling

Sets or returns the policy for handling Unicode noncharacters of the receiver and the underlaying JSON parser.

@property (nonatomic, assign) JPSemanticActionsUnicodeNoncharacterHandling unicodeNoncharacterHandling

Discussion

Possible values are constants defined in enumeration JPSemanticActionsUnicodeNoncharacterHandling:

  • JPSemanticActionsSignalErrorOnUnicodeNoncharacter
  • JPSemanticActionsSubstituteUnicodeNoncharacter
  • JPSemanticActionsSkipUnicodeNoncharacters

Default: JPSemanticActionsSignalErrorOnUnicodeNoncharacter

Declared In

JPSemanticActionsBase.h

Instance Methods

configureWithOptions:

Configures a JPSemanticActionsBase instance with the specified options.

- (void)configureWithOptions:(JPJsonParserOptions)options

Parameters

options

A set of ored flags from constants of enum JPJsonParserOptions.

This method will be invoked internally from JPJsonParser’s convenience methods. The receiver will set only those options which are “understood” by the receiver. “Unknown” flags will be ignored and may be used in subclasses. A subclass shall invoke super.

For possible values for options see .

Declared In

JPSemanticActionsBase.h

init

Initializes a JPSemanticActions instance with a private default dispatch queue.

- (id)init

Discussion

The receiver creates a serial dispatch queue where handler blocks will be scheduled.

Declared In

JPSemanticActionsBase.h

initWithHandlerDispatchQueue:

Designated Initializer

- (id)initWithHandlerDispatchQueue:(dispatch_queue_t)handlerQueue

Parameters

handlerQueue

The dispatch queue where handler blocks will be scheduled, or nil, in which case no handlers will be executed.

Discussion

Initializes a JPSemanticActionsBase instance with the specified dispatch queue. If parameter handlerQueue equals nil no dispatch queue will be used and no handler blocks will be scheduled.

Declared In

JPSemanticActionsBase.h

setErrorCode:description:

Set error and description.

- (void)setErrorCode:(int)error description:(NSString *)description

Parameters

error

An integer indicating the error code. error should be negative.

description

A string describing the error.

Discussion

Allows a client, that is a JPJsonParser and JPAsyncJsonParser instance, to set an error code and an associated description which is saved by the semantic actions instance. This is useful in cases where the clients itself detect a error and want the semantic actions instance to safe the error information on behalf of the clients since they lack an interface which let users access the error state.

JPJsonParser and JPAsyncJsonParser set the error state when they detect unexpected errors not caught by the semantic actions instance, or when they detect errors during determining the input encoding.

Declared In

JPSemanticActionsBase.h