Creating Web Services and Web Clients in Caché
Fine-Tuning a Caché Web Client
[Back] [Next]
Go to:

After you generate a Caché web client class, you do not usually edit the class. Instead you write code that creates an instance of that class and that provides provide client-side error handling. This chapter discusses various ways to fine-tune the Caché web client, either by modifying the web client instance or (less commonly) by modifying the generated class. It discusses the following:

Also see the section Basic Settings of a Caché Web Client in the chapter Creating Web Clients.” This section discusses parameters that control the namespace, the type namespace, and other basics of the web client.
Do not create a subclass of the generated web client class. The compiler will not generate the supporting classes that it would need in order to run properly, and your subclass would not be usable.
Disabling Keep-Alive for a Web Client
By default, if you reuse a Caché web client instance to send multiple request messages, Caché sends all the messages in a single HTTP transmission (using a HTTP 1.1 keep-alive connection). Specifically, Caché keeps the TCP/IP socket open so that Caché does not need to close and reopen it. To disable this keep-alive behavior, do any of the following:
If you are using WS-ReliableMessaging and you are using SSL/TLS to communicate with the web service, do not disable keep-alive. For information on WS-ReliableMessaging, see Securing Caché Web Services.
Controlling the Form of Null String Arguments
Normally, if an argument is omitted, a Caché web client omits the corresponding element in the SOAP message that it sends. To change this, set the XMLIGNORENULL parameter to 1 in the web client class; in this case, the SOAP message includes an empty element.
This parameter affects only web method arguments of type %String.
Controlling the Client Timeout
You can control two separate timeout periods for a Caché web client:
Using a Proxy Server
Your Caché web client can communicate with a web service via a proxy server. In order to set this up, specify properties of your web client instance to indicate the proxy server to use. These properties are as follows:
Specifies the host name of the proxy server to use. If this property is not null, the HTTP request is directed to this machine.
For information on specifying the default proxy server, see Using a Proxy Server in Using Caché Internet Utilities.
Specifies the port to connect to, on the proxy server.
For information on specifying the default proxy port, see Using a Proxy Server in Using Caché Internet Utilities.
Specify this as true if you are using a proxy server and if that proxy server supports HTTPS.
Note that if you are using HTTPS, you must also set the SSLConfiguration property of the client equal to the name of the SSL/TLS configuration; for more details on security, see the section Configuring the Client to Use SSL earlier in this book.
If the web client should authenticate itself with the proxy server, specify this as the required Proxy-Authorization header field.
Specify this as true if the web client should establish a tunnel through the proxy to the target HTTP server. If true, the request uses the HTTP CONNECT command to establish a tunnel. The address of the proxy server is taken from the HttpProxyServer and HttpProxyPort properties. If the endpoint URL has the https: protocol, then once the tunnel is established, Caché negotiates the SSL connection. In this case, the HttpProxyHTTPS property is ignored because the tunnel establishes a direct connection with the target system.
Setting HTTP Headers
If you need further control over the HTTP headers sent by a web client, you can use the following methods of %SOAP.WebClient:
Adds a header to the HTTP request. Note that the Content-Type, Content-Encoding, and Content-Length headers are part of the entity body rather than the HTTP main headers. You cannot set the Content-Length header, which is read-only. Nor can you set the Connection header, because this class does not support persistent connections.
Clear all HTTP headers.
Also see the section Using HTTP User Authentication,” earlier in this chapter.
Specifying the HTTP Version to Use
By default, a Caché web client uses HTTP/1.1. You can instead use HTTP/1.0. To do so, set the HttpVersion property of the client to "1.0".
Disabling SSL Server Name Checking
By default, when a Caché web client connects to a server via SSL, it checks that the certificate server name matches the DNS name used to connect to the server. (This checking is described in RFC 2818 section 3.1. Wildcard support is described in RFC 2595, but browsers generally do check the server name, and InterSystems has chosen to do the same.)
To disable this checking, set SSLCheckServerIdentity property of the client to 0.
Controlling Use of the xsi:type Attribute
By default, Caché SOAP messages include the xsi:type attribute only for the top-level types. For example:
<?xml version="1.0" encoding="UTF-8" ?>
<GetPersonResult href="#id1" />
<types:Person id="id1" xsi:type="types:Person">
<Name>Yeats,Clint C.</Name>
In these examples, line breaks have been added for readability. To use this attribute for all types in the SOAP messages, do either of the following:
The same output would look like this:
<?xml version="1.0" encoding="UTF-8" ?>
<GetPersonResult href="#id1" />
<types:Person id="id1" xsi:type="types:Person">
<Name xsi:type="s:string">Yeats,Clint C.</Name>
<DOB xsi:type="s:date">1944-12-04</DOB>
The property takes precedence over the parameter.
Controlling Use of Inline References for Encoded Format
With encoded format, any object-valued property is included as a reference, and the referenced object is written as a separate element in the SOAP message.
To instead write the encoded objects inline, specify the REFERENCESINLINE parameter or the ReferencesInline property as 1. The property takes precedence over the parameter.
Specifying the Envelope Prefix
By default, a Caché web client uses the prefix SOAP-ENV in the envelope of the SOAP messages it sends. You can specify a different prefix. To do so, set the SOAPPREFIX parameter of the web client class. For example, if you set this parameter equal to MYENV, the web client includes this prefix in its messages instead of SOAP-ENV.
Adding Namespace Declarations to the SOAP Envelope
To add a namespace declaration to the SOAP envelope (<SOAP-ENV:Envelope> element) of the SOAP responses returned by a given web client, call the %AddEnvelopeNamespace() method of the web client before calling the web method. This method has the following signature:
Method %AddEnvelopeNamespace(namespace As %String, 
                             prefix As %String, 
                             schemaLocation As %String, 
                             allowMultiplePrefixes As %Boolean) As %Status
