SOAP class

Background

The SOAP communication protocol and the Web Services framework provide a standard mechanism to communicate between applications and more precisely to request the execution of a particular service in a different application (a "remote procedure call"). The communicating applications may be running on the same computer, on computers in the same local network or on remote computers across the Internet.

For more information see http://www.w3.org/TR/SOAP/.

Overview

The SOAP class supports a subset of the SOAP 1.1 communication protocol over HTTP. Specifically, it allows remote procedure calls to be made to a remote server. The SOAP protocol is used to marshall JavaScript parameters to a remote procedure call and to unmarshall the result as a JavaScript object.

The current implementation has the following restrictions:

Supports only SOAP 1.1 (and not 1.2).
Supports only synchronous processing (and not asynchronous).
Supports DIME and MIME attachments in the SOAP message
Always uses SOAP encoding style (as defined in the specification section 5).

Class instances

The send and request methods - which were already available in older Switch versions – are static functions which allow sending of a simple SOAP message without headers. As they are static functions, there is no need to create instances of the SOAP class.

For more direct control an instance of the SOAP class may be created. This represents an entire SOAP request and/or response message including body, headers and envelope.

Static Functions

request( url : String, request-object : request-object, action : String ) : response-object

Initiates a remote procedure call (RPC) or sends an XML message to a SOAP HTTP endpoint, waits for the endpoint to reply (synchronous processing) and returns its response.

An exception is thrown if the request object does not conform, when the SOAP endpoint returns a SOAPFault or when there is a failure from the underlying HTTP transport layer.

send ( url : String, request-object : request-object, action : String )

Initiates a remote procedure call (RPC) or sends an XML message to a SOAP HTTP endpoint without waiting for a reply.

An exception is thrown if the request object does not conform or when there is a failure from the underlying HTTP transport layer.

Constructing

SOAP ( ): Constructs a new empty SOAP request.
SOAP ( request-object : request-object ): Constructs a new SOAP request and sets the SOAP body
SOAP ( in-path : String ): Constructs a new SOAP request and reads the SOAP envelope from the specified XML file.

Property accessing

isResponse ( ) : Boolean: Returns whether the SOAP message is a SOAP response.
getBody ( ) response-object: Returns the SOAP body from the SOAP message.
setBody ( request-object : request-object ): Sets the SOAP body to the SOAP request. The body is replaced with the new body and the headers are preserved.
getHeader ( ) : header-object: Returns the SOAP header from the SOAP message.
setHeader ( header-object : header-object ): Sets the SOAP header to the SOAP request. The body is associated with the new header and the body itself is preserved.

Sending messages

requestMessage ( url : String, action : String ) : SOAP

Initiates a remote procedure call (RPC) or sends an XML message to a SOAP HTTP endpoint, waits for the endpoint to reply (synchronous processing) and returns its response.

An exception is thrown if the request object does not conform, when the SOAP endpoint returns a SOAPFault or when there is a failure from the underlying HTTP transport layer.

sendMessage ( url : String, action : String )

Initiates a remote procedure call (RPC) or sends an XML message to a SOAP HTTP endpoint without waiting for a reply.

An exception is thrown if the request object does not conform or when there is a failure from the underlying HTTP transport layer.

Logging and debugging

writeToFile ( filename : String ) : Boolean: Writes the SOAP message envelope (including body and headers) to an XML file

Working with attachments

Data exchange is widely used in Web Services word. SOAP message is convenient to exchange with text data, but not convenient when exchanging large amount of data or when data is in binary format. For such purposes SOAP protocol provides ability to attach additional data to SOAP message. Switch SOAP class supports two types of attachments:

DIME (Direct Internet Message Encapsulation) - in this case SOAP message contains DIME attachments, when sending the message is being sent packet in DIME format and SOAP message header contains type of "application/dime". See http://msdn.microsoft.com/en-us/magazine/cc188797.aspx
MIME (Multipurpose Internet Mail Extensions) - in this case SOAP message contains MIME attachments, when sending the message is being sent in MIME format and SOAP message header contains type of "multipart/related". See article http://www.w3.org/TR/SOAP-attachments

addAttachment(file-path : String, id : String, type : String, chunk-size : Number): add attachment to message specifying the file name, attachment id and type values, chunk size is not used and reserved for future use, should be 0
getAttachmentsCount() : Number: return number of attachments in the SOAP message
getAttachment(index : Number) : ByteArray
getAttachment(id : String) : ByteArray: return contents of attachment specified by index "inIndex" of attachment identifier "inID"
getAttachmentID(index : Number) : String: get attachment identifier, specifying attachment by index
getAttachmentType(index : Number) : String: return attachment type string
getAttachmentIndex(id : String) : Number: get index of attachment with the given identifier
saveAttachment(index : Number, file-path : String) : Boolean
saveAttachment(id : String, file-path : String) : Boolean: save attachment to the disk file
setAttachmentSendType(attachment-type : Number)
getAttachmentSendType() : Number: set/get attachment send type: 0 - DIME format; 1 - MIME format

Working with SOAP message body, retrieving information

Since SOAP message body is a text in XML format, it is convenient to gather information from it as from XML. There are some functions to work with SOAP message as with XML document:

parseBody(element-name : String) : String[ ]: returns array of elements' values specified with name equivalent to Document's evalToNodesList, getNodeValue, except that elements specified by name, not by XPath
saveBody(file-path : String, root-element-name : String) : Boolean: saves extract from SOAP body specifying root element into file on disk
changeElement(element-name : String, new-value : String): set SOAP body element value