JSON DOM Interfaces

17 JSON DOM Interfaces

The JSON Interface for DOM C APIs are grouped into the following sections:

17.1 JSON DOM Functions

The following table summarizes the methods available through the JSON interface of DOM for C APIs.

Table 17-1 Summary of DOM Methods for JSON C Implementation

Function	Summary
JsonDomGetRoot	Returns the root node of a DOM, which is one of the three types of nodes.
JsonDomSetRoot	Sets the specified node as the root.
JsonDomGetNumFields	Returns the number of fields within the object.
JsonDomGetArraySize	Returns the number of elements within the array.
JsonDomGetElements	Returns a set of elements from an array in a batch interface.
JsonDomGetNodeType	Returns the type of the node.
JsonDomGetScalarInfoOci	Returns the value information from the scalar node.
JsonDomCreateObject	Creates a new orphan DOM object node.
JsonDomCreateOCIInterval	Creates a new DOM scalar node of OCIInterval type.
JsonDomCreateArray	Creates a new orphan DOM array node.
JsonDomCreateString	Creates a new orphan DOM scalar node of string type.
JsonDomCreateBinary	Creates a new orphan DOM scalar node of binary type.
JsonDomCreateFloat	Creates a new orphan DOM scalar node of float type.
JsonDomCreateDouble	Creates a new orphan DOM scalar node of double type.
JsonDomCreateBoolean	Creates a new orphan DOM scalar node of boolean type.
JsonDomCreateOCINumber	Creates a new orphan DOM scalar node of `NUMBER` type from an OCINumber input.
JsonDomCreateOCIDate	Creates a new orphan DOM scalar node of date type.
JsonDomCreateOCIDateTime	Create a new orphan DOM scalar node of type `DATE`, `TIMESTAMP`, or `TIMESTAMP WITH TIME ZONE` from an OCIDateTime type.
JsonDomCreateNull	Creates a new orphan DOM scalar node of null type.
JsonDomSetField	Sets the value of the specified field to the specified object within DOM.
JsonDomAppendElement	Append an orphan node as a new element in an array, at the last position within the array.
JsonDomFreeNode	Free an orphan node and all its descendants.
JsonDomGetError	Returns an error code for a DOM operation that failed.
JsonDomClearError	Clear the error code for the DOM.
JsonDomGetErrorMessage	Returns a rendered error message for the current DOM error code.

17.1.1 JsonDomGetRoot()

Returns the root node of a DOM, which is one of the three types of nodes (although rare, a scalar with no children is a valid JSON document per the RFC).

Syntax

JsonDomNode *JsonDomGetRoot(
      JsonDomDoc    *jdoc
);

Parameter	In/Out	Description
jdoc	IN	JSON DOM Container

Returns

(JsonDomNode *) root node for the DOM (or NULL if none is set).

Note:

The orphan nodes cannot be accessed by descending the tree starting from the root.
Check the error code by calling JsonDomGetGetError() before proceeding.

17.1.2 JsonDomSetRoot()

Sets the specified node as the root.

The new node may be a NULL. The new root must be an orphan node, that is, it cannot be a node that exists within the tree descending from the old root, if any.

Orphan nodes are created by constructors, or by copying node(s) from another DOM document, or by unlinking them from the DOM tree.

Syntax

void  JsonDomSetRoot(  
    JsonDomDoc     *jdoc,
    JsonDomNode    *root
);

Parameter	In/Out	Description
jdoc	IN	JSON DOM Container
root	IN	Orphan node within the DOM

Returns

(ub4) A count of the number of fields within the object.

Note:

The old root and all descendants are freed.
Check the error code by calling JsonDomGetGetError() before proceeding.

17.1.3 JsonDomGetNumFields()

Returns the number of fields within the object.

Syntax

ub4 JsonDomGetNumFields(  
    JsonDomDoc     *jdoc,  
    JsonDomObject  *obj
);

Parameter	In/Out	Description
jdoc	IN	JSON DOM Container
obj	IN	Object node within the DOM

Returns

