Copyright © Cloud Software Group, Inc. All Rights Reserved

The SOAP Palette

TIBCO ActiveMatrix BusinessWorks can act as a SOAP client and send SOAP requests to remote web services, or TIBCO ActiveMatrix BusinessWorks can act as a SOAP server and handle incoming SOAP requests. Figure 56 illustrates how the activities of the SOAP palette allow TIBCO ActiveMatrix BusinessWorks to send and receive SOAP requests.

Figure 56 Activities in the SOAP palette

Sending SOAP Requests

A TIBCO ActiveMatrix BusinessWorks process definition can perform a SOAP request operation using the SOAP Request Reply activity. In this case, the process acts as a SOAP client that sends a request to a web service. The web service is described in a WSDL file. You can retrieve WSDL files from well-known web service registries. See WSIL Files and UDDI Registries for more information.

Once a WSDL file is retrieved, you can store and use the WSDL file in the project. You can view and manipulate the WSDL file with the WSDL palette. See TIBCO ActiveMatrix BusinessWorks Palette Reference for more information.

The web service may be configured to send a reply or a fault. The SOAP Request Reply activity executes synchronously. When the web service sends a fault, the fault is stored in the error output of the activity and an error transition is taken to the next activity in the process definition. One-way operations do not receive reply or fault messages.

Receiving SOAP Requests

TIBCO ActiveMatrix BusinessWorks can implement a web service through a process definition. The SOAP Event Source process starter defines the concrete WSDL file for the web service. SOAP clients must retrieve the concrete WSDL file before sending a SOAP request to the service. The WSDL Palette allows you to locate and store existing concrete service definitions or create your own abstract service definition. If you use an existing concrete service definition, the concrete bindings are ignored, and you can configure the service to use different namespaces and input/output headers.

Using the SOAP Event Source process starter allows you to use WSDL interface files that have only one operation. That is, you can only implement one operation in the process definition that has the SOAP Event Source. If you wish to implement a service with multiple operations, use the Service resource.

To create a web service, perform the following general procedure:

1.	Create XSDs to define the input, output, and fault messages for the web service.

2.	Create a WSDL File resource that defines the interface to the web service.

3.	Create a process definition that performs the work of the web service. Use the SOAP Event Source process starter for this process definition. Use the SOAP Send Reply activity to return a reply or the SOAP Send Fault activity to return a fault to the client.

4.	Create a process definition that retrieves the concrete WSDL file and sends it to web service clients. Use the HTTP Receiver process starter and the Retrieve Resources activity for this process definition.

See TIBCO ActiveMatrix BusinessWorks Palette Reference for more information about the resources in the SOAP palette.

Processing SOAP Messages with Attachments

SOAP messages can have message parts that contain attachments. For a message part to contain an attachment, specify the Special Type in the Type field of the Part Details section of the Message resource when creating a WSDL file configuration. See TIBCO ActiveMatrix BusinessWorks Palette Reference for information about creating WSDL files.

Messages with Attachments

