view enabled.
The HTTPAdapter component enables the user to get content from an external HTTP Server (Web Server).
The Hyper Text Transfer Protocol (HTTP) is one of the most widely used protocols on the Internet today. Various Event Processes are being hosted on the World Wide Web, due to which Event Process developers face the challenge of integrating their existing solutions to work with HTTP. The Fiorano HTTPAdapter component helps Event Process developers to achieve this task with minimum knowledge of this protocol.
The Fiorano HTTPAdapter component enables Event Processes to use either the Get or the Post method. This component can function in conjunction with other Fiorano components to solve business problems in a highly productive manner.
Consider a stock portfolio management company that employs several consultants who advise clients on investing their money. The Shares and Scripts section consists of three clerks who track the stock quotes in three different verticals: IT, Automobiles, and Pharmaceuticals. The task of sending requests for stock quotes can be accomplished by running multiple instances of the Get implementation. Each instance constantly provides information for a different stock quote. The results can then be sent to other components for further processing.
Consider an enterprise implementing an Enterprise Resource Planning (ERP) system to automate its inventory management system across its suppliers and customers. The suppliers are generally not in the vicinity of the manufacturing facility and hence it is not possible to have a dedicated link between the two parties. In this case, the supplier can provide web access to the enterprise through a secure interface and the Post method can be used to post purchase order information at the supplier server.
Points to note
The component never tries to guess the content type like most browsers.
If the HTTP Server is secured using Basic or Digest authentication and required details are not provided in the component CPS, a runtime UI is displayed to capture the same.
If the response has an application/xml content type, then in the Http Response configuration, the Response Body has to be set as "Headers". The XML can be extracted from the binary data using XSLT component.
Connection details are configured in the Managed Connection
Factory (MCF) panel. Figure 1 illustrates the
panel with expert properties view enabled.
Figure 1: Connection configuration details in MCF panel
Parameters to create the connection can be specified in the input message when this property is set to true. If this property is selected the validation errors in the managed connection factory panel of the CPS are treated as warnings. So user can bypass this step without giving valid configuration and complete the configuration of the component. If valid properties are not provided even in the input message exception will be thrown at runtime.
The host name or the IP address where the Web Server is located. The URI relative to this host name/IP has to be configured in the request details editor in Interaction Configurations. It can also be sent in the URI element of the input message.
The port number on which Web Server is running.
Specifies the time for which this component will wait for an HTTP request to be acknowledged. The default value is 0, specifies infinite timeout.
Determines the action to be taken if the requested page sends the request to another page.
yes
This is used to allow automatic redirection of request page if required.
no
Do no allow automatic redirection of request page.
yes
HTTP1.0 protocol is used while sending requests to the web server.
no
HTTP1.1 protocol is used while sending requests to the web server.
This property enables the user to specify authentication information, if any.
None
This is the default selection. This is used when the requested resource does not require any authentication.
Basic
A method designed to allow client program to provide credentials in the form of user name and password while making a request. These credentials are passed in plain text format using Base64 encoding.
Digest
In this method, request is encrypted using MD5 cryptographic hashing and sent to web server.
When Authentication Mode is either Basic or Digest, following credentials have to be specified.
Username
The name of the user with privileges to access the protected resource.
Password
The password for the user name specified above.
The semi-colon separated list of hostnames/IP addresses for which the request must be sent without passing the proxy specified, if any. If no proxy is defined, this property is ignored.
The business logic configuration details are configured in the Interaction
Configurations panel. Figure 2 illustrates the panel with expert
properties view enabled.
Figure 2: Business logic configuration in Interaction Configurations panel
This property defines properties of the request that is sent to Web Server.
Click the ellipsis button 
to launch an editor
for providing these configurations.
Figure 3: Launching editor for configuring Request properties
Method
The HTTP method that is used to send the request to the server. This is either set to GET or POST.
The usage of these methods are described in the sections The GET Implementation and The POST Implementation respectively.
The Request Properties depends on the HTTP method specified. Figure 3 shows the request properties when HTTP method is set to GET. Request properties when HTTP method is set to POST are shown in Figure 6.
URI
The Uniform Resource Identifier of the resource that is being requested by the component. This will be calculated relative to the host name/IP and port number provided in the Managed Connection Factory.
Cookie
The HTTP cookies provide the server with a mechanism to store and retrieve state information on the client application's system. This mechanism allows Web-based applications the ability to store information about selected items, user preferences, registration information, and other information that can be retrieved later.
The cookie can be specified in the form of name value pairs separated by semicolon. For example, name1=value1;name2=value2. The input schema will have an element Cookie corresponding to this property.
Note: Cookies set by the server will be discarded after servicing the client request If Connection pooling is disabled.
Pragma
The Pragma general-header field is used to include implementation- specific directives that might apply to any recipient along the request/response chain. For more information refer section 14.32 Pragma at http://www.w3.org/Protocols/rfc2616/rfc2616-sec14.html.
The input schema will have an element Pragma corresponding to this property.
Custom Headers
If there are any custom headers that have to be sent along with the request, then select the checkbox against this property and click the Headers button. Headers can be added using the editor as shown in the Figure 4.
Figure 4: Custom Headers configuration
If custom headers are enabled, then the Header element of the input schema will have a child element CustomHeaders and any custom headers specified in the table are added as child elements of this CustomHeaders element.
Parameter/PostData Details
If there are any parameters to be sent along with the request, then the select the checkbox against this property and click the Parameters button. Parameters can be added using the editor as shown in the Figure 5.
Figure 5: Parameters/PostData configuration
The schema of the component has an element entity which accepts parameters as name value pairs.
Apply URL Encoding on Parameters
If this property is selected, parameters are converted to the application/x-www-form-urlencoded MIME format (HTML form encoding) using the platform’s default encoding scheme.
When HTTP method is set as POST, request properties appear as shown in Figure 6.
Figure 6: Request properties when HTTP method is set POST
Refer to previous section for description of properties URI, Cookie, Pragma, Custom Headers, and Apply URL Encoding on Parameters. Additional properties are described below.
Content-Encoding
The Content-Encoding header field is used as a modifier to the media-type. When present, its value indicates what additional content coding have been applied to the body, and thus what decoding mechanisms must be applied in order to obtain the media-type referenced by the Content-Type header field.
Content-Encoding is primarily used to allow a document to be compressed without losing the identity of its underlying media type.
An element Content-Encoding will be added corresponding to this property in the input schema of the component.
Content-Length
The Content-Length header field indicates the size of the body of the posted content. An element Content-Length will be added corresponding to this property in the input schema of the component.
Content-Type
The Content-Type header field indicates the media type of the body sent to the recipient. Component supports the following values:
text/html
image/jpeg
model/vrml
video/quickline
application/java
text/css
text/javascript
multipart/form-data
An element Content-Type will be added corresponding to this property in the input schema of the component.
To upload files Content-Type has to be set to multipart/form-data. When the Content-Type is set to multipart/form-data, then the generated input schema doesn’t contain Content-Type element and the value specified in the CPS is used internally.
Parameters/PostData Details
When HTTP method is set to POST, then the post data type can be configured as shown in Figure 7.
Figure 7: PostData configuration when HTTP method is set to POST
Simple Text
This is used when data to be posted is simple text. The text to be posted can be specified by using the text area that opens by clicking the button Post Data. In this case, an element text is added as a child to entity element in the schema of the input port corresponding to the text that is being posted.
Binary Data
This is used when data to be posted is in binary format. The content can be specified by clicking on the Load from File button in the UI that opens up when the Post Data button is clicked. In this case, an element BinaryData is added as child to entity element in the schema of the input port corresponding to the data that is being posted.
XML Data
This is used when data to be posted is in the form of XML conforming to a specific schema. The content can be specified in the schema editor that opens up when the Post Data button is clicked. In this case, an element XMLData is added as child to entity element in the schema of the input port, whose type is same as the schema provided.
Parameters
This is used when parameters are being posted and these can be configured as shown in Figure 5. This is the default option when the Content-Type is set to multipart/form-data.
Files:
When HTTP method is set to POST and the Content-Type is set to multipart/form-data, then the files to be posted can be specified by clicking Files button. This button will be enabled when the Content-Type is set to multipart/form-data. The file parameters will be set as name-value pairs where the name is the parameter name and the value is the complete path of the file which has to be uploaded.
Figure 8: Files Button
Example: To upload a file on http://www.filefactory.com the following parameters has to be set
1. redirect to 1
2. enabled to 1
3. file to the path of the file which has to be uploaded
4. uploadStart to true
5. uploadOne to true
These parameters can be determined by looking at the HTML page source.
If the input type of the parameter is ‘file’ then it has to be provided under Files and all the other parameters have to be provided under Parameters.
In the above example, parameters ‘redirect’, ‘enabled’, ‘uploadStart’, ‘uploadOne’ should be provided under Parameters and the parameter ‘file’ should set under Files. These parameters can also be provided in the input message. If a parameter is specified in both the CPS and in the input, then the value provided in CPS will be overridden by the value provided in input.
The sample input is shown in Figure 23.
Refer to section Input and Output for details about the effects of these configurations on input and output structures.
HTTPResponseProperty
When a request is sent to HTTP Server, a HTTP response is obtained. Output message is created from this HTTP response based on the configuration details of this HTTPResponse property.
Click the ellipsis button to launch HTTPresponseProperty
dialog box as shown in Figure 9.
Figure 9: HTTPResponse Property configuration
Response Code
The HTTP response code that is sent from the server. If the corresponding checkbox is selected, this is included in the output message. If the response type property is chosen as XML, an element Response-Code is added to the schema of the output port. Other wise a message Header with name HTTP_Response-Code is set as message property on output message.
Response Message
The message corresponding to the response code returned. If corresponding checkbox is selected, it is included in the output message. If the response type property is chosen as XML, an element Response-Message is added to the schema of the output port. Other wise a message Header with name HTTP_Response-Message is set as message property on output message.
Headers form part of the HTTP response stream which carries information about the response stream that is sent. The headers below are standard HTTP response headers. If corresponding checkbox is selected, it is included in the output message. An element with same name as the header is added as child element of Header element in the schema of the output port if the response type property is chosen as XML. Other wise a message header with name prefixed with HTTP_ is set as message property on output message.
Content-Type
The Content-Type header field indicates the media type of the body sent to the recipient.
● Content-Length
The Content-Length header field indicates the size of the body sent to the server. Any Content-Length greater than or equal to zero is a valid value.
● Content-Location
The Content-Location header field is used to supply the resource location for the entity enclosed in the message when that entity is accessible from a location separate from the requested resource's URI.
● Content-Range
The Content-Range header is sent with a partial body to specify where in the full body the partial body should be applied.
● Content-Encoding
The Content-Encoding header field is used as a modifier to the media-type. When present, its value indicates what additional content coding have been applied to the body, and thus what decoding mechanisms must be applied in order to obtain the media-type referenced by the Content-Type header field.
● Set-Cookie
The Set-Cookie header is sent by the server in response to an HTTP request, which is used to create a cookie on the user's system. The Cookie header is included by the client application with an HTTP request sent to a server, if there is a cookie that has a matching domain and path.
The Set-Cookie value can be specified in the following format name1=value1;name2=value2.
● Last-Modified
The Last-Modified header field indicates the date and time at which the origin server believes the variant was last modified. The exact meaning of this header field depends on the implementation of the origin server and the nature of the original resource. For files, it may be just the file system last-modified time. For entities with dynamically included parts, it may be the most recent of the set of last-modify times for its component parts. For database gateways, it may be the last-update time stamp of the record. For virtual objects, it may be the last time the internal state changed.
For detailed information on standard HTTP headers, please refer to http://www.w3.org/Protocols/rfc2616/rfc2616-sec14.html .
Headers to be included (comma-separated)
If there are any custom headers apart from the standard HTTP headers, those headers can be specified here in a comma-separated list.
If the custom headers are added and the response type is chosen as XML, the specified properties appear as the child elements of Custom-Headers element in the output message. If response type is chosen as Headers, then a message header with name prefixed with HTTP_ will be sent in the output message.
Response Body
This property defines the format of output message that is sent to output port. At runtime, the component converts the HTTP response obtained from HTTP Server into output message based on this property.
Headers
This property is used to set the selected headers (both standard HTTP and custom headers) as message properties on output message. All the selected headers are read from HTTP response obtained and set on output message. The response message from HTTP response is set body of the output message.
XML
When this property is used, all the selected headers are set as elements in output schema created by the component.
Response
The message body of the output message that is generated from HTTP response can be specified in schema editor that opens on clicking this button. This property is optional. If specified, output schema depends on the response type (Headers or XML).If response type is Headers, the schema specified here is set output schema. If response type is XML, a response message is created in the form of XML data conforming to the schema specified here and set as CDATA in the body of the output message.
Please refer to section Input and Output for details about the effects of these configurations on input and output structures.
When the Content-Type header in HTTP response stream is null, the action to be taken is specified here as shown in Figure 10.
Figure 10: Configuration of null 'Content-Type'
Exception
If this property is set, an exception is sent to error port.
application/octet-stream
If this property is set, then Content-Type header of the response is set to Application/octet-stream.
The input schema for the component is defined based on the configuration of HTTPRequestProperty.
When the HTTP method is set to GET, the input schema varies based on the configuration of headers. Configuration of parameters does not affect the input schema generated.
When no headers are selected, input schema is defined as shown in Figure 11 and a sample input is shown in Figure 12.
Figure 11: Schema when there are no header
Figure 12: Sample input XML for schema in Figure 11
When custom headers are added as shown in Figure 13
Figure 13: Sample Headers configuration
The input schema is defined as shown in Figure 14 and a sample input is shown in Figure 15.
Figure 14: Schema when custom headers are selected
Figure 15: Sample input XML for schema in Figure 14
Note: Headers and parameter values defined in input XML override the values set in CPS. If the corresponding header or parameters elements are not present in the input XML values from CPS are used.
When the HTTP method is set to Post, the input schema varies based on the configuration of headers and parameters/post data details.
When no custom headers are added and Parameters/PostData Details is set to Simple Text, input schema is defined as shown in Figure 16 and a sample input is shown in Figure 17.
Figure 16: Schema when parameters/postdata set to SimpleText
Figure 17: Sample input XML for schema in Figure 16
When custom headers are added as shown in Figure 12 and Parameters/PostData Details is set to Binary Data, input schema is defined as shown in Figure 18 and a sample input is shown in Figure 19. Content of element BinaryData in input XML should be a base64 encoded value of actual binary input.
Figure18: Schema when parameters/postdata set to 'BinaryData'
Figure19: Sample input XML for schema in Figure 18
When custom headers are added as shown in Figure 12 and Parameters/PostData Details is set to XML, input schema is defined as shown in Figure 20 and a sample input is shown in Figure 21.
Figure 20: Schema when parameters/postdata set to 'XML'
Figure 21: Sample input XML for schema in Figure 20
A sample schema is provided by clicking PostData button. This schema is set as child element under XMLData element. In the input message, xml data conforming to the schema specified should be set else an error can be thrown as this is a required field.
When Content-Type is set as multipart/form-data and the custom headers are added then the input schema is defined as shown in Figure 22 and a sample input is shown in Figure 23. The Schema doesn’t contain the Content-Type element in this case.
Figure 22: Schema when Content-Type set to multipart/form-data
Figure 23: Sample input XML for schema in Figure 22
The files to be uploaded can be provided under Files element as shown in Figure 25. In the element File the Name attribute specifies the name of the parameter and the Value specifies the path of the file to be uploaded. If the custom headers are not configured, then the element CustomHeaders will not be present in the schema.
When custom headers are added as shown in Figure 13 and Parameters/PostData Details is set to parameters, input schema is defined as shown in Figure 24 and a sample input is shown in Figure 25.
Figure 24: Schema when parameters/postdata set to Parameters
Figure 25: Sample input XML for schema in Figure 24
When custom headers are added, they are added as child elements under CustomHeaders element. The addition of parameter does not affect the input schema generated.
In all the above cases except when PostData is set to XML, all the elements present in the Input message are optional. A Sample input message with no fields can be used as shown in Figure 26.
Figure 26: Sample input XML
If there are no fields as shown in above Figure 26, the default values which are configured in CPS are set on the request message. Else the value of the corresponding field is taken from input message.
When the property Use Connection details from input is chosen, an additional element ConnectionFactorySettings is added to the input schema, as shown in the figure. Properties that are used to create the connection are present under this element.
Figure 27: Input schema with ConnectionFactorySettings
The output schema for the component is based on the configuration details provided for HTTPResponseProperty.
When the Response Body for output message is set as Headers and no schema is provided for the Response, then no schema is set on output port. If a schema is provided by clicking the Response button, it is set as the output schema. If any headers are selected or if any custom headers are configured, then they are set as message properties on the output message.
When the Response Body for output message is set as XML, output schema generated depends on the schema provided by clicking the Response button.
When no schema is provided in Response, output schema is defined as shown in Figure 28 and a sample output XML is shown in Figure 29.
Figure 28: Output Schema when no schema is set in Response
Figure 29: Sample XML for schema in Figure 28
If any custom headers are configured, then they are added as child elements under CustomHeaders element which is set as child element under Header element.
When schema is provided in Response, output schema is defined as shown in Figure 30 and a sample output XML is shown in Figure 31.
Figure 30: Output Schema when sample schema is set in Response
Figure 31: Sample XML for schema in Figure 30
To communicate with https websites, SSL has to be enabled in HTTPAdapter and the values for KeyStore, TrustStore, KeyStore Password, TrustStore password and KeyStore Client Key have to be specified in the SSL Security dialog in the CPS.
Client keystore and truststore are required for SSL communication. The procedure to obtain the certificate from the https website and to generate the client keystore and truststore is explained in sections 3.11.2.1, 3.11.2.2 and 3.11.2.3 of Fiorano SOA User Guide.
Section 3.11.2.4 (Using the Keystore and Truststore in an SSL Application) explains the procedure to use the generated Client keystore and truststore in HTTPAdapters for SSL configuration.
The default HTTP Port to be used for SSL communication is 443. If the http server uses a different port then it has to be mentioned.
Send a request to Web Server and display the response.
Configure the HTTPAdapters as described in Configuration and Testing section and use feeder and display component to send sample input and check the response respectively.
Figure 32: Demonstrating Scenario 1 with sample input and output
<ns1:HTTPRequest xmlns:ns1="http://www.fiorano.com/fesb/activity/HTTPAdapters1/HTTP/In">
<URI>www.google.com</URI>
<Header>
<Cookie>Cookie</Cookie>
<Pragma>Pragma</Pragma>
</Header>
<Entity>
<NVPairs>
<ns1:NVPair Name="Name" Value="Value"/>
</NVPairs>
</Entity>
</ns1:HTTPRequest>
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN">
<HTML><HEAD>
<META http-equiv=Content-Type content="text/html; charset=iso-8859-1">
<META content="MSHTML 6.00.2600.0" name=GENERATOR>
<script language="JavaScript" type="text/JavaScript">
<!--
function MM_preloadImages() { //v3.0
var d=document; if(d.images){ if(!d.MM_p) d.MM_p=new Array();
var i,j=d.MM_p.length,a=MM_preloadImages.arguments; for(i=0; i<a.length; i++)
if (a[i].indexOf("#")!=0){ d.MM_p[j]=new Image; d.MM_p[j++].src=a[i];}}
}
//-->
</script>
<link href="css/fiorano.css" rel="stylesheet" type="text/css">
</HEAD>
<BODY bgcolor="#FFFFFF" leftmargin="0" topmargin="0" marginwidth="0" marginheight="0">
<Script Language="JavaScript" >
<!--
function search_check()
{
if(document.search.query.value == "")
{
alert("Query cannot be blank")
}
else
{
document.search.submit()
}
}
-->
</Script>
<html>
<head>
<link rel="stylesheet" href="/css/fiorano.css" type="text/css">
………………….
</body>
</html>
In Order Entry sample, a user is provided a web based interface to send a purchase order to a company. In case the order is accepted, HTTPAdapters is used to POST the order delivery request to a third party vendor.
Figure 33: Order Entry
When connecting to secured sites, the component accesses truststore from different locations in different launch modes -
Separate Process - %JAVA_HOME%\jre\lib\security\cacerts
In-memory - %FIORANO_HOME%\esb\server\profiles\certs\jssecacerts
'jssecacerts' in %FIORANO_HOME% does not have trusted certificates required by most of the secured sites. Hence, to connect to secured sites when component is launched in-memory, either the trusted certificates should be added to 'jssecacerts' or the property 'javax.net.ssl.trustStore' (in %FIORANO_HOME%\esb\server\bin\server.conf, if FPS is launched using server.bat/server.sh and %FIORANO_HOME%\esb\fps\bin\fps.conf, if FPS is launched using fps.bat/fps.sh) should be set to %JAVA_HOME%\jre\lib\security\cacerts.