Copyright © TIBCO Software Inc. All Rights Reserved
Copyright © TIBCO Software Inc. All Rights Reserved


Chapter 6 HTTP and SOAP Channels : Parsing and Building SOAP Messages

Parsing and Building SOAP Messages
This section explains how to use the SOAP functions to parse information from incoming requests, and to construct outgoing messages (responses and requests) in your rules and rule functions.
This manual does not explain how to work with the SOAP protocol. For example, you should understand how the Actor and MustUnderstand attributes in SOAP headers are used to process the message as it passes from its originator, through intermediary applications, to its ultimate destination.
Working with Incoming SOAP Messages (Event Payloads)
An incoming SOAP message can be a request, or a response, depending on whether TIBCO BusinessEvents is acting as the server or the client. TIBCO BusinessEvents can also act as an intermediate node along the path of a SOAP message to its ultimate destination. This section explains how to parse (get) information out of the incoming event payload, which contains the SOAP message.
To Parse the SOAP Envelope
String getEnvelope(SimpleEvent inSoapEvent)
Given a request SOAPEvent, this function returns the SOAP envelope in the request event payload, for example:

 
<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns:sch="http://www.tibco.com/schemas/SoapOverHttp/Schema/Schema.xsd" >
  <soapenv:Header/>
    <soapenv:Body>
      <sch:root>
        <sch:First>1</sch:First>
        <sch:Second>2</sch:Second>
      </sch:root>
    </soapenv:Body>
  </soapenv:Envelope>
</message>

 
To Parse (and Optionally Remove) Headers and Header Attributes
String[] getHeaders(SimpleEvent inSoapEvent, String actor, Boolean removeHeaders)
If the actor parameter has a null value then all the immediate children of the Header element are retrieved:
getHeaders(inSoapEvent,null,false)
Otherwise, the header specified by the actor attribute is retrieved. For example, given this Headers element in a SOAP event payload:

 
    <soapenv:Header>
      <t:user xmlns:t="http://schemas/xml.com" soapenv:mustUnderstand="true"
            soapenv:actor="http://localhost:9090/Service">jon</t:user>
      <t:user_surname xmlns:t="http://schemas/xml.com"
                    soapenv:mustUnderstand="true"
                    soapenv:actor="http://localhost:9090">smith</t:user_surname>
    </soapenv:Header>

 
If you specify the following:
getHeaders(inSoapEvent,"http://localhost:9090/Service",false)
To remove the specified header part or parts, set the final parameter to true. (The SOAP specification states that if a header is processed it should be removed. You would remove a header if TIBCO BusinessEvents is acting as an intermediary node and the request created using the SOAP functions will be sent on to another server.)
Then the first Headers element is returned:

 
      <t:user xmlns:t="http://schemas/xml.com" soapenv:mustUnderstand="true"
            soapenv:actor="http://localhost:9090/Service">jon</t:user>

 
