JSON Component
Properties Methods Events Configuration Settings Errors
The JSON component can be used to parse and write JSON documents.
Syntax
TipwJSON
Remarks
The JSON component offers a fast and simple way to parse and write information in JSON documents.
Parsing JSON
The JSON component parses JSON documents and verifies that they are well-formed. The results are provided through a set of events.
In addition, the document structure may be queried through an XPath mechanism that supports a subset of the XPath and JSONPath specification.
The parser is optimized for read applications, with a very fast engine that builds internal DOM structures with close to zero heap allocations. Additionally, BuildDOM can be set to False which reduces the overhead of creating the DOM and offers a fast forward-only parsing implementation which fires events to provide the parsed data.
When parsing a document events will fire to provide information about the parsed data. After Parse returns the document may be navigated by setting XPath if BuildDOM is True (default). If BuildDOM is False parsed data is only accessible through the events.
The following events will fire during parsing:
If BuildDOM is True (default), XPath may be set after this method returns. XPath may be set to navigate to specific elements within the JSON document. This will be the path to a specified value within the document. Since arrays in JSON only contain values, and no associated object name, an empty name will be used for these values. To reach an array element at position 1, the path must be set to "[1]". In addition, a root element named "json" will be added to each JSON document in the parser.
BuildDOM must be set to True prior to parsing the document for the XPath functionality to be available.
The XPath property accepts both XPath and JSONPath formats. Please see notes below on both formats.
XPath
The path is a series of one or more element accessors separated by '/'. The path can be absolute (starting with '/') or relative to the current XPath location.
The following are possible values for an element accessor:
'name' | A particular element name. |
[i] | The i-th subelement of the current element. |
.. | the parent of the current element. |
- XElement
- XElementType
- XParent
- XText
- XSubTree
- XChildren*
BuildDOM must be set to True prior to parsing the document for the XPath functionality to be available.
Simple JSON document
{ "firstlevel": { "one": "value", "two": ["first", "second"], "three": "value three" } }Example (Setting XPath)
Document root | JsonControl.XPath = "/" |
Specific Element | JsonControl.XPath = "/json/firstlevel/one/" |
i-th Child | JsonControl.XPath = "/json/firstlevel/two/[i]/" |
JSONPath
This property implements a subset of the JSONPath notation. This may be set to point to a specific element in the JSON document.The JSONPath is a series of one or more accessors in either dot-notation
$.store.book[0].titleOr bracket-notation
$['store']['book'][0]['title']
After setting XPath the following properties are populated:
- XChildren
- XElement
- XElementType
- XSubTree
- XText
Given the following JSON document:
{ "store": { "book": [ { "category": "reference", "author": "Nigel Rees", "title": "Sayings of the Century", "price": 8.95 }, { "category": "fiction", "author": "Evelyn Waugh", "title": "Sword of Honour", "price": 12.99 }, { "category": "fiction", "author": "Herman Melville", "title": "Moby Dick", "isbn": "0-553-21311-3", "price": 8.99 }, { "category": "fiction", "author": "J. R. R. Tolkien", "title": "The Lord of the Rings", "isbn": "0-395-19395-8", "price": 22.99 } ], "bicycle": { "color": "red", "price": 19.95 } }, }The following code shows several examples.
Get the first book's author:
json.XPath = "$.store.book[0].author"; Console.WriteLine(json.XText); //Output //"Nigel Rees"Select the first book and inspect the children:
json.XPath = "$.store.book[0]"; Console.WriteLine("Child Count: " + json.XChildren.Count); Console.WriteLine(json.XChildren[1].Name + ": " + json.XChildren[1].XText); //Output //Child Count: 4 //author: "Nigel Rees"Get the price of the second book:
json.XPath = "$['store']['book'][1]['price']"; Console.WriteLine(json.XText); //Output //12.99Get the second to last book's author:
json.XPath = "$['store']['book'][last() - 1]['author']"; Console.WriteLine(json.XText); Console.WriteLine(json.XPath); //Note that "last() - 1" is resolved to "3". //Output //"Herman Melville" //$['store']['book'][3]['author']Display the full subtree at the current path:
json.XPath = "$.store.book[0]"; Console.WriteLine(json.XSubTree); //Output // { // "category": "reference", // "author": "Nigel Rees", // "title": "Sayings of the Century", // "price": 8.95 // }
Input Properties
The component will determine the source of the input based on which properties are set.
The order in which the input properties are checked is as follows:
When a valid source is found the search stops.If parsing multiple documents call Reset between documents to reset the parser.
Writing JSON
The JSON component can also be used to create a JSON document.
The document is written to the selected output property. In addition as the document is written, the JSON event will fire. The Text event parameter contains the part of the document currently being written.
Output Properties
The component will determine the destination of the output based on which properties are set.
The order in which the output properties are checked is as follows:
- OutputFile
- OutputData: The output data is written to this property if no other destination is specified.
Example
Writing a simple JSON document describing a pet:
Json json = new Json(); json.OutputFile = "C:\\temp\\fido.json"; json.StartObject(); json.PutProperty("name", "fido", 2); json.PutName("previousOwners"); json.StartArray(); json.PutValue("Steve Widgetson", 2); json.PutValue("Wanda Widgetson", 2); json.PutValue("Randy Cooper", 2); json.PutValue("Linda Glover", 2); json.EndArray(); json.PutProperty("weightUnit", "lbs", 2); json.PutProperty("weight", "62", 3); json.EndObject(); json.Flush();
This example results in the following JSON:
{ "name": "fido", "previousOwners": [ "Steve Widgetson", "Wanda Widgetson", "Randy Cooper", "Linda Glover" ], "weightUnit": "lbs", "weight": 62 }
When writing multiple documents call Reset between documents to reset the writer.
Property List
The following is the full list of the properties of the component with short descriptions. Click on the links for further details.
BuildDOM | When True, an internal object model of the JSON document is created. |
InputData | The JSON data to parse. |
InputFile | The file to process. |
OutputData | The output JSON after processing. |
OutputFile | The path to a local file where the output will be written. |
Overwrite | Indicates whether or not the component should overwrite files. |
Validate | When True, the parser checks that the document consists of well-formed XML. |
XChildCount | The number of records in the XChild arrays. |
XChildName | The Name property provides the name of the element. |
XChildXText | This property contains the text of the element. |
XCommentCount | The number of records in the XComment arrays. |
XCommentText | This property holds the comment text. |
XElement | The name of the current element. |
XElementType | Indicates the data type of the current element. |
XErrorPath | An XPath to check the server response for errors. |
XParent | The parent of the current element. |
XPath | Provides a way to point to a specific element in the response. |
XSubTree | A snapshot of the current element in the document. |
XText | The text of the current element. |
Method List
The following is the full list of the methods of the component with short descriptions. Click on the links for further details.
Config | Sets or retrieves a configuration setting . |
EndArray | Writes the closing bracket of a JSON array. |
EndObject | Writes the closing brace of a JSON object. |
Flush | Flushes the parser's or writer's buffers. |
HasXPath | Determines whether a specific element exists in the document. |
LoadSchema | Load the JSON schema. |
Parse | This method parses the specified JSON data. |
PutComment | Writes a comment to the JSON document. |
PutName | Writes the name of a property. |
PutProperty | Write a property and value. |
PutRaw | Writes a raw JSON fragment. |
PutValue | Writes a value of a property. |
Remove | Removes the current. |
Reset | Resets the component. |
Save | Saves the JSON data. |
StartArray | Writes the opening bracket of a JSON array. |
StartObject | Writes the opening brace of a JSON object. |
TryXPath | Navigates to the specified XPath if it exists. |
Event List
The following is the full list of the events fired by the component with short descriptions. Click on the links for further details.
Characters | Fired for plain text segments of the input stream. |
EndElement | Fired when an end-element tag is encountered. |
Error | Information about errors during data delivery. |
IgnorableWhitespace | Fired when a section of ignorable whitespace is encountered. |
JSON | Fires with the JSON data being written. |
StartElement | Fired when a new element is encountered in the document. |
Configuration Settings
The following is a list of configuration settings for the component with short descriptions. Click on the links for further details.
CacheContent | If true, the original JSON is stored internally in a buffer. |
PrettyPrint | Determines whether output is on one line or "pretty printed". |
StringProcessingOptions | Defines options to use when processing string values. |
XPathNotation | Specifies the expected format when setting XPath. |
CodePage | The system code page used for Unicode to Multibyte translations. |
UseInternalSecurityAPI | Tells the component whether or not to use the system security libraries or an internal implementation. |