From 13160e33d3cf4d55e4497daf92e6986df87e6beb Mon Sep 17 00:00:00 2001 From: WSO2 Builder Date: Fri, 5 Jul 2019 09:02:38 +0000 Subject: [PATCH] [WSO2-Release] [Release 2.0.2] update documentation for release 2.0.2 --- README.md | 28 +- docs/api/2.0.2.md | 769 +++++++++++++++++++++++++++++++++++++++++++++ docs/api/latest.md | 13 +- docs/index.md | 28 +- mkdocs.yml | 1 + 5 files changed, 807 insertions(+), 32 deletions(-) create mode 100644 docs/api/2.0.2.md diff --git a/README.md b/README.md index ca7aa86..ec21432 100644 --- a/README.md +++ b/README.md @@ -19,23 +19,23 @@ For information on Siddhi and i ## Latest API Docs -Latest API Docs is 2.0.1. +Latest API Docs is 2.0.2. ## Features -* getBool *(Function)*

Function retrieves the 'boolean' value specified in the given path of the JSON element.

-* getDouble *(Function)*

Function retrieves the 'double' value specified in the given path of the JSON element.

-* getFloat *(Function)*

Function retrieves the 'float' value specified in the given path of the JSON element.

-* getInt *(Function)*

Function retrieves the 'int' value specified in the given path of the JSON element.

-* getLong *(Function)*

Function retrieves the 'long' value specified in the given path of the JSON element.

-* getObject *(Function)*

Function retrieves the object specified in the given path of the JSON element.

-* getString *(Function)*

Function retrieves value specified in the given path of the JSON element as a string.

-* isExists *(Function)*

Function checks whether there is a JSON element present in the given path or not.

-* setElement *(Function)*

Function sets JSON element into a given JSON at the specific path.

-* toObject *(Function)*

Function generate JSON object from the given JSON string.

-* toString *(Function)*

Function generates a JSON string corresponding to a given JSON object.

-* tokenize *(Stream Processor)*

Stream processor tokenizes the given JSON into to multiple JSON string elements and sends them as separate events.

-* tokenizeAsObject *(Stream Processor)*

Stream processor tokenizes the given JSON into to multiple JSON object elements and sends them as separate events.

+* getBool *(Function)*

Function retrieves the 'boolean' value specified in the given path of the JSON element.

+* getDouble *(Function)*

Function retrieves the 'double' value specified in the given path of the JSON element.

+* getFloat *(Function)*

Function retrieves the 'float' value specified in the given path of the JSON element.

+* getInt *(Function)*

Function retrieves the 'int' value specified in the given path of the JSON element.

+* getLong *(Function)*

Function retrieves the 'long' value specified in the given path of the JSON element.

+* getObject *(Function)*

Function retrieves the object specified in the given path of the JSON element.

+* getString *(Function)*

Function retrieves value specified in the given path of the JSON element as a string.

+* isExists *(Function)*

Function checks whether there is a JSON element present in the given path or not.

+* setElement *(Function)*

Function sets JSON element into a given JSON at the specific path.

+* toObject *(Function)*

Function generate JSON object from the given JSON string.

+* toString *(Function)*

Function generates a JSON string corresponding to a given JSON object.

+* tokenize *(Stream Processor)*

Stream processor tokenizes the given JSON into to multiple JSON string elements and sends them as separate events.

+* tokenizeAsObject *(Stream Processor)*

Stream processor tokenizes the given JSON into to multiple JSON object elements and sends them as separate events.

## Dependencies diff --git a/docs/api/2.0.2.md b/docs/api/2.0.2.md new file mode 100644 index 0000000..0b73728 --- /dev/null +++ b/docs/api/2.0.2.md @@ -0,0 +1,769 @@ +# API Docs - v2.0.2 + +!!! Info "Tested Siddhi Core version: *5.0.2*" + It could also support other Siddhi Core minor versions. + +## Json + +### getBool *(Function)* +

Function retrieves the 'boolean' value specified in the given path of the JSON element.

+Syntax + +``` + json:getBool( json, path) +``` + +QUERY PARAMETERS + + + + + + + + + + + + + + + + + + + + + + + + + +
NameDescriptionDefault ValuePossible Data TypesOptionalDynamic
jsonThe JSON input containing boolean value.STRING
OBJECT		NoYes
pathThe JSON path to fetch the boolean value.STRINGNoYes
+ +Examples +EXAMPLE 1 +``` +json:getBool(json,'$.married') +``` +