You can also retrieve the attributes of a SOAP Header element:
String[] getSOAPHeaderAttribute(SimpleEvent inSoapEvent, int index, String attribute)
You can also remove all or selected headers using one of these functions:
removeHeaderPart()
removeHeaderParts()
To Parse the SOAP Body (SOAPBodyParts)
Two functions are available for getting SOAP body parts.
String[] getAllSOAPBodyParts(SimpleEvent inSoapEvent)
String[] getSOAPBodyParts(SimpleEvent inSoapEvent, String name, String namespace)
The getAllSOAPBodyParts() function simply returns all SOAP body parts.
The getSOAPBodyParts() function allows you to specify which parts are of interest. Given a body part name and a namespace for a specified SOAPEvent, it returns a String array of matching SOAP body parts in serialized form. Name and namespace parameters cannot be null.
Example
Given this function:

 
String[] body_part= getSOAPBodyParts
(soapeventin,"root",http://www.tibco.com/schemas/SoapOverHttp/Schema/Schema.xsd)

 
And this soapeventin event payload:

 
<?xml version="1.0" encoding="UTF-8"?>
<message>
  <soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns:sch="http://www.tibco.com/schemas/SoapOverHttp/Schema/Schema.xsd" xmlns:temp="http://temp/">
  <soapenv:Header/>
    <soapenv:Body>
      <sch:root>
        <sch:First>1</sch:First>
        <sch:Second>2</sch:Second>
      </sch:root>
      <sch:parent2>
        <sch:child1>3</sch:child1>
        <sch:child2>4</sch:child2>
      </sch:parent2>
    </soapenv:Body> </soapenv:Envelope>

 
You would get this as the SOAP body part:

 
body_part[0]=
<?xml version="1.0" encoding="UTF-8"?>
<ns0:root xmlns:ns0="http://www.tibco.com/schemas/SoapOverHttp/Schema/Schema.xsd">
  <ns0:First>1</ns0:First>
  <ns0:Second>2</ns0:Second>
</ns0:root>

 
To Parse Attachments
The following functions enable you to work with SOAP attachments in the request message:
getNumberOfAttachments(SimpleEvent inSOAPEvent)
getAttachmentContentID(SimpleEvent inSOAPEvent, int Index)
getAttachmentContentType(SimpleEvent inSOAPEvent, int Index)
getAttachmentContent(SimpleEvent inSOAPEvent, int Index)
getAttachmentContentByContentID(SimpleEvent inSOAPEvent, string contentID)
The content ID is the attachment identifier. You can select which attachment to work with using its index position. First get the count of the attachments using getNumberOfAttachments(). Then using the index, you can get the content ID and content type, as well as the attachment content itself.
The content is returned in byte form, so after you get the content, you must then use other functions to make the content human-readable.
For an example, see http://www.w3.org/TR/SOAP-attachments#SOAPReferenceToAttachements.
To Parse SOAP Fault XML Nodes
The following functions enable you to work with the standard SOAP Fault XML nodes from the payload of a SOAP event:
getFault (SimpleEvent, soapEvent)
getFaultActor (SimpleEvent, soapEvent)
getFaultCode (SimpleEvent, soapEvent)
getFaultString (SimpleEvent, soapEvent)
Working with Outgoing SOAP Messages (Event Payloads)
You can add header parts, body parts, fault parts and attachments to the outgoing SOAP message (whether it is a response or a request).
The signatures of the relevant functions are as follows:
addHeaderPart(SimpleEvent outSOAPEvent, String headerPartXml)
addSOAPBodyPart(SimpleEvent outSOAPEvent, String bodyXML)
addSOAPHeaderAttribute(SimpleEvent outSOAPEvent, int index, String attribute, String value)
addFaultPart(SimpleEvent outSOAPEvent, String faultCode, String faultMessage, String faultActor, String faultDetailString)
addAttachment(SimpleEvent outSOAPEvent, String contentID, String content, String contentType, String contentEncoding)
TIBCO BusinessEvents adds each type of fragment to the appropriate part of the event payload — header, body, or fault. The fragments must be well-formed XML. You can also add attachments.
For example, to add a body part containing information for a response you would include all the required details including any namespace information:

 
SOAP.addSOAPBodyPart(outSOAPEvent,"<ns0:BookStore xmlns:ns0=\"http://www.abc.com/xsd/books\"><ns0:Book><ns0:Author>J.K.Rowling</ns0:Author></ns0:Book></ns0:BookStore>");

 
The specified body part is added to the correct place in the outline structure of the SOAP message, which is provided by the SOAPEvent. The resulting payload would look similar to the following:

 
<SOAP-ENV:Envelope xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/">
  <SOAP-ENV:Body>
    <ns0:BookStore xmlns:ns0="HTTP://www.abc.com/xsd/books">
      <ns0:Book>
        <ns0:Author>J.K.Rowling</ns0:Author></ns0:BookStore>"
      </ns0:Book>
    </ns0:BookStore>
  </SOAP-ENV:Body>
</SOAP-ENV:Envelope>

 
 

Copyright © TIBCO Software Inc. All Rights Reserved
Copyright © TIBCO Software Inc. All Rights Reserved