docs.intersystems.com
Home  /  Application Development: Additional Options  /  Creating Web Services and Web Clients  /  Introduction to Web Services and Web Clients in InterSystems IRIS


Creating Web Services and Web Clients
Introduction to Web Services and Web Clients in InterSystems IRIS
[Back]  [Next] 
InterSystems: The power behind what matters   
Search:  


InterSystems IRIS 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 InterSystems IRIS and is available on every platform supported by InterSystems IRIS.
This chapter introduces the following:
Introduction to InterSystems IRIS Web Services
This section introduces InterSystems IRIS web services.
Creating InterSystems IRIS Web Services
In InterSystems IRIS, you can create a web service in any of the following ways:
InterSystems IRIS Web Service as Part of a Web Application
An InterSystems IRIS web service must run within a web application that you configure within the Management Portal. Specifically, before you can use a web service class, you must define a web application that uses the namespace that contains the class.
For details on defining and configuring this web application, see the chapter Applications in the Security Administration Guide.
The WSDL
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 InterSystems IRIS, 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 an InterSystems IRIS 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 Web Gateway.
  3. The Web 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 an InterSystems IRIS 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 InterSystems IRIS SOAP support. The SOAP specification does not define a standard for sessions. However, InterSystems IRIS SOAP support provides a proprietary InterSystems IRIS 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 InterSystems IRIS 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 InterSystems IRIS 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 InterSystems IRIS Web Clients
This section introduces InterSystems IRIS web clients.
Creating InterSystems IRIS Web Clients
In InterSystems IRIS, you create a web client by using the InterSystems IRIS 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 an InterSystems IRIS 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 InterSystems IRIS web services and web clients:
For details on supported standards, see the next section.
Standards Supported in InterSystems IRIS
This section lists the basic standards and WSDL support details for InterSystems IRIS web services and web clients.
Additional standards are listed in Securing Web Services.
Basic Standards
InterSystems IRIS web services and clients support the following basic standards:
For information on XML standards supported in InterSystems IRIS, see the book Using XML Tools.
WSDL Support in InterSystems IRIS
InterSystems IRIS 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 InterSystems IRIS web services do not include headers. Also, the web services that you can create in InterSystems IRIS 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 InterSystems IRIS SOAP Wizard cannot process all possible WSDL documents. In particular:
The SOAP Wizard does allow the use of the MIME binding in a WSDL (http://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 InterSystems IRIS SAX parser is used whenever InterSystems IRIS receives a SOAP message. It is useful to know its default behavior. Among other tasks, the parser does the following: