HTTP and SOAP Channels : Working with HTTP Requests

Working with HTTP Requests
This section explains how an HTTP request is mapped to an event, and how to add an HTTP channel and destination. It assumes basic familiarity with HTTP and with the procedure of setting up a channel. See Adding Channels and Destinations if you need basic instructions.
Mapping of HTTP Requests to Events
RESTMessageSerializer, which is set while configuring the channel, maps HTTP requests to BusinessEvents. HTTP headers and HTTP parameters get mapped to similarly named event properties. When both parameters and POST data are specified, then parameters take precedence.
The POST data in the request must match with the payload as defined in the corresponding event. If there is no payload defined for the event, the POST data is translated into a ByteArray payload, and is not accessible via the mapper. In other words, only XML payloads are visible via the mapper.
When you want the REST Serializer to deserialize a GET request into an event with a payload, include the _payload_ request parameter. The string value of the _payload_ parameter will always be used as payload in the event.
For HTTP responses, all event properties are translated to similarly named HTTP headers and the payload is sent as HTTP content.
Mapping of HTTP Request URI to Destination
An HTTP request URI must map to a valid BusinessEvents destination. If not, an error is returned, and the message is discarded. Once the destination is established, the HTTP message is converted either into an event based upon _ns_/_nm_, or into the default event associated with this destination.
In this case BusinessEvents server looks for the destination having the same URI as the requestURI.
For example, the requestURI for the request https://localhost:7000/Transport/Channel/StudentDestination is /Transport/Channel/StudentDestination. BusinessEvents engine maps the request with a destination having URI /Transport/Channel/StudentDestination if it exists.
Configuring BusinessEvents to Receive and Send HTTP Requests
To configure BusinessEvents to receive and send HTTP requests, you need to perform the following tasks:
Task A Add an HTTP Connection
Add an HTTP Connection resource to your project. In the Host and Port fields, specify the host and port to which HTTP clients send requests.
In the Host field, enter the name or IP address of the machine running BusinessEvents. This is the HTTP server.
In the Port field, enter any available port on the host machine. This is the port on which the server listens for HTTP requests.
To configure an HTTPS (Secure) Connection  Check the SSL checkbox, click the Configure SSL button, and complete the pop-up dialog settings. The server must authenticate to the client. In the Identity field, provide the location of the Server Identity File. (See Task B).
In one-way SSL, the server authenticates itself to the client using a Server Identity File, but the client does not have to authenticate to the server.
In two-way SSL, the server authenticates itself to the client using a Server Identity File and the client also authenticates to the server using the Client Identity file. Enable the Requires Client Authentication checkbox. This disables the Trusted Certificates Folder, and you need to provide the Client certificates.
Task B For SSL Only—Add an Identity Resource
BusinessEvents supports use of an identity file for SSL. Before you configure the secure HTTP connection, add an Identity resource to your project and configure it.
In the URL field, specify the project path of the keystore file, which must be within the project folders.
In the File Type field, specify the keystore file type, and in the Password field, provide the password for the keystore file.
Task C Add a Channel
Add a channel to your project and configure it as follows:
1.
2.
In the serverType field select BUILT-IN or TOMCAT, as appropriate.
3.
In the Method of Configuration field, select Resource. (This is enabled by default and is the only choice for HTTP channel.)
4.
Task D Add a Destination
Add a destination to the channel in the usual way. (See Adding Channels and Destinations for details.) In the Serializer field select the appropriate serializer:
com.tibco.cep.driver.http.serializer.RESTMessageSerializer
Specify the default event in the usual way as needed by your project requirements.
HTTP clients of the BusinessEvents server would use the complete destination URI, after the host and port for example, http://www.acme.com:5560/Transport/Channel/MyDestination.
See Mapping of HTTP Request URI to Destination.
Task E Create Ontology
For receiving HTTP requests and sending responses, configure events in the usual way, and by choosing an HTTP-based destination.
Task F Configure Rules and Rule Functions
Configure rules and rule functions according to your needs.
For example, in response to a POST request you might do the following:
Create a response event and use Event.replyEvent() to send back an empty response using the request event’s default destination.
As another example, in response to a GET request you might do the following:
Return the data using Event.replyEvent.
Task G Configure the Processing Unit
Configure the processing unit for deployment as needed, but note the following requirement.
Workers Setting  Only Callers thread option is supported for TOMCAT based channels. This is because when a client application sends a request, TOMCAT spawns a thread to handle it. If the response is not returned on the same caller thread, then this thread returns with an empty response.
Task H Set HTTP Channel Configuration Properties
You set the run-time configuration properties in the Processing Units tab of the CDD editor. See Configuring the Processing Units Tab (All OM Types) in TIBCO BusinessEvents Administration for configuration details. These properties provide information such as the location of the document root folder, as explained in HTTP Channel Configuration Properties.
Some properties are for SSL configuration of HTTP Component servers.