If the json is the format {'name' : 'John', 'married' : true}, the function returns true as there is a matching boolean at $.married.

+ +EXAMPLE 2 +``` +json:getBool(json,'$.name') +``` +

If the json is the format {'name' : 'John', 'married' : true}, the function returns null as there is no matching boolean at $.name.

+ +EXAMPLE 3 +``` +json:getBool(json,'$.foo') +``` +

If the json is the format {'name' : 'John', 'married' : true}, the function returns null as there is no matching element at $.foo.

+ +### getDouble *(Function)* +

Function retrieves the 'double' value specified in the given path of the JSON element.

+Syntax + +``` + json:getDouble( json, path) +``` + +QUERY PARAMETERS + + + + + + + + + + + + + + + + + + + + + + + + + +
NameDescriptionDefault ValuePossible Data TypesOptionalDynamic
jsonThe JSON input containing double value.STRING
OBJECT		NoYes
pathThe JSON path to fetch the double value.STRINGNoYes
+ +Examples +EXAMPLE 1 +``` +json:getDouble(json,'$.salary') +``` +

If the json is the format {'name' : 'John', 'salary' : 12000.0}, the function returns 12000.0 as there is a matching double at $.salary.

+ +EXAMPLE 2 +``` +json:getDouble(json,'$.salary') +``` +

If the json is the format {'name' : 'John', 'age' : 23}, the function returns null as there are no matching element at $.salary.

+ +EXAMPLE 3 +``` +json:getDouble(json,'$.name') +``` +

If the json is the format {'name' : 'John', 'age' : 23}, the function returns null as there are no matching double at $.name.

+ +### getFloat *(Function)* +

Function retrieves the 'float' value specified in the given path of the JSON element.

+Syntax + +``` + json:getFloat( json, path) +``` + +QUERY PARAMETERS + + + + + + + + + + + + + + + + + + + + + + + + + +
NameDescriptionDefault ValuePossible Data TypesOptionalDynamic
jsonThe JSON input containing float value.STRING
OBJECT		NoYes
pathThe JSON path to fetch the float value.STRINGNoYes
+ +Examples +EXAMPLE 1 +``` +json:getFloat(json,'$.salary') +``` +

If the json is the format {'name' : 'John', 'salary' : 12000.0}, the function returns 12000 as there is a matching float at $.salary.

+ +EXAMPLE 2 +``` +json:getFloat(json,'$.salary') +``` +

If the json is the format {'name' : 'John', 'age' : 23}, the function returns null as there are no matching element at $.salary.

+ +EXAMPLE 3 +``` +json:getFloat(json,'$.name') +``` +

If the json is the format {'name' : 'John', 'age' : 23}, the function returns null as there are no matching float at $.name.

+ +### getInt *(Function)* +

Function retrieves the 'int' value specified in the given path of the JSON element.

+Syntax + +``` + json:getInt( json, path) +``` + +QUERY PARAMETERS + + + + + + + + + + + + + + + + + + + + + + + + + +
NameDescriptionDefault ValuePossible Data TypesOptionalDynamic
jsonThe JSON input containing int value.STRING
OBJECT		NoYes
pathThe JSON path to fetch the int value.STRINGNoYes
+ +Examples +EXAMPLE 1 +``` +json:getInt(json,'$.age') +``` +

If the json is the format {'name' : 'John', 'age' : 23}, the function returns 23 as there is a matching int at $.age.

+ +EXAMPLE 2 +``` +json:getInt(json,'$.salary') +``` +

If the json is the format {'name' : 'John', 'age' : 23}, the function returns null as there are no matching element at $.salary.

+ +EXAMPLE 3 +``` +json:getInt(json,'$.name') +``` +

If the json is the format {'name' : 'John', 'age' : 23}, the function returns null as there are no matching int at $.name.

+ +### getLong *(Function)* +

Function retrieves the 'long' value specified in the given path of the JSON element.