Sending Responses Compressed by gzip
A Caché web client can compress its response messages with gzip, a free compression program that is widely available on the internet. This compression occurs after any other message packaging (such as creating MTOM packages). To cause a web client to do so, do either of t he following:
If you do so, be sure that the web service can automatically decompress the message with gunzip, the corresponding decompression program. (If the web service is a Caché web service, note that the CSP Gateway automatically decompresses inbound messages before sending them to the web service.)
Quoting the SOAP Action (SOAP 1.1 Only)
In SOAP 1.1 request messages, the HTTP header includes a SOAPAction line as follows:
POST /csp/gsop/GSOP.DivideWS.cls HTTP/1.1
User-Agent: Mozilla/4.0 (compatible; Cache;)
Host: localhost:8080
Connection: Close
Accept-Encoding: gzip
Content-Length: 397
Content-Type: text/xml; charset=UTF-8

By default, the value for SOAPAction is not quoted. To place this value in quotes, specify SOAPACTIONQUOTED as 1 in the web client class. Then the HTTP header of the request message would be as follows:
POST /csp/gsop/GSOP.DivideWS.cls HTTP/1.1
User-Agent: Mozilla/4.0 (compatible; Cache;)
Host: localhost:8080
Connection: Close
Accept-Encoding: gzip
SOAPAction: ""
Content-Length: 397
Content-Type: text/xml; charset=UTF-8

In SOAP 1.2, the SOAPACTIONQUOTED parameter has no effect. This is because the request messages do not have a SOAPAction line. Instead the SOAP action is always quoted and is included within the Content-Type line as follows:
Content-Type: application/soap+xml; 
   charset=UTF-8; action=""
This example shows an artificial line break, to ensure that the line fits on the page when this book is formatted as PDF.
Treating HTTP Status 202 Like Status 200
By default, a Caché web client follows the standard WS-I Basic Profile, which uses the HTTP response status 202 only if the HTTP response does not contain a SOAP envelope.
If you want to treat HTTP status 202 in the same way as HTTP status 200, set the HttpAccept202 property of the client to 1. To see the actual return status, check the HttpResponse.StatusCode property of the client.
The WS-I Basic Profile supports but does not encourage this practice: “The Profile accepts both status codes because some SOAP implementations have little control over the HTTP protocol implementation and cannot control which of these response status codes is sent.”
Defining a One-Way Web Method
Normally, when a web client calls a web service, a SOAP message is returned, even if the method has no return type and returns nothing when executed in Caché.
In rare cases, you might need to define a web method as being “one-way.” Such a method must return no value, and no SOAP response is expected to the message.
One-way methods should normally not be used. A request-response pair is much more common, supported, and expected — even for a method that has no return type.
To define a one-way web method, define the return type of the method as %SOAP.OneWay. The WSDL does not define output defined for this web method, and the web service does not return a SOAP message.
Adding Line Breaks to Binary Data
You can cause the Caché web service to include automatic line breaks for properties of type %Binary or %xsd.base64Binary. To do so, do either of the following:
For the parameter and the property, the default value is 0; by default, a Caché web service does not include automatic line breaks for properties of type %Binary or %xsd.base64Binary.
Adding a Byte-Order Mark to the SOAP Messages
By default, a message sent by a Caché web client does not start with a BOM (byte-order mark).
The BOM is usually not needed because the message is encoded as UTF-8, which does not have byte order issues. However, in some cases, it is necessary or desirable to include a BOM in a SOAP message; this BOM merely indicates that the message is UTF-8.
To add a BOM to the messages sent by a Caché web client, set the RequestMessageStart property of the client. This property must equal a comma-separated list of the parts to include at the start of a message. These parts are as follows:
The default is "DCL".
In practice, RequestMessageStart can equal any of the following values:
Creating Custom SOAP Messages
In special cases, you may want a web client to send a custom SOAP message. The essential requirements are as follows:
  1. Create a subclass of %SOAP.WebRequest and set its LOCATION parameter or Location property.
  2. In this subclass, create a method to send a SOAP message. This method must create an instance of %Library.CharacterStream and place into it the SOAP message you want to send. It is your responsibility to ensure that the message is correctly formed.
  3. The method must next invoke the SendSOAPBody() method:
    method SendSOAPBody(Action As %String, 
                        OneWay As %Boolean = 0, 
                        Request As %CharacterStream, 
                        ByRef Response) as %Status
