Calling web services

It is possible to call Service Broker web services from applications written in languages that have support for sockets, HTTP, and SOAP (e.g. Java, C#, and VB.NET). Details on how to create and configure this type of applications is beyond the scope of this document, since it can be done in many different ways. To understand how to use the information described here, you must be experienced in the area of web services and WSDL.

Importing the Service Broker WSDL definition

The WSDL description of the web services exposed by the Service Broker (SendDocument and SendReceiveDocument) is located in:

<StreamServe installation>\Applications\StreamServer\<version>\
Server\servicebroker.wsdl

You must use the appropriate tools to convert this file to the proxy code needed to make a SOAP call. For example in a .NET environment you just have to import servicebroker.wsdl to the Visual Studio development environment.

Creating the function calls

When the proxy code is generated, you must write the function calls that you need to pass all necessary parameters to the web service.

Methods

The following methods are available:

•	SendDocument(ServiceDescription, ServiceVersion, ServerID, DocData)

•	SendReceiveDocument(ServiceDescription, ServiceVersion, ServerID, DocData)


Parameter	Description
ServiceDescription	A string specifying the name of the published service to invoke.
ServiceVersion	A string specifying the version of the published service. If omitted, the Service Broker invokes the highest available version of the service.
ServerID	A string specifying the service name of a specific StreamServer. Specify this only if you want to send the data to a specific StreamServer.
DocData	The document to send to the service. In the WSDL description, this is declared as soap-enc:base64 encoded data. The document can be anything ranging from plain ASCII to PDF. It must therefore be base64 encoded. In a VB.NET environment, the actual base64 conversion is done by the generated VB.NET web service proxy code, and is therefore transparent to the calling application.

Example 4

Simple VB.NET client call – SendDocument

Use SendDocument to send the text “Test data” to the service Service_3, version 1.

Dim soapSendDocument As SOAPReference.SendDocumentSOAP Dim soapRequestData As Byte() Dim unicodeEncoder As System.Text.UnicodeEncoding ’Create the SOAP method wrapper. soapSendDocument = New SOAPReference.SendDocumentSOAP soapSendDocument.Url = "http://wghot06:1717" ’Convert input data from a unicode encoded string to a byte array. unicodeEncoder = New System.Text.UnicodeEncoding soapRequestData = unicodeEncoder.GetBytes("Test data") unicodeEncoder = Nothing ’Make the SOAP call. soapSendDocument.SendDocument("Service_3","1","", soapRequestData) soapSendDocument = Nothing

Dim soapSendDocument As SOAPReference.SendDocumentSOAP

Dim soapRequestData As Byte()

Dim unicodeEncoder As System.Text.UnicodeEncoding

’Create the SOAP method wrapper.

soapSendDocument = New SOAPReference.SendDocumentSOAP

soapSendDocument.Url = "http://wghot06:1717"

’Convert input data from a unicode encoded string to a byte array.

unicodeEncoder = New System.Text.UnicodeEncoding

soapRequestData = unicodeEncoder.GetBytes("Test data")

unicodeEncoder = Nothing

’Make the SOAP call.

soapSendDocument.SendDocument("Service_3","1","", soapRequestData)

soapSendDocument = Nothing

Example 5

Simple VB.NET client call – SendReceiveDocument

Use SendReceiveDocument to send the text “Test data” to the service Service_3, version 1, and to receive a response from the service.

Dim soapSendReceiveDocument As ServiceBroker.SendReceiveDocumentSOAP Dim soapRequestResponseData As Byte() Dim decoder As System.Text.ASCIIEncoding Dim unicodeEncoder As System.Text.UnicodeEncoding Dim soapResponseString As String ’Call SendRevceiveDocument method. soapSendReceiveDocument = New ServiceBroker.SendReceiveDocumentSOAP soapSendReceiveDocument.Url = "http://wghot06:1717" unicodeEncoder = New System.Text.UnicodeEncoding soapRequestResponseData = unicodeEncoder.GetBytes("Test data") unicodeEncoder = Nothing soapSendReceiveDocument.SendReceiveDocument("TestService", "1", "", soapRequestResponseData) ’Convert the received ascii byte array to a unicode string. ’This depends on the returned data. Assume that return data is a Unicode string. decoder = New System.Text.ASCIIEncoding soapResponseString = decoder.GetChars(soapRequestResponseData) decoder = Nothing

Dim soapSendReceiveDocument As ServiceBroker.SendReceiveDocumentSOAP

Dim soapRequestResponseData As Byte()

Dim decoder As System.Text.ASCIIEncoding

Dim unicodeEncoder As System.Text.UnicodeEncoding

Dim soapResponseString As String

’Call SendRevceiveDocument method.

soapSendReceiveDocument = New ServiceBroker.SendReceiveDocumentSOAP

soapSendReceiveDocument.Url = "http://wghot06:1717"

unicodeEncoder = New System.Text.UnicodeEncoding

soapRequestResponseData = unicodeEncoder.GetBytes("Test data")

unicodeEncoder = Nothing

soapSendReceiveDocument.SendReceiveDocument("TestService", "1", "", soapRequestResponseData)

’Convert the received ascii byte array to a unicode string.

’This depends on the returned data. Assume that return data is a Unicode string.

decoder = New System.Text.ASCIIEncoding

soapResponseString = decoder.GetChars(soapRequestResponseData)

decoder = Nothing

Client call scenario

When the Service Broker receives a call, it will parse the SOAP package to make sure that it conforms to the SOAP standard. Then it starts to extract all known parameters for a given SOAP action (SendDocument or SendReceiveDocument). If any parameter is missing or unrecognized, the Service Broker returns a SOAP error to the client. If all parameters are present and valid, the Service Broker uses an internal protocol mapping to convert the SOAP call into an HTTP call. It then forwards the HTTP call to a service that matches the ServiceDescription and ServiceVersion parameters in the SOAP call.

When the StreamServer has processed the data, and returned a response to the Service Broker (SendReceiveDocument only), the Service Broker creates a SOAP response package, and returns the processed data to the calling client.