Class Reference
Cache for UNIX 2018.1.3
InterSystems: The power behind what matters   
Documentation  Search
Private  Storage  

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.

Inventory

Parameters Properties Methods Queries Indices ForeignKeys Triggers
25 40 30


Summary

Properties
AddressingIn AddressingOut Attachments Base64LineBreaks
BodyId BodyXmlId ContentId ContentLocation
HeadersIn HeadersOut ImportHandler IsMTOM
Location MTOMRequired OutputTypeAttribute Password
RMSession ReferencesInline RequestMessageStart ResponseAttachments
ResponseContentId ResponseContentLocation SAXFlags SecurityContextToken
SecurityIn SecurityNamespace SecurityOut SessionCookie
SoapFault SoapVersion Timeout Transport
Username WriteSOAPBodyMethod

Methods
%AddEnvelopeNamespace %AddToSaveSet %ClassIsLatestVersion %ClassName
%ConstructClone %DispatchClassMethod %DispatchGetModified %DispatchGetProperty
%DispatchMethod %DispatchSetModified %DispatchSetMultidimProperty %DispatchSetProperty
%Extends %GetParameter %IsA %IsModified
%New %NormalizeObject %ObjectModified %OriginalNamespace
%PackageName %RemoveFromSaveSet %SerializeObject %SetModified
%ValidateObject GetBodyId NormalizeName

Subclasses
%SOAP.WebClient %SOAP.WebService

Parameters

• 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 BASE64LINEBREAKS = 0;
If BASE64LINEBREAKS is true (1), then remove line breaks from base64 encoded XML output for all properties of type %Binary or %xsd.base64Binary. The default is 0 which will be to not include line breaks. If the Base64LineBreaks property is specified, then it will override the BASE64LINEBREAKS parameter.
• 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 REFERENCESINLINE = 0;
If REFERENCESINLINE is true (1), then encoded objects are exported inline. By default, SOAP encoded XMLExport of a class uses idref's for class instances referenced by a class that is being exported. This change allows the referenced class instances to be exported inline as for "literal" format. If the ReferencesInline property is specified, then it will override the REFERENCESINLINE parameter.
• 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, NOHEADER, 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.

- The value of NOHEADER will REALLY 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 SOAPCHECKREQUIRED = 0;
Checking the existence of REQUIRED properties and arguments is off by default. To turn on REQUIRED checking. set the SOAPCHECKREQUIRED parameter to 1 (default is 0).
• 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 USEPPGHANDLER;
If USEPPGHANDLER is true (1), then force SOAP request or response parsing to use PPG memory.
If USEPPGHANDLER is false (0), then force SOAP request or response parsing to use local array memory.
If USEPPGHANDLER is not set ( or = ""), then use default memory -- usually local array memory.
The %SOAP.WebClient UsePPGHandler property may be used to override this parameter for each invocation.
• 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.

Properties

• 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 Base64LineBreaks as %Boolean [ Transient ];
If Base64LineBreaks is true (1), then remove line breaks from base64 encoded XML output for all properties of type %Binary or %xsd.base64Binary. The default is 0 which will be to not include line breaks. If this property is specified, then it will override the BASE64LINEBREAKS parameter.
• 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.
Note that Cache security login is based on the UsernameToken element of the Security header.
For a web client, if Username is set then a UsernameToken will be included in the Security header based on the Username and Password properties.
For a web service, Password is set based on the password contained in the UsernameToken in the Security header of the message.
• property RMSession as %SYS.RMSession [ Transient ];
The WS-ReliableMessaging sequence for this client or service.

For a web client this is the sequence that was created by the call to the %StartRMSession method that started the sequence. This call will save the $SYS.RMSession object from the CreateSequenceResponse in this property.

For a web service this is the $SYS.RMSession that was used for the request message.
• property ReferencesInline as %Boolean [ Transient ];
If ReferencesInline is true (1), then encoded objects are exported inline. By default, SOAP encoded XMLExport of a class uses idref's for class instances referenced by a class that is being exported. This change allows the referenced class instances to be exported inline as for "literal" format.
• 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 RequestSecurityTokenResponse 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.
Note that Cache security login is based on the UsernameToken element of the Security header.
For a web client, if Username is set then a UsernameToken will be included in the Security header based on the Username and Password properties.
For a web service, Username is set based on the username contained in the UsernameToken in the Security header of the message. 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.

Methods

• method %AddEnvelopeNamespace(namespace As %String, prefix As %String, schemaLocation As %String, allowMultiplePrefixes As %Boolean) as %Status
Add a namespace definition to the SOAP Envelope element of the message to be output, i.e. reply message for service, request message for client. To add a namespace to a web service reply message, %AddEnvelopeNamespace must be called from the web method. To add a namespace to a web client request message, %AddEnvelopeNamespace must be called before the web client method is invoked.

prefix is the optional preferred prefix for this namespace. If no prefix is specified, a unique prefix will be computed.

A schemaLocation attribute value for the first definition of this namespace may also specified.

If allowMultiplePrefixes is true then multiple prefixes may be defined for the same namespace. The default is false which will override the previously defined prefix for the same namespace.
• 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


Copyright © 1997-2019, InterSystems Corporation