%SOAP.WebRequest is a subclass of %SOAP.WebClient, so you may want to set other parameters and properties. You can also add SOAP headers as described earlier in this book. See the class documentation for %SOAP.WebRequest for further notes.
Specifying Custom HTTP Requests
By default, if you use a Caché web client, the web client uses HTTP to transport the SOAP message to the web service and to receive the response. The web client automatically creates and sends an HTTP request, but you can create a custom HTTP request. To do, you use the following procedure:
  1. Create an instance of %Net.HttpRequest and set properties as needed. For information on this class, see the book Using Caché Internet Utilities or see the class documentation for %Net.HttpRequest.
  2. Set the HttpRequest property of your web client equal to this instance.
This is useful in particular if you want to support multiple calls to a SOAP service within the same session. By default, the Caché web client does not support multiple calls to a SOAP service using the same session. To work around this, create a new instance of %Net.HttpRequest and use it as the HttpRequest property of your web client. This change forces the same HTTP request to be reused for all calls, which returns all cookies in a response to the next request.
Specifying Custom Transport from the Web Client
By default, if you use a Caché web client, the web client uses HTTP to transport the SOAP message to the web service and to receive the response. You can define and use your own transport class.
To communicate with the web service that it uses, a Caché web client requires a transport class. The transport class contains parameters, properties, and methods related to communication. The overall communication works as follows:
  1. When a web client proxy method is run, the web client instance checks the value of its Transport property.
    If this property is null, the web client instance uses itself as the transport class instance. You can instead set the Transport property equal to an instance of some other suitable class, if you have defined such a class.
  2. The web client instance executes the DoSOAPRequest() method of the transport class, passing the following arguments:
    1. The OREF of the web client class.
    2. A string that specifies the SOAP action.
    3. A stream containing the request encoded in UTF-8.
    4. (By reference) A stream containing the response.
  3. The web client instance checks the status of the result and acts accordingly.
For HTTP transport, the DoSOAPRequest() method includes the following logic:
  1. Create a request object (an instance of %Net.HttpRequest) and set its properties. Here, the method uses values of the properties of the web client instance, in particular HttpRequestHeaderCharset and other HTTP-related properties.
  2. Go through the headers in the SOAP request and initialize the headers in the request object.
  3. Execute the Post() method of the request object, which is a suitable action for HTTP transport.
  4. Get the response and return that.
Do not directly use the DoSOAPRequest() method of %SOAP.WebClient. No guarantee is made about its behavior or future operation. The preceding summary is provided only as a general tip.
Defining Custom Transport for a Caché Web Client
To enable a Caché web client to use custom transport, define a custom transport class. Then after you create an instance of the web client, set its Transport property equal to an instance of the transport class.
The requirements for the transport class are as follows:
The DoSOAPRequest() method should transport the request to the web service and obtain the response. The signature of this method must be as follows:
Method DoSOAPRequest(webClient,action,requestStream, responseStream) As %Status 
Specifying Flags for the SAX Parser
When a Caché web client invokes a web service, it internally uses the SAX parser, a third-party product that is shipped with Caché. You can set the SAXFlags property of the web client in order to set the flags for the parser to use.
For information on the parser flags themselves, see the book Using Caché XML Tools.
Using the WS-Security Login Feature
If your Caché web client is using a web service that requires authentication, and if do not want to use the newer WS-Security features, you can use the older and simpler WS-Security login feature.
To use the WS-Security login feature:
  1. Ensure that you are using SSL between the web client and the web server that hosts the web service. The WS-Security header is sent in clear text, so this technique is not secure unless SSL is used. See the section Configuring the Client to Use SSL,” earlier in this book.
  2. Invoke the WSSecurityLogin() method of the web client. This method accepts the username and password, generates a WS-Security username token with clear text password, and adds a WS-Security header to the web request.
  3. Invoke the web method.
This technique adds the security token only to the next SOAP message.
For information on the newer WS-Security features, see Securing Caché Web Services.
Using HTTP User Authentication
Instead of using WS-Security as described in Securing Caché Web Services, you can use basic HTTP authentication. To do so:
This method is less secure than WS-Security but is required by some web services.