Qore SoapClient Module Reference  0.2.5
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, *int xml_opts, *string soapaction)
 returns a hash representing the serialized SOAP request for a given WSOperation More...
 
any callOperation (string operation, any args, *hash opts, *reference info)
 makes a server call with the given operation, arguments, options, and optional info hash reference and returns the result More...
 
any call (string operation, any args, *hash header, *hash nsh, *string binding)
 makes a server call with the given operation and arguments and returns the deserialized result More...
 
any call (string operation, any args, *reference info, *string binding)
 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...
 
any methodGate (string op)
 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
 
hash getInfo ()
 returns a hash of information about the current WSDL More...
 
 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.5"
 version of the implementation of this class
 
const Headers = ("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
 
 private
 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
 

Private Member Functions

nothing msglog (hash msg)
 

Detailed Description

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

Member Function Documentation

◆ addDefaultHeaders()

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
ha 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

◆ call() [1/3]

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

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

Parameters
operationthe operation name for the SOAP call
argsthe arguments to the SOAP operation
headeroptional soap headers (if required by the operation)
nsha hash giving HTTP header information to include in the message (does not override automatically-generated SOAP message headers)
bindingthe SOAP binding name, if not provided, the first binding assigned to the operation will be used
Returns
the deserialized result of the SOAP call to the SOAP server
Exceptions
WSDL-OPERATION-ERRORthe operation is not defined in the WSDL
WSDL-BINDING-ERRORthe binding is not assigned to a SOAP operation in the WSDL
HTTP-CLIENT-RECEIVE-ERRORthis exception is thrown when the SOAP server returns an HTTP error code; if a SOAP fault is returned, then it is deserialized and returned in the arg key of the exception hash
Note
this method can throw any exception that HTTPClient::send() can throw as well as any XML parsing errors thrown by parse_xml()

◆ call() [2/3]

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

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

Parameters
operationthe operation name for the SOAP call
argsthe arguments to the SOAP operation
infoan optional reference to return a hash of technical information about the SOAP call (raw message info and headers); the following keys are present in this hash:
  • "headers": a hash of HTTP request headers
  • "request-uri": the request URI string (ex: "POST /services/Soap/c/29.0 HTTP/1.1")
  • "response-uri": the response URI string (ex: "HTTP/1.1 200 OK")
  • "charset": the character encoding string (ex: "UTF-8")
  • "body-content-type": the Content-Type of the response without any charset declaration
  • "accept-charset": the valus of any Accept-Charset header in the response
  • "response-headers": a hash of HTTP response headers
  • "response-body": the raw XML response body (in case content encoding is used, this is the decoded value)
  • "request-body": the raw XML request body
  • "request-soap-headers": an optional hash of SOAP headers used in the request (if applicable)
bindingthe SOAP binding name, if not provided, the first binding assigned to the operation will be used
Returns
the deserialized result of the SOAP call to the SOAP server
Exceptions
WSDL-OPERATION-ERRORthe operation is not defined in the WSDL
WSDL-BINDING-ERRORthe binding is not assigned to a SOAP operation in the WSDL
HTTP-CLIENT-RECEIVE-ERRORthis exception is thrown when the SOAP server returns an HTTP error code; if a SOAP fault is returned, then it is deserialized and returned in the arg key of the exception hash
Note
this method can throw any exception that HTTPClient::send() can throw as well as any XML parsing errors thrown by parse_xml()

◆ call() [3/3]

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
infoan optional reference to return a hash of technical information about the SOAP call (raw message info and headers); the following keys are present in this hash:
  • "headers": a hash of HTTP request headers
  • "request-uri": the request URI string (ex: "POST /services/Soap/c/29.0 HTTP/1.1")
  • "response-uri": the response URI string (ex: "HTTP/1.1 200 OK")
  • "charset": the character encoding string (ex: "UTF-8")
  • "body-content-type": the Content-Type of the response without any charset declaration
  • "accept-charset": the valus of any Accept-Charset header in the response
  • "response-headers": a hash of HTTP response headers
  • "response-body": the raw XML response body (in case content encoding is used, this is the decoded value)
  • "request-body": the raw XML request body
  • "request-soap-headers": an optional hash of SOAP headers used in the request (if applicable)
operationthe operation name for the SOAP call
argsthe arguments to the SOAP operation
optsan optional hash of options for the call as follows:
  • soap_header: a hash giving SOAP header information, if required by the message
  • http_header: a hash giving HTTP header information to include in the message (does not override automatically-generated SOAP message headers)
  • xml_opts: an integer XML generation option code; see XML Generation Constants for possible values; combine multiple codes with binary or (|)
  • soapaction: an optional string that will override the SOAPAction for the request; en empty string here will prevent the SOAPAction from being sent
Returns
the deserialized result of the SOAP call to the SOAP server
Exceptions
WSDL-OPERATION-ERRORthe operation is not defined in the WSDL
WSDL-BINDING-ERRORthe binding is not assigned to a SOAP operation in the WSDL
HTTP-CLIENT-RECEIVE-ERRORthis exception is thrown when the SOAP server returns an HTTP error code; if a SOAP fault is returned, then it is deserialized and returned in the arg key of the exception hash
Note
this method can throw any exception that HTTPClient::send() can throw as well as any XML parsing errors thrown by parse_xml()

◆ callOperation()

any SoapClient::SoapClient::callOperation ( string  operation,
any  args,
*hash  opts,
*reference  info 
)

makes a server call with the given operation, arguments, options, and optional info hash reference and returns the result

Parameters
operationthe SOAP operation to use to serialize the request; if the operation is not known to the underlying WebService class, an exception will be thrown
argsthe arguments to the SOAP operation
optsan optional hash of options for the call as follows:
  • soap_header: a hash giving SOAP header information, if required by the message
  • http_header: a hash giving HTTP header information to include in the message (does not override automatically-generated SOAP message headers)
  • xml_opts: an integer XML generation option code; see XML Generation Constants for possible values; combine multiple codes with binary or (|)
  • soapaction: an optional string that will override the SOAPAction for the request; en empty string here will prevent the SOAPAction from being sent
  • binding: the SOAP binding name, if not provided the first binding assigned to the operation will be used
infoan optional reference to return a hash of technical information about the SOAP call (raw message info and headers); the following keys are present in this hash:
  • "headers": a hash of HTTP request headers
  • "request-uri": the request URI string (ex: "POST /services/Soap/c/29.0 HTTP/1.1")
  • "response-uri": the response URI string (ex: "HTTP/1.1 200 OK")
  • "charset": the character encoding string (ex: "UTF-8")
  • "body-content-type": the Content-Type of the response without any charset declaration
  • "accept-charset": the valus of any Accept-Charset header in the response
  • "response-headers": a hash of HTTP response headers
  • "response-body": the raw XML response body (in case content encoding is used, this is the decoded value)
  • "request-body": the raw XML request body
  • "request-soap-headers": an optional hash of SOAP headers used in the request (if applicable)
Returns
a hash with the following keys:
  • hdr: a hash of message headers
  • body: the serialized message body
Exceptions
WSDL-OPERATION-ERRORthe operation is not defined in the WSDL
WSDL-BINDING-ERRORthe binding is not assigned to a SOAP operation in the WSDL
HTTP-CLIENT-RECEIVE-ERRORthis exception is thrown when the SOAP server returns an HTTP error code; if a SOAP fault is returned, then it is deserialized and returned in the arg key of the exception hash
Note
this method can throw any exception that HTTPClient::send() can throw as well as any XML parsing errors thrown by parse_xml()
Since
SoapClient 0.2.4.1

◆ constructor()

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
hvalid 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; note that the SOAP binding is resolved from the service and port options.
  • [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::HTTPOptions, which are passed to HTTPClient::constructor()

◆ getDefaultHeaders()

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
getDefaultHeaders()
Since
SoapClient 0.2.4

◆ getInfo()

hash SoapClient::SoapClient::getInfo ( )

returns a hash of information about the current WSDL

Returns
a hash with the following keys:
  • "service": the name of the SOAP service used
  • "pore": the name of the SOAP port used
  • "binding": the name of the binding used
  • "url": the target URL

◆ getMsg()

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

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

Parameters
operationthe SOAP operation to use to serialize the request; if the operation is not known to the underlying WebService class and port/binding, an exception will be thrown
argsthe arguments to the SOAP operation
headerdata structure for the SOAP header, if required by the message
opa reference to return the WSOperation object found
nsha hash giving HTTP header information to include in the message (does not override automatically-generated SOAP message headers)
xml_optsan integer XML generation option code; see XML Generation Constants for possible values; combine multiple codes with binary or (|)
soapactionan optional string that will override the SOAPAction for the request; en empty string here will prevent the SOAPAction from being sent
Returns
a hash with the following keys:
  • hdr: a hash of message headers
  • body: the serialized message body
  • path: the path part of URL
  • method: the HTTP request method
Exceptions
WSDL-OPERATION-ERRORthe operation is not defined in the WSDL
WSDL-BINDING-ERRORthe binding is not assigned to a SOAP operation in the WSDL
Note
content encoding is not applied here but rather internally by the call() methods

◆ getSendEncoding()

*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
Since
SoapClient 0.2.4

◆ methodGate()

any SoapClient::SoapClient::methodGate ( string  op)

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

Parameters
opthe operation name, which is the method name passed to methodGate()
...zero or more arguments for the operation
Returns
the deserialized result of the SOAP call to the SOAP server
Exceptions
WSDL-OPERATION-ERRORthe operation is not defined in the WSDL
HTTP-CLIENT-RECEIVE-ERRORthis exception is thrown when the SOAP server returns an HTTP error code; if a SOAP fault is returned, then it is deserialized and returned in the arg key of the exception hash
Note
this method can throw any exception that HTTPClient::send() can throw as well as any XML parsing errors thrown by parse_xml()

◆ msglog()

nothing SoapClient::SoapClient::msglog ( hash  msg)
private

Method is to be overriden to implement custom logging HTTP message sent and received from this object.

msg information about message to be logged. There are keys 'reason' with value 'request', 'response' or 'error',
'header' (HTTP headers, as received from the remote) and 'body' containing XML data in readable form, i.e. uncompressed, and, in case of a multipart message, only the related part is passed. Method is executed before message is sent or after has been received. Do not allow exception raising in method not to interrupt client function.
Example:
private nothing msglog(hash msg) {
log(sprintf("%s:\n%s\n", msg.reason, msg.body));
}
Since
SoapClient 0.2.5

◆ setContentEncoding()

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
encthe 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-ERRORinvalid or unsupported data content encoding / compression option
See also
Since
SoapClient 0.2.4

◆ setSendEncoding()

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
encthe 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-ERRORinvalid or unsupported data content encoding / compression option
See also

Member Data Documentation

◆ EncodingSupport

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