About SOAP and Web Services
Ensemble provides support for 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 Ensemble and is available on every platform supported by Ensemble. Using Ensemble SOAP support, you can do the following:
Add a web service to an Ensemble production to provide a SOAP-enabled front end to the production. Client applications can invoke this Ensemble web service by using the SOAP protocol. Such methods can be discovered and invoked by other SOAP-aware applications. Ensemble runs SOAP methods directly within the database; the execution is highly efficient.
Add a web client to an Ensemble production. You can use a tool to generate a business operation and the proxy client classes, given the existing WSDL document of the web service you want to use. The Ensemble web client invokes the external web service via the Ensemble SOAP outbound adapter and a generated proxy client class.
This chapter discusses the following topics:
See the Creating Web Services and Web Clients in Caché book in the Caché documentation set for information on the specific standards followed by InterSystems product support for SOAP and web services, including WSDL limitations.
Ensemble Support for Web Services
You can provide a SOAP-enabled front end for your Ensemble production. To do so, you create an Ensemble web service, which is both a web service and an Ensemble business service. Internally, your web methods generally receive SOAP request messages, use them to create and send Ensemble request messages as needed within the production, receive the Ensemble response messages, and use them to create SOAP response messages.
To enable you to create an Ensemble web service, Ensemble provides the base Ensemble web service class (EnsLib.SOAP.Service), as well as supporting classes in the %SOAP and %XML packages.
Ensemble provides powerful, built-in support for web services. The base Ensemble web service class does the following for you:
Validates incoming SOAP messages.
Unpacks SOAP messages, converts data to Ensemble representation, and invokes the corresponding method, which sends an Ensemble request message to a destination inside the production.
Runs the method.
Receives an Ensemble response message and then creates and returns a response message (a SOAP message) to the caller.
The SOAP specification does not include session support. However, it is often useful to maintain a session between a web client and the web service that it uses. You can do this with an Ensemble web service. If a web service uses sessions, it establishes a session ID and allows repeated calls on the service after one successfully authenticated call from a client.
The Ensemble web service class also provides the full functionality of any Ensemble business service.
To create an Ensemble web service, you do not use an Ensemble adapter.
Ensemble Support for Web Clients
You can invoke an external web service from within an Ensemble production. To do so, you create an Ensemble web client.
At a high level, your Ensemble web client receives Ensemble requests, converts them to SOAP requests and sends them to the appropriate web service. Similarly, it receives SOAP responses and converts them into Ensemble responses.
The Ensemble web client consists of the following parts, all of which you can generate in Studio by using the SOAP wizard:
A proxy client class that defines a proxy method for each method defined by the web service. The purpose of the proxy client is to specify the location of the web service and to contain the proxy methods. Each proxy method uses the same signature used by the corresponding web service method and invokes that method when requested.
A business operation that uses the Ensemble SOAP outbound adapter to invoke the proxy methods.
Supporting classes as needed to define XML types and Ensemble messages.
The SOAP Wizard
In order to understand these parts, it is useful to consider how they are generated. First, when you use the SOAP wizard, you provide the URL for the WSDL of the web service of interest. The wizard reads the WSDL and then generates a set of classes.
The Proxy Client
The generated classes include the proxy client class that defines a proxy method for each method of the web service. Each proxy method sends a SOAP request to the web service and receives the corresponding SOAP response.
As shown in the figure, the generated classes also include classes that define any XML types needed as input or output for the methods.
The Business Operation of an Ensemble Web Client
The wizard cab also generate a business operation class that invokes the proxy client, as well as classes that define message types as needed. The following figure shows how these classes work:
The classes and methods shown within dashed lines are all generated by the SOAP wizard.
The business operation uses the SOAP outbound adapter, which provides useful runtime settings and the generic method InvokeMethod(). To invoke a proxy method in the proxy client class, the business operation class calls InvokeMethod(), passing to it the name of the method to run, as well as any arguments. In turn, InvokeMethod() calls the method of the proxy client class.