Class Reference
IRIS for UNIX 2019.4
InterSystems: The power behind what matters   
Documentation  Search
  [%SYS] >  [%SOAP] >  [WebClient]
Private  Storage   

abstract class %SOAP.WebClient extends %SOAP.WebBase

SOAP Web Client class.
Properties of this class that begin with Http are passed through to the %Net.HttpRequest instance used by the class. The only supported use of this class is as the super class for a SOAP Web Client. Parameters, properties and methods may be used by the application.

Inventory

Parameters Properties Methods Queries Indices ForeignKeys Triggers
3 32 19


Summary

Properties
Action AddressingIn AddressingOut Attachments
Base64LineBreaks BodyId BodyXmlId ContentId
ContentLocation ContentType GzipOutput HTTPVersion
HeadersIn HeadersOut HttpAccept202 HttpFollowRedirect
HttpForceReuseDevice HttpInitiateAuthentication HttpPassword HttpProxyAuthorization
HttpProxyHTTPS HttpProxyPort HttpProxySSLConnect HttpProxyServer
HttpProxyTunnel HttpRequest HttpRequestHeaderCharset HttpRequester
HttpResponse HttpUsername HttpWriteTimeout ImportHandler
IsMTOM KeepSessionCookie Location MTOMRequired
MethodName NamespacesOut OneWay OpenTimeout
OutputTypeAttribute Password PolicyConfiguration RMSession
ReferencesInline RequestMessageStart ResponseAttachments ResponseContentId
ResponseContentLocation SAXFlags SSLCheckServerIdentity SSLConfiguration
SSLError SecurityContextToken SecurityIn SecurityNamespace
SecurityOut SessionCookie SoapBinary SoapBinaryCharset
SoapFault SoapVersion Timeout Transport
UsePPGHandler Username WSANamespace WriteSOAPBodyMethod
policyAlternative

Methods
%%OIDGet %AddEnvelopeNamespace %AddToSaveSet %BindExport
%BuildObjectGraph %ClassIsLatestVersion %ClassName %Close
%CloseRMSession %ConstructClone %DispatchClassMethod %DispatchGetModified
%DispatchGetProperty %DispatchMethod %DispatchSetModified %DispatchSetMultidimProperty
%DispatchSetProperty %Extends %GetParameter %IncrementCount
%IsA %IsModified %New %NormalizeObject
%ObjectModified %OnSOAPFinished %OnSOAPRequest %OnSOAPResponse
%OriginalNamespace %PackageName %RemoveFromSaveSet %SerializeObject
%SetModified %StartRMSession %ValidateObject BeginSOAPEnvelope
CancelSecureConversation CheckSOAPEnvelope DoSOAPRequest EndSOAPEnvelope
GetBinaryWriter GetBodyId GetSecurityOut InitializeSecurity
InvokeClient LogGlobal LogInput LogInputHTTPHeaders
LogOutput LogOutputHTTPHeaders LogText Namespace
NormalizeName OnCompile ProcessSOAPEnvelope ReadBinaryMessage
ResetHttpHeaders ResetSecurity SOAPRequestResponse SecurityOutGet
SecurityOutSet SendSOAPRequest SessionCookieSet SessionCookieSetInternal
SetHttpHeader SoapBinarySet StartSecureConversation WSCheckSignatureConfirmation
WSSecurityLogin WebMethod WriteHTTPContent WriteSOAPHeaders
WriteSOAPMessage WriteStartAttachments

Subclasses
%CSP.Monitor.Client %Net.OpenAM.IdentityServicesImplPort %SOAP.WebRequest
%Studio.SourceControl.ItemSetWS %WebStress.Comms.Client
PKI.CAServerSoap SYS.Mirroring.GetMirroringInformationSoap
SYS.WSMon.Client

Parameters

• parameter SOAPACTIONQUOTED = 0;
If the web client has the parameter SOAPACTIONQUOTED=1, then the web client will quote the SOAPAction value for SOAP 1.1. The default will be SOAPACTIONQUOTED=0 in order to be compatible with earlier versions of InterSystems IRIS.
• parameter SOAPBINARYCHARSET;
Default charset for remote SOAP binary server. This parameter is by default used to dertermine if binary message needs to be UTF8 encoded.
• parameter SOAPVERSION;
The SOAPVERSION parameter specified the version of SOAP which is supported. Possible values for the version are 1.1 and 1.2. The default value "" specifies that both SOAP 1.1 and SOAP 1.2 are supported.

