Skip to content

Latest commit

 

History

History
106 lines (85 loc) · 5.14 KB

soap_client_tutorial.md

File metadata and controls

106 lines (85 loc) · 5.14 KB
Raw

Introduction

This tutorial shows how to create a SOAP client from an existing WSDL, based on the same example that was used in the server tutorial.

The server tutorial shows how the client module that is generated by soap:wsdl2soap() can be used. It explains how you can call a service, with or without SOAP headers.It does not explain how the generated client can be customized. This is necessary in particular if you want to access information in the SOAP header of the response message.

This document gives a more thorough description of how the generated client module can be used, and it describes how the client can be modified to make the SOAP header information available.

Contents

Generating the client module

A module that implements an Erlang client from a WSDL can be generated using soap:wsdl2erlang(). See the SOAP reference manual for more detail, and the SOAP server tutorial for an example.

Using the generated client

The client module that is generated by soap:wsdl2erlang() exports a function for each of the service's operations. These functions take 3 parameters (or 4, if the option {attachments, true} was used when generating the client).

  1. The first argument must be the record that corresponds with the body of the SOAP request. In the generated module you can find the type of that record, and in the generated .hrl file you can find a specification of the record. The soap application will encode this record and use it as the content of the SOAP Body.

    Alternatively it is possible to pass an iolist() as the first argument. In that case the value will be used as the value for the complete request message. In other words, the iolist must contain a complete SOAP envelope, with SOAP body and SOAP header, and it is not possible to specify SOAP header blocks separately (the second argument, see below, must be []).

  2. The second argument is a list of SOAP header blocks. If any are specified, these will be included in the SOAP header.

There are 2 ways to specify a SOAP header block:

  1. As an iolist(). This must be a valid XML snippet. It will simply be copied literally to the SOAP Header.

  2. As a record that corresponds to a type from the WSDL. This is comparable with the way the content of the SOAP body is passed. The record will be translated to XML by the soap application.

  3. The third argument is a list of options. The following options are available:

  4. {http_client, module()} - use an HTTP client that is different from what was specified when generating the client module. The Module must be an Erlang module that implements the interface that is described in Integrating a HTTP client.

  5. {url, URL::string()} - use a URL that is different from the URL specified in the WSDL.

  6. {timeout, Value}. This allows to set the timeout for the request, in milliseconds. It defaults to the default of the used client (ibrowse: 3000 milliseconds, inets/httpc: infinity).

All other options used here are passed on to the application that is used to implement the HTTP client (so the options that are available and their effect depends on the selected HTTP server).

  1. (Only if the option {attachments, true} was used to generate the client) - Attachments to be added to the request. See SOAP attachments for an explanation how to specify the attachments.

Customizing the generated client

The SOAP response that is received by the client may contain SOAP header blocks. By default these header blocks will not be parsed, and they will not be available in the SOAP response. In order to change that, some customization of the client module is necessary.

This customization follows a pattern that is similar to what is done on the server side, see the server tutorial.

When the soap application finds a SOAP header block during the parsing of the response message, it will call the client module to find out how to handle the header block, based on the namespace of that header block. For this the callback function header_parser/1 is called in the client module.

The header_parser/1 function must return {ok, {Parser, Start_state}}, where Parser is an erlsom sax callback function and a Start_state the initial state that will be passed to the parser. The module soap_parsers provides a number of possible alternatives, such as a parser that translates the header block to a map, or a parser that simply skips the content of the header block. For more details see the reference for soap_parsers.

The default return value is a parser that ignores the content of the header block (it returns undefined, whatever the value of the header block is).

An example of the use of this callback can be found in "example_client.erl".