Package baljsn

Detailed Description

Basic Application Library JSoN (baljsn)

• Purpose
• Mnemonic
• Description
  • Hierarchical Synopsis
  • Component Synopsis
  • Encoding Format
  • validateInputIsUtf8 Option

Purpose

Provide components for encoding/decoding in the JSON format.

Mnemonic

Basic Application Library JSoN (baljsn)

Description

The baljsn package provides facilities for encoding and decoding value-semantic objects in the JSON encoding format. Currently, the encoder and decoder provided in this package work with types that support the bdeat framework (see the bdlat package for details), which is a compile-time interface for manipulating struct-like and union-like objects. Typical usage is illustrated in the baljsn_encoder and baljsn_decoder components documentation.

There are 2 sets of the encoding/decoding member functions:

1. encode & decode, and
2. encodeAny & decodeAny (referred as "any-functions" below).

The first set uses templates and compile-time metaprogramming to generate the encoding/decoding C++ code. The second set uses the runtime dispatch approach - base classes and virtual functions - to provide the same functionality. The result does not depend on the functions you use - their functionality is absolutely identical. The difference is not in what they do, but in how they do it.

As usual, the compile-time approach can be faster, but generates a lot of code. And since this code is in the headers, this causes big load on the compiler and linker - the generated code is in each translation unit and in the object file generated from it. As a result, slow compilation, huge memory and CPU consumption during the compilation and linking, and a larger resulting executable file size.

All the above mentioned shortcomings (except the final runtime performance) can be mitigated by using the "any-functions", at the cost of a small runtime slowdown. All the encoding/decoding code is pre-compiled and located in one place - the BDE library (archive) files. But how big is the execution slowdown? Our benchmarks show that the slowdown is less than 10%.

Hierarchical Synopsis

The 'baljsn' package currently has 20 components having 8 levels of physical dependency. The list below shows the hierarchical ordering of the components. The order of components within each level is not architecturally significant, just alphabetical.

  8. baljsn_jsonconverter
 
  7. baljsn_decoder
 
  6. baljsn_encoder
 
  5. baljsn_datumutil
     baljsn_encodeimplutil
     baljsn_jsonformatter
     baljsn_jsonparserutil
 
  4. baljsn_formatter
     baljsn_parserutil
     baljsn_simpleformatter
 
  3. baljsn_printutil
 
  2. baljsn_datumdecoderoptions
     baljsn_datumencoderoptions
     baljsn_decoderoptionsutil
     baljsn_encoderoptions
     baljsn_jsontokenizer
 
  1. baljsn_decoderoptions
     baljsn_encoder_testtypes                                         !PRIVATE!
     baljsn_encodingstyle
     baljsn_tokenizer

Component Synopsis

baljsn_datumdecoderoptions : Provide options for decoding JSON into a Datum object.

baljsn_datumencoderoptions : Provide an attribute class for specifying Datum<->JSON options.

baljsn_datumutil : Provide utilities converting between bdld::Datum and JSON data.

baljsn_decoder : Provide a JSON decoder for bdeat compatible types.

baljsn_decoderoptions : Provide an attribute class for specifying JSON decoding options.

baljsn_decoderoptionsutil : Provide a utility for configuring baljsn::DecoderOptions.

baljsn_encodeimplutil : Provide a utility to encode bdlat-compatible types as JSON.

baljsn_encoder : Provide a JSON encoder for bdlat-compatible types.

baljsn_encoder_testtypes : !PRIVATE! Provide value-semantic attribute classes

baljsn_encoderoptions : Provide an attribute class for specifying JSON encoding options.

baljsn_encodingstyle : Provide value-semantic attribute classes.

baljsn_formatter : Provide a formatter for encoding data in the JSON format.

baljsn_jsonconverter : Provide conversions between JSON and bdlat-compatible types.

baljsn_jsonformatter : Provide a formatter for converting bdlat object to Json analog.

baljsn_jsonparserutil : Provide a utility to get simple types from bdl::json objects

baljsn_jsontokenizer : Provide a tokenizer for viewing parts of a bdljsn::Json object.

baljsn_parserutil : Provide a utility for decoding JSON data into simple types.

baljsn_printutil : Provide a utility for encoding simple types in the JSON format.

baljsn_simpleformatter : Provide a simple formatter for encoding data in the JSON format.

baljsn_tokenizer : Provide a tokenizer for extracting JSON data from a streambuf.

Encoding Format

The following table provides a mapping between an element's 'bdem' elem type (as specified in bdem_elemtype ), its XSD type, its C++ type, its corresponding JSON type, and the encoding used.

BDEM type         XSD type      C++ Type         JSON type       Format
---------         --------      --------         ---------       ------
BDEM_VOID         N/A           N/A              null            Encoding error
 