+Syntax + +``` + json:getLong( json, path) +``` + +QUERY PARAMETERS + + + + + + + + + + + + + + + + + + + + + + + + + +
NameDescriptionDefault ValuePossible Data TypesOptionalDynamic
jsonThe JSON input containing long value.STRING
OBJECT		NoYes
pathThe JSON path to fetch the long value.STRINGNoYes
+ +Examples +EXAMPLE 1 +``` +json:getLong(json,'$.age') +``` +

If the json is the format {'name' : 'John', 'age' : 23}, the function returns 23 as there is a matching long at $.age.

+ +EXAMPLE 2 +``` +json:getLong(json,'$.salary') +``` +

If the json is the format {'name' : 'John', 'age' : 23}, the function returns null as there are no matching element at $.salary.

+ +EXAMPLE 3 +``` +json:getLong(json,'$.name') +``` +

If the json is the format {'name' : 'John', 'age' : 23}, the function returns null as there are no matching long at $.name.

+ +### getObject *(Function)* +

Function retrieves the object specified in the given path of the JSON element.

+Syntax + +``` + json:getObject( json, path) +``` + +QUERY PARAMETERS + + + + + + + + + + + + + + + + + + + + + + + + + +
NameDescriptionDefault ValuePossible Data TypesOptionalDynamic
jsonThe JSON input containing the object.STRING
OBJECT		NoYes
pathThe JSON path to fetch the object.STRINGNoYes
+ +Examples +EXAMPLE 1 +``` +json:getObject(json,'$.address') +``` +

If the json is the format {'name' : 'John', 'address' : {'city' : 'NY', 'country' : 'USA'}}, the function returns {'city' : 'NY', 'country' : 'USA'} as there is a matching object at $.address.

+ +EXAMPLE 2 +``` +json:getObject(json,'$.age') +``` +

If the json is the format {'name' : 'John', 'age' : 23}, the function returns 23 as there is a matching object at $.age.

+ +EXAMPLE 3 +``` +json:getObject(json,'$.salary') +``` +

If the json is the format {'name' : 'John', 'age' : 23}, the function returns null as there are no matching element at $.salary.

+ +### getString *(Function)* +

Function retrieves value specified in the given path of the JSON element as a string.

+Syntax + +``` + json:getString( json, path) +``` + +QUERY PARAMETERS + + + + + + + + + + + + + + + + + + + + + + + + + +
NameDescriptionDefault ValuePossible Data TypesOptionalDynamic
jsonThe JSON input containing value.STRING
OBJECT		NoYes
pathThe JSON path to fetch the value.STRINGNoYes
+ +Examples +EXAMPLE 1 +``` +json:getString(json,'$.name') +``` +

If the json is the format {'name' : 'John', 'age' : 23}, the function returns John as there is a matching string at $.name.

+ +EXAMPLE 2 +``` +json:getString(json,'$.salary') +``` +

If the json is the format {'name' : 'John', 'age' : 23}, the function returns null as there are no matching element at $.salary.

+ +EXAMPLE 3 +``` +json:getString(json,'$.age') +``` +

If the json is the format {'name' : 'John', 'age' : 23}, the function returns 23 as a string as there is a matching element at $.age.

+ +EXAMPLE 4 +``` +json:getString(json,'$.address') +``` +

If the json is the format {'name' : 'John', 'address' : {'city' : 'NY', 'country' : 'USA'}}, the function returns {'city' : 'NY', 'country' : 'USA'} as a string as there is a matching element at $.address.

+ +### isExists *(Function)* +

Function checks whether there is a JSON element present in the given path or not.

+Syntax + +``` + json:isExists( json, path) +``` + +QUERY PARAMETERS + + + + + + + + + + + + + + + + + + + + + + + + + +
NameDescriptionDefault ValuePossible Data TypesOptionalDynamic
jsonThe JSON input that needs to be searched for an elements.STRING
OBJECT		NoYes
pathThe JSON path to check for the element.STRINGNoYes
+ +Examples +EXAMPLE 1 +``` +json:isExists(json, '$.name') +``` +

If the json is the format {'name' : 'John', 'age' : 23}, the function returns true as there is an element in the given path.

+ +EXAMPLE 2 +``` +json:isExists(json, '$.salary') +``` +

If the json is the format {'name' : 'John', 'age' : 23}, the function returns false as there is no element in the given path.

