Skip to main content

This is documentation for Caché & Ensemble. See the InterSystems IRIS version of this content.Opens in a new tab

For information on migrating to InterSystems IRISOpens in a new tab, see Why Migrate to InterSystems IRIS?

%SOAP.WebService

abstract class %SOAP.WebService extends %CSP.Page, %SOAP.WebBase

Super class for all classes that are to be projected as a Web Service.
The only supported use of this class is as the super class for a WebService. Parameters, properties and methods may be used by the application.

Property Inventory

Method Inventory

Parameters

parameter ALLOWREDUNDANTARRAYNAME;
The ALLOWREDUNDANTARRAYNAME parameter of a web service class allows the old form of array name in the XML schemas in the web service's WSDL. If true, then the schemas in the WSDL an array name that is used for a Cache List or a pair type name that is used for a Cache Array will be allowed to have a type name = to the item name. i.e. the old longer format is kept.
parameter INCLUDEDOCUMENTATION = 0;
If INCLUDEDOCUMENTATION is true, then include s:documentation in the WSDL schema based on class and property comments.
parameter LOCATION;
LOCATION - the URL not including the web service class name which is the location of the web service. If LOCATION is specified, the location for the WSDL is formed by appended .cls to the LOCATION value. LOCATION defaults to the location of this class as used to display the WSDL. It will need to be overridden only in very unusual circumstances.
parameter REQUESTVERSION;
The REQUESTVERSION parameter specifies the version(s) of SOAP which are supported for a SOAP request. Possible values for the version are 1.1 and 1.2. The value "" specifies that both SOAP 1.1 and SOAP 1.2 are supported. The default is ""
parameter RMDELIVERYASSURANCE;
The WS-ReliableMessaging Delivery Assurance parameter
parameter RMINACTIVITYTIMEOUT = 600;
The WS-ReliableMessaging inactivity timeout in seconds. Default is 10 minutes.
parameter RMINORDER;
The WS-ReliableMessaging InOrder parameter
parameter SOAP12BINDING;
The SOAP 1.2 binding name in the WSDL. Default is SOAP 1.1 binding with "12" appended.
parameter SOAPBINDING;
The SOAP 1.1 binding name in the WSDL. Default is the service name with "Soap" appended.
parameter SOAPDISABLEWSDL;
If SOAPDISABLEWSDL parameter is true (1), then no WSDL will be returned when the service is invoked with ?wsdl query parameter. The FileWSDL method will still produce the WSDL, since all information is available anyway if the web service class can be call directly from COS. The default is false which will produce a WSDL for the wsdl query parameter.
parameter SOAPINTERNALWSDL = 1;
If SOAPINTERNALWSDL parameter is true (1), then the WSDL produced for the service will include WebMethods which are marked as Internal. Otherwise, only non-internal WebMethods will be included in the WSDL. The default for SOAPINTERNALWSDL is true (1).
parameter SOAPMETHODINHERITANCE;
If the SOAPMETHODINHERITANCE parameter is true (1), then WebMethods are inherited from any super class. The default for the SOAPMETHODINHERITANCE parameter is false (0) which means no WebMethods are inherited from a super class.
parameter SOAPSESSION = 0;
When SOAPSESSION = 1, then the returned response will have a session header added to allow the web client to continue the session. Subsequent requests by the client could then contain the session header to maintain the session.
parameter SOAPVERSION = 1.1;
The SOAPVERSION parameter specifies the version of SOAP which is supported. The SOAPVERSION parameter effects only the WSDL that is created for this service. The version for which requests are accepted is specified by REQUESTVERSON. Possible values for the version are 1.1 and 1.2. The value "" specifies that both SOAP 1.1 and SOAP 1.2 are supported. The default is "1.1"
parameter USECLASSNAMESPACES;
When USECLASSNAMESPACES = 1, then the WSDL of the Web service reflects the namespaces defined for the referenced classes by the NAMESPACE parameters of those classes. The default, for compatibility with previous versions, is that the NAMESPACE parameters of the referenced classes are ignored when creating the WSDL. If USECLASSNAMESPACES has no value, then the default value from ^ISCSOAP("USECLASSNAMESPACES") is used.

Properties

