SoapClient::SoapClient Class Reference

SOAP client class implementation, publically inherits qore's HTTPClient class. More...

Inherits HTTPClient.

## Public Member Functions

| constructor (hash h)
| creates the object based on a WSDL which is parsed to a WebService object which provides the basis for all communication with this object More...
hash | getMsg (string operation, any args, *hash header, reference op, *hash nsh)
| returns a hash representing the serialized SOAP request for a given WSOperation More...
any | call (string operation, any args, *hash header, *hash nsh)
| makes a server call with the given operation and arguments and returns the deserialized result More...
any | call (string operation, any args, *reference info)
| makes a server call with the given operation and arguments and returns the deserialized result More...
any | call (reference info, string operation, any args, *hash header, *hash nsh)
| makes a server call with the given operation and arguments and returns the deserialized result with an output argument giving technical information about the call More...
private any | makeCallIntern (*reference info, string operation, any args, *hash header, *hash nsh)
| makes the call to the SOAP server and ensures that SOAP fault responses returned with a 500-series status code are processed as a SOAP fault so that error information is returned in the resulting exception
any | methodGate (string op, any arg)
| uses SoapClient::call() to transparently serialize the argument and make a call to the given operation and return the deserialized results More...
hash | getType (string type, any v)
| returns a hash that can be used to ensure serialization with the XSD type given as the type argument
WSDL::WebService | getWebService ()
| returns the WSDL::WebService object associated with this object
| setSendEncoding (string enc="auto")
| change the data content encoding (compression) option for the object; see EncodingSupport for valid options More...
| setContentEncoding (string enc="auto")
| sets the request and desired response encoding for the object; see EncodingSupport for valid options More...
| addDefaultHeaders (hash h)
| adds default headers to each request; these headers will be sent in all requests but can be overridden in requests as well More...
hash | getDefaultHeaders ()
| returns the hash of default headers to sent in all requests More...
*string | getSendEncoding ()
| returns the current data content encoding (compression) object or nothing if no encoding option is set; see EncodingSupport for valid options More...
| log (string msg)
| sends a log message to the log closure or call reference, if any
| dbglog (string msg)
| sends a log message to the debug log closure or call reference, if any

## Public Attributes

const | Version = "0.2.4"
| version of the implementation of this class
const | Headers = ("Accept": (MimeTypeSoapXml + "," + MimeTypeXml + "," + MimeTypeXmlApp), "User-Agent": ("Qore-Soap-Client/" + SoapClient::Version))
| default HTTP headers
const | HTTPOptions = ("connect_timeout", "http_version", "max_redirects", "proxy", "timeout")
| option keys passed to the HTTPClient constructor
string | url
| target URL
hash | headers = Headers
| HTTP headers to use.
const | EncodingSupport
| Send content encoding options. More...
const | CompressionThreshold = 1024
| default threadhold for data compressions; transfers smaller than this size will not be compressed

## Detailed Description

SOAP client class implementation, publically inherits qore's HTTPClient class.

## Member Function Documentation

SoapClient::SoapClient::addDefaultHeaders | ( | hash | h | ) |

adds default headers to each request; these headers will be sent in all requests but can be overridden in requests as well

Example:
  # disable gzip and bzip encoding in responses
  soap.addDefaultHeaders(("Accept-Encoding": "compress"));

Parameters

  h | a hash of headers to add to the default headers to send on each request

Note
  default headers can also be set in the constructor

See also
  SoapClient::getDefaultHeaders()

Since
  SoapClient 0.2.4

any SoapClient::SoapClient::call | ( | string | operation,
|  | any | args,
|  | *hash | header,
|  | *hash | nsh
| ) |  |

makes a server call with the given operation and arguments and returns the deserialized result

Parameters

  operation | the operation name for the SOAP call
  args | the arguments to the SOAP operation
  header | optional soap headers (if required by the operation)

Returns
  the deserialized result of the SOAP call to the SOAP server

any SoapClient::SoapClient::call | ( | string | operation,
|  | any | args,
|  | *reference | info
| ) |  |

makes a server call with the given operation and arguments and returns the deserialized result

Parameters

  operation | the operation name for the SOAP call
  args | the arguments to the SOAP operation
  info | an optional reference to return a hash of technical information about the SOAP call (raw message info and headers)

Returns
  the deserialized result of the SOAP call to the SOAP server

any SoapClient::SoapClient::call | ( | reference | info,
|  | string | operation,
|  | any | args,
|  | *hash | header,
|  | *hash | nsh
| ) |  |

makes a server call with the given operation and arguments and returns the deserialized result with an output argument giving technical information about the call

Parameters

  info | an optional reference to return a hash of technical information about the SOAP call (raw message info and headers)
  operation | the operation name for the SOAP call
  args | the arguments to the SOAP operation
  header | optional soap headers (if required by the operation)

Returns
  the deserialized result of the SOAP call to the SOAP server

SoapClient::SoapClient::constructor | ( | hash | h | ) |

creates the object based on a WSDL which is parsed to a WebService object which provides the basis for all communication with this object