SOAP clients that send messages with attachments must conform to the SOAP Messages with Attachments specification (http://www.w3.org/TR/SOAP-attachments).

As described in this specification, the messages are transmitted separately as a MIME attachment and the SOAP message may or may not have a reference to the attachment. The actual data for attachments is always contained within the mimeEnvelopeElement of the output schema for the given resource. This element contains a repeating element named mimePart that holds the list of attachments in the SOAP message. The attachment list can be correlated to the message parts containing the attachments by using the content-id mimeHeader element. Note that the attachment is not a part of the SOAP infoset.

For all existing projects, the SwA attachment style is the default option.

Message Transmission Optimization Mechanism

Message Transmission Optimization Mechanism (MTOM) provides another way of sending binary content or attachment processing by serializing SOAP messages with attachments. This is available only with SOAP verion 1.2. Optimization is only available for element content that is in a canonical lexical representation of xs:base64Binary data type. Message Transmission Optimization Mechanism (MTOM) conforms to the specification http://www.w3.org/TR/soap12-mtom.

For an outbound SOAP Message with MTOM attachments sent by SOAP Request Reply or SOAP Send Reply activities, any element of type xs:base64Binary (or an extension of xs:base64Binary) in the SOAP response message is treated as an MTOM attachment and appears as a separate MIME part on the wire.

For an inbound SOAP Message with MTOM attachments received by the SOAP Event Source or SOAP Request Reply activities, the SOAP message will have a XOP include reference to the attachment. Any XOP include reference in the SOAP message will be replaced by the corresponding attachment’s content encoded in Base64. Any MIME attachment that is not referenced from the SOAP Message using XOP include reference will be ignored by the MTOM Processing layer.

Following is an example of how a MTOM message is transmitted on the wire and the XOP mechanism is used to reference the attachments from the SOAP message.

MIME-Version: 1.0

Content-Type: Multipart/Related;boundary=MIME_boundary;

type="application/xop+xml";

start="<mymessage.xml@example.org>";

startinfo="application/soap+xml; action=\"ProcessData\""

Content-Description: A SOAP message with my pic and sig in it

--MIME_boundary

Content-Type: application/xop+xml;

charset=UTF-8;

type="application/soap+xml; action=\"ProcessData\""

Content-Transfer-Encoding: 8bit

Content-ID: <mymessage.xml@example.org>

<soap:Envelope

xmlns:soap='http://www.w3.org/2003/05/soap-envelope'

xmlns:xmlmime='http://www.w3.org/2004/11/xmlmime'>

<soap:Body>

<m:data xmlns:m='http://example.org/stuff'>

<m:photo

xmlmime:contentType='image/png'><xop:Include

xmlns:xop='http://www.w3.org/2004/08/xop/include'

href='cid:http://example.org/me.png'/></m:photo>

<m:sig

xmlmime:contentType='application/pkcs7-signature'><xop:Include

xmlns:xop='http://www.w3.org/2004/08/xop/include'

href='cid:http://example.org/my.hsh'/></m:sig>

</m:data>

</soap:Body>

</soap:Envelope>

--MIME_boundary

Content-Type: image/png

Content-Transfer-Encoding: binary

Content-ID: <http://example.org/me.png>

// binary octets for png

--MIME_boundary

Content-Type: application/pkcs7-signature

Content-Transfer-Encoding: binary

Content-ID: <http://example.org/my.hsh>

// binary octets for signature

--MIME_boundary--

Although the attachment is transmitted outside the SOAP message with a reference to it, the attachment appears as if it’s embedded in the SOAP message. The binary content or the attachment is a part of the SOAP Infoset. MTOM-style attachments are available inline with the SOAP message at as shown in Figure 57.

Figure 57 MTOM Attachment

As a result, the attachment threshold configuration is not applicable to MTOM attachments.

A runtime error will be thrown if a SOAP 1.1 message with MTOM attachments is received.

A way to handle two specific non-standard MTOM/XOP message scenarios: Scenario 1: Non-standard content-type header value in root MIME part in the payload. Set property 'java.property.com.tibco.net.mime.mpwob true' in designer.tra or bwengine.tra. "mpwob" stands for "Multi-parts without boundary". As per MIME multipart spec MIME multipart message without a specified boundary is illegal. Setting this property to 'true' provides a mechanism by which a Content-Type header with a mulitpart field, but without a boundary field, will be treated as a body part. Without this property, the MIME parser will throw an exception when it encounters such a non-standard compliant Content-Type header. Scenario 2: XML-Invalid Characters in SOAP Envelope. The SOAP Envelope in the payload had characters which are reserved characters in XML and cannot be used in XML content. For example, a Windows file name path, C:\. To get around this issue, turn off validation for the Service Resource or SOAP Event Source. • To turn off Validation for all Job creators, set the following property to "false": java.property.Validate.JC • To turn off validation for a particular Service Resource, set the following property to "false": java.property.Validate.JC.<service resource name>.serviceagent • If the Service Resource is inside nested folders, then set the property to "false" using the following pattern property: java.property.Validate .JC.<folder1>/<folder2>/<service resource name>.serviceagent

Handling Large Attachments

TIBCO ActiveMatrix BusinessWorks supports large attachments using the Write to File feature. The support for large attachments is added to the SOAP, Service and HTTP activities (SOAP Request Reply, SOAP Event Source, SOAP Send Reply, Service Resource, Send HTTP Request, HTTP Receiver, and Send HTTP Response). These large attachments can be the files of gigabyte size which are shared between the Client and Server irrespective of the Heap size. For details, refer to the Write to File section in the respective activities in TIBCO ActiveMatrix BusinessWorks Palette Reference.

Service resource handles only large incoming attachments. It does not support large outgoing attachments.

Ensure that the Threshold Data Size is less than the Heap Size and select the "Exclude File Content" checkbox in the 'Read File’ activity. You must also map the 'fileName' output of Read File activity to the 'fileName' attribute of the respective activities’ mimePart.

Write to File is now supported for both SwA and MTOM attachments.

 

 

 

Copyright © Cloud Software Group, Inc. All Rights Reserved