In this section: |
The NHTTP adapter is a nonblocking HTTP with improvement in performance, connection management, and various other security features.
The NHTTP adapter provides extensive flexibility by exposing an array of configurable parameters for security, connectivity, and header manipulation. Below are descriptions of some features that have been added as part of the improvement to the NHTTP component.
Named SSL Context Provider
Since this provider uses configured keystore/truststore providers, it allows you to configure multiple SSL context providers and use them as named providers in the NHTTP configuration.
A listener is a component that is responsible for receiving inbound messages via an assigned listener protocol. After a listener is created, it must be added to an inlet configuration. An inlet will become part of the final channel configuration that will consist of an inlet, route, and an outlet. For more information on configuring channels, see the iWay Service Manager User's Guide.
To configure a NHTTP listener:
On Windows, you can start iWay Service Manager by clicking Start, selecting Programs, iWay 6.0 SM, and then Start Service Manager for the configuration you are currently using.
For more information on starting and stopping iWay Service Manager, see the iWay Service Manager User's Guide.
http://host:port/ism
where:
Is the host machine on which iWay Service Manager is installed.
Is the port on which iWay Service Manager is listening. The default port is 9999.
On Windows, alternatively, you can click Start, select Programs, iWay 6.0 SM, and then click Console.
A login dialog box opens.
The iWay Service Manager Administration Console opens.
The Listeners pane opens.
The table that is provided lists all the previously configured listeners and a brief description for each.
The Select listener type pane opens.
The Configuration parameters for the NHTTP listener pane opens.
Note: The parameters prefixed with a (*) in the listener configuration pane are required.
For more information, see NHTTP Listener Configuration Parameters.
You are returned to the Select listener type pane.
You can now use this listener as part of your channel configuration where the business logic will be applied to the received messages.
The following table lists and describes parameters for the NHTTP listener.
Parameter |
Description |
---|---|
IP Properties | |
Port |
TCP port for receipt of HTTP requests. |
Local bind address |
Local bind address for multi-homed hosts. This parameter value is usually not specified. |
Persistence |
If set to True, the connection is maintained when the client requests to do so. Otherwise, the connection is closed. |
Maximum Connections |
Defines the maximum number of simultaneous connections that are allowed. When this threshold is reached, new connections will not be accepted until current connections are closed and the total number of connections is below the limit. Leave this field blank (default) or set a value of zero to have no maximum limit of connections. |
Persistence Timeout value in Minutes |
Maximum length of time that a connection can persist with no activity. |
Set Response NoDelay |
If set to True, it disables Nagle's Algorithm on the response. This will result in a faster line turnaround at the expense of an increased number of packets. |
Reuse Address |
If set to True, when a connection is closed, it immediately makes the address available, bypassing TCP's defaults. |
Allowable Clients |
If supplied, only messages from this list of fully qualified host names and/or IP addresses are accepted. Accepts comma-separated list or use the FILE() function. |
Secure Connection (SSL) | |
Secure Connection |
If set to True, a connection using secure HTTP (HTTPS) is made. |
SSL Context Provider |
Named iWay Security provider for SSL Context. |
General Properties | |
GET Handling |
Determines how GET requests are handled. Options include:
|
PUT and DELETE Handling |
Determines how PUT and DELETE requests are handled. Options include:
|
Document Root |
Base directory from which all HTTP pages will be served via GET if GET Handling is enabled for page access. |
Default Page |
The default page to display if no page is identified in the incoming HTTP[s] request. |
Default Text |
The default text to send with 200 OK, which will take configured ContentType. |
Response content type |
Overrides the content type of the response. |
HTTP Response Code |
The HTTP status code to send with the response. This parameter will be evaluated and can prefix runtime functions with a backtick to defer evaluation until emit time. Leave blank for default HTTP 200 status. The HTTP status code of any NHTTP emits earlier in the process to be stored in the httpspecial register in the response namespace configured for the emitter. |
Authentication Scheme |
Scheme to apply when authenticating HTTP requests. Select one of the following options from the drop-down list:
|
Authentication Realm |
If authentication is required, provide the name of the configured Realm provider to use. |
Request Header Namespace |
Special register namespace into which HTTP headers from the incoming requests are saved. The "Default" option will create HDR type special registers without a namespace prefix. |
Response Header Namespace |
Special register namespace from which HTTP headers for the outgoing response are taken. The "Default"option will send HDR type registers with no namespace prefix. If "none" is selected, no special registers are sent as HTTP headers. |
Response Main Part Header Namespace |
Special register namespace from which MIME headers for the outgoing response will be taken. Provide a prefix to control the response Main BodyPart headers in the presence of attachments. Selecting none means that no special registers will be sent as MIME headers. An empty namespace prefix will be treated as none. |
Maximum Request Entity size |
When a request document is received that is larger than the specified maximum size, the listener will return HTTP 413 Request Entity Too Large and close the connection. A value of 0 specifies no maximum. The default size is 256KB. |
Excluded Headers |
A comma delimited list (case insensitive) of headers that should not be sent with the response, even if they are found in the response header namespace. |
Compress Response |
If set to True, the response will be compressed with gzip or deflate compression when the client indicates that it can accept compressed transfer encoding. |
Other | |
Whitespace Normalization |
Specifies how the parser treats whitespace in element objects. Select preserve (default) to turn off all normalization as prescribed by the XML Specification. Select condense to remove extra whitespaces in pretty printed documents and for compatibility with earlier versions. |
Accepts non-XML(flat) only |
If set to True, the listener expects flat (non-XML) documents. Preparsers do not run. |
Optimize Favoring |
Selection of memory is useful for large input documents. |
Multithreading |
Number of documents that can be processed in parallel. |
Execution Time Limit |
Time limit for document execution (in seconds) before it is terminated. |
Default Java File Encoding |
Default encoding if incoming message is not self-declaring. |
Agent Precedence |
Changes the order by which iSM selects agents. This is normally set to Document overrides listener. |
Always reply to listener default |
If set to True, the default reply definition is used in addition to defined replies. |
Error Documents treated normally |
If set to True, error documents are processed by any configured pre-emitters. |
Listener in Transaction Manager |
If set to True, agents run within a local transaction managed by the listener. |
Record in Activity Log(s) |
If set to true (default), activity on this channel will be recorded in the activity logs. If set to false, the activity will not be recorded. |
The following table lists and describes the special registers for the NHTTP listener.
Special Register |
Level |
Description |
---|---|---|
... |
Header |
Each header value from the message. |
action |
Document |
Action field of the post. |
docroot |
Document |
The defined docroot from configuration. |
ip |
Document |
The IP of the sending system. |
iwayconfig |
System |
Current active configuration name. |
iwayhome |
System |
Base at which the server is loaded. |
iwayworkdir |
System |
Path to base of the current configuration. |
msgsize |
Document |
Physical length of the message payload. |
name |
System |
Assigned name of the master (listener). |
protocol |
System |
The protocol on which the message was received. |
requestType |
Header |
Type of HTTP request (GET, POST, or HEAD). |
source |
Document |
Host name of the sending system. |
url |
Header |
Full URL of the HTTP request (GET, POST, or HEAD). |
You can configure outbound processing of HTTP messages as a service that can be used within a process flow, which will become part of the route configuration or directly as a service assigned to a route. In this case, a business process can continue after an HTTP message has been sent out to the client. The following section describes how to configure an HTTP nonblocking emit service. For more information on configuring outlets and routes, see the iWay Service Manager User's Guide.
To configure an HTTP nonblocking emit service:
The Services pane opens.
The table that is provided lists all the previously configured services and a brief description for each.
The Select Service type pane opens.
The configuration parameters pane for the HTTP nonblocking emit service opens.
For more information, see HTTP Nonblocking Emit Service Configuration Parameters.
The name and description pane opens.
The following table lists and describes parameters for the HTTP nonblocking emit service.
Parameter |
Description |
---|---|
Configuration Parameters | |
Destination (required) |
Destination URL to post information that uses the following format: http[s]://host[:port]/action |
HTTP Client Provider (required) |
HTTP client Provider that is used to manage connections for this emitter. |
Action Method |
Select one of the following supported methods from the drop-down list:
|
Request Content Type |
Content type for the HTTP request to be sent by this emitter. Select a value from the drop-down list or provide your own. Available values from the drop-down list include:
|
User ID |
User ID for Basic Authentication challenges. |
Password |
Password for Basic Authentication challenges. |
Domain |
Domain for NTLM authentication challenges. Note that to use NTLM, you must enable connection persistence. |
Request Header Namespace |
Special register namespace from which HTTP headers for the outgoing request will be taken. Choose "Default Namespace" to send HDR type registers with no nonamespace prefix, or supply a namespace prefix here. "None" means that no special registers will be sent as HTTP headers.
|
Request Main Part Header Namespace |
Special register namespace from which MIME headers for the outgoing request will be taken. Provide a prefix to control the request Main BodyPart headers in the presence of attachments. Selecting none means that no special registers will be sent as MIME headers. |
Response Header Namespace |
Special register namespace into which HTTP headers from the incoming response will be saved. Choose "Default Namespace" to create special registers with no namespace prefix, or supply a namespace prefix here."None" means that no special registers will be created.
|
Excluded Headers |
A comma delimited list (case insensitive) of headers that should not be sent with the request, even if they are found in the request header namespace. |
Ask for Compressed Response |
If set to True, the request will set the accept-encoding to indicate that that the client can accept a compressed response. If the response has a compressed content encoding, the client will automatically inflate the response. |
Compress Request |
If set to True, the request entities will be compressed using the selected encoding and the content-encoding header will be set accordingly. |
Replace Connection? |
If set to False, the connection is not returned to the connection pool immediately. The connection's identifier will be stored in the httpclient-key special register and the connection can be handled by the HTTP Client Manager agent. |
Maximum HTTP Client Manager Delay |
Maximum time for the HTTP Client Manager to handle a particular connection before it is automatically aborted. The format is [xxh][xxm]xx[s]. The default is 60 seconds. |
Try Expect/Continue Handshake? |
If set to true, the client will send the HTTP Expect: 100-continue header and await HTTP 100 response before sending the request body. By default, false is selected. |
Chunk Encoded Request? |
If set to true, the request entity will be sent with chunk encoding. By default, false is selected. |
Maxium Request Size |
Maximum size, after compression, of a request entity that can be sent with this emitter. A value of zero (0) means there is no maximum size limit and if no value is specified, the default value of 256KB is applied. |
Maxium Response Size |
Maximum size of a response entity that can be received by this emitter. A value of zero (0) means there is no maximum size limit and if no value is specified, the default value of 256KB is applied. |
IP Properties | |
Persistence |
If set to true, the server is requested to maintain the connection. |
Response Timeout value in seconds |
The value in seconds to wait for a response before generating an error. The default value is 60 seconds. |
Agent Specific Parameters | |
Return |
The type of return from this agent. Select input to return input document, status for an XML document with transaction parameters and status, or response to capture the output from the server. |
Preemitter |
If set to true, the preemitters will not run. |
Response Wrapper Tag |
The tag name with which to wrap the response if the response is non-XML and must be XML. |
Response Base64 Encoded |
If set to true, the response will use Base64 encoding. |
When you connect the NHTTPEmitAgent object to an End object using the OnCustom build relation in a process flow, the available line edges are provided in the Line Configuration dialog box.
The following table lists and describes the available line edges for the NHTTPEmitAgent object.
Line Edge |
Description |
---|---|
OnError |
Error |
OnSuccess |
Success |
OnFailure |
Failure |
fail_connect |
fail_connect |
fail_info |
fail_info |
fail_redirection |
fail_redirection |
fail_client |
fail_client |
fail_server |
fail_server |
fail_operation |
fail_operation |
fail_parse |
fail_parse |
fail_unsigned |
faul_unsigned |
This section provides additional information about the NHTTP listener and includes samples you can use as a reference.
The NHTTP listener allows you to configure the handling of incoming HTTP requests. For example, the available options for the GET Handling parameter include docroot, error, and event. If you select event, an event document is created for the incoming request. This document can then be used in your process to determine an action for the request. The event document corresponds to the following structure:
The following syntax is a sample document for the GET event:
<?xml version="1.0" encoding="ISO-8859-1" ?> <http user="unknown" type="GET"> <parms> <parm name="version">1.1</parm> <parm name="source">beck-xp.ibi.com</parm> <parm name="ua-cpu">x86</parm> <parm name="reqType">GET</parm> <parm name="accept-encoding">gzip, deflate</parm> <parm name="accept-language">en-us</parm> <parm name="connection">keep-alive</parm> <parm name="url">/TEST?A=B&C=D</parm> <parm name="user-agent">Mozilla/4.0 (compatible; Win 5.1</parm> <parm name="host">theservercom:7777</parm> <parm name="ip">172.19.22.60</parm> </parms> <body /> <url secure="true"> <host>theserver.com</host> <port>7777</port> <path>/TEST</path> <query>A=B&C=D</query> </url> <version>1.1</version> </http>
The following table lists the supported HTTP requests that can be processed by the NHTTP listener. Flow refers to the generation of the event signal document that can be processed within a process flow. A Reject action causes the client's request to be rejected with an HTTP 405 Method Not Allowed response.
Request Type |
Available Actions |
---|---|
GET |
From File, Flow, or Reject |
POST |
Flow |
HEAD |
Like GET |
PUT |
Flow or Reject |
DELETE |
Flow or Reject |
TRACE |
Echoes request as per RFC |
OPTION |
Reject |
The NHTTP listener has a parameter that can be configured to limit the number of simultaneous connections. However, this is not related to pool sizes or persistent connections. This parameter simply limits the number of clients that can connect to the server at once, persistent or not.
The listener tracks the current number of connections. When a new connection is accepted, the count is raised. When a connection closes, the count is lowered. Before accepting a new connection, the listener checks the current number of connections against the max connections parameter. If the current number is at the threshold, the new connection is not accepted and the following error message is written to the log:
ERROR (nh2) max connection threshold exceeded
Please note that the client has no knowledge of this back-end functionality. From its point of view, the connection might just be slow. The client will continue making connection attempts until it times out. As a result, it is normal to see multiple instances of this error message when simultaneous connections are over the limit. If the client does not time out and another connection closes, the new connection will be accepted and normal processing is continued
A blank value or 0 specified for the parameter indicates no limit.
When SSL Host Verification is enabled, the client verifies that the certificate the server is presenting in the handshake matches the server's hostname.
So, in the keystore of the server's SSL context, there needs to be a key pair with CN == server's hostname. If there is more than one private key in this keystore, you need to specify the server key alias to point to this key.
The client needs to add the <certificate of the CA that signed the server certificate> to its truststore. In the case of a self-signed certificate, this is the server certificate itself. The server never verifies the client's hostname, even if SSL client authentication is enabled.
The following shows some of the information in a self-signed certificate with the CN in the subject Distinguished Name set to the host and port as required by the host name verifier.
Owner CN=myMachine.ibi.com:7777, OU=iWay, O=IBI, L=Cranston, ST=Rhode Island, C=US Issuer CN=myMachine.ibi.com:7777, OU=iWay, O=IBI, L=Cranston, ST=Rhode Island, C=US Serial number 46141cb7 Valid from Wed Apr 04 17:46:31 EDT 2007 until: Mon Oct 01 17:46:31 EDT 2007 Certificate fingerprints MD5 61:02:2E:F2:D6:C2:0B:A8:AF:1F:6F:86:64:23:C9:17 SHA1 5F:7B:6C:A5:0E:FC:0C:33:F6:4C:4D:48:1B:C9:07:A4:DD:EF:54:62
iWay Software |