HTTPStub

The HTTPStub component acts as an interface between an HTTP client and an Event process and receives HTTP requests using the Hyper Text Transfer Protocol (HTTP). This component creates a context in the HTTP Gateway hosted on the peer server based on the configuration provided.

The component receives client request on its output port and passes the request message to the connected components in the event process.

Configuration and Testing

Open the component to setup the configuration in HTTPStub Configuration Property Sheet (CPS).

Component Configuration

The component has the following attributes which can be configured from its CPS. The figure below illustrates the panel with Expert Properties enabled.

Deployment Configuration

 Below are the attributes to configure the deployment properties.

Validate Input

Please refer the respective section in the Common Configurations page.

Context Name

The name of the context which will be created for this component. The Effective End Point URL for this context will be computed based on the context name; the URL has to be in the format as below:

http://<PEER_SERVER_IP>:<PEER_SERVER_HTTP_PORT>/<CONTEXT_ROOT>/<CONTEXT_NAME

Context Description

A brief description of the context which will be displayed in HTTP gateway, for example, stating the purpose of the context.

Is One Way

Determines whether a response has to be sent back to client invoking the service.

• If enabled, no response will be sent back to the client. Only an output port REQUEST will be present to send the request to the event process.

• If disabled, response is sent after processing the request. Two input ports RESPONSE and FAILURE will be added in addition to the output port to send response and error details and to receive response and error details respectively from the event process.

  

  The properties Response details and Error details will not be present if this property is set to yes.

Execution Configuration

This section helps in configuring details of Execution, Request, Response and Error.

Execution details

The details necessary for execution of a request that is sent to the component can be configured here.

Message ttl

The request received by the component is parsed and converted into a JMS message. This property indicates the time in milliseconds for which the JMS messages will be stored on the peer server. The default value 0 indicates that the messages will be stored on the server without any timeout.

Request timeout

If the property IsOneWay is enabled, the component accepts the response if it reaches before the timeout period. If no response is received, on timeout Error message will be sent to the client.

Request will be processed by the connected components in the Event Process even after the timeout but the response is not sent back to the client by HTTPStub. 0 indicates infinite timeout.

Request details

When an 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.

These properties can be configured by clicking on the ellipsis

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 of the request details editor as shown in the figure above. Added parameters can be removed by clicking on the Remove button.

• 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 schema set on output port 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 will be same.

• Include All/Other Parameters
  This option is used if all the parameters that are present in request stream have to be included , not only the parameters configured but also the other parameters(if any) which are not configured are parsed from the request stream and set on the response stream.

For each added parameter, a new element will be added as child of Params element in the schema of the output port REQUEST.

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 and providing details as shown in the figure below.

• -----------
  This option must be specified when the data is not required to be posted as part of the request. If chosen, then post data if passed as part of the HTTP request will not be present in the request message and parameters must be compulsorily added.

