About the Ensemble HTTP Adapters
The HTTP adapters (EnsLib.HTTP.InboundAdapter and EnsLib.HTTP.OutboundAdapter) enable your production to send and receive HTTP requests and responses. This chapter provides a brief introduction to these adapters.
Ensemble also provides specialized business service classes that use these adapters, and one of those might be suitable for your needs. If so, no programming would be needed. See “Connectivity Options” in Introducing Ensemble.
HTTP Inbound Adapter and Helper Classes
The 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).
The class provides runtime settings that you use to specify items like the following:
A local port, where the adapter will listen for input
A list of IP addresses from which the adapter will accept input (if you want to restrict the possible sources)
Settings that specify whether to use the character set given in the inbound request, and if not, what other character set to use
The inbound HTTP adapter listens on the specified port, reads the input, and sends the input as a stream (either binary or character, depending on the character set in use) to the associated business service. The business service, which you create and configure, uses this stream and communicates with the rest of the production.
When you work with the HTTP inbound adapter, there are two helper classes that you might use: %Library.GlobalCharacterStream and %Library.GlobalBinaryStream. The inbound adapter sends a stream to the associated business service. Specifically, this is an instance of %Library.GlobalCharacterStream or %Library.GlobalBinaryStream, depending on the character set being used. In general, these classes provide methods that you can use to read the contents of the stream, get the length of the stream, read a single line, rewind, append data, and so on. Both of these basic classes are documented in the Caché documentation; for example, see the chapter “Working with Streams” in Using Caché Objects.
HTTP Outbound Adapter and Helper Classes
EnsLib.HTTP.OutboundAdapter is the Ensemble adapter for sending HTTP requests outside Ensemble and receiving HTTP responses. This adapter provides settings to control items such as the following:
Server and port to which the adapter will send HTTP requests
URL path for the resource to request, at the given server and port
An optional SSL configuration to use for the connection to the server
Optional information to specify a proxy server through which the adapter can route requests
The adapter provides methods for sending HTTP POST, GET, and PUT actions:
The main methods are PostFormData() and GetFormData(). Each accepts an output argument for the response object, a comma-separated list of form variable names, and a variable number of form variable arguments, one for each of the names in the comma-separated list. If you want to set multiple values for a form variable, you can use the same name multiple times in the list. Of course, you can also use these methods with no form variables to request flat scalar content such as a regular web page.
For situations with a complicated set of form variables, use the methods PostFormDataArray() and GetFormDataArray(). These methods accept a multidimensional array instead of a variable argument list. This can help keep things organized, because you can provide multiple values for a given form variable as subnodes in the array, rather than as multiple entries in the list of names. You can also index the array by form variable name rather than by position.
The low-level worker method SendFormDataArray() is available for situations when you need to use a PUT or some other unusual HTTP request, or where you need to customize aspects of your HTTP request other than form variables or cookies.
The adapter also provides properties and methods to manage cookies.
When you work with the HTTP outbound adapter, there are two helper classes that you can use:
The HTTP outbound adapter uses %Net.HttpRequest to encapsulate the HTTP request that it sends.
However, if you use SendFormDataArray(), you can create an instance of the %Net.HttpRequest class, set its properties, and use it to initialize the HTTP request that you send in that method. You use this technique when you need to set properties of the HTTP request (such as the proxy authentication) that cannot be set via the adapter.
In all cases, the HTTP response is encapsulated in an instance of %Net.HttpResponse. The %Net.HttpResponse class provides methods to access the HTTP headers, as well as properties that contain the body of the response (a stream object), reason codes, the HTTP version of the server, and so on.