Creating Web Clients

Properties to Control Class Generation and Compilation

%SOAP.WSDL.ReaderOpens in a new tab includes the following properties which you can set in order to specify the types of classes to generate from the WSDL.

CompileClasses

Specifies whether to compile classes after generating them.

If CompileClasses is 1, you can control the behavior of the compiler by specifying flags in the CompileFlags property. For more information, execute the following command:

 Do $System.OBJ.ShowFlags()

Properties to Control Class Details

%SOAP.WSDL.ReaderOpens in a new tab includes the following properties to control details of the classes generated from the WSDL:

MakeMessageStyle

Specifies whether to use an unwrapped message format for the methods in the generated web client. This option affects only methods that have SoapBindingStyle equal to "document".

If either of the following statements are true of the WSDL, specify MakeMessageStyle as 1:

• The <message> elements contain multiple parts.

• The types used by the response messages belong to multiple namespaces.

Alternatively, the code generation fails and displays an error message such as the following:

ERROR #6425: Element 'wsdl:binding:operation:msg:input' - message 'AddSoapOut' 
Message Style must be used for document style message with 2 or more parts.

For more information, see Using InterSystems IRIS Web Client Classes.

Example 1: Using the Client That Uses Wrapped Messages

In this example, we create a wrapper class for a web client that uses wrapped messages. To use the example GSOAPClient.AddComplex.AddComplexSoap shown previously, we could create a class like the following:

Class GSOAPClient.AddComplex.UseClient Extends %RegisteredObject
{

ClassMethod Add(arg1 As ComplexNumber, arg2 As ComplexNumber) As ComplexNumber
{
    Set client=##class(AddComplexSoap).%New()
    //uncomment the following to enable tracing
    //set client.Location="https://devsys:8080/csp/mysamples/GSOP.AddComplexWS.cls"
    Set ans=client.Add(arg1,arg2)
    Quit ans 
}

}

The client application would invoke this method in order to execute the web method.

Example 2: Using the Client That Uses Unwrapped Messages

In this example, we create a wrapper class for a web client that uses unwrapped messages. To use the example GSOAPClient.AddComplex.AddComplexSoap shown previously, we could create a class like the following:

Class GSOAPClient.AddComplexUnwrapped.UseClient Extends %RegisteredObject
{

ClassMethod Add(arg1 As GSOAPClient.AddComplexUnwrapped.s0.ComplexNumber, 
arg2 As GSOAPClient.AddComplexUnwrapped.s0.ComplexNumber) 
As GSOAPClient.AddComplexUnwrapped.s0.ComplexNumber
{
    //create the Add message
    Set addmessage=##class(GSOAPClient.AddComplexUnwrapped.s0.Add).%New()
    Set addmessage.a = arg1
    Set addmessage.b = arg2

    Set client=##class(AddComplexSoap).%New()
    
    //send the Add message to client and get response
    Set addresponse=client.Add(addmessage)
    
    //get the result from the response message
    Set ans=addresponse.AddResult
    
    Quit ans
 
}

}

The method has the signature that would typically be expected; that is, it accepts two complex numbers and returns a complex number. The method creates the message that the web client expects. The elements of this message are the two complex numbers.

As you can see, when the web client uses unwrapped messages, it is necessary to write slightly more code to convert arguments in a user-friendly form into the message used by the web client.

Adjusting the Generated Classes for Extremely Long Strings

In rare cases, you might need to edit the generated client class to accommodate extremely long strings or binary values — values whose lengths exceed the string length limit.

When generating a web client from a WSDL, InterSystems IRIS assumes that any string-type input or output can be represented in InterSystems IRIS as %StringOpens in a new tab, which is not always true. In rare cases, a string might exceed the string length limit. Similarly, InterSystems IRIS assumes that any input or output with XML type base64Binary can be represented in InterSystems IRIS as %xsd.base64BinaryOpens in a new tab), which is not always true, due to the same string length limitation. In neither case does the WSDL contain any information to indicate that this input or output could exceed the string length limit.

When your web client encounters a string or a binary value that is too long, it throws one of the following errors:

• A <MAXSTRING> error

• A datatype validation error:

  ERROR #6232: Datatype validation failed for tag your_method_name ...
  

  

  (This error, of course, can also be caused by a datatype mismatch.)

