Fine-Tuning a Caché Web Client

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:

• Kill the web client instance and create and use a new one.

• Set the client’s HttpRequest.SocketTimeout property to 0 after you send the first message. For example:

  Set client.HttpRequest.SocketTimeout=0
  

  

• Add the Connection: close HTTP header in the second request from the client. To do so, add code like the following after you send the first message:

  Set sc=client.HttpRequest.SetHeader("Connection","close")
  

  

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.

Controlling the Client Timeout

You can control two separate timeout periods for a Caché web client:

• The Timeout property of the web client is the read timeout. This specifies how long, in seconds, the web client waits for a response.

  If this property is not specified, the web client uses the default value specified for the Timeout property of the %Net.HttpRequestOpens in a new tab class. This default is 30 seconds.

  If you are using a proxy server, this property controls how long the client waits for a response from the proxy.

• The OpenTimeout property specifies the open timeout, which is the number of seconds to wait for the TCP/IP connection to open. If this property is not specified, the value specified by Timeout is used instead.

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:

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.WebClientOpens in a new tab:

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 2818Opens in a new tab section 3.1. Wildcard support is described in RFC 2595Opens in a new tab, 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" ?>
...
<types:GetPersonResponse>
<GetPersonResult href="#id1" />
</types:GetPersonResponse>
<types:Person id="id1" xsi:type="types:Person">
<Name>Yeats,Clint C.</Name>
<DOB>1944-12-04</DOB>
</types:Person>  
...

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:

• Set the OutputTypeAttribute property equal to 1 in the web client instance.

• Set the OUTPUTTYPEATTRIBUTE parameter equal to 1 in the web client class.

The same output would look like this:

<?xml version="1.0" encoding="UTF-8" ?>
...
<types:GetPersonResponse>
<GetPersonResult href="#id1" />
</types:GetPersonResponse>
<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>
</types:Person> 
...

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

Where:

• namespace is the namespace to add.

• prefix is the optional prefix to use for this namespace. If you omit this argument, a prefix is generated.

• schemaLocation is the optional schema location for this namespace.

• allowMultiplePrefixes controls whether a given namespace can be declared multiple times with different prefixes. If this argument is 1, then a given namespace can be declared multiple times with different prefixes. If this argument is 0, then if you add multiple declarations for the same namespace with different prefixes, only the last supplied prefix is used.

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:

• Set the GzipOutput property equal to 1 in the web client instance.

• Set the GZIPOUTPUT parameter equal to 1 in the web client class.

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
SOAPAction: http://www.mynamespace.org/GSOAP.DivideWS.Divide
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: "http://www.mynamespace.org/GSOAP.DivideWS.Divide"
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="http://www.mynamespace.org/GSOAP.DivideWS.Divide"

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.

To define a one-way web method, define the return type of the method as %SOAP.OneWayOpens in a new tab. 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 %BinaryOpens in a new tab or %xsd.base64BinaryOpens in a new tab. To do so, do either of the following:

• Set the BASE64LINEBREAKS parameter to 1 in the web service class.

• Set the Base64LineBreaks property to 1, for the web service class instance. The value of this property takes precedence over the value set by the BASE64LINEBREAKS parameter.

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 %BinaryOpens in a new tab or %xsd.base64BinaryOpens in a new tab.

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:

• DCL is the XML declaration:

  <?xml version="1.0" encoding="UTF-8" ?>
  

  

• BOM is the UTF-8 BOM.

The default is "DCL".

In practice, RequestMessageStart can equal any of the following values:

• "DCL"

• "BOM"

• "BOM,DCL"

Using Process-Private Globals When Parsing

By default, a Caché web client usually uses local array memory when it parses requests or responses. You can force it to use process-private globals instead; this enables the web client to process very large messages.

To do so, specify the USEPPGHANDLER parameter of the web service class as follows:

Parameter USEPPGHANDLER = 1;

If this parameter is 1, then the web client always uses process-private globals when it parses requests or responses. If this parameter is 0, then the web client always uses local array memory for these purposes. If this parameter is not set, then the web client uses the default, which is usually local array memory.

