The HTTPReceive component acts as an interface between an HTTP client and an Event Process and receives HTTP requests using the Hyper Text Transfer Protocol (HTTP). The request is then converted into an XML Message by the HTTPReceive component and is sent to the Event Process which in turn processes it and sends the result to the HTTPReceive component. The HTTPReceive component processes the input in either of the following ways.
The Event Process processes the input and sends the output to the HTTPReceive component. In this case, the input port of the HTTPReceive component receives the output, converts it into HTTP response and sends it back to the HTTP client through HTTP protocol.
The Event Process sends a response error message to the HTTPReceive component. In this case, the error event port of the HTTPReceive component receives the response error through its input event port, converts it into a HTTP response error and then sends it to the HTTP client using HTTP.
The Event Process need not return response. In this case, the HTTPReceive
component is preconfigured to the
one-way-send mode wherein the HTTPReceive component does not expect and
wait for any response. By default, HTTP(S) default response or OK would
be returned to the HTTP client for each HTTP request.
Note: The Stream Read Buffer size field should be set only by advanced users as the optimum value depends on specific scenarios in which the component is used.
The configuration of HTTPReceive is defined as shown in Figure 1.
Figure 1: Configuration of HTTPReceive
The host name or the IP address of the system on which the web server is present.
The port on which the Web Server is running.
The maximum time in milliseconds for which the component has to wait for processing the request.
For more details, refer http://jetty.codehaus.org/jetty/jetty-6/apidocs/org/mortbay/jetty/AbstractConnector.html#setMaxIdleTime(int)
A Context will encapsulate details of a single HTTP service. Multiple contexts can be configured as shown in Figure 2.
Figure 2: Configuration of Multiple Contexts
A Context can be added by clicking on the Add button. For each context added, ports will be added to the component based on the value given in the editable table as explained below.
Context Specific path: The unique context path of the HTTP request corresponding to a context. The path of the context will be computed relative to the server details provided by properties Host Name and Port.
The URI of a context will be http://<Host Name>:<Port>/<Context Spec Path>.
Display Name: The unique display name for the context. The names of the ports that are generated corresponding to a context are suffixed by __<Display Name>.
Connection Mode:
The connection mode defines the way the client interacts with the server. The client sends the request to the server. The HTTPReceive adapter parses the request and sends it to the Event Process through output port HTTPRequest__<Display Name> which will be sent to the Event Process. The behavior of the component after this will be dependant on the connection mode chosen.
Request/Response
In this mode, the HTTPReceive adapter waits for reply from the Event Process after sending the request. Two input ports with names HTTPResponse__<Display Name> and ERROR__<Display name> will be created for receiving response and error messages respectively. Then the component handles the response based on the response generation details provided for the context.
One Way Send
In this mode, the HTTPReceive adapter will send a default response, HTTP(S) default response/OK back to the HTTP client after sending the request message to the Event Process. No input ports will be created in this case for this context.
When a context is selected the details of handling the request and response can be configured using the tabs Request Parsing Details and Response Generation Details.
Request Parsing Details:
The HTTP Request stream received by the component when a client sends request will be parsed based on the details provided in this tab. The UI has three tabs at the bottom which define various types of request parsing details as shown in Figure 3.
Figure 3: Configuration of Request Parsing Details
When a HTTP request is received by the component, it is transformed into a JMS message and sent to the Event Process through the output port of the component based on the details configured using this property. Schema of the output port HTTPRequest_<Context Display Name> will change based on the details provided for this property.
Parameters
Parameters define the characteristics of the HTTP request data stream being parsed for converting the request to message. Parameters can be added by clicking Add button in the Parameters tab in request parsing details tab. Added parameters can be removed by clicking on the Remove button. For each parameter added a new element will be added as child of Params element in the schema of the corresponding output port based on the following details.
Name
The name of the parameter that is passed in the request. The name for corresponding element in the output schema will be set to this value.
Cardinality
If a parameter is definitely necessary for the processing of a request then it must be marked required, otherwise, optional must be chosen. The cardinality of the corresponding element in the output schema will be the same.
Type
The data type of he parameter can be specified as one of String, Boolean, Decimal or Integer. The XSD type of corresponding element in the output schema will be same.
Include All/Others
If this option is selected, parameters from the request that are not defined as parsing parameters will also be added in output message. These will be added under the Params element in the output schema.
Treat empty string as null
If this option is selected, and the content of this parameter in HTTP Request stream is empty, the parameter will be considered as null otherwise it will be considered as an empty string.
Post Data
If data is relatively large and is to be posted from the request, the way it has to be parsed must be specified by selecting the Post Data tab in the request parsing details tab.
The data to be posted by the client can be one of the following types.
-----------
This option must be specified when data is not posted as part of the request. If chosen, post data, if passed as part of the HTTP request will not be present in the request message. In this case parameters or headers must be compulsorily included.
XML Text [Provide an XSD for the XML text]
This must be chosen if the data posted is XML that conforms to a schema. The schema can be provided using the XSD editor as shown in Figure 4. If parameters or headers are specified then an element XMLData will appear in the schema of output port whose type is same as that of the provided schema. Otherwise, this schema will be set as output port schema.
Figure 4: Configuration of Post Data in Request Parsing Details
Simple Text
If data from the request stream is text not conforming to any schema. This option can be selected if the data need not be transformed using Fiorano Mapper and needs to be transferred as is. If parameters or headers are specified, an element Data of string type will appear in the schema of output port and the text will be inserted as CDATA. Otherwise, it will be set as message text.
Bytes
Data from the request stream will be filled as bytes in the JMS Message. Use this option in case you need to send media files as binary data via HTTP.
Headers
A Header is a part of a data stream which specifies information about the data stream. This option is used to specify the type of information being sent across the data stream. Headers can be added by clicking Add button in the Headers tab in request parsing details tab. Added Headers can be removed by clicking on the Remove button. For each Header added a new element will be added as child of Headers element with attributes name, cardinality and type similar to Parameters.
Fill Defaults
This button can be used to include the default headers as shown in the Table1.
|
Scheme |
Optional |
String |
|
Version |
Optional |
String |
|
IsCommitted |
Optional |
String |
|
Host |
Optional |
String |
|
Port |
Optional |
String |
|
EncodedPath |
Optional |
String |
|
Method |
Optional |
String |
|
Connection |
Optional |
String |
|
Pragma |
Optional |
String |
|
Content-Length |
Optional |
String |
|
Content-Type |
Optional |
String |
|
Cookie |
Optional |
String |
Table 1: Default headers and their data types
Include All/Others
If this option is selected all headers from the request stream are included in the message from the output port. The headers will be added under Headers element.
Response Generation details:
If the context connection mode is chosen as Request/Reply, the component sends the request message and waits for response from the Event Process. The response message that is received on input port HTTPResponse__<Context Display Name> is converted to HTTP Response stream suitable for the invoking client based on the details provided here.
The selection can be made in the Response Generation Details tab and selecting the Response Data tab at the bottom, as shown in the Figure 5.
Figure 5: Response Generation Details – Response Data
Response Data
-------
When this option is used, no information is put on the response stream.
Simple Text
Text portion of the JMS Message will be read and put in the response stream. This option can be chosen when the invoking client does not expect a response that conforms to a specific schema. No schema is set on the input port RESPONSE.
XML Text [Provide an XSD for the XML Text]
If the client expects the response to be compliant to a particular schema, then the schema must be provided using the schema editor. The schema will be set as schema of the input port RESPONSE.
Bytes
If the client expects the response to be compliant to a particular schema, then the schema must be provided using the schema editor. The schema will be set as schema of the input port RESPONSE.
Headers
This option is used to specify the type of information being sent across the response stream. Headers can be added by clicking Add button in the Headers tab in Request Parsing Details tab. Added Headers can be removed by clicking on the Remove button. For each header added, a new element will be added as child of Headers element in the schema of the input port with attributes name, cardinality and type similar to Parameters in Request Parsing Details.
Fill Defaults
This is used to include all default headers in the response message. Please refer to Table 1 for default headers.
Handle All
If this option is selected all headers that are present in the response received from the Event Process will be added as headers in the response stream.
Advanced Properties:
The advanced properties for a context can be configured by clicking on the Advanced Properties button in Context Details panel. These properties depend on the connection mode between the adapter and the client.
If the Connection Mode of the adapter is Request/Response, then clicking this button pops up the following details as shown in Figure 6.
Figure 6: Advanced Properties - Request/Response
Request TimeOut (msec)
It is the length of time in milliseconds which the HTTP Receive adapter will wait for the response message.
Number of Retries
It is the number of times adapter will retry in case there is no response.
Stream Read Buffer Size (Bytes)
It is the size of the buffer that will be used to read a HTTP request stream.
Validate Stream
Validates the request and response stream based on the schema generated. It has the following options:
- Both Request and Response Stream: validates both the request and response streams.
- Only Request Stream: Validates only request stream
- Only Response Stream: Validates only response stream
- None: No validation is done for request and response streams
o Resource Base
Location of the resource that contains the static content like images, css and so on. This can be any valid path in the file system (may also be relative to %FIORANO_HOME%\runtimedata\PeerServers\<profile-name>\FPS\run\components\HttpReceive\4.0) or a web URL. The resources present in resource base will then be hosted in URLs of the form http://<hostname>:<port>/<contextpath>/<resource>
o Cache Control
The cache control mechanism that is to be used to cache the static content. For example, cache control value "max-age=3600,public" states that static content would be cached for up to an hour and shared between all users, without checking the server.
For valid Cache-Control values, please refer to section 14.9 in the following link http://www.w3.org/Protocols/rfc2616/rfc2616-sec14.htmlo Request TargetNameSpace
The target name space for the schema generated for the output port HTTPRequest_<Context Display Name>.
o Response TargetNameSpace
The target name space for the schema generated for the input port HTTPResponse_<Context Display Name>.
If the Connection Mode is One Way Send, the following properties as shown in Figure 7 can be configured.
Figure 7: Advanced Properties - One Way Send
For description of these properties, refer to the section of Advanced properties for Request/Response connection mode.
Error Actions Map:
The suitable actions that have to be taken for possible errors that
might happen while the component is running can be specified using the
Error Actions Map editor, by clicking
on the ellipsis button 
against this property.
Figure 8: Configuration of Error Actions Map
The various options for handling errors that might occur while sending or receiving data streams can be configured. The various instances when an error might occur are as follows:
While parsing HTTP Request
These errors may occur while parsing the HTTP request.
o [1001] - I/O Exception: This error may occur while reading the HTTP Request Stream
o [1002] - Invalid Request: This error may occur when HTTP Request does not match with the configured Format.
While processing Request over Bus
These errors may occur while processing the request over the bus.
o [2001] - Request Timed Out: This error may occur when the request is timed out.
o [2002] - No Response: This error may occur when there is no response.
o [2003] - Connection Lost: This error may occur when the Connection to Peer Server is lost while sending Request Document over the Bus.
o [2004] - Error Response: This error may occur when the Response received from the Bus contains one or more errors.
o [2005] - Invalid Response: This error may occur when the Response does not match with the configured Format.
While Generating HTTP Response
These errors may occur when the HTTPReceive adapter is generating the HTTP Response.
o [3001] - Illegal State: This error may occur while setting HTTP Response Headers.
o [3002] - I/O exception: This error may occur while sending data over the HTTP Response Stream.
Various remedial actions can be specified for each of the above mentioned errors to handle the errors effectively. The remedial actions that are displayed in the Error Handling panel are as follows:
Log using service log settings
The error is logged using the settings for the business service. These settings can be changed by using the properties view of the component.
Raise User Event
The error is logged as a user event.
Send Error on error port
The error is sent to the error port of the component.
Send Error to HTTP client
The error is sent to the HTTP client invoking the service.
Timed out Message:
This is an expert property which will be displayed by clicking the button
show expert properties 
in the CPS. The message that has to be sent to the client
invoking a context when the request sent gets timed out.
Maximum No of Threads:
A thread pool ensures threads are used efficiently within the container. A number of threads are created at initialization and placed in the pool. When there is work to be done, for example, to service a request, a free thread from the pool is allocated and then returned to the pool when the work has been completed.
If the maximum pool size is reached, jobs wait for a free thread.
Minimum No of Threads:
The minimum number of threads that have to be present in the thread pool. Idle threads in the pool will timeout and terminate until the minimum number of threads are running.
The input schema is auto generated based on the configuration of Response Generation Details provided for the context as described under Response Generation Details.
When Handle Response Stream in Response Data is set to option ------ or Bytes, and no headers are configured, then no schema is set on the input port RESPONSE .
If headers are configured as shown in Figure 9, input schema generated is shown in Figure 10 and sample input XML is shown in Figure 11.
Figure 9: Sample Configuration of Response Generation Details – Headers
Figure 10: Sample Input Schema when headers are configured
Figure 11: Sample Input XML for schema shown in Figure 10
Figure 12: Input port Schema when Response data is XML
When Handle Response Stream in Response Data is set to XML, and headers are configured as shown in Figure 9, input schema generated is shown in Figure 12 and sample input XML in Figure 13.
Figure 13 : Sample Input XML for schema shown in Figure 12
The schema provided in Response data is set under XMLData element in input port schema. If headers are not configured, then this schema is directly set on the input port.
When Handle Response Stream in Response Data is set to Simple Text, and headers are configured as shown in Figure 9, input schema generated is shown in Figure 14 and sample input XML in Figure 15.
Figure 14: Input port Schema when Response data is Simple Text
Figure 15: Sample Input XML for schema shown in Figure 14
The output schema is auto generated based on the configuration of request parsing details provided. If parameters are also provided, then the schema is a concatenation of the parameters and the schema provided.
When Post Data in Request Parsing details is set to a option ------ or Bytes.
Configure headers shown in Figure 9 in Request details and parameters as shown in Figure 16.
Figure 16: Sample Configuration of Request details – Parameters
For the above configuration, schema set on output port RESPONSE is shown in Figure 17 and sample XML in Figure 18.
Figure 17: Output Schema with parameters and headers.
Figure 18: Output XML for schema shown in Figure 17
When Post Data is set to Bytes and if no headers and parameters are configured then no schema is set on the output port. When Post Data is set to -----, configuration of parameters is mandatory, at least one parameter should be configured.
When Post Data in Request Parsing details is set to a option either XML, output schema is defined as shown in Figure 19 and sample XML shown in Figure 20.
Figure 19: Output schema when Post Data set to 'XML'
Figure 20: Output XML for schema shown in Figure 19
Schema which is provided in Post Data is set under XMLData of output schema. If no headers and parameters are provided, the schema provided is directly set on the output port.
When Post Data in Request Parsing details is set to a option Simple Text, parameters defined as shown in Figure 16 and headers configured as shown in Figure 9, then output schema is defined as shown in Figure 21 and sample XML shown in Figure 22.
Figure 21: Output schema when Post Data set to 'Simple Text'
Figure 22: Output XML when Post Data set to Simple Text.
When Post Data is set to Simple Text and if no headers and parameters are configured, then no schema is set on the output port.
Receiving a HTTP request and returning the parsed request as response.
Configure the HTTP Receive adapter as described in Configuration section. Add two parameters REQUEST and CREDENTIALS in Request Parsing Details.
Connect a Display component to its output port and also the output port of Display to the response port of HTTP Receive as shown in Figure 23.
Figure 23: Sample Event Process demonstrating Scenario 1
Open %FIORANO_HOME%\esb\samples\EventProcesses\PurchasingSystem\resources\PurchasingSystem_Input.html in web browser. The web page looks like Figure 24. Click the Submit button to send the HTTP request. Check the port number by editing the html page, it should be same as provided in the component CPS.
Figure 24: Sample HTTP Request
Now, HTTPReceive picks the parameters REQUEST and CREDENTIALS as configured in the Context details and sends the same XML back to the web page. Figure 25 shows the response sent by HTTP Receive.
Figure 25: Response sent by HTTPReceive adapter
In the Purchasing System sample Event Process, the purchase details submitted from the web page are received using the HTTP Receive component.
Figure 26: Sample use case scenario
The error ports of the components that receive the HTTP request through HTTP Receive could be connected to the Error port of HTTP Receive to report errors.