BDEM_BOOL         boolean       bool             true/false      <BOOLEAN>
 
BDEM_CHAR         byte          char             number/string   <NUMBER>
 
BDEM_SHORT        short         short            number/string   <NUMBER>
 
                  unsignedByte  unsigned char    number/string   <NUMBER>
 
BDEM_INT          int           int              number/string   <NUMBER>
 
                  unsignedShort unsigned short   number/string   <NUMBER>
 
BDEM_INT64        integer       Int64            number/string   <NUMBER>
 
                  long          Int64            number/string   <NUMBER>
 
                  unsignedInt   unsigned int     number/string   <NUMBER>
 
                  unsignedLong  unsigned Uint64  number/string   <NUMBER>
 
BDEM_FLOAT        float         float            number/string   <DOUBLE>
 
BDEM_DOUBLE       decimal       double           number/string   <DOUBLE>
 
                  double        double           number/string   <DOUBLE>
 
BDEM_STRING       string        bsl::string      string          <STRING>
 
BDEM_DATETIME     dateTime      bdlt::Datetime   string          "<DATETIME>"
 
BDEM_DATETIMETZ   dateTime      bdlt::DatetimeTz string          "<DATETIMETZ>"
 
BDEM_DATE         date          bdlt::Date       string          "<DATE>"
 
BDEM_DATETZ       date          bdlt::DateTz     string          "<DATETZ>"
 
BDEM_TIME         time          bdlt::Time       string          "<TIME>"
 
BDEM_TIMETZ       time          bdlt::TimeTz     string          "<TIMETZ>"
 
BDEM_CHAR_ARRAY   base64Binary  vector<char>     string          "<BASE64STR>"
 
                  hexBinary     vector<char>     string          "<BASE64STR>"
 
BDEM_TYPE_ARRAY   maxOccurs > 1 vector<TYPE>     array           <SIMPLE_ARRAY>
 
BDEM_LIST         sequence      bcem_Aggregate   object          <SEQUENCE>
 
BDEM_TABLE        maxOccurs > 1 bcem_Aggregate   array of objs   <SEQ_ARRAY>
 
BDEM_CHOICE       choice        bcem_Aggregate   object          <CHOICE>
 
BDEM_CHOICE_ARRAY maxOccurs > 1 bcem_Aggregate   array of objs   <CHOICE_ARRAY>
 
BDEM_INT          enumeration   C++ enumeration  string/number   "<NUMBER>"
 
BDEM_STRING       enumeration   C++ enumeration  string          <STRING>
 
BDEM_*            minOccurs = 0 NullableValue    null            <NULL_VALUE>

• The exact syntax of the format is specified below.
• BDEM_TYPE_ARRAY refers to all the types supported by bdem (such as BDEM_INT_ARRAY, BDEM_STRING_ARRAY etc) including BDEM_CHAR_ARRAY. A 'vector<char>' that is not specified with the 'xs:base64Binary' or 'xs:hexBinary' is treated similarly to vector of any scalar type. Vectors of nullable scalar types (specified via the 'xs:nillable' attribute) are encoded similar to their vector of non-nullable scalar types except that their elements could also be specified as 'null'.
• Integral types are always encoded in the <NUMBER> format and int-valued enumerations are always encoded in the "<NUMBER>" format, but during decoding both of these formats are supported for both of these categories of types. This flexibility applies to all integral types, including ones that do not support an enumeration constraint.

The format grammar specified below uses the Extended BNF notation (except that ',' is not used for concatenation to enhance readability). A quick reference of EBNF is provided below (refer here for more details):

|       is used to select between alternate options
[ ... ] (square brackets) are used to specify an optional item
{ ... } (curly brackets) are used to specify an item that can be repeated zero
         or more times
( ... ) (parenthesis) are used to group elements
 
<VOID>            Results in an encoding error
 
<BOOLEAN>         'true' | 'false';
 
<STRING>          Same as the spec for 'string' on http://www.json.org;
 
<NUMBER>          Same as the spec for 'number' on http://www.json.org;
 
<DOUBLE_STRING>   "NaN" | "+INF" | "-INF";
 
<DOUBLE>          <NUMBER> | <DOUBLE_STRING>; (1)
 
<DATE>            <YEAR>'-'<MONTH>'-'<DAY>; (2)
 
<DATETZ>          <DATE><TZ>;
 
<TIME>            <HOUR>':'<MINUTES>':'<SECONDS>[<MILLISEC>]; (2)
 
<TIMETZ>          <TIME><TZ>;
 
<DATETIME>        <DATE>'T'<TIME>; (2)
 
