From 2aafe75487b434187fd3b0b7f8cefdc0bf371d26 Mon Sep 17 00:00:00 2001 From: WSO2 Builder Date: Mon, 27 May 2019 14:54:35 +0000 Subject: [PATCH] [WSO2-Release] [Release 5.0.3] update documentation for release 5.0.3 --- README.md | 6 +-- docs/api/5.0.3.md | 127 +++++++++++++++++++++++++++++++++++++++++++++ docs/api/latest.md | 2 +- docs/index.md | 6 +-- mkdocs.yml | 1 + 5 files changed, 135 insertions(+), 7 deletions(-) create mode 100644 docs/api/5.0.3.md diff --git a/README.md b/README.md index 8e8a03c..8037c07 100644 --- a/README.md +++ b/README.md @@ -12,7 +12,7 @@ Find some useful links below: ## Latest API Docs -Latest API Docs is 5.0.2. +Latest API Docs is 5.0.3. ## How to use @@ -48,8 +48,8 @@ extension you can replace the component json *(Sink Mapper)*

This extension is an Event to JSON output mapper.
Transports that publish messages can utilize this extension to convert Siddhi events to JSON messages.
You can either send a pre-defined JSON format or a custom JSON message.

-* json *(Source Mapper)*

This extension is a JSON-to-Event input mapper. Transports that accept JSON messages can utilize this extension to convert an incoming JSON message into a Siddhi event. Users can either send a pre-defined JSON format, where event conversion happens without any configurations, or use the JSON path to map from a custom JSON message.
In default mapping, the JSON string of the event can be enclosed by the element "event", though optional.

+* json *(Sink Mapper)*

This extension is an Event to JSON output mapper.
Transports that publish messages can utilize this extension to convert Siddhi events to JSON messages.
You can either send a pre-defined JSON format or a custom JSON message.

+* json *(Source Mapper)*

This extension is a JSON-to-Event input mapper. Transports that accept JSON messages can utilize this extension to convert an incoming JSON message into a Siddhi event. Users can either send a pre-defined JSON format, where event conversion happens without any configurations, or use the JSON path to map from a custom JSON message.
In default mapping, the JSON string of the event can be enclosed by the element "event", though optional.

## How to Contribute diff --git a/docs/api/5.0.3.md b/docs/api/5.0.3.md new file mode 100644 index 0000000..5ee497e --- /dev/null +++ b/docs/api/5.0.3.md @@ -0,0 +1,127 @@ +# API Docs - v5.0.3 + +## Sinkmapper + +### json *(Sink Mapper)* + +

This extension is an Event to JSON output mapper.
Transports that publish messages can utilize this extension to convert Siddhi events to JSON messages.
You can either send a pre-defined JSON format or a custom JSON message.

+ +Syntax +``` +@sink(..., @map(type="json", validate.json="", enclosing.element="") +``` + +QUERY PARAMETERS + + + + + + + + + + + + + + + + + + + + + + + + + +
NameDescriptionDefault ValuePossible Data TypesOptionalDynamic
validate.jsonIf this property is set to true, it enables JSON validation for the JSON messages generated.
When validation is carried out, messages that do not adhere to proper JSON standards are dropped. This property is set to 'false' by default.
falseBOOLYesNo
enclosing.elementThis specifies the enclosing element to be used if multiple events are sent in the same JSON message.
Siddhi treats the child elements of the given enclosing element as events and executes JSON expressions on them.
If an enclosing.element is not provided, the multiple event scenario is disregarded and JSON path is evaluated based on the root element.		$STRINGYesNo
+ +Examples +EXAMPLE 1 +``` +@sink(type='inMemory', topic='stock', @map(type='json')) +define stream FooStream (symbol string, price float, volume long); + +``` +

Above configuration does a default JSON input mapping that generates the output given below.
{
    "event":{
        "symbol":WSO2,
        "price":55.6,
        "volume":100
    }
}

+ +EXAMPLE 2 +``` +@sink(type='inMemory', topic='{{symbol}}', @map(type='json', enclosing.element='$.portfolio', validate.json='true', @payload( """{"StockData":{"Symbol":"{{symbol}}","Price":{{price}}}"""))) +define stream BarStream (symbol string, price float, volume long); +``` +

The above configuration performs a custom JSON mapping that generates the following JSON message as the output.
{"portfolio":{
    "StockData":{
        "Symbol":WSO2,
        "Price":55.6
      }
  }
}

+ +## Sourcemapper + +### json *(Source Mapper)* + +

This extension is a JSON-to-Event input mapper. Transports that accept JSON messages can utilize this extension to convert an incoming JSON message into a Siddhi event. Users can either send a pre-defined JSON format, where event conversion happens without any configurations, or use the JSON path to map from a custom JSON message.
In default mapping, the JSON string of the event can be enclosed by the element "event", though optional.

