Creating SOAP Services and Web Clients with Ensemble
Creating an Ensemble Web Client
[Home] [Back] [Next]
InterSystems: The power behind what matters   
Class Reference   
Search:    

This chapter describes how to create an Ensemble web client. At a high level, your Ensemble web client receives Ensemble requests from elsewhere within the production, converts them to SOAP requests, and sends them to the appropriate web service. Similarly, it receives SOAP responses, converts them into Ensemble responses, and sends them back within the production. This chapter discusses the following topics:

Tip:
Ensemble also provides specialized business service classes that use SOAP, and one of those might be suitable for your needs. If so, no programming would be needed. See Connectivity Options in Introducing Ensemble.
Overview
An Ensemble web client consists of the following parts:
The following figure shows how the business operation, adapter, and proxy client class work together. Supporting classes are not shown here.
In the preceding figure, all items within dashed lines can be generated by the SOAP client wizard in Studio. You can then edit this code as needed.
For a more detailed look at these parts, see Ensemble Support for Web Clients,” earlier in this book.
Basic Steps
This section outlines the basic steps to create an Ensemble web client.
To create an Ensemble web client, do the following within Studio:
  1. Use the SOAP wizard to generate the business operation class, proxy client class, and supporting classes. This tool is described in Using the SOAP Wizard in this chapter.
  2. Check whether you need to adjust the types of the inputs and outputs of the methods. In particular, if any of the methods of the web service have inputs or outputs that could exceed 32 KB in length, and if you have not enabled support for long strings in Ensemble, you should change the types of those inputs or outputs to an appropriate stream class.
Using the SOAP Wizard
To use the SOAP wizard to generate an Ensemble web client, do the following:
  1. In Studio, make sure that you are in the appropriate Ensemble namespace.
  2. On the first screen, enter the entire URL of the WSDL document for the web service you want to work with.
  3. Click Next.
  4. Select the check box to the left of Create Business Operation in Package. This option instructs the wizard to define a business operation class that invokes the proxy client, as well as message classes for use with that business operation.
  5. For Create Business Operation in Package, optionally change the subpackage name from BusOp to another name.
  6. For Optional Package Name, type a package name for the proxy client and related classes. The default package name is the service name. Also see the Generated Classes and XMLKEEPCLASS section.”
  7. For Class Type, choose a general type for the proxy client class: persistent or serial (the default).
  8. Click Next. The wizard generates and compiles the classes and displays a list of these classes.
  9. Click Finish.
Generated Classes and XMLKEEPCLASS
The SOAP wizard generates a set of classes; the details of these classes are discussed later in this chapter.
You specify the package in which the tool should create the proxy client class and the supporting classes. If this package is the same as an existing package, by default the tool will overwrite any existing classes that have the same name. To prevent the wizard from overwriting a class definition, add the XMLKEEPCLASS parameter to that class and set this parameter equal to 1.
Using the Process() Method
Instead of using the wizard, you can use the Process() method of the %SOAP.WSDL.Reader class. To use this method:
  1. Create an instance of %SOAP.WSDL.Reader.
  2. Optionally set properties to control the behavior of your instance.
    Property Purpose
    CompileFlags Specifies the flags to use when compiling the generated classes. The initial expression is "dk"; use $System.OBJ.ShowFlags() to get information on the available flags.
    MakePersistent If this property is 1, the proxy client is a persistent object; otherwise, it is a registered object. The initial expression is 0.
    MakeSerial If this property is 1 and if MakePersistent is 1, the proxy client is a serial class. The initial expression is 0.
    OutputTypeAttribute Controls how the WSDL reader sets the OUTPUTTYPEATTRIBUTE parameter in the proxy client that it generates; which controls the use of the xsi:type attribute in the SOAP messages. See Creating Web Services and Web Clients in Caché in the Caché documentation set.
    MakeBusinessOperation Specifies whether to generate an Ensemble business operation and related request and response objects. The ADAPTER setting for this business operation is EnsLib.SOAP.OutboundAdapter. This option works only if you are working within an Ensemble-enabled namespace.
    For other properties, see the class documentation for %SOAP.WSDL.Reader.
  3. Invoke the Process() method, providing the following arguments:
