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.
• 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 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 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;
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 specified the version of SOAP which is supported.
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.
• 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 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 MsgClass
as %SOAP.MsgDescriptor [ Transient ];
When the web method is called, this property contains the %SOAP.MsgDescriptor
class for the web method.
• 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 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.
• classmethod FileWSDL(fileName)
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.
• method OnCancelSecureConversation(RST As %SOAP.WST.RequestSecurityToken)
as %SOAP.WST.RequestSecurityTokenResponseCollection
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 primariily 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 it's 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.
• method OnStartSecureConversation(RST As %SOAP.WST.RequestSecurityToken)
as %SOAP.WST.RequestSecurityTokenResponseCollection
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. Initilaize 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 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.
• 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.