property FaultAddressing as %SOAP.Addressing.Properties [ Transient ];
WS-Addressing properties to be used if a fault is returned. SOAP headers will be constructed from these properties.
Property methods: FaultAddressingGet(), FaultAddressingGetSwizzled(), FaultAddressingIsValid(), FaultAddressingNewObject(), FaultAddressingSet()
property FaultHeaders as array of %SOAP.Header [ Transient ];
Any web service may add instances of any %SOAP.Header subclass to this array. The index is the element name of the header. The corresponding headers are then added to the any SOAP fault message.
Property methods: FaultHeadersBuildValueArray(), FaultHeadersCollectionToDisplay(), FaultHeadersCollectionToOdbc(), FaultHeadersDisplayToCollection(), FaultHeadersGet(), FaultHeadersGetObject(), FaultHeadersGetObjectId(), FaultHeadersGetSwizzled(), FaultHeadersIsValid(), FaultHeadersOdbcToCollection(), FaultHeadersSet(), FaultHeadersSetObject(), FaultHeadersSetObjectId()
property MsgClass as %SOAP.MsgDescriptor [ Transient ];
When the web method is called, this property contains the %SOAP.MsgDescriptor class for the web method.
Property methods: MsgClassGet(), MsgClassGetSwizzled(), MsgClassIsValid(), MsgClassNewObject(), MsgClassSet()
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 service, a request using either SOAP version 1.1 or 1.2 is supported if SOAPVERSION="". Otherwise, the version specified in SOAPVERSION is supported. The default is support for SOAP 1.1 only. A Misunderstood fault is returned if the request version is not supported. SoapVersion is set to the actual version of request and will be the version of the response.
Property methods: SoapVersionDisplayToLogical(), SoapVersionGet(), SoapVersionIsValid(), SoapVersionLogicalToDisplay(), SoapVersionLogicalToOdbc(), SoapVersionNormalize(), SoapVersionSet()
property Timeout as %Integer;
Can be set at the beginning of the web method that is being executed in which case this changes the amount of time the CSP gateway will wait for a response from the server in seconds before it reports the 'Server is not responding' error message. This is useful if you know that this web method is doing an expensive operation that will take a couple of minutes and you want to set the server response timeout on the CSP gateway to a minute and yet wait three minutes for this method to complete. It will just change the server response timeout for this method invocation only. If not set the the CSP gateway uses its default timeout value specified in the CSP gateway configuration.

The Timeout property is only meaningful if the default CSP transport is being used. If a user defined transport is used, setting the Timeout is ignored.
Property methods: TimeoutDisplayToLogical(), TimeoutGet(), TimeoutIsValid(), TimeoutLogicalToDisplay(), TimeoutNormalize()

Methods

method %OnCreateRMSession(response As %SOAP.RM.CreateSequenceResponse)
The %OnCreateRMSession web service callback is invoked at the start of WS-ReliableMessaging session before the %SOAP.RM.CreateSequenceResponse is returned. The response argument has been completely created and not yet returned at this point. The reason for this callback is to allow the web service to add any required Security header elements. If WS-Policy is used, then WS-Policy support does this automatically.
classmethod FileWSDL(fileName As %String, includeInternalMethods As %Boolean = 1) as %Status
Write a WSDL to a file
final classmethod Initialize(pAction As %String, requestStream, ByRef importHandler As %XML.Document, ByRef username As %String, ByRef password As %String, ByRef securityNamespace As %String, ByRef fault As %SOAP.Fault, securityIn As %String = "ignore", soapClassname As %String)
Initialize a SOAP request. The Initialize method must be called before the Process method to parse the SOAP message and process the security header.
The request argument contains the SOAP request. For a normal SOAP request, the request argument will be a stream containing the request. For a SOAP with Attachments format request, the request argument will be a multidimensional array of %CSP.Streams that is subscripted by the position in the original multipart message. request(1) is the SOAP message.
If the Initialize method wishes to return an error, it will set the SoapFault property to the appropriate fault to call. The caller should immediately call the Process method to actually return the SOAP fault.
The properties Username and Password may be set based on the security header. The property SessionCookie may be set based on the session header.
This method is meant to be used by SOAP transport classes.
classmethod MakeFault(pFaultCode As %String, pFaultString As %String, pDetail As %String = "", pFaultActor As %String = "") as %SOAP.Fault
Create a SOAP fault. Usually returned by ReturnFault method.
classmethod MakeFault12(pFaultCode As %String, pFaultString As %String, pDetail As %String = "", pFaultActor As %String = "") as %SOAP.Fault
Create a SOAP 1.2 fault.
classmethod MakeSecurityFault(pFaultCode As %String, securityNamespace As %String) as %SOAP.Fault
Create a SOAP security fault. The namespace for this security fault is found in SecurityNamespace property. Valid values for FaultCode are "FailedAuthentication", "FailedCheck", "InvalidSecurity", "InvalidSecurityToken", "SecurityTokenUnavailable", "UnsupportedAlgorithm" and "UnsupportedSecurityToken".
classmethod MakeStatusFault(pFaultCode As %String, pFaultString As %String, pStatus As %Status = "", pFaultActor As %String = "") as %SOAP.Fault
Create a SOAP fault based on a %Status value.
Process a request to cancel a WS-SecureConversation context that is represented by the RequestSecurityToken body in the RST argument. If successful a RequestSecurityTokenResponseCollection is returned which will act as the %SOAP.MsgDescriptor for this request.
If a fault is to be returned, the %SOAP.fault instance should be assigned to the SoapFault property and "" returned.