(ub4) A count of the number of fields within this object.

17.1.4 JsonDomGetArraySize()

Returns the number of elements within the array.

Orphan nodes are created by constructors, or by copying node(s) from another DOM document, or by unlinking them from the DOM tree.

Syntax

ub4 JsonDomGetArraySize(  
    JsonDomDoc *jdoc,
    JsonDomArray *ary
);

Parameter	In/Out	Description
jdoc	IN	JSON DOM Container
ary	IN	Array node within the DOM

Returns

(ub4) A count of the number of elements within this array.

Note:

Duplicate field names are not allowed in most DOMs.
Check the error code by calling JsonDomGetGetError() before proceeding.

17.1.5 JsonDomGetElements()

Returns a set of elements from an array in a batch interface.

This allows a caller to use a fixed-sized array to iterate over the elements, while still retrieving them in bulk.

Syntax

ub4 JsonDomGetElements(
  JsonDomDoc      *jdoc,
  JsonDomArray    *ary,
  ub4              startPos,
  ub4              fetchSz,
  JsonDomNode     *ndary[]
);

Parameter	In/Out	Description
jdoc	IN	JSON DOM Container
ary	IN	Array node within the DOM
startPos	IN	Starting position (0-based)
fetchSz	IN	Number of elements to retrieve
ndary	OUT	Returns nodes from the array

Returns

(ub4) The number of elements returned in the output node array.

Note:

The first element at start position 0. The iteration is backed directly by the DOM array, so this interface won't work properly if the array undergoes modification during the iteration.
Check the error code by calling JsonDomGetGetError() before proceeding.

17.1.6 JsonDomGetNodeType()

Returns the type of a node.

The possible return values are:

JZNDOM_SCALAR
JZNDOM_ARRAY
JZNDOM_OBJECT

The node may be safely cast to the subclass type. For example, if the return is JZNDOM_SCALAR, the node may be cast to (JsonDomScalar *).

Syntax

jznnodetype JsonDomGetNodeType(
  JsonDomDoc     *jdoc,
  JsonDomNode    *node
);

Parameter	In/Out	Description
jdoc	IN	JSON DOM Container
node	IN	Node within the DOM

Returns

(jznnodetype) the type of node (Object, Array, Scalar).

Note:

Check the error code by calling JsonDomGetGetError() before proceeding.

17.1.7 JsonDomGetScalarInfoOci()

Returns a scalar value in the val structure that must be applied by the caller, often a pointer to a local variable in the calling code.

The return structure is a discriminated union. The value's scalar subtype (for example, JZNVAL_NUMBER) is available as the first member, and the scalar's actual value can be read from the appropriate union member.

Syntax

jsonerr  JsonDomGetScalarInfoOci(
  JsonDomDoc       *jdoc,
  JsonDomScalar    *nd,
  jznScalarVal     *val,
  JsonOCIVal       *aux
);

Parameter	In/Out	Description
jdoc	IN	JSON DOM Container
nd	IN	Scalar node within the DOM
val	OUT	Output scalar value
aux	OUT	Auxiliary output structure

Returns

(jsonerr) An error code. JZNERR_OK (0) indicates no error.

Note:

Oracle native types are unpickled and returned in structured form in auxiliary union of type JsonOCIVal*.
Check the error code by calling JsonDomGetGetError() before proceeding.

17.1.8 JsonDomCreateObject()

Creates a new DOM object node.

The new node is an orphan which is not attached to the DOM tree that descends from the root node.

Syntax

JsonDomObject *JsonDomCreateObject(
  JsonDomDoc    *jdoc
);

Parameter	In/Out	Description
jdoc	IN	JSON DOM Container

Returns

(JsonDomObject *) new orphaned DOM object node.

17.1.9 JsonDomCreateOCIInterval()

Creates a new DOM scalar node of OCIInterval type.

The new node is an orphan which is not attached to the DOM tree that descends from the root node.

Syntax

JsonDomScalar *JsonDomCreateOCIInterval(
  JsonDomDoc     *jdoc,
  OCIInterval    *oinv
);

