Using HTTP Adapters with Ensemble
Using the HTTP Inbound Adapter
[Back] [Next]
Go to:

This chapter describes the default behavior of the Ensemble HTTP inbound adapter (EnsLib.HTTP.InboundAdapter) and describes how to use this adapter in your productions. It discusses the following topics:

Ensemble also provides specialized business service classes that use this adapter, and one of those might be suitable for your needs. If so, no programming would be needed. See Connectivity Options in Introducing Ensemble.
Overall Behavior
EnsLib.HTTP.InboundAdapter is the Ensemble HTTP listener for custom port listening, XML listening, and/or raw HTML handling. You use this adapter in cases when you prefer to listen on a private port rather than using a CSP page (which uses the standard web server to handle HTTP requests).
First, the class provides runtime settings that you use to specify items like the following:
The inbound HTTP adapter listens to a port on the local machine, reads the input, and sends the input as a stream to the associated business service. The business service, which you create and configure, uses this stream and communicates with the rest of the production. The following figure shows the overall flow:
In more detail:
  1. The adapter receives an HTTP message and opens a TCP connection. (HTTP is a format of header and body data that is sent over a TCP connection.)
  2. When the adapter connects, it executes its OnConnected() method, which first determines the character set to use. By default, it uses the character set specified in the inbound HTTP request. For details, however, see Specifying the Character Set to Use.”
  3. The adapter chooses the appropriate translation table for the character set.
  4. The adapter reads the body of the input, translates it, and places it into a new stream object.
    The adapter also extracts each HTTP header and adds that header to the Attributes property of the stream; this property is a multidimensional array, as discussed later.
    Also, if the URL includes form parameters, these are passed as follows:
  5. The adapter then calls the internal ProcessInput() method of the business service class, passing the stream as an input argument.
  6. The internal ProcessInput() method of the business service class executes. This method performs basic Ensemble tasks such as maintaining internal information as needed by all business services. You do not customize or override this method, which your business service class inherits.
  7. The ProcessInput() method then calls your custom OnProcessInput() method, passing the stream object as input. The requirements for this method are described later in Implementing the OnProcessInput() Method.”
  8. If ProcessInput() or OnProcessInput() returns an error, Ensemble invokes the OnErrorStream() method of the business service.
The response message follows the same path, in reverse.
Creating a Business Service to Use the HTTP Inbound Adapter
To use this adapter in your production, create a new business service class as described here. Later, add it to your production and configure it. You must also create appropriate message classes, if none yet exist. See Defining Ensemble Messages in Developing Ensemble Productions.
The following list describes the basic requirements of the business service class:
The following example shows the overall structure of your business service class. The details of the OnProcessInput() method depend on the character set that the adapter is using. If the adapter is using a non-binary character set, the general structure should be as follows:
Class EHTTP.NewService1 Extends Ens.BusinessService 
Parameter ADAPTER = "EnsLib.HTTP.InboundAdapter";

Method OnProcessInput(pInput As %GlobalCharacterStream, pOutput As %RegisteredObject) As %Status
   set tsc=$$$OK
   //your code here
   Quit tsc
Or, if the adapter is using a binary character set, the OnProcessInput() method should be as follows instead:
Method OnProcessInput(pInput As %GlobalBinaryStream, pOutput As %RegisteredObject) As %Status
   set tsc=$$$OK
   //your code here
   Quit tsc