abstract method OnPostWebMethod()
The OnPostWebMethod method will be called after any web method in a web service. OnPostWebMethod cannot return a value and thus cannot change the execution or return of the web method. OnPostWebMethod is primarily to do any cleanup required of structures created by OnPreWebMethod.
abstract method OnPreWebMethod()
The OnPreWebMethod method will be called before any web method in a web service. OnPreWebMethod cannot return a value and thus cannot change the execution of the web service except by returning a SOAP fault in the same way that a web method would return a SOAP fault. OnPreWebMethod can look at %request, %session and the web service properties to control its behavior. MsgClass is a web service property which is the message descriptor class which contains the web method arguments.
method OnRequestMessage(mode As %String, action As %String, request As %Stream.Object)
Callback when a SOAP request message has been received. The OnRequestMessage callback is called after security processing has taken place. This callback will not be called in the case of a security error.

The mode argument specifies the type of SOAP request "SOAP" or "binary".
The action argument contains the value of SOAPAction header.
The request argument contains the SOAP request message in a stream.

The CSP %request object is available at the time of the call. The %request.Content property will contain the raw request message. For a MIME SOAP request, the individual MIME parts may be retrieved using the %request.NextMimeData method.
Various properties of the web service class that are set during initiaization may be useful: ImportHandler - DOM for parsed SOAP request message.
SecurityIn - Security header
SecurityNamespace - Namespace for Security header
SoapFault - set if SOAP faut has been generated.

If the SoapFault property is set by the OnRequestMessage callback, then a SOAP fault will be written instead of calling the web method. The ReturnFaut method should not be called from OnRequestMessage.
method OnSOAPRequest(action As %String, ByRef request, ByRef responseStream As %BinaryStream)
Process a SOAP request from a transport class.

Arguments:
  • action -- specifies the WebMethod to invoke as pkg.classname.methodname
  • request -- contains the SOAP request. For a normal SOAP request, the request argument will be a stream containing the request. For a SOAP with Attachments format request, the request argument will be a multidimensional array of %CSP.Streams that is subscripted by the position in the original multipart message. request(1) is the SOAP message.
  • responseStream -- the stream to which the response SOAP message is to be written. If responseStream is not specified a new %FileBinaryStream is created for the response.
The Reset() method must be called before calling the OnSOAPRequest method again from this %SOAP.WebService instance.
Process a request to start a WS-SecureConversation context that is represented by the RequestSecurityToken body in the RST argument. If successful a RequestSecurityTokenResponseCollection is returned which will act as the %SOAP.MsgDescriptor for this request.
If a fault is to be returned, the %SOAP.fault instance should be assigned to the SoapFault property and "" returned.