You can override this parameter at runtime. To do so, set the UsePPGHandler property of the web client instance.

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.WebRequestOpens in a new tab 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.CharacterStreamOpens in a new tab 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
   

   

   • Action is a string that gives the name of SOAP action to perform.

   • OneWay is a true/false flag that controls whether the message is one way.

   • Request is an instance of %Library.CharacterStreamOpens in a new tab that contains the body of the SOAP request in the character set of the current locale.

   • Response is the response, returned by reference either as a character stream or an instance of %XML.NodeOpens in a new tab.

     If Response is null when you invoke SendSOAPBody(), then the method sets Response equal to an instance of %Library.CharacterStreamOpens in a new tab. This stream contains the body of the SOAP response in the character set of the current locale.

     If Response is an instance of %Library.CharacterStreamOpens in a new tab when you invoke SendSOAPBody(), then the method updates Response to contain the body of the SOAP response in the character set of the current locale.

     If Response is an instance of %XML.NodeOpens in a new tab when you invoke SendSOAPBody(), then the method updates Response to point to the body DOM.

%SOAP.WebRequestOpens in a new tab is a subclass of %SOAP.WebClientOpens in a new tab, 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.WebRequestOpens in a new tab 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.HttpRequestOpens in a new tab and set properties as needed. For information on this class, see the book Using Caché Internet Utilities or see the class documentation for %Net.HttpRequestOpens in a new tab.

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.HttpRequestOpens in a new tab 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.

Customizing Callbacks of a Web Client

You can customize the behavior of a Caché web client by overriding its callback methods:

%OnSOAPRequest()

Method %OnSOAPRequest(mode As %String, 
                      client As %SOAP.WebClient,  
                      action As %String,  
                      oneWay As %Boolean,  
                      method As %String,  
                      requestStream As %BinaryStream)

Called just before the web client invokes the DoSOAPRequest() method of the transport class (which makes the actual SOAP request). The default DoSOAPRequest() method is included in %SOAP.WebClient and uses HTTP for request/response.

• mode specifies the type of SOAP request ("SOAP" or "binary").

• client is the OREF of the web client instance.

• action contains the value of the SOAPAction header.

• oneWay is true if no body is to be sent.

• method argument is the name of the web method that is being invoked.

• requestStream argument contains the SOAP request message in a stream.

%OnSOAPResponse()

Method %OnSOAPResponse(mode As %String, 
                       client As %SOAP.WebClient, 
                       action As %String, 
                       oneWay As %Boolean, 
                       method As %String, 
                       requestStream As %BinaryStream, 
                       responseStream As %BinaryStream, 
                       sc As %Status)

Called after the web client has invoked the DoSOAPRequest() method of the transport class. The sc argument is the status returned by the DoSOAPRequest() method of the transport class. The other arguments are the same as for %OnSOAPRequest().

%OnSOAPFinished()

Method %OnSOAPFinished(mode As %String, client As %SOAP.WebClient, method As %String, sc As %Status)

Called after the web client has performed all its processing. The sc argument is the status returned by the web method that was invoked. The mode, client, and method arguments are the same as for the other callback methods.

Specifying Custom Transport from a 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.

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 class must be instantiable (that is, non-abstract).

• The class must implement the DoSOAPRequest() method as described below.

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 

• webClient is the OREF of the web client class.

• action is a %StringOpens in a new tab that specifies the SOAP action.

• requestStream is a stream containing the request encoded in UTF-8.

• responseStream is a %FileBinaryStreamOpens in a new tab argument that DoSOAPRequest() uses to write the response. This stream must contain data in the character set specified by the encoding attribute of the ?xml directive. UTF-8 is recommended.

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 Authentication

Some web services require HTTP authentication instead of using WS-Security (which is described in Securing Web Services). For these web services, InterSystems supports the following HTTP authentication schemes:

1. Negotiate (SPNEGO and Kerberos, per RFC 4559Opens in a new tab and RFC 4178Opens in a new tab)

2. NTLM (NT LAN Manager Authentication Protocol)

3. Basic (Basic Access Authentication as described in RFC 2617Opens in a new tab)

Note that on HTTP 1.0, only Basic authentication is used; the other authentication schemes require multiple round trips within a single connection, which is not permitted in HTTP 1.0.

To use HTTP authentication:

• Set the HttpUsername and HttpPassword properties of the web client before invoking the web method.

• If you want the client to send an initial header indicating the scheme to use (and you know that the server permits the scheme), set the HttpInitiateAuthentication property before invoking the web method. For the value of this property, specify an authentication scheme name, as given in “Providing Login Credentials” in the chapter “Sending HTTP Requests” in Using Internet Utilities.

• If you want to customize the list of schemes that the client tries, set the HttpInitiateAuthentication property before invoking the web method. For the value of the property, use a comma-separated list of names, as given in “Providing Login Credentials” in the chapter “Sending HTTP Requests” in Using Internet Utilities.