Creating Web Services and Web Clients in Caché
Creating Web Clients
[Back] [Next]
   
Server:docs2
Instance:LATEST
User:UnknownUser
 
-
Go to:
Search:    

A web client is software that accesses a web service. A web client provides a set of proxy methods, each of which corresponds to a method of the web service. A proxy method uses the same signature as the web service method to which it corresponds, and it invokes the web service method when asked to do so. This chapter describes how to create and use web clients in Caché:

For information on logging SOAP calls to your Caché web clients, see Caché SOAP Log,” later in this book.
Note:
For a Caché web service, the automatically generated WSDL might not include information about the SOAP header elements:
Note that the W3C specifications do not require a web service to provide a generated WSDL.
Overview of the SOAP Wizard
To create a Caché web client, you can use the SOAP Wizard in Caché Studio or the corresponding class method provided by Caché. In either case, the input is a WSDL document. The tools generate a web client class and all needed supporting classes.
You can use the tool with nearly any WSDL document; see WSDL Support in Caché in the first chapter.
You can provide either the URL or the file path for the WSDL.
Note:
If the WSDL indicates support for both SOAP 1.1 and SOAP 1.2, then the SOAP Wizard generates two sets of classes, if needed.
Using the SOAP Wizard
Studio provides the SOAP Wizard, which enables you to generate a client for a given web service, given the WSDL of that service.
Note:
When using templates such as the SOAP Wizard, Studio will use a proxy server, if it is enabled. For information on specifying the proxy server and port, see Using a Proxy Server in Using Caché Internet Utilities.
To use the SOAP wizard:
  1. Examine the WSDL and check for the following items:
    In either case, if the answer is yes, then you will need to select the option Use unwrapped message format for document style web methods, which is described in a later step.
  2. On the first screen:
    1. Click either URL or FILE, depending on the location of the WSDL.
    2. Enter the location of the WSDL. Type either the entire URL or the complete path and filename for the WSDL.
    3. If the WSDL is at a location that uses SSL (that is, if the URL starts with https), then select a suitable SSL configuration from the SSL Configuration dropdown list. For information on creating and managing SSL/TLS configurations, see the chapter Using SSL/TLS with Caché in the Caché Security Administration Guide.
      Important:
      This wizard specifies an SSL configuration to use when accessing the WSDL. This field is not used in any other way.
  3. Click Next.
    The wizard then attempts to access the WSDL and display it so that you can verify that you have chosen the correct one.
    If the wizard cannot access the WSDL, it displays a screen that displays the error and provides options that you can use to provide a username and password. (Many WSDLs are at URLs that are protected by a username and password, and this is a common reason for failing to access the WSDL.) In this scenario, first do one of the following:
    Then enter values in the Username and Username fields and press Try Again. Note that the wizard does not save your entries for these items.
  4. On the screen that displays the WSDL, specify options as follows:
  5. If you have an Ensemble installation, optionally provide values for the following additional fields:
    For information on Ensemble, see the Ensemble documentation.
  6. Click Next. The wizard then displays a screen like the following:
  7. Specify the following options:
  8. Optionally edit the package names. The wizard uses the following rules for package names:
  9. Click Next. The wizard generates and compiles the classes and displays a list of these classes.
  10. Click Finish.
Tip:
If you use a WSDL URL and there are problems with the wizard, save the WSDL as a file and try again, using that file as input.
If the WSDL contains references to externally defined entities, the wizard attempts to resolve those; for this task, the timeout period is 10 seconds.
For properties of these classes, if the corresponding element in the schema has a name that starts with an underscore (_), the name of the property starts with a percent sign (%).
Generating the Client Classes Programmatically
You can instead generate the client classes programmatically by using the %SOAP.WSDL.Reader class.
The resulting generated classes and their organization may not be the same as if you used the SOAP wizard, which provides greater control over the packages for the generated classes.
To generate the client classes programmatically:
  1. Create an instance of %SOAP.WSDL.Reader.
  2. Optionally set properties to control the behavior of your instance. For details, see the class documentation for %SOAP.WSDL.Reader.
  3. Invoke the Process() method of your instance:
    method Process(pLocationURL As %String, pPackage As %String = "") as %Status 
The following shows an example Terminal session:
set r=##class(%SOAP.WSDL.Reader).%New() 
GSOAP>set url="http://localhost:57772/csp/gsop/GSOP.AddComplexWS.CLS?WSDL=1"
 
GSOAP>d r.Process(url) 
Compilation started on 11/09/2009 12:53:52 with qualifiers 'dk'
Compiling class AddComplex.ns2.ComplexNumber
Compiling routine AddComplex.ns2.ComplexNumber.1
Compilation finished successfully in 0.170s.
 