+ +### setElement *(Function)* +

Function sets JSON element into a given JSON at the specific path.

+Syntax + +``` + json:setElement( json, path, json.element) + json:setElement( json, path, json.element, key) +``` + +QUERY PARAMETERS + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
NameDescriptionDefault ValuePossible Data TypesOptionalDynamic
jsonThe JSON to which a JSON element needs to be added/replaced.STRING
OBJECT		NoYes
pathThe JSON path where the JSON element should be added/replaced.STRINGNoYes
json.elementThe JSON element being added.STRING
BOOL
DOUBLE
FLOAT
INT
LONG
OBJECT		NoYes
keyThe key to be used to refer the newly added element in the input JSON.Assumes the element is added to a JSON array, or the element selected by the JSON path will be updated.STRINGYesYes
+ +Examples +EXAMPLE 1 +``` +json:setElement(json, '$', "{'country' : 'USA'}", 'address') +``` +

If the json is the format {'name' : 'John', 'married' : true},the function updates the json as {'name' : 'John', 'married' : true, 'address' : {'country' : 'USA'}} by adding 'address' element and returns the updated JSON.

+ +EXAMPLE 2 +``` +json:setElement(json, '$', 40, 'age') +``` +

If the json is the format {'name' : 'John', 'married' : true},the function updates the json as {'name' : 'John', 'married' : true, 'age' : 40} by adding 'age' element and returns the updated JSON.

+ +EXAMPLE 3 +``` +json:setElement(json, '$', 45, 'age') +``` +

If the json is the format {'name' : 'John', 'married' : true, 'age' : 40}, the function updates the json as {'name' : 'John', 'married' : true, 'age' : 45} by replacing 'age' element and returns the updated JSON.

+ +EXAMPLE 4 +``` +json:setElement(json, '$.items', 'book') +``` +

If the json is the format {'name' : 'Stationary', 'items' : ['pen', 'pencil']}, the function updates the json as {'name' : 'John', 'items' : ['pen', 'pencil', 'book']} by adding 'book' in the items array and returns the updated JSON.

+ +EXAMPLE 5 +``` +json:setElement(json, '$.item', 'book') +``` +

If the json is the format {'name' : 'Stationary', 'item' : 'pen'}, the function updates the json as {'name' : 'John', 'item' : 'book'} by replacing 'item' element and returns the updated JSON.

+ +EXAMPLE 6 +``` +json:setElement(json, '$.address', 'city', 'SF') +``` +

If the json is the format {'name' : 'John', 'married' : true},the function will not update, but returns the original JSON as there are no valid path for $.address.

+ +### toObject *(Function)* +

Function generate JSON object from the given JSON string.

+Syntax + +``` + json:toObject( json) +``` + +QUERY PARAMETERS + + + + + + + + + + + + + + + + + +
NameDescriptionDefault ValuePossible Data TypesOptionalDynamic
jsonA valid JSON string that needs to be converted to a JSON object.STRINGNoYes
+ +Examples +EXAMPLE 1 +``` +json:toJson(json) +``` +

This returns the JSON object corresponding to the given JSON string.

+ +### toString *(Function)* +

Function generates a JSON string corresponding to a given JSON object.

+Syntax + +``` + json:toString( json) +``` + +QUERY PARAMETERS + + + + + + + + + + + + + + + + + +
NameDescriptionDefault ValuePossible Data TypesOptionalDynamic
jsonA valid JSON object to generates a JSON string.OBJECTNoYes
+ +Examples +EXAMPLE 1 +``` +json:toString(json) +``` +

This returns the JSON string corresponding to a given JSON object.

+ +### tokenize *(Stream Processor)* +

Stream processor tokenizes the given JSON into to multiple JSON string elements and sends them as separate events.

