Creating Web Services and Web Clients in Caché
Introduction to Caché Web Services and Web Clients
[Home] [Back] [Next]
InterSystems: The power behind what matters   

Caché supports SOAP 1.1 and 1.2 (Simple Object Access Protocol). This support is easy to use, efficient, and fully compatible with the SOAP specification. This support is built into Caché and is available on every platform supported by Caché.

This chapter introduces the following:
Introduction to Caché Web Services
This section introduces Caché web services.
Creating Caché Web Services
In Caché, you can create a web service in any of the following ways:
Web Service as Part of a Web Application
A Caché web service class inherits from the %SOAP.WebService class, which in turn inherits from %CSP.Page.
Because of this fact, a Caché web service resides within a web application that you configure within the Management Portal. For details, see the chapter Applications in the Caché Security Administration Guide.
When the class compiler compiles a web service, it generates a WSDL for the service and publishes that via a web server, for your convenience. This WSDL complies with the Basic Profile 1.0 established by the WS-I (Web Services Interoperability Organization). In Caché, the WSDL document is served dynamically at a specific URL, and it automatically reflects any changes you make to the interface of your web service class (apart from header elements added at runtime). In most cases, you can use this document to generate web clients that interoperate with the web service.
For details and important notes, see Viewing the WSDL,” in the next chapter.
Web Service Architecture
To understand how a Caché web service works by default, it is useful to follow the events that occur when the web service receives a message it can understand: an HTTP request that includes a SOAP message.
First consider the contents of this HTTP request, which is directed to a specific URL:
Now let us examine what occurs when this request is sent:
  1. The request is received by a third-party web server.
  2. Because the request is directed to a URL that ends with .cls, the web server forwards the request to the CSP Gateway.
  3. The CSP Gateway examines the URL. It interprets part of this URL as the logical name of a web application. The Gateway forwards the request to the appropriate physical location (the page for the web service), within that web application.
  4. When the web service page receives the request, it invokes its OnPage method.
  5. The web service checks whether the request includes a Caché SOAP session header and if so, resumes the appropriate SOAP session or starts a new one.
    This step refers to SOAP sessions as supported by Caché SOAP support. The SOAP specification does not define a standard for sessions. However, Caché SOAP support provides a proprietary Caché SOAP session header that you can use to maintain a session between a web client and a web service, as described here.
  6. The web service unpacks the message, validates it, and converts all input parameters to their appropriate Caché representation. For each complex type, the conversion creates an object instance that represents the complex type and uses that object as input for the web method.
    The SOAP action from the HTTP header is used here to determine the method and hence the request object.
    When the web service unpacks the message, it creates a new request object and imports the SOAP message into that object. In this process, the web service uses a generated class (a web method handler class) that was created when you compiled the web service.
  7. The web service executes the requested Caché method, packages up the reply, and constructs a SOAP response, including a SOAP header if appropriate.
  8. The web service writes the SOAP response (an XML document) to the current output device.
The following figure shows the external parts of this flow:
Introduction to Caché Web Clients
This section introduces Caché web clients.
Creating Caché Web Clients
In Caché, you create a web client by using the Caché SOAP Wizard to read an existing WSDL document. The wizard generates a web client class and all supporting type classes.
The generated web client interface includes a client class that contains a proxy method for each method defined by the web service. Each proxy uses the same signature used by the corresponding web service method. The interface also includes classes to define any XML types needed as input or output for the methods.
Typically you do not customize the generated classes. You instead create additional classes that control the behavior of your web client and invoke its proxy methods.
Web Client Architecture
To understand how a Caché web client works, we follow the events that occur when a user or other agent invokes a method within the web client.
  1. First the web client creates a SOAP message that represents the method call and its argument values.
  2. Next it creates an HTTP request that includes the SOAP message. The HTTP request includes a request line and HTTP headers, as described earlier.
  3. It issues the HTTP request, sending it to the appropriate URL.
  4. It waits for the HTTP response and determines the status.
  5. It receives the SOAP response from the web service.
  6. It unpacks the SOAP response.
The following figure shows this flow:
Additional Features
You can add the following features to your Caché web services and web clients:
For details on supported standards, see the next section.
Standards Supported in Caché
This section lists the basic standards and WSDL support details for Caché web services and web clients.
Additional standards are listed in Securing Caché Web Services.
Basic Standards
Caché web services and clients support the following basic standards:
For information on XML standards supported in Caché, see the book Using Caché XML Tools.
WSDL Support in Caché
Caché does not support all possible WSDL documents. More flexibility is provided on the client side, because it is frequently necessary to create web clients that work with specific WSDLs that cannot be changed. This section discusses the details of the support.
Generated WSDL Documents
The WSDL documents generated by Caché web services do not include headers. Also, the web services that you can create in Caché do not reflect all possible variations.
Note that the SOAP specifications do not require a web service to generate a WSDL at all.
Consuming WSDLs
The Caché SOAP Wizard cannot process all possible WSDL documents. In particular:
The SOAP Wizard does allow the use of the MIME binding in a WSDL ( The MIME parts are ignored and the remainder of the WSDL is processed. When you create a web service or client based on a WSDL that contains MIME binding, you must add explicit ObjectScript code to support the MIME attachments; this task is beyond the scope of this book.
Key Points about the SAX Parser
The Caché SAX parser is used whenever Caché receives a SOAP message. It is useful to know its default behavior. Among other tasks, the parser does the following:

Send us comments on this page
Copyright © 1997-2019 InterSystems Corporation, Cambridge, MA