Skip to content

API Docs - v5.2.0

Tested Siddhi Core version: 5.1.14

It could also support other Siddhi Core minor versions.

Sinkmapper

xml (Sink Mapper)

This mapper converts Siddhi output events to XML before they are published via transports that publish in XML format. Users can either send a pre-defined XML format or a custom XML message containing event data.

Syntax

@sink(..., @map(type="xml", validate.xml="<BOOL>", enclosing.element="<STRING>")

QUERY PARAMETERS

Name Description Default Value Possible Data Types Optional Dynamic
validate.xml

This parameter specifies whether the XML messages generated should be validated or not. If this parameter is set to true, messages that do not adhere to proper XML standards are dropped.

false BOOL Yes No
enclosing.element

When an enclosing element is specified, the child elements (e.g., the immediate child elements) of that element are considered as events. This is useful when you need to send multiple events in a single XML message. When an enclosing element is not specified, one XML message per every event will be emitted without enclosing.

 None in custom mapping and <events> in default mapping STRING Yes No

Examples EXAMPLE 1

@sink(type='inMemory', topic='stock', @map(type='xml'))
define stream FooStream (symbol string, price float, volume long);

Above configuration will do a default XML input mapping which will generate below output
<events>
    <event>
        <symbol>WSO2</symbol>
        <price>55.6</price>
        <volume>100</volume>
    </event>
</events>

EXAMPLE 2

@sink(type='inMemory', topic='{{symbol}}', @map(type='xml', enclosing.element='<portfolio>', validate.xml='true', @payload( "<StockData><Symbol>{{symbol}}</Symbol><Price>{{price}}</Price></StockData>")))
define stream BarStream (symbol string, price float, volume long);

Above configuration will perform a custom XML mapping. Inside @payload you can specify the custom template that you want to send the messages out and addd placeholders to places where you need to add event attributes.Above config will produce below output XML message
<portfolio>
    <StockData>
        <Symbol>WSO2</Symbol>
        <Price>55.6</Price>
    </StockData>
</portfolio>

Sourcemapper

xml (Source Mapper)

This mapper converts XML input to Siddhi event. Transports which accepts XML messages can utilize this extension to convert the incoming XML message to Siddhi event. Users can either send a pre-defined XML format where event conversion will happen without any configs or can use xpath to map from a custom XML message.

Syntax

@source(..., @map(type="xml", namespaces="<STRING>", enclosing.element="<STRING>", enclosing.element.as.event="<BOOL>", fail.on.missing.attribute="<BOOL>", enable.streaming.xml.content="<BOOL>", extract.leaf.node.data="<BOOL>")

QUERY PARAMETERS

Name Description Default Value Possible Data Types Optional Dynamic
namespaces

Used to provide namespaces used in the incoming XML message beforehand to configure xpath expressions. User can provide a comma separated list. If these are not provided xpath evaluations will fail

 None STRING Yes No
enclosing.element

Used when custom mapping is enabled to specify the XPath in case of sending multiple events (if XPath consist of multiple elements, or consists of child elements.) using the same XML content or when the event is not in root node.
XML mapper will treat the child element/s of given enclosing element as event/s, when enclosing.element.as.event is set to false, and execute xpath expressions available in the attribute mappings on child elements.
 If enclosing.element is not provided XPaths in the attribute mappings will be evaluated with respect to root element.
When enclosing element is used and custom mapping is enabled, the attribute mapping XPaths should be relative to child elements

 Root element STRING Yes No
enclosing.element.as.event

This can either have value true or false. XML mapper will treat the child element/s of given enclosing element as event/s, when enclosing.element.as.event is set to false, and attribute mapping should be defined with with respect to the Xpath element's child elements.
 When enclosing.element.as.event is set to true, the elements (NOT child elements) retrieved from XPath itself will be treated as the event/s and attribute mapping should be defined with with respect to the Xpath element.
When enable.streaming.xml is set to true the enclosing.element.as.event value will be set to true by default

 False BOOL Yes No
fail.on.missing.attribute

This can either have value true or false. By default it will be true. This attribute allows user to handle unknown attributes. By default if an xpath execution fails or returns null DAS will drop that message. However setting this property to false will prompt DAS to send and event with null value to Siddhi where user can handle it accordingly(ie. Assign a default value)

 True BOOL Yes No
enable.streaming.xml.content

This will be used when the XML content is streamed without sending the XML element/ event as a whole. eg: When streaming XML file line by line.

 false BOOL Yes No
extract.leaf.node.data

This parameter will enable the event to contain the child element values.
This can be used when the given XPath node contains several child elements and also when the child elements have child elements as well.
If there are multiple child elements, the event count for one node will get multiplied by the number of child nodes.

 false BOOL Yes No

Examples EXAMPLE 1

@source(type='inMemory', topic='stock', @map(type='xml'))
define stream FooStream (symbol string, price float, volume long);

Above configuration will do a default XML input mapping. Expected input will look like below.<events>
    <event>
        <symbol>WSO2</symbol>
        <price>55.6</price>
        <volume>100</volume>
    </event>
</events>

EXAMPLE 2

@map(type='xml', enclosing.element="/events/wrapper/event", 
     enclosing.element.as.event="true", 
     @attributes(volume = "volume", price = "price", symbol = "symbol"))
define stream FooStream (symbol string, price float, volume long);

Above configuration will do a custom mapping and and get the <event> element as a whole event in the given XPath. The attribute mapping has to be done with respect to the element mapped in the XPath. Expected input will look like below<events><wrapper>
    <event>
        <symbol>WSO2</symbol>
        <price>55.6</price>
        <volume>100</volume>
    </event>
    <event>
        <symbol>WSO2</symbol>
        <price>55.6</price>
        <volume>100</volume>
    </event>
</wrapper></events>

EXAMPLE 3

@map(type='xml', enclosing.element='/events/event',
      @attributes(symbol='symbol', price='price', volume='volume'))
define stream FooStream (symbol string, price float, volume long);

Above configuration will do a custom mapping and and get the <event> element as a whole event in the given XPath. The attribute mapping has to be done with respect to the element mapped in the XPath. Expected input will look like below.<events>
    <event>
        <symbol>WSO2</symbol>
        <price>55.6</price>
        <volume>100</volume>
    </event>
</events>

EXAMPLE 4

@source(type='inMemory', topic='stock', 
  @map(type='xml', namespaces = "dt=urn:schemas-microsoft-com:datatypes", 
       enclosing.element="//portfolio", 
       @attributes(symbol = "company/symbol", price = "price", 
                   volume = "volume")))
define stream FooStream (symbol string, price float, volume long);

Above configuration will perform a custom XML mapping. In the custom mapping user can add xpath expressions representing each event attribute using @attribute annotation. Expected input will look like below.
<portfolio xmlns:dt="urn:schemas-microsoft-com:datatypes">
    <stock exchange="nasdaq">
        <volume>100</volume>
        <company>
           <symbol>WSO2</symbol>
        </company>
        <price dt:type="number">55.6</price>
    </stock>
</portfolio>

EXAMPLE 5

@map(type='xml', 
      enclosing.element="/root/child",
      enable.streaming.xml.content="true",
      enclosing.element.as.event="true",
      extract.leaf.node.data="true",
      fail.on.missing.attribute="false",
      @attributes(id = "/child/@id", timestamp = "/child/@timestamp", 
                  key = "/child/detail/@key", 
                  value = "/child/detail/@value"))
define stream FooStream (id string, timestamp string, key string, value string);

Above configuration will do a custom mapping and and get the <child> element as a whole event in the given XPath when the XML content received in a steaming manner (eg: when a file is read line by line and sent to the XML mapper to map).
The attribute mapping has to be done with respect to the element mapped in the XPath which is <child>
In here, the leaf node data is mapped to the <child> event as well.
Expected input will look like below.
<root>
   <bounds minlat="53.4281" minlon="-2.4142" maxlat="54.0097" maxlon="-0.9762"/>
   <child id="413229" timestamp="2014-09-10T14:12:48Z"/>
   <child id="414427" timestamp="2018-01-24T23:16:10Z"/>
   <child id="673959" timestamp="2019-10-20T12:07:13Z">
       <extra id="1234" timestamp="2014-09-11T10:36:37Z"/>
       <detail key="company" value="wso2"/>
       <extra id="0987" timestamp="2014-09-11T10:36:37Z"/>
       <detail key="country" value="Sri Lanka"/>
   </child>
   .
   .
</root>

EXAMPLE 6

@map(type='xml', 
      enclosing.element="/root/child",
      enable.streaming.xml.content="true",
      enclosing.element.as.event="true",
      fail.on.missing.attribute="false",
      @attributes(id = "/child/@id", timestamp = "/child/@timestamp"))
define stream FooStream (id string, timestamp string, key string, value string);

Above configuration will do a custom mapping and and get the <child> element as a whole event in the given XPath when the XML content received in a steaming manner (eg: when a file is read line by line and sent to the XML mapper to map).
The attribute mapping has to be done with respect to the element mapped in the XPath which is <child>
Expected input will look like below.
<root>
   <bounds minlat="53.4281" minlon="-2.4142" maxlat="54.0097" maxlon="-0.9762"/>
   <child id="413229" timestamp="2014-09-10T14:12:48Z"/>
   <child id="414427" timestamp="2018-01-24T23:16:10Z"/>
   <child id="673959" timestamp="2019-10-20T12:07:13Z">
       <extra id="1234" timestamp="2014-09-11T10:36:37Z"/>
       <detail key="company" value="wso2"/>
       <extra id="0987" timestamp="2014-09-11T10:36:37Z"/>
       <detail key="country" value="Sri Lanka"/>
   </child>
   .
   .
</root>