Parameter	In/Out	Description
jdoc	IN	JSON DOM Container
oinv	IN	OCIInterval Pointer

Returns

(JsonDomScalar *) new orphaned DOM scalar node.

17.1.10 JsonDomCreateArray()

Creates a new DOM array node.

The new node is an orphan which is not attached to the DOM tree that descends from the root node.

Syntax

JsonDomArray *JsonDomCreateArray(
  JsonDomDoc *jdoc
);

Parameter	In/Out	Description
jdoc	IN	JSON DOM Container

Returns

(JsonDomArray *) new orphaned DOM array node.

17.1.11 JsonDomCreateString()

Creates a new DOM scalar node of string type.

The new node is an orphan which is not attached to the DOM tree that descends from the root node. The scalar is set to the value of the string argument sval, which is of length slen.

Syntax

JsonDomScalar *JsonDomCreateString(
  JsonDomDoc      *jdoc,
  oratext         *sval,
  ub4              slen
);

Parameter	In/Out	Description
jdoc	IN	JSON DOM Container
sval	IN	String buffer pointer
slen	IN	Length of the string buffer in bytes

Returns

(JsonDomScalar *) new orphaned DOM scalar node

Note:

The string is copied into the DOM's memory space.

17.1.12 JsonDomCreateBinary()

Creates a new DOM scalar node of binary type.

The new node is an orphan which is not attached to the DOM tree that descends from the root node. The scalar is set to the contents of the byte array bval of length blen.

Syntax

JsonDomScalar *JsonDomCreateBinary(
  JsonDomDoc      *jdoc,
  oratext         *bval,
  ub4              blen
);

Parameter	In/Out	Description
jdoc	IN	JSON DOM Container
bval	IN	Binary buffer pointer
blen	IN	Length of the binary buffer

Returns

(JsonDomScalar *) new orphaned DOM scalar node

Note:

The binary value is copied into the DOM's memory space.

17.1.13 JsonDomCreateFloat()

Creates a new DOM scalar node of float type.

The new node is an orphan which is not attached to the DOM tree that descends from the root node. The scalar is set to the float value fval.

Syntax

JsonDomScalar *JsonDomCreateFloat(
  JsonDomDoc      *jdoc,
  float            fval
);

Parameter	In/Out	Description
jdoc	IN	JSON DOM Container
fval	IN	Float value

Returns

(JsonDomScalar *) new orphaned DOM scalar node

17.1.14 JsonDomCreateDouble()

Creates a new DOM scalar node of double type.

The new node is an orphan which is not attached to the DOM tree that descends from the root node. The scalar value is set to the double value dval.

Syntax

JsonDomScalar *JsonDomCreateDouble(
  JsonDomDoc      *jdoc,
  double           dval
);

Parameter	In/Out	Description
jdoc	IN	JSON DOM Container
dval	IN	Double value

Returns

(JsonDomScalar *) new orphaned DOM scalar node

17.1.15 JsonDomCreateBoolean()

Creates a new DOM scalar node of boolean type.

The new node is an orphan which is not attached to the DOM tree that descends from the root node.

Syntax

JsonDomScalar *JsonDomCreateBoolean(
  JsonDomDoc      *jdoc,
  boolean          bval
);

Parameter	In/Out	Description
jdoc	IN	JSON DOM Container
bval	IN	Boolean value

Returns

(JsonDomScalar *) new orphaned DOM scalar node

17.1.16 JsonDomCreateOCINumber()

Creates a new DOM scalar node of NUMBER type from an OCINumber.

The new node is an orphan which is not attached to the DOM tree that descends from the root node.

Syntax

JsonDomScalar *JsonDomCreateOCINumber(
  JsonDomDoc      *jdoc,
  OCINumber       *onum
);

Parameter	In/Out	Description
jdoc	IN	JSON DOM Container
onum	IN	OCINumber pointer

Returns

(JsonDomScalar *) new orphaned DOM scalar node

17.1.17 JsonDomCreateOCIDate()

Creates a new DOM scalar node of DATE type from an OCIDate.