+Syntax + +``` +json:tokenize( json, path) +json:tokenize( json, path, fail.on.missing.attribute) +``` + +QUERY PARAMETERS + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
NameDescriptionDefault ValuePossible Data TypesOptionalDynamic
jsonThe input JSON that needs to be tokenized.STRING
OBJECT		NoYes
pathThe path of the set of elements that will be tokenized.STRINGNoYes
fail.on.missing.attributeIf there are no element on the given path, when set to true the system will drop the event, and when set to false the system will pass 'null' value to the jsonElement output attribute.trueBOOLYesNo
+Extra Return Attributes + + + + + + + + + + + +
NameDescriptionPossible Types
jsonElementThe JSON element retrieved based on the given path will be returned as a JSON string. If the 'path' selects a JSON array then the system returns each element in the array as a JSON string via a separate events.STRING
+ +Examples +EXAMPLE 1 +``` +define stream InputStream (json string, path string); + +@info(name = 'query1') +from InputStream#json:tokenizeAsObject(json, path) +select path, jsonElement +insert into OutputStream; +``` +

If the input 'json' is {name:'John', enrolledSubjects:['Mathematics', 'Physics']}, and the 'path' is passed as $.enrolledSubjects then for both the elements in the selected JSON array, it generates it generates events as ('$.enrolledSubjects', 'Mathematics'), and ('$.enrolledSubjects', 'Physics').
For the same input JSON, if the 'path' is passed as $.name then it will only produce one event ('$.name', 'John') as the 'path' provided a single JSON element.

+ +EXAMPLE 2 +``` +define stream InputStream (json string, path string); + +@info(name = 'query1') +from InputStream#json:tokenizeAsObject(json, path, true) +select path, jsonElement +insert into OutputStream; +``` +

If the input 'json' is {name:'John', age:25},and the 'path' is passed as $.salary then the system will produce ('$.salary', null), as the 'fail.on.missing.attribute' is true and there are no matching element for $.salary.

+ +### tokenizeAsObject *(Stream Processor)* +

Stream processor tokenizes the given JSON into to multiple JSON object elements and sends them as separate events.

+Syntax + +``` +json:tokenizeAsObject( json, path) +json:tokenizeAsObject( json, path, fail.on.missing.attribute) +``` + +QUERY PARAMETERS + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
NameDescriptionDefault ValuePossible Data TypesOptionalDynamic
jsonThe input JSON that needs to be tokenized.STRING
OBJECT		NoYes
pathThe path of the set of elements that will be tokenized.STRINGNoYes
fail.on.missing.attributeIf there are no element on the given path, when set to true the system will drop the event, and when set to false the system will pass 'null' value to the jsonElement output attribute.trueBOOLYesNo
+Extra Return Attributes + + + + + + + + + + + +
NameDescriptionPossible Types
jsonElementThe JSON element retrieved based on the given path will be returned as a JSON object. If the 'path' selects a JSON array then the system returns each element in the array as a JSON object via a separate events.OBJECT
+ +Examples +EXAMPLE 1 +``` +define stream InputStream (json string, path string); + +@info(name = 'query1') +from InputStream#json:tokenizeAsObject(json, path) +select path, jsonElement +insert into OutputStream; +``` +

If the input 'json' is {name:'John', enrolledSubjects:['Mathematics', 'Physics']}, and the 'path' is passed as $.enrolledSubjects then for both the elements in the selected JSON array, it generates it generates events as ('$.enrolledSubjects', 'Mathematics'), and ('$.enrolledSubjects', 'Physics').
For the same input JSON, if the 'path' is passed as $.name then it will only produce one event ('$.name', 'John') as the 'path' provided a single JSON element.

+ +EXAMPLE 2 +``` +define stream InputStream (json string, path string); + +@info(name = 'query1') +from InputStream#json:tokenizeAsObject(json, path, true) +select path, jsonElement +insert into OutputStream; +``` +

If the input 'json' is {name:'John', age:25},and the 'path' is passed as $.salary then the system will produce ('$.salary', null), as the 'fail.on.missing.attribute' is true and there are no matching element for $.salary.

+ diff --git a/docs/api/latest.md b/docs/api/latest.md index b14c25c..0b73728 100644 --- a/docs/api/latest.md +++ b/docs/api/latest.md @@ -1,6 +1,6 @@ -# API Docs - v2.0.1 +# API Docs - v2.0.2 -!!! Info "Tested Siddhi Core version: *5.0.0*" +!!! Info "Tested Siddhi Core version: *5.0.2*" It could also support other Siddhi Core minor versions. ## Json @@ -491,7 +491,7 @@ json:isExists(json, '$.salary') key The key to be used to refer the newly added element in the input JSON. - Assumes the element is added to a JSON array. + Assumes the element is added to a JSON array, or the element selected by the JSON path will be updated. STRING Yes Yes @@ -525,6 +525,12 @@ json:setElement(json, '$.items', 'book') EXAMPLE 5 ``` +json:setElement(json, '$.item', 'book') +``` +

