Creating SOAP Services and Web Clients with Ensemble
Using the SOAP Inbound Adapter
[Home] [Back] [Next]
InterSystems: The power behind what matters   
Class Reference   
Search:    

This appendix briefly discusses the class EnsLib.SOAP.InboundAdapter, which you can use as an alternative to EnsLib.SOAP.Service (which is described in Creating an Ensemble Web Service.”)

The standard way to create an Ensemble web service is to create a subclass of EnsLib.SOAP.Service and set up a web server to be your production web server. In this way, your system will be able to utilize all the SOAP and security features provided by a commercial web server and the Ensemble SOAP framework. Using the EnsLib.SOAP.InboundAdapter is easier to configure and lighter weight but doing so bypasses the above mentioned formal web support machinery. Also, the adapter does not expose the WSDL and test page the way the standard Ensemble SOAP framework does.
Notes
The SOAP inbound adapter (EnsLib.SOAP.InboundAdapter) does not require web server software. Instead it spawns a TCP listener job using the Ensemble super server. This lets you run your service in a foreground window, which is useful for debugging. (To do this, you must be running the service locally. Also make sure the PoolSize setting is 1 and the JobPerConnection setting is false.) It also supports SSL.
The EnsLib.SOAP.InboundAdapter listens for HTTP input on a given port. When the adapter receives input, the following occurs:
  1. It extracts the HTTP SOAPaction header.
  2. It creates a stream (%Library.GlobalBinaryStream) that contains the body of the input.
  3. It calls the web method that corresponds to the given SOAPaction.
This adapter provides an advantage in that it supports persistent connections for successive SOAP calls. Also, if you use it with JobPerConnection=0, it can retain expensively instantiated resources such as XPath parsers even across successive connections that encompass individual SOAP service calls.
Development Tasks
To use the Ensemble SOAP inbound adapter, write and compile a new business service class in Studio. The following list describes the basic requirements:
Optionally, to disable support for calls via the adapter in your service, add this to your class:
Parameter ADAPTER=""; 
Configuration Tasks
Use the Management Portal to do the following:
  1. Add an instance of your custom class to the Ensemble production.
    Important:
    Ensure that the configuration name is the same as the full class name, including package. This is a requirement for running an Ensemble web service.
  2. Enable the business service.
  3. Set the PoolSize setting to 1 so that the adapter can use its TCP listener.
  4. Set the StayConnected setting to 0. Otherwise, clients may hang for their timeout period while waiting for the server to drop the connection.
  5. Specify other settings as needed; see Settings for the SOAP Inbound Adapter in Reference for Settings.”
  6. Run the production.