The new node is an orphan which is not attached to the DOM tree that descends from the root node.

Syntax

JsonDomScalar *JsonDomCreateOCIDate(
  JsonDomDoc      *jdoc,
  OCIDate         *odate
);

Parameter	In/Out	Description
jdoc	IN	JSON DOM Container
odate	IN	OCIDate pointer

Returns

(JsonDomScalar *) new orphaned DOM scalar node

17.1.18 JsonDomCreateOCIDateTime()

Creates a new DOM scalar node of DATE, TIMESTAMP or TIMESTAMP WITH TIME ZONE type from an OCIDateTime.

The new node is an orphan which is not attached to the DOM tree that descends from the root node.

Syntax

JsonDomScalar *JsonDomCreateOCIDateTime(
  JsonDomDoc      *jdoc,
  OCIDateTime     *odtime
);

Parameter	In/Out	Description
jdoc	IN	JSON DOM Container
odtime	IN	OCIDateTime pointer

Returns

(JsonDomScalar *) new orphaned DOM scalar node

17.1.19 JsonDomCreateNull()

Creates a new DOM scalar node of JSON null type.

The new node is an orphan which is not attached to the DOM tree that descends from the root node.

Syntax

JsonDomScalar *JsonDomCreateNull(
  JsonDomDoc      *jdoc
);

Parameter	In/Out	Description
jdoc	IN	JSON DOM Container

Returns

(JsonDomScalar *) new orphaned DOM scalar node

17.1.20 JsonDomSetField()

Sets the value of the specified field to the specified object within DOM.

The field is created if it doesn't exist, otherwise the old value is replaced.

Syntax

jsonerr JsonDomSetField(
  JsonDomDoc       *jdoc,
  JsonDomObject    *obj,
  oratext          *name,
  ub2               namelen,
  JsonDomNode      *node);

Parameter	In/Out	Description
jdoc	IN	JSON DOM Container
obj	IN	Object within the DOM
name	IN	String with field name to create or replace
namelen	IN	Length of field name string
node	IN	Orphan node to set as field value

Returns

(jsonerr) An error code. JZNERR_OK (0) indicates no error.

Note:

The old field value, if any, is freed along with all descendants.

17.1.21 JsonDomAppendElement()

Appends an orphan node as a new element in an array, at the last position within the array.

This function is equivalent to calling JsonDomAddElement and giving the array size as the insertion position.

Syntax

boolean JsonDomAppendElement(
  JsonDomDoc      *jdoc,
  JsonDomArray    *arr,
  JsonDomNode     *node
);

Parameter	In/Out	Description
jdoc	IN	JSON DOM Container
arr	IN	Array within the DOM
node	IN	Orphan node to set an element value

Returns

(boolean). TRUE if the element was appended, else FALSE.

Note:

Check the error code by calling JsonDomGetGetError() before proceeding.

17.1.22 JsonDomFreeNode()

Free an orphan node and all descendants.

Syntax

boolean JsonDomFreeNode(
  JsonDomDoc     *jdoc,
  JsonDomNode    *node
);

Parameter	In/Out	Description
jdoc	IN	JSON DOM Container
node	IN	Node to free within the DOM

Returns

(boolean). TRUE if freed, FALSE if not an orphan.

Note:

The old field value, if any, is freed along with all descendants.

17.1.23 JsonDomGetError()

Returns an error code for a DOM operation that failed.

Syntax

jsonerr JsonDomGetError(
  JsonDomDoc     *jdoc
);

Parameter	In/Out	Description
jdoc	IN	JSON DOM Container

Returns

(jsonerr) An error code. JZNERR_OK (0) indicates no error.

17.1.24 JsonDomGetErrorMessage()

Returns a rendered error message for the current DOM error code.

Syntax

oratext *JsonDomGetErrorMessage(
  JsonDomDoc    *jdoc,
  jsonerr       *err,
  boolean        clear
);

Returns an empty string if there is no current error. Returns the current error code in the optional <err> argument. If <clear> is TRUE, the internal error in the document is cleared.