If the json is the format {'name' : 'Stationary', 'item' : 'pen'}, the function updates the json as {'name' : 'John', 'item' : 'book'} by replacing 'item' element and returns the updated JSON.

+ +EXAMPLE 6 +``` json:setElement(json, '$.address', 'city', 'SF') ```

If the json is the format {'name' : 'John', 'married' : true},the function will not update, but returns the original JSON as there are no valid path for $.address.

@@ -761,4 +767,3 @@ insert into OutputStream; ```

If the input 'json' is {name:'John', age:25},and the 'path' is passed as $.salary then the system will produce ('$.salary', null), as the 'fail.on.missing.attribute' is true and there are no matching element for $.salary.

- diff --git a/docs/index.md b/docs/index.md index ca7aa86..ec21432 100644 --- a/docs/index.md +++ b/docs/index.md @@ -19,23 +19,23 @@ For information on Siddhi and i ## Latest API Docs -Latest API Docs is 2.0.1. +Latest API Docs is 2.0.2. ## Features -* getBool *(Function)*

Function retrieves the 'boolean' value specified in the given path of the JSON element.

-* getDouble *(Function)*

Function retrieves the 'double' value specified in the given path of the JSON element.

-* getFloat *(Function)*

Function retrieves the 'float' value specified in the given path of the JSON element.

-* getInt *(Function)*

Function retrieves the 'int' value specified in the given path of the JSON element.

-* getLong *(Function)*

Function retrieves the 'long' value specified in the given path of the JSON element.

-* getObject *(Function)*

Function retrieves the object specified in the given path of the JSON element.

-* getString *(Function)*

Function retrieves value specified in the given path of the JSON element as a string.

-* isExists *(Function)*

Function checks whether there is a JSON element present in the given path or not.

-* setElement *(Function)*

Function sets JSON element into a given JSON at the specific path.

-* toObject *(Function)*

Function generate JSON object from the given JSON string.

-* toString *(Function)*

Function generates a JSON string corresponding to a given JSON object.

-* tokenize *(Stream Processor)*

Stream processor tokenizes the given JSON into to multiple JSON string elements and sends them as separate events.

-* tokenizeAsObject *(Stream Processor)*

Stream processor tokenizes the given JSON into to multiple JSON object elements and sends them as separate events.

+* getBool *(Function)*

Function retrieves the 'boolean' value specified in the given path of the JSON element.

+* getDouble *(Function)*

Function retrieves the 'double' value specified in the given path of the JSON element.

+* getFloat *(Function)*

Function retrieves the 'float' value specified in the given path of the JSON element.

+* getInt *(Function)*

Function retrieves the 'int' value specified in the given path of the JSON element.

+* getLong *(Function)*

Function retrieves the 'long' value specified in the given path of the JSON element.

+* getObject *(Function)*

Function retrieves the object specified in the given path of the JSON element.

+* getString *(Function)*

Function retrieves value specified in the given path of the JSON element as a string.

+* isExists *(Function)*

Function checks whether there is a JSON element present in the given path or not.

+* setElement *(Function)*

Function sets JSON element into a given JSON at the specific path.

+* toObject *(Function)*

Function generate JSON object from the given JSON string.

+* toString *(Function)*

Function generates a JSON string corresponding to a given JSON object.

+* tokenize *(Stream Processor)*

Stream processor tokenizes the given JSON into to multiple JSON string elements and sends them as separate events.

+* tokenizeAsObject *(Stream Processor)*

Stream processor tokenizes the given JSON into to multiple JSON object elements and sends them as separate events.

## Dependencies diff --git a/mkdocs.yml b/mkdocs.yml index 2447ec2..c550406 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -34,6 +34,7 @@ pages: - Information: index.md - API Docs: - latest: api/latest.md + - 2.0.2: api/2.0.2.md - 2.0.1: api/2.0.1.md - 2.0.0: api/2.0.0.md - 1.1.1: api/1.1.1.md