The default behavior of this method is return a RequestSecurityTokenResponseCollection element based on the WS-Policy associated with this web service. If no policy alternative is found which can return a RequestSecurityTokenResponseCollection, then SoapFault is set to a wst:BadRequest fault.
method Process(pAction As %String, ByRef request, needHeaders As %Boolean = 1)
Process a SOAP request. Initialize must be called first.
The pAction argument contains the value of SOAPAction header.
The request argument contains the SOAP request. For a normal SOAP request, the request argument will be a stream containing the request. For a SOAP with Attachments format request, the request argument will be a multidimensional array of %CSP.Streams that is subscripted by the position in the original multipart message. request(1) is the SOAP message.
The needHeaders argument specifies if HTTP headers need to be output before the SOAP message. Normally the transport class will be responsible for any transport such as HTTP headers.
If the SoapFault property is set up before calling Process, then a SOAP fault is written instead of calling the web method.
The SessionCookie property may be set before calling Process to force value of SessionCookie. This method is meant to be used by SOAP transport classes.
method ProcessBinary(action As %String, request)
Process a SOAP request using the Cache proprietary binary SOAP protocol. The pAction argument contains the value of ISCSOAP header.
The request argument contains the SOAP request as a stream containing serialized message class. If the SoapFault property is set up call of Process, then a SOAP fault is written instead of calling the web method. The SessionCookie property may be set before calling Process to force value of SessionCookie. This method is meant to be used by SOAP transport classes.
abstract method ProcessBody(action As %String, requestBody As %CharacterStream, ByRef responseBody As %CharacterStream) as %Boolean
The ProcessBody method of %SOAP.WebService will be passed the request message body as a character stream and will return the response message body in another character stream.
The return value is 1 (true) if the body was processed and a response stream produced. If 0 is returned the %SOAP.MsgDescriptor class will be invoked as usual. If an error occurs during the processing of the request, then a fault should be returned in the usual way using the ReturnFault method.
The arguments to this method are:
action is the SOAPAction for the SOAP request.
requestBody is the body of the SOAP request.
responseBody is a character stream to which the body of the SOAP response will be written.

abstract method ProcessBodyNode(action As %String, body As %XML.Node, ByRef responseBody As %CharacterStream) as %Boolean
The ProcessBodyNode method of %SOAP.WebService will be passed an %XML.Node instance which is positioned at the child of the Body element of the SOAP which has the contents of the request body. ProcessBodyNode will return the response message body in another character stream.
The return value is 1 (true) if the body was processed and a response stream produced. If 0 is returned the %SOAP.MsgDescriptor class will be invoked as usual. If an error occurs during the processing of the request, then a fault should be returned in the usual way using the ReturnFault method.
The arguments to this method are:
action is the SOAPAction for the SOAP request.
body is an %XML.Node instance for the contents of the SOAP request body.
responseBody is a character stream to which the body of the SOAP response will be written.

method Reset()
Reset this %SOAP.WebService instance to state as newly created This method is meant to be used by SOAP transport classes.
classmethod ReturnFault(fault As %SOAP.Fault)
Return the SOAP fault in %SOAP.Fault as the result of this web method call. The ReturnFault method should only be called from the implementation of the WebMethod. This method will not return to its caller. It will act as a Quit from the Web Method with the %SOAP.Fault as the return value.

You can generate a SOAP fault from a web method as in the following example:

  Set fault=##class(%SOAP.Fault).%New()
  Set fault.faultcode=$$$FAULTServer
  Set fault.faultstring="Processing Error"
  Set fault.detail="<e:myError xmlns:e=""some-URI"">app didn't work</e:myError>"
  Do ..ReturnFault(fault) ; will not return
  
method ReturnOneWay()
Calling ReturnOneWay() will dynamically change the return of the web service to act as if the return type of the WebMethod was %SOAP.OneWay. ReturnOneWay may be called from a WebMethod or ProcessBody or ProcessBodyNode. The WebMethod, ProcessBody or ProcessBodyNode will still need to quit normally.
method WSAddSignatureConfirmation(coveringSignature As %XML.Security.Signature = "", encryptedKey As %XML.Security.EncryptedKey = "", symmetricReference As %Integer = "", derivedKey As %SOAP.WSSC.DerivedKeyToken = "")
Add WS-Security 1.1 SignatureConfirmation elements to response message. This method will add a SignatureConfirmation element to the SecurityOut for each Signature in the SecurityIn. If no Signature element exists in SecurityIn, then a SignatureConfirmation element will be added with no Value attribute as required by WS-Security 1.1.
coveringSignature should be the main signature of the Security header which will be used to sign the SignatureConfirmation elements.

Inherited Members

Inherited Properties

Inherited Methods

Subclasses

FeedbackOpens in a new tab