one of either the `wsdl` or `wsdl_file` keys is required in the hash given to the constructor or an exception will be thrown

Parameters

  h

  valid option keys:
  - `wsdl:` the URL of the web service or a WebService object itself
  - `wsdl_file:` a path to use to load the WSDL and create the WebService object
  - `url:` override the target URL given in the WSDL
  - `send_encoding:` a send data encoding option or the value `"auto"` which means to use automatic encoding; if not present defaults to no content-encoding on sent message bodies
  - `content_encoding:` for possible values, see EncodingSupport; this sets the send encoding (if the `"send_encoding"` option is not set) and the requested response encoding
  - [`service`]: in case multiple service entries are found in the WSDL, give the one to be used here
  - [`port`]: in case multiple port entries are found in the WSDL, give the one to be used here
  - [`log`]: a log closure or call reference taking a single string giving the log message
  - [`dbglog`]: a log closure or call reference taking a single string giving the debug log message
  - also all options from SoapClient::SoapClient::HTTPOptions, which are passed to the HTTPClient constructor

hash SoapClient::SoapClient::getDefaultHeaders | ( |  | ) |

returns the hash of default headers to sent in all requests

Example:
  hash h = soap.getDefaultHeaders();

Returns
  the hash of default headers to sent in all requests

Note
  default headers can be set in the constructor and in addDefaultHeaders()

See also
  SoapClient::addDefaultHeaders()

Since
  SoapClient 0.2.4

hash SoapClient::SoapClient::getMsg | ( | string | operation,
|  | any | args,
|  | *hash | header,
|  | reference | op,
|  | *hash | nsh
| ) |  |

returns a hash representing the serialized SOAP request for a given WSOperation

Parameters

  operation | the SOAP operation to use to serialize the request; if the operation is not known to the underlying WebService class, an exception will be thrown
  args | the arguments to the SOAP operation
  header | data structure for the SOAP header, if required by the message
  op | a reference to return the WSOperation object found

Returns
  a hash with the following keys:
  - `hdr:` a hash of message headers
  - `body:` the serialized message body

Exceptions

  SOAP-CLIENT-ERROR | the operation is not defined in the WSDL

Note
  content encoding is not applied here but rather internally by the call() methods

*string SoapClient::SoapClient::getSendEncoding | ( |  | ) |

returns the current data content encoding (compression) object or nothing if no encoding option is set; see EncodingSupport for valid options

Example:
  *string ce = soap.getSendEncoding();

Returns
  the current data content encoding (compression) object or nothing if no encoding option is set; see EncodingSupport for valid options

See also
  - SoapClient::setContentEncoding()
  - SoapClient::setSendEncoding()

Since
  SoapClient 0.2.4

any SoapClient::SoapClient::methodGate | ( | string | op,
|  | any | arg
| ) |  |

uses SoapClient::call() to transparently serialize the argument and make a call to the given operation and return the deserialized results

Parameters

  op | the operation name, which is the method name passed to methodGate()
  arg | a list or arguments or a single argument (or NOTHING) for the operation

Returns
  the deserialized result of the SOAP call to the SOAP server

SoapClient::SoapClient::setContentEncoding | ( | string | enc = `"auto"` | ) |

sets the request and desired response encoding for the object; see EncodingSupport for valid options

Example:
  soap.setContentEncoding("gzip");

Parameters

  enc | the data content encoding (compression) option for requests and the desired response content encoding for the object; see EncodingSupport for valid options; if the value `"auto"` is passed then `"gzip"` encoding is used for outgoing requests and requested for responses

Exceptions

  SOAPCLIENT-ERROR | invalid or unsupported data content encoding / compression option

See also
  - SoapClient::getSendEncoding()
  - SoapClient::setSendEncoding()

Since
  SoapClient 0.2.4

SoapClient::SoapClient::setSendEncoding | ( | string | enc = `"auto"` | ) |

change the data content encoding (compression) option for the object; see EncodingSupport for valid options

Example:
  sc.setSendEncoding("gzip");

The default is to send requests unencoded/uncompressed.

Parameters

  enc | the data content encoding (compression) option for the object; see EncodingSupport for valid options; if the value `"auto"` is passed then `"gzip"` encoding is used

Exceptions

  SOAPCLIENT-ERROR | invalid or unsupported data content encoding / compression option

See also
  - SoapClient::setContentEncoding()
  - SoapClient::getSendEncoding()

## Member Data Documentation

const SoapClient::SoapClient::EncodingSupport

Initial value:
= (
"gzip": (
"ce": "gzip",
"func": \gzip(),
),
"bzip2": (
"ce": "bzip2",
"func": \bzip2(),
),
"deflate": (
"ce": "deflate",
"func": \compress(),
),
"identity": (
"ce": NOTHING,
),
)

Send content encoding options.

Send content encoding options are as follows:

- `"bzip"`: use bzip2 compression
- `"gzip"`: use gzip compression
- `"deflate"`: use deflate compression
- `"identity"`: use no content encoding