Compilation started on 11/09/2009 12:53:52 with qualifiers 'dk'
Compiling class AddComplex.AddComplexSoap
Compiling routine AddComplex.AddComplexSoap.1
Compiling class AddComplex.AddComplexSoap.Add
Compiling routine AddComplex.AddComplexSoap.Add.1
Compilation finished successfully in 0.363s.
The WSDL URL is part of a web application, which might be protected by password authentication. For details on using the WSDL in this case, to generate Caché web clients or third-party web clients, see Using a Password-Protected WSDL URL,” later in this book.
In all cases, it is also possible to retrieve the WSDL from a browser after supplying the required username and password, save it as a file, and use the file instead.
Modifying the Generated Client Classes
After you generate a Caché web client class, you do not usually edit the class. Instead you write code that creates an instance of the web client and that provides provide client-side error handling. This section documents the notable exceptions where you do modify the generated client class.
Also see the section Additional Notes on Web Methods in the Generated Class and the chapter Fine-Tuning a Caché Web Client.”
Note:
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.
Adjusting the Generated Classes for Long Strings
In some cases, you might need to edit the generated client class to accommodate long strings or long binary values.
When the SOAP Wizard reads a WSDL, it assumes that any string-type input or output can be represented in Caché as %String, which is not always true. Some strings might exceed the Caché 32 KB limit for strings, and there is no information in the WSDL to inform the SOAP Wizard of this.
Similarly, it assumes that any input or output with XML type base64Binary can be represented in Caché as %xsd.base64Binary), which is not always true, due to the same long string limitation. There is no information in the WSDL to inform the SOAP Wizard that this input or output could exceed the long string limit.
In either case, if you have enabled long string operations in Caché, your web client works.
If you have not enabled long string operations in Caché, however, when your web client encounters a string or a binary value that is too long, it throws one of the following errors:
The problem, however, is easy to correct. If you expect long values for these inputs and outputs, adjust the method signature in your generated web client class (specifically the class that inherits from %SOAP.WebClient) to use an appropriate stream class:
For example, consider a web service (MyGiantStringService) that has one method (WriteIt), which takes no arguments and returns a very long string, greater than 32 KB. If you use the SOAP Wizard to generate the web client class, 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,"http://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,"http://tempuri.org/MyApp.MyGiantStringService.WriteIt")
}
When you compile this class, Caché 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 Caché web client classes, Caché creates a Container class with a ContainerPart property of type %String. If the web service sends a string longer than 32 KB in the <ContainerPart> element, and if you have not enabled long string operations, your web client throws an error. To avoid this error, change the type of the ContainerPart property to %GlobalCharacterStream.
Other Adjustments
If the WSDL does not specify the location of the web service, the SOAP Wizard does not specify the LOCATION parameter of the web client. This is a rare scenario. In this scenario, edit the web client class to include the LOCATION parameter. For example:
Parameter LOCATION = "http://localhost:57772/csp/gsop/GSOP.AddComplexWS.cls";
Or specify the Location property of your web client instance as shown later in this chapter.
You might need to adjust other parameters of the web client class to make other changes. See the chapter Fine-Tuning a Caché Web Client for details.
Using the Generated Web Client Classes
As noted in the previous section, after you generate a Caché web client class, you do not usually edit the generated class. Instead you write code that creates an instance of that web client and that provides provide client-side error handling. In this code, do the following:
  1. Create an instance of the web client class.
  2. Set its properties. Here you can control items such as the following:
  3. Invoke the methods of the web client as needed.
  4. Perform client-side error handling. See the chapter SOAP Fault Handling.”
  5. Optionally examine the HTTP response received by the web client, as described later in this chapter.
The following shows a simple example, from a session in the Caché Terminal:
GSOAP>set client=##class(Proxies.CustomerLookupServiceSoap).%New()

GSOAP>set resp=client.GetCustomerInfo("137")
 
GSOAP>w resp
 
11@Proxies.CustomerResponse

GSOAP>w resp.Name
Smith,Maria
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="http://localhost:8080/csp/gsop/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 Properties of a Web Client Instance
When you use an instance of your web client classes, you can specify properties of that instance to control its behavior. This section discusses the properties that are most commonly set, as well as their default values.
Changing the Endpoint for the Web Client
The SOAP Wizard automatically sets the endpoint for the web client by setting the LOCATION parameter of the web client. By default, it sets this parameter equal to 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 = "http://localhost:57772/csp/gsop/GSOP.AddComplexWS.cls";
When you use this client, you can include the following line:
   Set client.Location="http://localhost:8080/csp/gsop/GSOP.AddComplexWS.cls"
Note:
If the WSDL does not specify the location of the web service, the SOAP Wizard does not specify the LOCATION parameter of the web client. This is a rare scenario. In this scenario, either edit the web client class to include the LOCATION parameter or specify the Location property of your web client instance as shown here.
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:
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 a Caché web client to use a proxy server, see the chapter Fine-Tuning the Web Client.”
Specifying the SOAP Version
The SOAP Wizard 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:
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 the chapter Fine-Tuning a Caché Web Client for details.
Using the HTTP Response
By default, when you invoke a web client method, you do so via HTTP. The HTTP response is then available as the HttpResponse property of the web client instance. This property is an instance of %Net.HttpResponse, which in turn has properties like the following:
For details, see the book Using Caché Internet Utilities. Or see the class documentation for %Net.HttpResponse.