The problem, however, is easy to correct: adjust the method signature in your generated web client class (specifically the class that inherits from %SOAP.WebClientOpens in a new tab) to use an appropriate stream class:

• Use %GlobalCharacterStreamOpens in a new tab instead of %StringOpens in a new tab.

• Use %GlobalBinaryStreamOpens in a new tab instead of %xsd.base64BinaryOpens in a new tab.

For example, consider a web service (MyGiantStringService) that has one method (WriteIt), which takes no arguments and returns a very long string. The web client class originally looks something like this:

Class GetGiantString.MyServiceSoap Extends %SOAP.WebClient
{

Method WriteIt() As %String 
[Final,SoapBindingStyle=document,SoapBodyUse=literal,WebMethod]
{
 Quit ..WebMethod("WriteIt").Invoke($this,"https://tempuri.org/MyApp.MyGiantStringService.WriteIt")
}

}

In this case, there is only one adjustment to make. Change the return type of WriteIt as follows:

Method WriteIt() As %GlobalCharacterStream 
[Final,SoapBindingStyle=document,SoapBodyUse=literal,WebMethod]
{
 Quit ..WebMethod("WriteIt").Invoke($this,"https://tempuri.org/MyApp.MyGiantStringService.WriteIt")
}

When you compile this class, the system automatically regenerates the associated classes as needed.

You may also need to adjust property types within any generated type classes. For example, suppose the web service uses an element called <Container>, which includes an element <ContainerPart> of type string. When you generate the InterSystems IRIS web client classes, the system creates a Container class with a ContainerPart property of type %StringOpens in a new tab. If the web service sends a string longer than the string length limit in the <ContainerPart> element, your web client throws an error. To avoid this error, change the type of the ContainerPart property to %GlobalCharacterStreamOpens in a new tab.

Other Adjustments

If the WSDL does not specify the location of the web service, the generated web client does not specify the LOCATION parameter. This is a rare scenario. In this scenario, edit the web client class to include the LOCATION parameter. For example:

Parameter LOCATION = "https://devsys/csp/mysamples/GSOP.AddComplexWS.cls";

Or specify the Location property of your web client instance as shown later in this topic.

You might need to adjust other parameters of the web client class to make other changes. See Fine-Tuning a Web Client in InterSystems IRIS for details.

Changing the Endpoint for the Web Client

When you generate web client, the class automatically specifies the LOCATION parameter as the URL of the web service with which it communicates.

To override this, set the Location property of your web client instance. If Location is null, then the LOCATION parameter is used.

A common usage is to set the Location property to use a different port, in order to enable tracing. For example, suppose that in the generated web client class, the endpoint is defined as follows:

Parameter LOCATION = "https://devsys/csp/mysamples/GSOP.AddComplexWS.cls";

When you use this client, you can include the following line:

   Set client.Location="https://devsys:8080/mysamples/mysamples/GSOP.AddComplexWS.cls"

Configuring the Client to Use SSL

If the endpoint for a web client has HTTPS protocol, the web client must be configured to use SSL. Specifically:

• If you have not already done so, use the Management Portal to create an SSL/TLS configuration that contains the details of the needed SSL connection. For information, see About Configurations in the TLS Guide.

• Set the SSLConfiguration property of the web client equal to that SSL/TLS configuration name.

Note that if the client is connecting via a proxy server, you must also set the HttpProxySSLConnect property equal to 1 in the web client. For information on configuring an InterSystems IRIS web client to use a proxy server, see Fine-Tuning the Web Client.

Specifying the SOAP Version

The generated web client automatically specifies the SOAP version to use in request messages, based on the SOAP version in the WSDL of the web service. Specifically it sets the SOAPVERSION parameter.

To override this, set the SoapVersion property of your web client instance. Use one of the following values:

• "" — The client sends SOAP 1.1 messages.

• "1.1" — The client sends SOAP 1.1 messages.

• "1.2" — The client sends SOAP 1.2 messages.

If SoapVersion is null, then the SOAPVERSION parameter is used.

Other Adjustments

You might need to set other properties of the web client instance to make other changes. See Fine-Tuning a Web Client in InterSystems IRIS for details.