<DATETIMETZ>      <DATETIME><TZ>;
 
<BASE64STR>       Strings encoded in base 64 encoding;
 
<SEQUENCE>        '{' '}' | '{' <MEMBER> {',' <MEMBER> } '}';
 
<CHOICE>          '{' <MEMBER> '}';
 
<SIMPLE_ARRAY>    '[' ']' | '[' <VALUE> {',' <VALUE> } ']';
 
<SEQ_ARRAY>       '[' ']' | '[' <SEQUENCE> {',' <SEQUENCE> } ']';
 
<CHOICE_ARRAY>    '[' ']' | '[' <CHOICE> {',' <CHOICE> } ']';
 
<NULL>            'null';
 
<NULL_VALUE>      <NULL> | ''; (3)
 
<NAME>            <STRING>; (4)
 
<SIMPLE>          <NUMBER> | <STRING> | '"' <DATE> '"' | '"' <DATETZ> '"'
                           | '"' <TIME> '"' | '"' <TIMETZ> '"'
                           | '"' <DATETIME> '"' | '"' <DATETIMETZ> '"'
                           | '"' <BASE64STR> '"';
 
<VALUE>           <NULL> | <SIMPLE> | <SEQUENCE> | <CHOICE> | <SIMPLE_ARRAY>
                         | <COMPLEX_ARRAY>;
 
<MEMBER>          <NAME>':'<VALUE>;
 
<SIGN>            '+' | '-';
 
<POSITIVE_DIGIT>  '1' | '2' | '3' | '4' | '5' | '6' | '7' | '8' | '9';
 
<DIGIT>           '0' | <POSITIVE_DIGIT>;
 
<YEAR>            <DIGIT><DIGIT><DIGIT><POSITIVE_DIGIT>;
 
<MONTH>           '0' <POSITIVE_DIGIT> | '1' ( '0' | '1' | '2' );
 
<DAY>             ( '0' | '1' | '2' ) <POSITIVE_DIGIT> | '3' ( '0' | '1' );
 
<HOUR>            ( '0' | '1' ) <DIGIT> | '2' ( '0' | '1' | '2' | '3');
 
<MINUTES>         ( '0' | '1' | '2' | '3' | '4' | '5' ) <DIGIT>;
 
<SECONDS>         ( '0' | '1' | '2' | '3' | '4' | '5' ) <DIGIT>;
 
<MILLISEC>        '.' <DIGIT> { <DIGIT> };
 
<TZ>              <SIGN><HOUR>':'<MINUTES> | 'Z' | 'z';

(1) Double types (float, decimal, and double) are encoded in the number format by default with the values NaN, +INF and -INF resulting in an encoding error. These values can be printed as strings by setting the 'encodeInfAndNaNAsStrings' encoder option to 'true'.

(2) In practice only the timezone-enabled components are used by bcem_Aggregate and generated types. The supported format is a subset of the ISO 8601 standard. For further details refer to the bdepu_iso8601 component.

(3) Null values are not encoded on the wire by default. The 'encodeNullElements' options can be set to 'true' to ensure that null values are encoded.

(4) The name of an element corresponds to that element's name in the provided xsd.

validateInputIsUtf8 Option

The 'baljsn::DecoderOption' parameter of the 'decode' function has a configuration option named 'validateInputIsUtf8'. If this option is 'true', the 'decode' function will succeed only if the encoding of the JSON data is UTF-8, which the JSON specification requires. If the option is 'false', 'decode' will not validate that the encoding of the JSON data is UTF-8, and may succeed even if the data does not satisfy the UTF-8 validity requirement of the JSON specification. This option primarily affects the acceptance of string literals, which are the parts of JSON documents that may have rational justification for having non-UTF-8, and therefore invalid, content.

Ideally, users should set 'validateInputIsUtf8' to 'true'. However, some legacy applications currently might be trafficking in JSON that contains non-UTF-8 with no adverse effects to their clients. Consequently, this option is 'false' by default to maintain backward compatibility.

Modules
	baljsn_convertfromjsonoptions
	baljsn_converttojsonoptions
	baljsn_datumdecoderoptions
	baljsn_datumencoderoptions
	baljsn_datumutil
	baljsn_decoder
	baljsn_decoderoptions
	baljsn_decoderoptionsutil
	baljsn_encodeimplutil
	baljsn_encoder
	baljsn_encoder_testtypes
	baljsn_encoderoptions
	baljsn_encodingstyle
	baljsn_formatter
	baljsn_jsonconverter
	baljsn_jsonformatter
	baljsn_jsonparserutil
	baljsn_jsontokenizer
	baljsn_parserutil
	baljsn_printutil
	baljsn_simpleformatter
	baljsn_tokenizer