Introduction to Caché Web Services and Web Clients
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:
By converting an existing class to a web service with a few small changes. You also need to modify any object classes used as arguments so that they extend %XML.Adaptor and can be packaged in SOAP messages.
By creating a new web service class from scratch.
By using the Caché SOAP Wizard to read an existing WSDL document and generate a web service class and all supporting type classes.
This technique (WSDL-first development) applies if the WSDL has already been designed and it is now necessary to create a web service that complies with it.
Web Service as Part of a Web Application
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:
HTTP headers that indicate the HTTP version, character set, and other such information.
The HTTP headers must include the SOAP action, which is a URI that indicates the intent of the SOAP HTTP request.
For SOAP 1.1, the SOAP action is included as the SOAPAction HTTP header. For SOAP 1.2, it is included within the Content-Type HTTP header.
The SOAP action is generally used to route the inbound SOAP message. For example, a firewall could use this header to appropriately filter SOAP request messages in HTTP. SOAP places no restrictions on the format or specificity of the URI or that it is resolvable.
A request line, which includes a HTTP method such as GET, POST, or HEAD. This line indicates the action to take.
The message body, which in this case is a SOAP message that contains a method call. More specifically, this SOAP message indicates the name of the method to invoke and values to use for its arguments. The message can also include a SOAP header.
Now let us examine what occurs when this request is sent:
The request is received by a third-party web server.
Because the request is directed to a URL that ends with .cls, the web server forwards the request to the CSP Gateway.
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.
When the web service page receives the request, it invokes its OnPage method.
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.Note:
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.
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.
The web service executes the requested Caché method, packages up the reply, and constructs a SOAP response, including a SOAP header if appropriate.
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.
First the web client creates a SOAP message that represents the method call and its argument values.
Next it creates an HTTP request that includes the SOAP message. The HTTP request includes a request line and HTTP headers, as described earlier.
It issues the HTTP request, sending it to the appropriate URL.
It waits for the HTTP response and determines the status.
It receives the SOAP response from the web service.
It unpacks the SOAP response.
The following figure shows this flow:
You can add the following features to your Caché web services and web clients:
Session support. As noted earlier, although the SOAP specification does not define a standard for sessions, you can create client-server SOAP sessions by using the CSP infrastructure and the session support provided by the %SOAP package.
Custom SOAP headers (including WS-Addressing headers), custom SOAP message bodies, and custom SOAP faults.
Use of MTOM (Message Transmission Optimization Mechanism).
Authentication (user login) between a web client and a web service, as well as key parts of the WS-Security standard.
Policies, which can control how the service or client do the following:
Specify the WS-Security header elements to use or to require.
Specify the use of MTOM.
Specify the use of WS-Addressing.
Options to fine-tune the generated WSDL document to meet most format requirements.
Use of transport other than HTTP between the web client and web service.
For details on supported standards, see the next section.
Standards Supported in Caché
Additional standards are listed in Securing Caché Web Services.
Caché web services and clients support the following basic standards:
SOAP 1.1 (see https://www.w3.org/TR/2000/NOTE-SOAP-20000508/), including encoded format.
SOAP 1.2, including encoded format as specified in section 3 SOAP Version 1.2 Part 2: Adjuncts (https://www.w3.org/TR/soap12-part2/).
MTOM (Message Transmission Optimization Mechanism) 1.0 (https://www.w3.org/TR/soap12-mtom/).
WSDL 1.1. Caché web services produce WSDL documents that comply with the Basic Profile 1.0 established by the WS-I (Web Services Interoperability Organization). However, Caché web clients do work for more general WSDL documents.
See “WSDL Support in Caché.”
UDDI version 1.0 with client access only (no repository provided). See http://uddi.xml.org/
Attachments handled as a multipart/related MIME message according to the SOAP with Attachments specification (https://www.w3.org/TR/SOAP-attachments).
SOAP with Attachments is supported for SOAP 1.2 and SOAP 1.1.
Transport via HTTP 1.1 or HTTP 1.0.
Output from the web client is supported only in UTF-8.
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.
The Caché SOAP Wizard cannot process all possible WSDL documents. In particular:
It does not support the <fault> element. That is, if you include a <fault> element within the <operation> element of the binding, the <fault> element is ignored.
For the response messages, one of the following must be true:
Each response message must be in the same namespace as the corresponding request message.
The response messages must all be in the same namespace as each other (which can be different from the namespaces used by request messages).
The Caché SOAP Wizard does not process headers of the WSDL.
The SOAP Wizard does allow the use of the MIME binding in a WSDL (https://www.w3.org/TR/wsdl#_Toc492291084). 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:
It verifies whether the XML document is well-formed.
It attempts to validate the document, using the given schema or DTD.
Here it is useful to remember that a schema can contain <import> and <include> elements that refer to other schemas. For example:
<xsd:import namespace="target-namespace-of-the-importing-schema" schemaLocation="uri-of-the-schema"/> <xsd:include schemaLocation="uri-of-the-schema"/>Copy code to clipboard
The validation fails unless these other schemas are available to the parser. Especially with WSDL documents, it is sometimes necessary to download all the schemas and edit the primary schema to use the corrected locations.
It attempts to resolve all entities, including all external entities. (Other XML parsers do this as well.) This process can be time-consuming, depending on their locations. In particular, Xerces uses a network accessor to resolve some URLs, and the implementation uses blocking I/O. Consequently, there is no timeout and network fetches can hang in error conditions, which have been rare in practice.
If needed, you can create custom entity resolvers; see “Customizing How the SAX Parser Is Used” in Using Caché XML Tools.