Copyright © TIBCO Software Inc. All Rights Reserved
Copyright © TIBCO Software Inc. All Rights Reserved


Chapter 6 HTTP and SOAP Channels : Working with HTTP Requests

Working with HTTP Requests
HTTP requests are parsed and executed using either of the following approaches:
Event based approach HTTP request is mapped to an event using deserializer.
Action Rule Function based approach HTTP request parameters and data are retrieved using HTTP catalog functions and processed using rule function.
The Is Page Flow parameter of the destination identifies the approach followed by destination for processing HTTP requests. If the Is Page Flow parameter is set to true the HTTP request is processed using the Action Rule Function based approach otherwise Event based approach is used. This section explains the two different approaches for working with HTTP requests, and how to add an HTTP channel and destination.
Event Based Approach
The following paragraphs explain how an HTTP request is mapped to an event. 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, with the REST serializer
RESTMessageSerializer, which is set while configuring the channel, maps HTTP requests to TIBCO BusinessEvents. HTTP headers and HTTP parameters in the GET method are mapped to similarly named event properties. When both parameters and headers are specified, parameters take precedence.
Each HTTP Header consists of a name and field value, which are mapped into an event property name and value.
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.
The transfer encoding (charset) in the Content-Type header indicates what type of transformation is applied to the POST data (message body) to safely transfer content between sender and recipient. If the Content-Type header is missing, UTF-8 is used as the default transfer encoding.
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.
Sending Non-ASCII Content to Event Properties
The HTTP 1.1 specification states that only ASCII characters can be sent in HTTP headers.
To send non-ASCII event properties in GET methods, use HTTP parameters. HTTP parameters are passed as the QueryString of the request URI, that is, the part of the URI that contains data to be passed to web applications.
To decode the QueryString, use either the URI Encoding or the body encoding. The body encoding is specified in the contentType HTTP header. Select either the URI Encoding or Use Body Encoding for URI setting in the HTTP channel Advanced tab.
Mapping of HTTP Request URI to Destination
An HTTP request URI must map to a valid TIBCO BusinessEvents destination. If not, an error is returned, and the message is discarded.
In the event based approach, 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 TIBCO 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. TIBCO BusinessEvents engine maps the request with a destination having URI /Transport/Channel/StudentDestination if it exists.
Action Rule Function Based Approach
The following paragraphs explain how a HTTP request is processed in TIBCO BusinessEvents Studio without mapping to an event.
HTTP Request Processing
The TIBCO BusinessEvents server parses the HTTP request received from client. The server extracts the request header and identifies the request URI of the request. The request URI should map to the context specified in the destination defined for the channel. In this case TIBCO BusinessEvents server looks for the destination having the same context path as the requestURI.
For example, the requestURI for the request https://localhost:7000/Transport/Channel/StudentDestination is /Transport/Channel/StudentDestination. TIBCO BusinessEvents engine maps the request with a destination having context path /Transport/Channel/StudentDestination if it exists.
Action rule function defined in the destination uses catalog functions to get required data and parameters from the HTTP request. The rule function processes these parameters and creates a response, similar to a preprocessor. TIBCO BusinessEvents supports all HTTP methods stated in the HTTP 1.1 specification for Action Rule Function based approach.
Sample Code for Action Rule Function
 

 
void rulefunction RuleFunctions.Callback {
   attribute {
      validity = ACTION;
   }
   scope {
      Object asyncContextObject;
   }
   body {
      //getting servlet request and response objects
      Object servletRequest = HTTP.Servlet.getServletRequest(asyncContextObject);
      Object servletResponse = HTTP.Servlet.getServletResponse(asyncContextObject);
      System.debugOut("##Servlet request method : " + HTTP.Servlet.Request.getMethod(servletRequest));
      System.debugOut("##Servlet request content : " + HTTP.Servlet.Request.getRequestContent(servletRequest));
      System.debugOut("##Servlet request Requester Address : " + HTTP.Servlet.Request.getRequestorAddress(servletRequest));
      System.debugOut("##Servlet request Request URI : " + HTTP.Servlet.Request.getRequestURI(servletRequest));
      //getting parameters
      String[] params = HTTP.Servlet.Request.getRequestParameters(servletRequest);
      for(int i=0;i<params@length;i++)
      {
         System.debugOut("## Servlet request Parameters :" + HTTP.Servlet.Request.getRequestParameter(servletRequest,params[i]));
      }
      //getting headers
      System.debugOut("## Servlet request Header Accept : " + HTTP.Servlet.Request.getRequestHeader(servletRequest,"Accept"));
      System.debugOut("## Servlet request Header Accept-Encoding : " + HTTP.Servlet.Request.getRequestHeader(servletRequest,"Accept-Encoding"));
      System.debugOut("## Servlet request Header Accept-Language : " + HTTP.Servlet.Request.getRequestHeader(servletRequest,"Accept-Language"));
      System.debugOut("## Servlet request Header Accept-Charset : " + HTTP.Servlet.Request.getRequestHeader(servletRequest,"Accept-Charset"));
      System.debugOut("## Servlet request Header Connection : " + HTTP.Servlet.Request.getRequestHeader(servletRequest,"Connection"));
      System.debugOut("## Servlet request Header User-Agent: " + HTTP.Servlet.Request.getRequestHeader(servletRequest,"User-Agent"));
      System.debugOut("## Servlet request Header Content-Length : " + HTTP.Servlet.Request.getRequestHeader(servletRequest,"Content-Length"));
      System.debugOut("## Servlet request Header Content-Type : " + HTTP.Servlet.Request.getRequestHeader(servletRequest,"Content-Type"));
      System.debugOut("## Servlet request Header Host : " + HTTP.Servlet.Request.getRequestHeader(servletRequest,"Host"));
      HTTP.Servlet.Response.setResponseHeader(servletResponse, "Content-type", "text/plain");
      HTTP.Servlet.Response.setResponseContent(asyncContextObject, "response", true);
   }
}

 
Deploying Multiple Web Applications
You can deploy multiple web applications on single channel. Specify the *.WAR file or a valid J2EE web application folder under the Web Applications section in the advanced tab.Specify the context URI and resource path for the web application. Resource path identifies the actual path of web application resources. In case of a *.WAR file resource path is the location of the war file, and in case of the J2EE web application folder the resource path is the location of the base folder of the web application.
Configuring TIBCO BusinessEvents to Receive and Send HTTP Requests
To configure TIBCO 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 TIBCO 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).
Task B For SSL Only — Add an Identity Resource
TIBCO 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 an HTTP Channel
Add a channel to your project and configure it as follows:
1.
2.
3.
4.
Click Advanced, and configure run-time configuration properties. These properties provide information such as the location of the document root folder. Some properties are for SSL configuration of HTTP Component servers. See HTTP Channel Advanced Configuration Settings.
Task D Add a Destination
Add a destination to the channel in the usual way. (See Adding Channels and Destinations for details.) The fields for destination differs based on different approaches.
To follow the action rule function based approach Check the Is Page Flow checkbox and specify the appropriate Context Path and Action Rule function for the destination. Specify the context path in the same format as the server would receive the requestURI in the HTTP request.
To follow the event based approach 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.
See Mapping of HTTP Request URI to Destination.
Task E Create Events as Needed and Set Default Destinations
Skip this step for action rule function based approach.
In the event based approach For receiving HTTP requests and sending responses, configure events in the usual way, and select an HTTP-based destination as the default destination.
Task F Configure Rules and Rule Functions
Configure rules and rule functions according to your needs and HTTP request processing approach.
In the action rule function based approach For example, in response to a POST request you might do the following:
In the event based approach 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 In the CDD, Configure the Processing Unit
In the Cluster Deployment Descriptor (CDD) Configure the processing unit for deployment as needed (see Configuring Processing Units (All OM Types) for details). Note the following requirement.
 

Copyright © TIBCO Software Inc. All Rights Reserved
Copyright © TIBCO Software Inc. All Rights Reserved