Properties

• property ContentType as %String [ Transient ];
Content-Type to be used for transport class
• property GzipOutput as %Boolean [ InitialExpression = ..#GZIPOUTPUT,Transient ];
If the GzipOutput property is set to true (1), then the output request will be compressed using GZIP. The default value for GzipOutput is the GZIPOUTPUT parameter.
• property HTTPVersion as %String [ InitialExpression = "1.1",Transient ];
The HTTP version we should report to the server when making the request. Defaults to '1.1'.
• property HttpAccept202 as %Boolean [ Transient ];
If HttpAccept202=0 (default) we follow the WS-I Basic Profile which calls for HTTP response status 202 to be used only if no SOAP envelope is in the HTTP response and return an error if no envelope.
If HttpAccept202=1, HTTP status 202 will treated just the same as HTTP status 200. The HttpResponse.StatusCode property may be checked to see if 202 was actually returned.
• property HttpFollowRedirect as %Boolean [ Transient ];
If true then automatically follow redirection requests from the web server. These are signaled by the HTTP status codes of the form 3xx. The default is false.
• property HttpForceReuseDevice as %Boolean [ InitialExpression = 0 ];
If set to true then this will force the %Net.HttpRequest class to reuse the existing connection to the web server if the socket is already open. If there is any error it will be reported to the caller. This has been introduced to support reliable SOAP messaging, so should not normally be set by other code.
• property HttpHeaders as %String [ Private,MultiDimensional,Transient ];
Internal structure used to store the collection of headers for %Net.HttpRequest.
• property HttpInitiateAuthentication as %String [ Transient ];
A client may initiate a connection to the server with an "Authorization" header containing the initial token for the server for a chosen authentication scheme. %Net.HttpRequest is asked to initiate the connection by setting the InitiateAuthentication property to a string which is a single scheme name. This form will bypass the initial 401 error from the server when the client knows that the server will accept the specified scheme. Supported schemes are Negotiate, NTLM and Basic.
• property HttpPassword as %String [ Transient ];
If the Username and Password are defined then this information will be sent using Basic authentication to the web server. If you manually set the Authorization header this property will be ignored.
• property HttpProxyAuthorization as %String [ Transient ];
Sets/get the 'Proxy-Authorization:' header field in the Http request.

A user agent that wishes to authenticate itself with a proxy-- usually, but not necessarily, after receiving a 407 response--may do so by including an Proxy-Authorization header field with the request. The Proxy-Authorization field value consists of credentials containing the authentication information of the user agent for the realm of the resource being requested.

• property HttpProxyHTTPS as %Boolean [ Transient ];
HttpProxyHTTPS property is ignored since the use of SSL to the end point is now determiend from the url. If using a proxy server and this is true then it issues a request for an https page rather than the normal http page. This allows a proxy server that support https to support a secure connection from this %Net.Httprequest class.
• property HttpProxyPort as %String [ Transient ];
The port to connect to the proxy web server on. This is often port 8080 (the default).

You can specify a default proxy server for this namespace or for the entire instance by setting ^SYS("HttpRequest","ProxyPort") or ^%SYS("HttpRequest","ProxyPort").

• property HttpProxySSLConnect as %Boolean [ Transient ];
SSL connection to the proxy server will be used if the HttpProxySSLConnect property = 1. Use of SSL to the eventual endpoint is determined by the protocol part of web service's location url.
• property HttpProxyServer as %String [ Transient ];
If you need to make SOAP request through a proxy server you specify the proxy server host name in this property. If this property is defined then the http request will be directed at this machine and it will forward the request to the machine at Location and return the response.

You can specify a default proxy server for this namespace or for the entire instance by setting ^SYS("HttpRequest","ProxyServer") or ^%SYS("HttpRequest","ProxyServer").

• property HttpProxyTunnel as %Boolean [ Transient ];
If true then use the HTTP CONNECT command to establish a tunnel through the proxy to the target HTTP server. The address of the proxy server is taken from HttpProxyServer and HttpProxyPort. If the endpoint URL has the https: protocol, then once the tunnel is established we will negociate the SSL connection.
• property HttpRequest as %Net.HttpRequest [ Transient ];
If specified, the caller assigned %Net.HttpRequest instance is used for the web service request.
• property HttpRequestHeaderCharset as %String [ Transient ];
The character set to send the HTTP request header in. According to the RFC the HTTP header should only contain ASCII characters as the behaviour with characters outside this range is unspecified. This class defaults to using UTF-8 as this leaves all the ASCII characters unchanged. You should never need to change this parameter.
• property HttpRequester as %String(VALUELIST=",SAX,CACHE");
Deprecated. %Net.HttpRequester will always be used as the network access layer
• property HttpResponse as %Net.HttpResponse [ Transient ];
The HttpResponse property is set to the %Net.HttpResponse instance for the response to the web service request. This property is only set when the %Net.HttpRequest object is used to make the request, i.e. when HttpRequestor="CACHE" (the default).
• property HttpUsername as %String [ Transient ];
If the Username and Password are defined then this information will be sent using Basic authentication to the web server. If you manually set the Authorization header this property will be ignored.
• property HttpWriteTimeout as %Float [ Transient ];
Set this to the timeout the HttpRequest object will use when writing to the remote HTTP server. If not set the value from the HttpRequest object (%Net.HttpRequest) WriteTimeout property will be used which has a default of -1. -1 means it will wait indefinitely for the remote server to accept the written data, change it to another value to specify the timeout in seconds. The minimum value accepted is 2 seconds.
• property KeepSessionCookie as %Boolean;
If set then we keep session cookie even if not binary session.
• property OpenTimeout as %Integer [ Transient ];
If specified is the amount of time we will wait for the TCP/IP connection to open. If not specified then it will default to Timeout value.
• property PolicyConfiguration as %String [ Transient ];
Property to allow override of policy to be used for the web client.
PolicyConfiguration is specified as 'Configuration class name':'Configuration name' where 'Configuration name' comes from the name attribute of the configuration element in the configuration class (i.e. sublcass of %SOAP.Configuration" If PolicyConfiguration="" or is not specified, then the policy specified by the service classname attribute is attached to this class.
• property SSLCheckServerIdentity as %Boolean;
When making an SSL connection check the server identity in the certificate matches the name of the system we are connecting to. This defaults to being on and matches based on the rules layed out in section 3.1 of RFC 2818.
• property SSLConfiguration as %String [ Transient ];
The name of the activated TLS/SSL configuration to use for https requests.
• property SSLError as %String;
If request uses an SSL connection and a SSL handshake error has occurred, then SSLError contains text describing the SSL error.
• property SoapBinary as %Boolean [ InitialExpression = ..#SOAPBINARY,Transient ];
If SoapBinary is 1, then the web client will use proprietary binary SOAP protocol. The SoapBinary property defaults to the SOAPBINARY parameter.
• property SoapBinaryCharset as %String [ InitialExpression = ..#SOAPBINARYCHARSET,Transient ];
Property to allow override of charset for remote SOAP binary server. This parameter is used to dertermine if binary message needs to be UTF8 encoded. The default for SoapBinaryCharset is the SOAPBINARYCHARSET parameter.
• property SoapVersion as %String;
The SoapVersion property is either "1.1" or "1.2" and indicates the SOAP version for the current invocation.

For a SOAP web client, SoapVersion specifies the SOAP version that is used for the request.
If SoapVersion="" (the default), then "1.1" is used if SOAPVERSION="1.1" or "" (the default). Otherwise "1.2" is used if SOAPVERSION="1.2".
After the response is received, it is the version of the response. This, SoapVersion should be set before each method call.
• property UsePPGHandler as %Boolean [ InitialExpression = ..#USEPPGHANDLER,Transient ];
If UsePPGHandler is true (1), then force SOAP response parsing to use PPG memory.
If UsePPGHandler is false (0), then force SOAP response parsing to use local array memory.
If UsePPGHandler is not set ( or = ""), then use default memory -- usually local array memory.
The default value of this property is the USEPPGHANDLER parameter value.
• property WSANamespace as %String [ Transient ];
Property to allow the WS-Addressing namespace to be specified for requests

Methods

• method %CloseRMSession() as %Status
Close this client's current WS-ReliableMessaging session specified by the RMSession property. Clear the RMSession property.
• method %OnSOAPFinished(mode As %String, client As %SOAP.WebClient, method As %String, sc As %Status)
This method is a callback which will be invoked after all processing of the web client call has been completed. This method may be override by the user's web client class.

The mode argument specifies the type of SOAP request "SOAP" or "binary".
The client argument is the oref of the web client class.
The method argument is the name of the WebMethod that is being invoked
The sc argument is the %Status for this method. sc will be be $$$OK unless an error has been detected.
• method %OnSOAPRequest(mode As %String, client As %SOAP.WebClient, action As %String, oneWay As %Boolean, method As %String, requestStream As %BinaryStream)
This method is a callback which will be invoked before invoking transport.DoSOAPRequest() method to make the actual SOAP request. This method may be override by the user's web client class. DoSOAPRequest is the transport method which is responsible for sending the SOAP request and receiving the response. The default DoSOAPRequest is included in %SOAP.WebClient and uses HTTP for request/response.

The mode argument specifies the type of SOAP request "SOAP" or "binary".
The client argument is the oref of the web client class.
The action argument contains the value of the SOAPAction.
The oneWay argument is true if no body is to be sent. The method argument is the name of the WebMethod that is being invoked
The requestStream argument contains the SOAP request message in a stream. requestStream may =0 as an optimization to improve SOAP performance. requestStream=0 means that the stream is kept in memory as much as possible with overflow to a global. requestStream may be accessed by using $$$XMLRewind and $$$XMLRead macros.
• method %OnSOAPResponse(mode As %String, client As %SOAP.WebClient, action As %String, oneWay As %Boolean, method As %String, requestStream As %BinaryStream, responseStream As %BinaryStream, sc As %Status)
This method is a callback which will be invoked after invoking transport.DoSOAPRequest() method that made the actual SOAP request. This method may be override by the user's web client class. DoSOAPRequest is the transport method which is responsible for sending the SOAP request and receiving the response. The default DoSOAPRequest is included in %SOAP.WebClient and uses HTTP for request/response.

The mode argument specifies the type of SOAP request "SOAP" or "binary".
The client argument is the oref of the web client class.
The action argument contains the value of the SOAPAction.
The oneWay argument is true if no body is to be sent. The method argument is the name of the WebMethod that is being invoked
The requestStream argument contains the SOAP request message in a stream.

The responseStream argument contains the SOAP response message in a stream.
The sc argument is the %Status that was returned by DoSOAPRequest.
• method %StartRMSession(createSequence As %SOAP.RM.CreateSequence) as %Status
Start a WS-ReliableMessaging sequence by sending the specified CreateSequence body to the web service and obtaining a CreateSequenceResponse. Sessions are only supported for HTTP synchronous (HTTP request/response) with anonymouse WS-Addressing and for only a single client instance. The %SYS.RMSession object that is referenced in the %SOAP.RM.CreateSequence object is updated based on the CreateSequenceResponse and saved in the RMSession property of this client. Future calls to this client will use this %SYS.RMSession to make future calls part of this sequence.

The SecurityOut header needs to be set for proper security for the CreateSequence request. The SecurityOut header used for WS-ReliableMessaging will be cleared after when this method is complete. If the SecurityContextToken property contains a SecurityContextToken, then this token will be associated with the new sequence.
• method CancelSecureConversation() as %Status
Cancel the this client's current WS-SecureConversation token specified by the SecurityContextToken property. Clear the SecurityContextToken propery. If SecurityOut header has not been set, then a minimal SecurityOut using the token for signing is created. The SecurityOut header used for WS-StartSecureConversation will be cleared after when this method is complete.
• method DoSOAPRequest(Client As %SOAP.WebClient, Action As %String, OneWay As %Boolean, requestStream As %BinaryStream, ByRef responseStream As %BinaryStream) as %Status
Default transport for HTTP protocol %SOAP.WebClient acts as its own transport class. This method is for internal use only. You should not make direct use of it within your applications. There is no guarantee made about either the behavior or future operation of this method.
• method InvokeClient(proxy As %SOAP.ProxyDescriptor, method As %String, Action As %String, OneWay As %Boolean = 0) as %Status
Execute the Web Method represented by the descriptor class on the server. If an error is detected, a ztrap "SOAP" will be issued with %objlasterror containing the error %Status. If is the responsibilty of the caller of the proxy method to set an error trap and test for $ZE["<ZSOAP>". Note that if a SOAP fault is received, then the error is $$$SOAPFaultReceived. If method argument is "", then this is an internal call to send the XML body. In this case proxy is the character stream containing the body. This method is for internal use only. You should not make direct use of it within your applications. There is no guarantee made about either the behavior or future operation of this method.
• method LogInputHTTPHeaders()
Log the HTTP headers associated with a an input SOAP message. This method is for internal use only. You should not make direct use of it within your applications. There is no guarantee made about either the behavior or future operation of this property.
• method LogOutputHTTPHeaders()
Log the HTTP headers associated with a an output SOAP message. This method is for internal use only. You should not make direct use of it within your applications. There is no guarantee made about either the behavior or future operation of this property.
• private method MakeSecurityHeader()
• method ResetHttpHeaders() as %Status
Clear all previously set Http headers.
• method SOAPRequestResponse(proxy As %SOAP.ProxyDescriptor, method As %String, Output retryAllowed As %Boolean) as %Status
Send SOAP request and process response This method is for internal use only. You should not make direct use of it within your applications. There is no guarantee made about either the behavior or future operation of this method.
• method SendSOAPRequest(action As %String, oneWay As %Boolean = 0, request As %SOAP.RequestMessage, methodName As %String) as %Status
Send a %SOAP.RequestMessage subclass instance as a request message The arguments to this method are:
Action is the SOAPAction for the SOAP request.
If OneWay is 1 (true) then no response is expected.
Request is the %SOAP.RequestMessage subclass instance.
MethodName is an optional name of the method being called which is used to select the WS-Policy.
The response message node will be set in the ResponseDocuemtn and ResponseNodeId properties of %SOAP.RequestMessage.
• method SetHttpHeader(name As %String, value As %String) as %Status
Add a header to the http request. For example:
	Do httprequest.SetHeader("MyHeader","Data to display")
The header name is case insensitive and this class forces it to upper case so when the Http request is issued it will output the header as:

MYHEADER: Data to display

Note that headers such as Content-Type, Content-Encoding, and Content-Length are part of the entity body rather than the http main headers and as such as forwarded to the ContentType, ContentEncoding and trying to set the Content-Length is just ignored as this is a read only property. Also any attempt to set the 'Connection' header is ignored at this request class does not support persistent connections.

• method SoapBinarySet(value As %Boolean) as %Status
Setter method to insure that first not binary message uses session cookie form binary messages
• method StartSecureConversation(RST As %SOAP.WST.RequestSecurityToken) as %Status
Start a WS-SecureConversation session by sending the specified RequestSecurityToken body to the web service and obtaining a RequestSecurityTokenResponse. If ComputedKey is to be used with both client and server entropy, ComputedKeySize property of the RequestSecurityToken object should be set before calling StartSecureConversation. RequireServerEntropy property of the RequestSecurityToken object should be set before calling StartSecureConversation.

The SecurityContextToken thus returned will be saved in the SecurityContextToken property. Future calls to this client may use this token if needed for the WS-Policy or by explicitly adding to SecurityOut by calling AddSecurityElement.

The SecurityOut header needs to be set for proper security for the RequestSecurityToken request. The SecurityOut header used for WS-StartSecureConversation will be cleared after when this method is complete.
• method WSCheckSignatureConfirmation() as %Boolean
Test for valid WS-Security 1.1 SignatureConfirmation elements in response message. Return true if valid.
• method WSSecurityLogin(Username As %String, Password As %String) as %Status
The WSSecurityLogin method adds the WS-Security Security header with /UsernameToken. Only the /UsernameToken/Username and /UsernameToken/Password fields are supported. Signing and/or encryption as specified by WS-Security is not supported. These facilities are expected to be implemented by the use of SSL.


Copyright (c) 2019 by InterSystems Corporation. Cambridge, Massachusetts, U.S.A. All rights reserved. Confidential property of InterSystems Corporation.