Studio provides a wizard that you can use to create a business service stub similar to the preceding. To access this wizard, click File —> New and then click the Production tab. Then click Business Service and click OK. Note that the wizard provides a generic input argument. If you use the wizard, InterSystems recommends that you edit the method signature to use the specific input argument that you need; the input argument type should be %GlobalCharacterStream or %GlobalBinaryStream.
Implementing the OnProcessInput() Method
Within your custom business service class, the signature of your OnProcessInput() method depends on the character set that the adapter is using:
Here pInput is the input that the adapter will send to this business service. Also, pOutput is the generic output argument required in the method signature.
The OnProcessInput() method should do some or all of the following:
  1. Examine the input object and extract the needed data from it. See Using the HTTP Request,” later in this chapter.
  2. Create an instance of the request message, which will be the message that your business service sends.
    For information on creating message classes, see Defining Ensemble Messages in Developing Ensemble Productions.
  3. For the request message, set its properties as appropriate, using values obtained from the input stream.
    If the attribute Content-Type is specified in the Attributes property, by default, that is used as the Content-Type of the request message. If Content-Type is not specified in the Attributes property, by default, the Content-Type of the request message is set to "text/html". If these defaults are not appropriate, be sure to set this attribute. For example, the following code checks the value of the attribute Content-Type of the input stream and uses "text/xml" if the value is missing:
     Set outputContentType=$GET(pInput.Attributes("Content-Type"),"text/xml")
  4. Call a suitable method of the business service to send the request to some destination within the production. Specifically, call SendRequestSync(), SendRequestAsync(), or (less common) SendDeferredResponse(). For details, see Sending Request Messages in Developing Ensemble Productions
    Each of these methods returns a status (specifically, an instance of %Status).
  5. Optionally check the status of the previous action and act upon it.
  6. Optionally examine the response message that your business service has received and act upon it.
  7. Make sure that you set the output argument (pOutput). This step is required.
  8. Return an appropriate status. This step is required.
The following shows a simple example:
Method OnProcessInput(pInput As %GlobalCharacterStream, Output pOutput As %RegisteredObject) As %Status
    //get contents of inbound stream
    //in this case, the stream contains a single value: a patient ID
    Set id=pInput.Read(,.tSC)

    //make sure Read went OK
    If $$$ISERR(tSC) do $System.Status.DisplayError(tSC)

    //create request object to send
   Set tRequest=##class(EHTTP.Request.Patient).%New()
    Set tRequest.patientID=id

   //send to lookup process
   Set tSC=..SendRequestSync("EHTTP.LookupProcess",tRequest,.tResponse)

    //define output for OnProcessInput
    Set pOutput=tResponse

    Quit tSC
Implementing the OnErrorStream() Method
If the ProcessInput() or OnProcessInput() method of your business service returns an error, Ensemble invokes the OnErrorStream() method of the business service. You can implement this method to contain any desired error handling. The method should accept a status code as input and should return the desired output stream.
Using the HTTP Request
Within OnProcessInput(), the HTTP request is available as pInput, which is an instance of %GlobalCharacterStream or %GlobalBinaryStream, depending on your implementation. The following figure illustrates how this instance represents the HTTP request:
The body of the request is written to the pInput stream. For information on working with streams, see the Caché documentation, for example, the chapter Defining and Using Stream Properties in Using Caché Objects.
Additional data is available in the Attributes property of the pInput stream, as discussed in the following subsection. This includes the HTTP headers. If the request was a GET request, it also includes any form variables (URL parameters).
If the request was a POST request, then the form variables are available in the body.
About the Attributes Array
The Attributes property of the pInput stream is a multidimensional array that carries the following data:
Node Contents
Attributes(http_header_name) Where http_header_name is the header name in lowercase, for example, "content-length" Value of the given HTTP header
Attributes("Params",form_variable_name,n) Value of the nth instance of the given URL form variable (if the HTTP request was a GET request).
Attributes("URL") Complete URL of the HTTP request
So you can retrieve a header value as follows:
 set contentlength = pInput.Attributes("content-length") 
Or, to retrieve a URL form variable (for a GET request):
 set pResponse.MessageRequestTimeStamp = pInput.Attributes("Params","REQUESTTIMESTAMP",1)
Adding and Configuring the Business Service
To add your business service to an Ensemble production, use the Management Portal to do the following:
  1. Add an instance of your custom business service class to the Ensemble production.
  2. Configure the adapter so that it can receive input. Specifically:
  3. Enable the business service.
  4. Run the production.
Specifying the Sources of HTTP Requests
You can configure the inbound HTTP adapter to recognize sources of HTTP requests in two different ways:
Specifying the Character Set to Use
When the EnsLib.HTTP.InboundAdapter receives input, it translates the characters in that input according to a translation table. To determine which translation table to use, the adapter first determines which character set the input uses.
In general, the HTTP Content-Type header of the input indicates which character set that request uses. By default, the adapter uses that character set.
However, you can control which character set the adapter uses, by using the following runtime settings:
See Reference for Settings.”
For background information on character translation in Caché, see Localization Support in the Caché Programming Orientation Guide.