Generated Classes for an Ensemble Web Client
This section provides information about the classes that the SOAP wizard generates.
Consider a web service named MyService that has the following details:
Suppose that you use the SOAP wizard to generate a Ensemble web client for this web service. If you specify the package for the client classes as MyClient, the SOAP wizard will generate the following classes and add them all to your current project:
When you compile these classes, the compiler also generates a class for each method defined in the web service. These classes are not automatically added to your project and their internal details are subject to change. These classes extend %SOAP.ProxyDescriptor, which you should never subclass yourself.
Creating a Business Operation Class Manually
Rather than using the business operation class that the SOAP wizard generates, you can create your own class. This section describes how to do so. It discusses the following:
Basic Requirements of the Class
The following list describes the basic requirements of the business operation class:
You will also need to define the Ensemble message classes that the business operation uses.
Basic Requirements of the Methods
Within your business operation class, your methods should invoke the proxy methods. Here the general requirements are as follows:
  1. The method should have the same signature as the proxy method that it is invoking.
  2. The method should be marked with the WebMethod keyword.
  3. The method should set the SoapBindingStyle and SoapBodyUse keywords as expected by the proxy client. (That is, use the same values as in the signature of the corresponding proxy method.)
  4. The method should set the WebServiceClientClass property of the adapter. When this property is set, a proxy client instance is created and placed in the %Client property of the adapter.
  5. The method should call the corresponding proxy method, using one of the techniques in the next section.
  6. The method should check the status.
  7. Then:
Ways to Execute the Proxy Methods
Within your business operation, your methods should execute the proxy methods of the proxy client class. You can do this in multiple ways, which are best shown via an example. This section uses an example web service that has a web method named GetStock that accepts a stock symbol (a string) and returns a number. Suppose that you have used the SOAP wizard to generate a proxy client (GetStock.StockServiceSoap), which contains a method called GetStock.
Also suppose that you have created message classes as follows:
Class GetStock.BusOp.GetQuoteRequest Extends Ens.Request
{

Parameter RESPONSECLASSNAME = "GetStock.BusOp.GetQuoteResponse";

Property StockName As %String;

}
And
Class GetStock.BusOp.GetQuoteRequest Extends Ens.Request 
{

Parameter RESPONSECLASSNAME = "GetStock.BusOp.GetQuoteResponse";

Property StockName As %String;

}
To execute the proxy method GetStock, your business operation class can do any of the following:
Reference Information
This section provides reference information for the adapter property and methods mentioned in the previous section.
%Client property
%SOAP.WebClient 
The associated instance of the proxy client (an instance of %SOAP.WebClient). This property is set when you set the WebServiceClientClass property of the adapter.
InvokeMethod() method
Method InvokeMethod(pMethodName As %String,
       Output pResult As %RegisteredObject,
       pArgs...) As %Status
Calls the specified method of the proxy client class, passing all the arguments and returns the status. The output is returned by reference as the second argument.
WebMethod() method
Method WebMethod(pMethodName As %String) As %SOAP.ProxyDescriptor
Returns an object that corresponds to the specified method. This object has one property corresponding to each method argument; you should set this properties before using the Invoke() method. For details on %SOAP.ProxyDescriptor, see the class reference.
Invoke() method
Method Invoke(pWebMethod As %SOAP.ProxyDescriptor) As %Status
Calls the given method and returns the status.
Adding and Configuring the Web Client
To add your Ensemble web client to an Ensemble production, use the Management Portal to do the following:
  1. Add an instance of your custom business operation class to the Ensemble production, specifically the business operation class generated by the SOAP wizard.
  2. Enable the business operation.
  3. Specify appropriate values for the runtime settings of the associated adapter, as discussed below.
  4. Run the production.
The following subsections describes the runtime settings for your Ensemble web client, which fall into several general groups:
For settings not listed in this book, see Settings in All Productions in Managing Ensemble Productions.
Specifying Basics
The following settings specify the basic information for the Ensemble web client:
Specifying Credentials
The web service that you are accessing might require a username and password. In general, the Ensemble SOAP client can log into a web service in either of the following ways:
Use the technique that is appropriate for the web service you are using.
Specifying an SSL Configuration
If the web server supports it, you can connect with SSL. To do so, specify a value for the SSL Configuration setting.
Note:
You must also ensure the web service is at a URL that uses https://. The web service location is determined by the Web Service URL setting; if this is not specified, the Ensemble web client assumes the web service is at the URL specified by the LOCATION parameter in the proxy client class.
Specifying a Proxy Server
You can communicate with the web service via a proxy server. To set this up, use Proxy Server and other settings in the Proxy Settings group.