Parameter	In/Out	Description
jdoc	IN	JSON DOM Container
err	OUT	Error code or `JZNERR_OK (0)` for none
clear	IN	`TRUE` to clear error after reading

Returns

(oratext *) error message string, NULL on memory error.

17.1.25 JsonDomClearError()

Clear the error code for the DOM.

Syntax

void JsonDomClearError(
  JsonDomDoc     *jdoc
);

Parameter	In/Out	Description
jdoc	IN	JSON DOM Container

Returns

(void)

17.2 Constants

The below tables list the different types of constants in JSON.

DOM Node Type Constants

Constant	Description
JZNDOM_OBJECT	Indicates that the DOM node is of object type
JZNDOM_ARRAY	Indicates that the DOM node is of array type
JZNDOM_SCALAR	Indicates that the DOM node is of scalar type

Scalar Value Type Constants

Constant	JSON Value Type
JZNVAL_STRING	String
JZNVAL_ORA_NUMBER	Number
JZNVAL_TRUE	Boolean true
JZNVAL_FALSE	Boolean false
JZNVAL_BINARY	Binary
JZNVAL_DOUBLE	Double
JZNVAL_FLOAT	Float
JZNVAL_ORA_DATE	Date
JZNVAL_ORA_TIMESTAMP	Timestamp
JZNVAL_ORA_DAYSECOND_DUR	Day-second Interval
JZNVAL_ORA_YEARMONTH_DUR	Year-month interval
JZNVAL_ORA_TIMESTAMPTZ	Timestamp with time zone
JZNVAL_NULL	JSON null

Note:

The constants JZNVAL_DOUBLE and JZNVAL_FLOAT map to IEEE FLOAT and DOUBLE respectively, which are most commonly used in programming languages.

JSON Validation Constants

Constant	Description
JZN_ALLOW_NONE	Strict conformance to JSON specification.
JZN_ALLOW_UNQUOTED_NAMES	Object field names can appear without being enclosed in double quotes. Example: `{a: 123}`
JZN_ALLOW_SINGLE_QUOTES	Field names and string items can optionally be enclosed in single quote marks. Example: `{'a': 'cat'}`
JZN_ALLOW_UNQUOTED_UNICODE	Allow non-ASCII characters to appear in unquoted field names.
JZN_ALLOW_NUMERIC_QUIRKS	Allow common numeric formats that are not strictly conforming to JSON specification. Example: `+.123`
JZN_ALLOW_CONTROLS_WHITESPACE	Allow ASCII control characters to appear where insignificant whitespace is allowed (normally restricted to tab, newline, carriage-return). Example: a form-feed character
JZN_ALLOW_TRAILING_COMMAS	Allow a trailing comma to appear in a container without a following item or field/value pair. Example: `[1,2,3,]`
JZN_ALLOW_MIXEDCASE_KEYWORDS	Allow keywords to appear in any case. Normally they are required to be in lower case. Examples: `NULL, True`
JZN_ALLOW_SCALAR_DOCUMENTS	Allow a single scalar item to be considered a valid JSON document. The older RFC required that a document be one of the two container types. The newer RFC allows any item, which includes scalars.
JZN_ALLOW_LEADING_BOM	Allow a byte-order-mark to appear as the first character of a JSON document, even if the document is encoded in UTF-8. Normally it's restricted to UTF-16 documents only.
JZN_ALLOW_ALL	Turns on all of the above flags.

Note:

The JSON validation constants are bit flags and they can be used in combination.

JSON Encoding Constants

Constant	Description
JZN_INPUT_UTF8	Input is UTF-8 encoding
JZN_INPUT_DETECT	Encoding of the input needs to be detected
JZN_INPUT_CONVERT	Input requires character set conversion

JSON Printing Constants

Constant	Description
JZNU_PRINT_PRETTY	Render textual JSON pretty printed
JZNU_PRINT_ASCII	Render textual JSON with native ASCII, with escape
JZNU_PRINT_NUMFORMAT	Render textual JSON with numbers printed canonically