• XML Text [Provide a 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 schema editor. If chosen, an element XMLData will appear in the schema of output port which is of the same schema type.

• Simple Text
  Data from the request stream will be considered as text not conforming to any schema. Hence it will be added as CDATA. This option can be selected if the data is not required to be transformed using the Fiorano mapper and needs to be transferred as is. If chosen, an element Data of string type will appear in the schema of output port.

• 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.

HTTP headers are received from the gateway as message properties with the header name prefixed with http_. Example http_Content-Type. For more information about HTTP Headers refer http://www.w3.org/Protocols/rfc2616/rfc2616-sec14.html.

Response Details

If the property Is One Way is disabled, the component sends the request message and waits for response from the event process. The response message that is received is converted to HTTP Response stream suitable for the invoking client based on the details provided here.

• 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 is provided using the schema editor as shown in Figure 6. The schema is set as schema of the input port RESPONSE.

• Bytes
  Bytes portion of the JMS Message will be read and put in the response stream. This option can be chosen when the client expects the response message in the form raw bytes.
  Refer to section Input and Output for details about the effects of these configurations on input and output structures.

Error Details

Click the ellipsis

If the client expects the error to be compliant to a particular schema, then the schema is provided using the schema editor as shown in the above figure. The schema is set as schema of the input port FAILURE.

Expert Properties

Enable the Expert Properties view to configure these properties.

Expert properties are meant for advanced users; use with caution.

Deployment Configuration

Pre Processing XSL Configuration

Pre Processing XSL configuration can be used to transform request message before processing it. Click the ellipses button against the property to configure the properties.

Refer to the Pre/Post Processing XSL Configuration section under the Common Configurations page for details regarding Pre Processing XSL configuration and Post Processing XSL configuration (below).

Post Processing XSL Configuration 

Post Processing XSL configuration can be used to transform the response message before sending it to the output port.

Threadpool Configuration

This property is used when there is a need to process messages in parallel within the component, still maintaining the sequence from the external perspective. 

Please refer to the respective section in the Common Configurations page.

Store imported schemas

Enables to save schemas in Schema Repository.

Elements to Decrypt and Elements to Encrypt

Please refer to the respective sections in the Common Configurations page.

FES Connection Configuration

Details of Enterprise Server Connection can be provided by clicking the ellipses button.

Use connection details from FPS

Enable this property if the FPS connection configuration has to be the same as the FES configuration.

URL

The URL of the enterprise server to which the peer server on which the component is running is connected.

Backup URL

The alternate URL that should be tried for connecting to the enterprise server if the enterprise server cannot be connected to using the URL mentioned against property FES URL.

In case of enterprise servers in HA mode, this should point to secondary server URL if the primary is set against Server URL property and vice-versa.

Username

User name that should be used to connect to the enterprise server.

Password

Password that should be used to connect to the enterprise server.

Server Call Timeout

Sets the timeout for the calls made to the Enterprise Server. By default it is set to 180 Seconds. 
This value should be increased to avoid timeout with the Enterprise server while launching Components.

SSL Configuration

Please refer SSL Security section in the Common Configurations page.

Authentication Configuration

Basic Authentication

Use this property if basic HTTP Authentication is required. For configuration details, please refer Use HTTP Authentication section in HTTPAdapters page.

Input and output

Input

The input schema for the component is defined based on the configuration of Response Details property.
When Response is set to XML Text , then the schema provided is set as schema on input port RESPONSE. Else if response is either set to Simple Text or Bytes, then no schema is set on the RESPONSE port.

Output

The output schema for the component is based on the configuration details provided for Request Details.

Post Data set to '--------' or  'Bytes'

When Parameters are added (param1) and Post Data is set to '--------' or when Post Data is set to 'Bytes', then schema set on port REQUEST is defined as shown in Figure 8 and a sample XML in Figure 9.

Post Data set to 'Simple Text'

When Post Data is set to Simple Text, then schema set on port REQUEST is defined as shown in Figure 10 and a sample XML in Figure 11.

Post Data is set to 'XML Text'

When Post Data is set to 'XML Text', schema provided in Request details is set under XMLData element in output schema on port REQUEST. The schema set on port REQUEST is defined as shown in Figure 12 and a sample XML in Figure 13.

Functional demonstration

Scenario 1

Configure the component with Response Details set to Simple Text and parameters are configured in request details as shown in the figure below.

When the flow is launched, the HTTP context is deployed based on the configuration provided. Right-click the component and use the option 'View HTTP Context ' to view the deployed context. HTTPAdapters component can be used to send the request to the service. When a request is sent, a sample output message that is sent to output port REQUEST is shown below.

Output Message

<?xml version="1.0" encoding="UTF-8"?>
<ns1:HTTPRequest xmlns:ns1="http://www.fiorano.com/httpGateway">
   <Params>
      <REQUEST>OPA_CHANNEL</REQUEST>
   </Params>
</ns1:HTTPRequest>

Scenario 2

The below figure demonstrates how HTTPStub can be used to deploy a mailing service as a context in HTTP Gateway.

In the flow, HTTPStub is configured to take the Request as XML and the schema is set as same as that of the input port of SMTP component. The XMLData element is mapped to the input schema of the SMTP component child to child recursively using Xslt Component. The Response is also chosen as XML and schema is set to be that of the output port of the HttpStub component. The error schema is set that of *ON_EXCEPTION port of SMTP component.

When the event process is launched, the context becomes active on the web server hosted on the peer on which the HTTPStub component is deployed. HTTPAdapters can be configured to send in the request to this service.

Use Case Scenario

In Order Entry sample, you can find 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. In an Order Entry scenario, the HTTPStub can be used for receiving orders as HTTP requests.

Documentation of the scenario and instructions to run the flow can be found in the Context Help of the flow in eStudio.

Useful Tips

When HttpStub component is configured to launch on HA (High Availability) peer server,

• If both Primary and Secondary servers are on the same machine:
  Initially, if HttpStub is launched on the Primary server and the generated HTTP Context contains Primary server jetty port number. In case of failover, the primary server shuts down and the secondary server becomes Active and relaunches the component. If the secondary server uses a different jetty port then the generated context URL will be changed since the jetty port is different. The clients have to be reconfigured to use a new URL in this case.
  To avoid this situation, it is recommended to use the same jetty ports for both primary and secondary peer servers.
  Jetty service will be started only after the server started successfully. In case of HA, only one server will be active at a given time and the Jetty server will be running only in the active server and there will be no bind exceptions even if both the servers use same port number for Jetty.
• If both Primary and Secondary servers are on different machines:
  In this case, if the failover happens the hostname/IP address in the context URL will be changed. So the clients have to be reconfigured accordingly.
  • HTTP headers are received from the gateway as message properties with the header name prefixed with http_.
    Example: http_Content-Type.
  • Right-click on the component and use the option 'View HTTP Context ' to view the deployed context.