abstract class %SOAP.WebBase
extends %RegisteredObject
Super class for SOAP Web Client and Web Server Base class and super class for Web Service classes.
The only supported use of this class is as the super class for
%SOAP.WebService and %SOAP.WebClient in order to define common properties and parameters.
Parameters and properties may be used by the application.
In addition to parameters, an XData block may be used to supply additional information about
the web service or web client.
The XData member may contain descriptions of the expected request and response headers. However, only one configuration
The format of the parameters element is as follows:
<parameters xmlns="http://www.intersystems.com/configuration">
<request>
<header ... </header> *
</request> ?
<response>
<header ... </header> *
</response> ?
<method name="xs:NCNAME">
<request>
<header ... </header> *
</request> ?
<response>
<header ... </header> *
</response> ?
</method> *
</parameters>
Cardinality is indicated by ? (0 or 1), * (0 or more) and + (1 or more) after the ending element.
The following describes the elements and attributes:
/parameters
Identifies parameters root
/parameters/request
The parameters for the request message corresponding to all methods for this web service or client.
These parameters are merged with the parameters for the individual method.
/parameters/request/header
The specification of a SOAP header which may be associated with this request message.
The format of the header element is described below.
/parameters/response
The parameters for the response message corresponding to all methods for this web service or client.
These parameters are merged with the parameters for the individual method.
/parameters/response/header
The specification of a SOAP header which may be associated with this response message.
The format of the header element is described below.
/parameters/method
The parameters for this method for this web service or client.
/parameters/method/@name
The name of the method
/parameters/method/request
The parameters for the request message corresponding to this method for this web service or client.
/parameters/method/request/header
The specification of a SOAP header which may be associated with this request message.
The format of the header element is described below.
/parameters/method/response
The parameters for the response message corresponding to this method for this web service or client.
/parameters/method/response/header
The specification of a SOAP header which may be associated with this response message.
The format of the header element is described below.
The definition of the header element is as follows:
<header name="s:string"
namespace="s:string"
class="s:string"
alias="s:string"?
/>
.../header/@name
The required element name of the header.
.../header/@namespace
The required namespace of the header.
.../header/@class
The required name of the Cache class that corresponds to the header.
.../header/@alias
The optional alias to be used for this header in the HeadersIn array.
The default is the element name specified in the name attribute.
• parameter ARGUMENTSTYLE;
The ARGUMENTSTYLE parameter may be used to specify a message format in which
each request message part (not the elements of the part's type) is an argument
and each response message part is a return value or output argument.
The use of the message or wrapped format is specified by the ARGUMENTSTYLE parameter
of the web service or web client class.
The default value for ARGUMENTSTYLE is "wrapped" or "".
Message style arguments are indicated by a value of "message".
The ARGUMENTSTYLE parameter will be ignored if the SoapBindingStyle is not document.
• parameter ATTRIBUTEQUALIFIED;
ATTRIBUTEQUALIFIED controls the format of the SOAP body.
The ATTRIBUTEQUALIFIED specification reflects the attributeFormDefault attribute of the
schema element for the TYPENAMESPACE in the WSDL defining the SOAP service.
ATTRIBUTEQUALIFIED defaults ot 0 if not specified.
• parameter ELEMENTQUALIFIED;
ELEMENTQUALIFIED controls the format of the SOAP body.
The ELEMENTQUALIFIED specification reflects the elementFormDefault attribute of the
schema element for the TYPENAMESPACE in the WSDL defining the SOAP service.
To maintain compatibility, ELEMENTQUALIFIED will default to 1 (true) for SoapBodyUse="literal"
and will default to 0 (false) for SoapBodyUse="encoded".
These were the values always previously assumed for the elementFormDefault attribute.
• parameter GZIPOUTPUT;
If the GZIPOUTPUT parameter is set to true (1), then output (request for client,
response for service) will be compressed using GZIP.
For a web client, this may be overridden by setting the GzipOutput
property of the web client class.
• parameter LOCATION;
LOCATION - Should be the URL for invoking the web service for which this is a proxy.
Override this parameter in the subclass.
Also, can be overridden by setting the Location property of the client at runtime.
Parameter LOCATION = "http://localhost/csp/MyNameSpace/client.cls";
This parameter is normally only used with Web service clients (subclasses of %SOAP.WebClient) —
not Web services themselves (subclasses of %SOAP.WebService).
• parameter MTOMREQUIRED = 0;
MTOMREQUIRED is the default value for the MTOMRequired which controls use
of MTOM optimization.
• parameter NAMESPACE = "http://tempuri.org";
NAMESPACE - Should be an unique URI
Override this parameter in the subclass with the unique namespace URI
of your organization.
Override this parameter in the subclass.
• parameter OUTPUTTYPEATTRIBUTE = 0;
OUTPUTTYPEATTRIBUTE allows the programmer to force the xsi:type attribute to be included
in all elements of a SOAP message which is a web client request or web service response.
• parameter RESPONSENAMESPACE;
The RESPONSENAMESPACE parameter for SOAP client and SOAP service classes allows
the SOAP request and SOAP response messages when SoapBindingStyle="rpc"
to each be in a different namespace. The RESPONSENAMESPACE parameter specifies
the namespace for the SOAP response message descriptor class.
If RESPONSENAMESPACE is not specified the default is the NAMESPACE parameter.
The RESPONSENAMESPACE parameter applies to all methods in the class and is not
overridden by the SoapNameSpace method keyword.
• parameter RESPONSETYPENAMESPACE;
The RESPONSETYPENAMESPACE parameter for SOAP client and SOAP service classes allows
the SOAP request and SOAP response message parts when SoapBindingStyle="document"
to each be in a different namespace. The RESPONSETYPENAMESPACE parameter specifies
the namespace for the SOAP response message descriptor class.
If RESPONSETYPENAMESPACE is not specified the default is the TYPENAMESPACE parameter.
The RESPONSETYPENAMESPACE parameter applies to all methods in the class and is not
overridden by the SoapTypeNameSpace method keyword.
• parameter SECURITYIN = "IGNORE";
The SECURITYIN parameter controls the treatment of a WS-Security header
in the input SOAP message.
The possible values of SECURITYIN are ALLOW, IGNORE, IGNOREALL and REQUIRE.
- The default value of IGNORE will ignore any WS-Security headers in the input
except for the UsernameToken which can always be used to login the user.
- The value of ALLOW will cause the WS-Security header to be verified on input.
- The value of REQUIRE will require the presence of the WS-Security header and
verify the header on input.
- The value of IGNOREALL will ignore any WS-Security headers in the input
including the UsernameToken.
Note that if validation of the Security header is enabled (ALLOW or REQUIRE),
then a CA file, named cache.cer, containing the trusted root X509 certificates
should be put in the Cache Mgr directory if signature verification or decryption
is to be performed. An optional Certificate Revocation List (cache.crl) may
also be put in the Cache Mgr directory.
• parameter SERVICENAME;
SERVICENAME - Should be the name of the service for which this is a proxy.
Override this parameter in the subclass.
• parameter SOAPBINARY;
SOAPBINARY - If = 1, then binary SOAP messages will be supported.
• parameter SOAPHEADERS;
A list of supported SOAP headers is specified as a comma separated list of input header
specifications. Each specification is of the form "headerName:headerClass" where
headerName is the element name of the supported header and
headerClass is the %SOAP.Header subclass that corresponds to that header.
This list defines all headers supported in the SOAP request.
• parameter SOAPPREFIX = "SOAP-ENV";
SOAPPREFIX allows override of the default SOAP prefix. Default is SOAP-ENV.
The prefix must be specified without the trailing ":".
• 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 value "" specifies
that both SOAP 1.1 and SOAP 1.2 are supported.
• parameter TYPENAMESPACE;
TYPENAMESPACE specifies the XML namespace for the types used for
the method arguments and return types in this web client or
web service. If TYPENAMESPACE is not specified or is "",
then the default namespace used for the types is from
the NAMESPACE parameter.
Override this parameter in the subclass.
• parameter WSADDRESSING = "OFF";
WSADDRESSING parameter controls automatic generation of WS-Addressing headers.
• parameter XMLELEMENT;
Specifies if part elements of messages in the WSDL use type or element attribute.
XMLELEMENT defaults to 1 for "literal" WSDL and to 0 for "encoded" WSDL.
• parameter XMLIGNORENULL;
XMLIGNORENULL allows the programmer to override the default XML handling
of empty strings for web method arguments of type %String. By default (XMLIGNORENULL = 0),
empty strings in the XML input are stored as $c(0) and $c(0) is written to XML
as an empty tag. A missing tag in the XML input is always stored as "" and
"" is always output to XML as no tag.
If XMLIGNORENULL is set = 1, then both missing tags in the XML and empty
strings are input as "", and both "" and $c(0) are output as empty tags
(i.e. <tag />).
If XMLIGNORENULL is set = "inputonly", then both missing tags in the XML and empty
strings are input as "". Output of "" and $c(0) are for XMLIGNORENULL = 0:
$c(0) is output as an empty tag (i.e. <tag />) and "" is output as no tag.
XMLIGNORENULL specified in the web client or service class specifies
XMLIGNORENULL for the SOAP messages used for each web method.
• property AddressingIn
as %SOAP.Addressing.Properties;
WS-Addressing properties of the input message.
AddressingIn will be = "", unless some WS-Addressing headers are
encountered in the SOAP headers.
• property AddressingOut
as %SOAP.Addressing.Properties;
WS-Addressing properties for the output message.
SOAP headers will be constructed from these properties.
• property Attachments
as list of %Net.MIMEPart [ Transient ];
The Attachments property of %SOAP.WebService will contain any attachments as
%Net.MIMEPart instances when a multipart/related SOAP request is received.
The SOAP message itself will be executed as for any SOAP message.
If any %Net.MIMEPart instances are in the Attachments property list collection in
%SOAP.WebClient, then the SOAP request will be sent as a multpart/related MIME message
per the SOAP with Attachments specification.
• property BodyId
as %String(MAXLEN="") [ Transient ];
The wsu:Id attribute to be added to the Body element when writing a SOAP message.
• property BodyXmlId
as %String(MAXLEN="") [ Transient ];
The xml:id attribute to be added to the Body element when writing a SOAP message.
Usually wsu:Id will be used, but in certain cases xml:id is needed.
• property ContentId
as %String [ Transient ];
The Content-Id of the SOAP part of the SOAP with Attachments package for SOAP requests.
ContentId is used only in conjunction with the Attachments property.
Set to the received Content-Id by the web service.
Set before calling a web client method to set the Content-Id.
• property ContentLocation
as %String [ Transient ];
The Content-Location of the SOAP part of the SOAP with Attachments package for SOAP requests.
ContentLocation is used only in conjunction with the Attachments property.
Set to the received Content-Location by the web service.
Set before calling a web client method to set the Content-Location.
• property HeadersIn
as array of %SOAP.Header [ Transient ];
Any SOAP header in the SOAP request that is found in the SOAPHEADERS list or header element
of parameters XData is imported as a %SOAP.Header subclass and added to the HeadersIn array.
The web method may then act on these headers as appropriate.
• property HeadersOut
as array of %SOAP.Header [ Transient ];
Any web service or web client method may add instances of any %SOAP.Header subclass to this array.
The index is arbitrary but is usually the element name of the header.
The corresponding headers are then added to the SOAP response message.
This collection of headers is cleared after each method call.
• property ImportHandler
as %XML.Document [ Transient ];
After the %SOAP.WebService Initialize method is called, this property contains the %XML.Document
instance for the parsed SOAP request.
After the %SOAP.Webclient parses the response, this property contains the %XML.Document
instance for the parsed SOAP response.
• property IsMTOM
as %Boolean;
IsMTOM is set to true if an MTOM package was received.
• property Location
as %String [ InitialExpression = ..#LOCATION,Transient ];
Location property. Initialized to LOCATION parameter.
• property MTOMRequired
as %Boolean [ InitialExpression = ..#MTOMREQUIRED,Transient ];
MTOMRequired controls use of MTOM optimization.
If MTOMRequired is true, then SOAP messages will be sent as an MTOM package.
For a web client, MTOMRequired=1 means that the SOAP request will be a MTOM package.
A web client will always be able to process a response as an MTOM package independent of the value of MTOMRequired.
For a web service, MTOMRequired=1 means that the SOAP response will always be an
MTOM package even if the request was not MTOM. MTOMRequired may be set in the
web method being called or in the OnPreWebMethod callback. A web service will always respond with
an MTOM package if the request was an MTOM package independent of the value of MTOMRequired.
The default for the MTOMRequired property is the value of the
MTOMREQUIRED parameter.
• property OutputTypeAttribute
as %Boolean [ InitialExpression = 0 ];
• property Password
as %String [ Transient ];
The password that is associated with this SOAP request.
For a request message Username is based on the WS-Security SOAP header in the request.
This property is only set for custom transports and is not available for web service
requests using the default CSP transport.
• property RequestMessageStart
as %String [ InitialExpression = "DCL",Transient ];
Control use of BOM for request message.
Comma separated list of message start parts:
BOM to include BOM, DCL to include XML declaration.
• property ResponseAttachments
as list of %Net.MIMEPart [ Transient ];
If any %Net.MIMEPart instances are in the ResponseAttachments property list collection in
%SOAP.WebService, then the SOAP response will be sent as a multpart/related MIME message
per the SOAP with Attachments specification.
The ResponseAttachments property of %SOAP.WebClient will contain any attachments as
%Net.MIMEPart instances when a multipart/related SOAP response is received.
The SOAP message itself will be executed as for any SOAP message.
• property ResponseContentId
as %String [ Transient ];
The Content-Id of the SOAP part of the SOAP with Attachments package for SOAP responses.
ResponseContentId is used only in conjunction with the ResponseAttachments property.
Set to the received Content-Id by the web client.
Set during the web service method to set the Content-Id.
• property ResponseContentLocation
as %String [ Transient ];
The Content-Location of the SOAP part of the SOAP with Attachments package for SOAP responses.
ResponseContentLocation is used only in conjunction with the ResponseAttachments property.
Set to the received Content-Location by the web client.
Set during the web service method to set the Content-Location.
• property SAXFlags
as %Integer [ InitialExpression = $$$SAXFULLDEFAULT-$$$SAXVALIDATIONSCHEMA,Transient ];
SAXFlags property. The flags passed to the SAX parser.
• property SecurityContextToken
as %SOAP.WSSC.SecurityContextToken [ Transient ];
The SecurityContextToken that is to be used for this WS-SecureConversation context.
For a web client this is the SecurityContextToken that was obtained by the call to the StartSecureConversation
call that started the session. This call will save the SecureConversation token from the
RequestSecurityTokeResponse in this property.
For a web service this is the SecurityContextToken that was used to secure the request message.
Future request or response messages may use this token if needed for the WS-Policy or
by explicitly adding to SecurityOut by calling AddSecurityElement.
• property SecurityIn
as %SOAP.Security.Header [ Transient ];
The WS-Security header associated with the received SOAP message.
SecurityIn will = "" unless a Security heaader is present in the message.
• property SecurityNamespace
as %String [ Transient ];
The XML namespace used for the security header.
SecurityNamespace is set based on WS-Security namespace used for an input message
or may be set to control the WS-Security namespace used for an output message.
• property SecurityOut
as %SOAP.Security.Header [ Transient ];
The WS-Security header to be output with this SOAP message.
Note that SecurityOut is not automatically reset to "" between calls to the
web service or client. Therefore, the same security headers will also
be used for any following calls.
Any combination of Timestamp, UsernameToken and Signature elements may be included
in the Security header.
To add a Timestamp element:
do ..SecurityOut.AddSecurityElement(##class(%SOAP.Security.Timestamp).Create(interval))
The interval argument is the time in seconds between Created and Expires times.
If interval is not specified, then the default is 300 seconds.
To add a UsernameToken element:
do ..SecurityOut.AddSecurityElement(##class(%SOAP.Security.UsernameToken).Create(username,password))
The UsernameToken added using the above call will be used for all subsequent calls.
The WSSecurityLogin method should be used to add the UsernameToken just for the next call.
To add a Signature element:
set x509=##class(%SYS.X509Credentials).GetByAlias(x509Alias)
set cert=##class(%SOAP.Security.BinarySecurityToken).CreateX509Token(x509)
do ..SecurityOut.AddSecurityElement(cert)
do ..SecurityOut.AddSecurityElement(##class(%XML.Security.Signature).CreateX509(cert))
The configName argument is the name of a SSL/TLS Configuration, specified using the System Management Portal,
that contains the certificate file and private key file/password used for signing.
The private key password may be included with the configuration name as
"name|password" instead of in the configuration.
For initial release the configuration name is that of an SSL/TLS Configuration.
BEWARE that this is subject to change in future releases.
• property SessionCookie
as %String [ Transient ];
This property contains the session cookie to be included in the Cache proprietary
SOAP session header to maintain the Cache SOAP session.
SessionCookie will be set from the Cache SOAP session header received in the SOAP request.
• property SoapFault
as %SOAP.Fault [ Transient ];
For a web service, this is the SOAP Fault to return.
The SoapFault property may be set before calling Process to return a SOAP fault.
For a web client, when the response message is a SOAP fault, then ZTRAP is throw and
SoapFault is the corresponding %SOAP.Fault instance.
• property SoapVersion
as %String;
The SoapVersion property is either "1.1" or "1.2" and indicates the SOAP
version for the current invocation.
• property Timeout
as %Integer [ Transient ];
Timeout property. Controls timeout waiting, in seconds, for response.
• property Transport
as %RegisteredObject [ Transient ];
The Transport property may be set to an instance of a transport class which will
provide a DoSoapRequest method that will take a request and obtain the response
using its transport.
• property Username
as %String [ Transient ];
The username that is associated with this SOAP request.
For a request message Username is based on the WS-Security SOAP header in the request.
• property WriteSOAPBodyMethod
as %String [ Transient ];
Specify the name of the method to call to write the SOAP body by putting the method
name into the WriteSOAPBodyMethod property of the web service or web client class. For example
Method test(..... [WebMethod] ; for a client
{
Set ..WriteSOAPBodyMethod="override"
Do ..WebMethod("test").Invoke(.....
Set ..WriteSOAPBodyMethod=""
}
or
Method test(..... [WebMethod] ; for a service
{
Set ..WriteSOAPBodyMethod="override"
; service method follows
.....
}
The signature of the override method is
Method override(proxy As %SOAP.ProxyDescriptor, tag As %String)
The override method uses the Write command to output the body.
• method GetBodyId()
as %String
Return the value of the BodyId property.
Populate the BodyId property if it is not yet set.
• classmethod NormalizeName(pName, pMaxLen, isMethod As %Boolean)
as %String
Normalize name to comply with Cache constraints