+ +Syntax +``` +@source(..., @map(type="json", enclosing.element="", fail.on.missing.attribute="") +``` + +QUERY PARAMETERS + + + + + + + + + + + + + + + + + + + + + + + + + +
NameDescriptionDefault ValuePossible Data TypesOptionalDynamic
enclosing.elementThis is used to specify the enclosing element when sending multiple events in the same JSON message.
Mapper treats the child elements of a given enclosing element as events and executes the JSON path expressions on these child elements.
If the enclosing.element is not provided then the multiple-event scenario is disregarded and the JSON path is evaluated based on the root element.		$STRINGYesNo
fail.on.missing.attribute
This parameter allows users to handle unknown attributes.The value of this can either be true or false. By default it is true.
 If a JSON execution fails or returns null, mapper drops that message.
However, setting this property to false prompts mapper to send an event with a null value to Siddhi, where users can handle it as required, ie., assign a default value.)		trueBOOLYesNo
+ +Examples +EXAMPLE 1 +``` +@source(type='inMemory', topic='stock', @map(type='json')) +define stream FooStream (symbol string, price float, volume long); + +``` +

This configuration performs a default JSON input mapping.
 For a single event, the input is required to be in one of the following formats:
{
    "event":{
        "symbol":"WSO2",
        "price":55.6,
        "volume":100
    }
}

or

{
    "symbol":"WSO2",
    "price":55.6,
    "volume":100
}

+ +EXAMPLE 2 +``` +@source(type='inMemory', topic='stock', @map(type='json')) +define stream FooStream (symbol string, price float, volume long); + +``` +

This configuration performs a default JSON input mapping.
For multiple events, the input is required to be in one of the following formats:
[
{"event":{"symbol":"WSO2","price":55.6,"volume":100}},
{"event":{"symbol":"WSO2","price":56.6,"volume":99}},
{"event":{"symbol":"WSO2","price":57.6,"volume":80}}
]

or

[
{"symbol":"WSO2","price":55.6,"volume":100},
{"symbol":"WSO2","price":56.6,"volume":99},
{"symbol":"WSO2","price":57.6,"volume":80}
]

+ +EXAMPLE 3 +``` +@source(type='inMemory', topic='stock', @map(type='json', enclosing.element="$.portfolio", @attributes(symbol = "company.symbol", price = "price", volume = "volume"))) +``` +

This configuration performs a custom JSON mapping.
For a single event, the expected input is similar to the one shown below:
.{
 "portfolio":{
     "stock":{ "volume":100,
        "company":{
           "symbol":"WSO2"
       },
        "price":55.6
    }
}

+ +EXAMPLE 4 +``` +@source(type='inMemory', topic='stock', @map(type='json', enclosing.element="$.portfolio", @attributes(symbol = "stock.company.symbol", price = "stock.price", volume = "stock.volume"))) +define stream FooStream (symbol string, price float, volume long); + +``` +

The configuration performs a custom JSON mapping.
For multiple events, expected input looks as follows.
.{"portfolio":
   [ {"stock":{"volume":100,"company":{"symbol":"wso2"},"price":56.6}}, {"stock":{"volume":200,"company":{"symbol":"wso2"},"price":57.6}} ]
}

+ diff --git a/docs/api/latest.md b/docs/api/latest.md index 08071a9..5ee497e 100644 --- a/docs/api/latest.md +++ b/docs/api/latest.md @@ -1,4 +1,4 @@ -# API Docs - v5.0.2 +# API Docs - v5.0.3 ## Sinkmapper diff --git a/docs/index.md b/docs/index.md index 8e8a03c..8037c07 100644 --- a/docs/index.md +++ b/docs/index.md @@ -12,7 +12,7 @@ Find some useful links below: ## Latest API Docs -Latest API Docs is 5.0.2. +Latest API Docs is 5.0.3. ## How to use @@ -48,8 +48,8 @@ extension you can replace the component json *(Sink Mapper)*

This extension is an Event to JSON output mapper.
Transports that publish messages can utilize this extension to convert Siddhi events to JSON messages.
You can either send a pre-defined JSON format or a custom JSON message.

-* json *(Source Mapper)*

This extension is a JSON-to-Event input mapper. Transports that accept JSON messages can utilize this extension to convert an incoming JSON message into a Siddhi event. Users can either send a pre-defined JSON format, where event conversion happens without any configurations, or use the JSON path to map from a custom JSON message.
In default mapping, the JSON string of the event can be enclosed by the element "event", though optional.

+* json *(Sink Mapper)*

This extension is an Event to JSON output mapper.
Transports that publish messages can utilize this extension to convert Siddhi events to JSON messages.
You can either send a pre-defined JSON format or a custom JSON message.

+* json *(Source Mapper)*

This extension is a JSON-to-Event input mapper. Transports that accept JSON messages can utilize this extension to convert an incoming JSON message into a Siddhi event. Users can either send a pre-defined JSON format, where event conversion happens without any configurations, or use the JSON path to map from a custom JSON message.
In default mapping, the JSON string of the event can be enclosed by the element "event", though optional.

## How to Contribute diff --git a/mkdocs.yml b/mkdocs.yml index 0a2326a..efa5899 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -32,6 +32,7 @@ markdown_extensions: pages: - Welcome: index.md - API Docs: + - 5.0.3: api/5.0.3.md - 5.0.2: api/5.0.2.md - 5.0.1: api/5.0.1.md - 5.0.0: api/5.0.0.md