The HTTP Server communication point enables Rhapsody to act as an HTTP server (or web server) so HTTP clients (such as web browsers) can directly send or receive messages to and from Rhapsody. In general, the HTTP Server communication point is configured to listen for HTTP requests to a specific URL on a certain port and perform a certain action when the request arrives. It can be configured to perform a different action for different HTTP request methods (for example, it can perform one action on a GET and another on a PUT). Some actions can only be performed when the communication point is running in a certain mode (Input or Output mode).

It should also be noted that some actions cannot be performed in response to requests of a certain method because they do not make sense; for example, a message cannot be received from an HTTP GET request because GET requests do not contain any content. Similarly, you cannot ask the communication point to send a message in response to a HEAD request as responses to HEAD requests may not contain any content.

You can have multiple HTTP servers running on the same port, as long as they have a different context; for example, http://<Local Address>:<Port>/<Context Path>. Refer to Published Properties for a list of properties associated with this communication point.

Supported Operational Modes: Input, Output, In->Out.

In order to make this server communication point more tolerant to connection failures from clients or misconfigured clients, we recommend that its connection retry count is set to infinite. Refer to Connection Retries for details.

Input Mode Properties

Property

Description

Local Address

The local interface to listen for connections on; if empty, all interfaces are listened on.

Local Port

The port to listen for connections on. HTTP usually runs on port80, HTTPS on port 443.

Context Path

The URL path that this communication point will respond to requests for. The full URL for HTTP requests for this communication point will be of the form: http://<Local Address>:<Port>/<Context Path>.

Timeout

An internal timeout, which is the length of time the communication point waits for the servlet to generate a response. If a response is not generated within the specified timeout period, the communication point sends a 504 Gateway Timeout error response to the client HTTP system.

In In->Out mode the Timeout property is automatically set to the same value as the communication point's Response Timeout setting.

Use HTTPS

Identifies whether to use HTTPS (encrypted communication) instead of HTTP:

  • Enabled - use HTTPS.
  • Disabled (default).

Refer to TLS/SSL Support in Rhapsody for details on TLS/SSL (Transport Layer Security/Secure Sockets Layer) support in Rhapsody. 

It is strongly recommended that SSL is enabled for HTTP Server communication points.

SSL Protocol Mode

 Refer to SSL Protocol Versions for details.

SSL Cipher Suites

 Refer to SSL Cipher Suites for details.

Require Client Authentication

Determines whether HTTPS client authentication is to be performed. If this is enabled then the Trusted Certificates configuration property must be configured with the certificates used to authenticate the HTTPS clients. In order to successfully connect, an HTTPS client must present either the configured certificate, or a certificate directly or indirectly issued by the configured certificate. It is highly recommended that client authentication be enabled if possible.

Secure Keys

The list of private keys to choose from when selecting a private key to use in the communication with the client. During the establishment of the TLS session, the HTTP Server communication point presents the SSL certificate associated with this private key to any HTTPS client that tries to connect. This allows the HTTPS client to verify that it is connecting to the HTTPS server that it expected. As it is mandatory, it is not possible to configure the HTTPS server to operate with anonymous server authentication. If required, a private key can be generated from Rhapsody's Certificate Manager.

Refer to Server Authentication for details.

Trusted Certificates

Identifies the trusted certificates used at the non-Rhapsody end of the HTTPS connection. If it is configured with one or more certificates, then the HTTPS server requires client authentication as part of the TLS protocol negotiation, and will reject clients that do not present either the configured certificate, or a certificate directly or indirectly issued by the configured certificate. Only required if client authentication is required.

Refer to Client Authentication for details.

HTTP Actions

The action to perform when a request is received (Rhapsody currently supports GET, PUT, POST, HEAD, TRACE, DELETE, and OPTIONS). Refer to Supported HTTP Actions for details.

Redirect URL

The URL to redirect to.

Static Content

The static content to return.

Request Parameters

The request parameters to use to populate message properties on the new Rhapsody message. These enable you to match POST request properties to the Rhapsody properties.

Message Body Parameter Name

The value of the named request parameter will be used as the body of the new Rhapsody message.

Allow Null Message Body

Whether a new Rhapsody message may have a null body when receiving a message from request parameters:

  • Enabled.
  • Disabled.

Only available if Message Body Parameter Name is specified.

Protocol Support

Identifies the level of support for application-level protocols which use HTTP:

  • Standard HTTP Only.
  • SOAP Support.
  • ebXML Support.

Request Headers

A list of headers from incoming HTTP request messages which should be set as the associated properties on input.

Output Mode Properties

Property

Description

Local Address

The local interface to listen for connections on; if empty, all interfaces will be listened on.

Local Port

The port to listen for connections on. HTTP usually runs on port 80, HTTPS on port 443.

Context Path

The URL path that this communication point will respond to requests for. The full URL for HTTP requests for this communication point will be of the form: http://<Local Address>:/Path>

Timeout

An internal timeout, which is the length of time the communication point waits for the servlet to generate a response. If a response is not generated within the specified timeout period, the communication point sends a 504 Gateway Timeout error response to the client HTTP system.

In In->Out mode the Timeout property is automatically set to the same value as the communication point's Response Timeout setting.

Use HTTPS

Whether to use HTTPS (encrypted communication) instead of HTTP:

  • Enabled.
  • Disabled (default). 

Refer to TLS/SSL Support in Rhapsody for details. 

It is strongly recommended that SSL be enabled for HTTP Server communication points.

SSL Protocol Mode

 Refer to SSL Protocol Versions for details.

SSL Cipher Suites

 Refer to SSL Cipher Suites for details.

Require Client Authentication

Determines whether HTTPS client authentication is to be performed. If this is enabled then the Trusted Certificates configuration property must be configured with the certificates used to authenticate the HTTPS clients. In order to successfully connect, an HTTPS client must present either the configured certificate, or a certificate directly or indirectly issued by the configured certificate. It is highly recommended that client authentication be enabled if possible.

Secure Keys

The list of private keys to choose from when selecting a private key to use in the communication with the client. During the establishment of the TLS session, the HTTP Server communication point will present the SSL certificate associated with this private key to any HTTPS client that tries to connect. This allows the HTTPS client to verify that it is connecting to the HTTPS server that it expected. As it is mandatory, it is not possible to configure the HTTPS server to operate with anonymous server authentication. If required, a private key can be generated from Rhapsody's certificate manager.

Refer to Server Authentication for details.

Trusted Certificates

Identifies the trusted certificates used at the non-Rhapsody end of the HTTPS connection. If it is configured with one or more certificates, then the HTTPS server requires client authentication as part of the TLS protocol negotiation, and will reject clients that do not present either the configured certificate, or a certificate directly or indirectly issued by the configured certificate. Only required if client authentication is required.

Refer to Client Authentication for details.

HTTP Actions

The action to perform when a request is received (Rhapsody currently supports GET, PUT, POST, HEAD, TRACE, DELETE, and OPTIONS).

Refer to Supported HTTP Actions for details.

Redirect URL

The URL to redirect to.

Static Content

The static content to return.

Request Parameters

The request parameters to use to populate message properties on the new Rhapsody message.

Message Body Parameter Name

The value of the named request parameter will be used as the body of the new Rhapsody message.

Allow Null Message Body

Whether a new Rhapsody message may have a null body when receiving a message from request parameters:

  • Enabled.
  • Disabled.

Only available if Message Body Parameter Name is specified.

Protocol Support

Identifies the level of support for application-level protocols which use HTTP:

  • Standard HTTP Only.
  • SOAP Support.
  • ebXML Support.

Content Type

The MIME content type of the Rhapsody message to be sent in the content of the HTTP response: usually, text/plain, text/xml or text/rtf.

You can use a published message property on a route or a Rhapsody variable as the value for this property.

Response Headers

A list of headers to be read from the incoming HTTP response messages and the corresponding message properties to which the header values should be written.

Copy headers

When a message is received in either the HTTP client or HTTP server Communication Point the HTTP headers are copied onto message properties in lower case with the prefix http:.

If Copy headers is enabled, these HTTP headers can be copied to the response message using regular expressions to match the HTTP header names.

Regular expressions

List of regular expressions to match the HTTP headers and actions (Copy to response or Discard) to take. If a regular expression matches an HTTP header it will be copied to the response or discarded depending on the setting of 'action'. If the header does not match the next regular expression in the list will be tried. If no regular expressions match the header it will be discarded.

This communication point supports Java Regex (case insensitive).

In->Out Mode

The configuration properties for the HTTP Server communication point in In->Out mode is a combination of the properties described above.

Refer to Out->In and In->Out Properties for general details on a communication point's In->Out mode.

Supported HTTP Actions

The actions that the HTTP Server communication point can perform are:

Receive Message

Receive a message from the request by reading the HTTP content associated with the request. If the communication point is in In->Out mode then the HTTP response from the server will contain a message in its content.

If the communication point is in input mode, a response will be returned with a 200 response code and the message Rhapsody successfully processed the message as the response content. This action cannot be used when the communication point is running in output mode.

Receive Message in Query Parameters

Receive a message from the request's query parameters. The exact query parameters looked for are defined by the Request Parameters and Message Body Parameter Name configuration parameters. If the communication point is in In->Out mode the HTTP response from the server will contain a message in its content.

If the communication point is in input mode, a response will be returned with a 200 response code and the message Rhapsody successfully processed the message as the response content. This action cannot be used when the communication point is running in output mode.

Return Message

Ignores any request parameters or content and returns a response with a 200 response code and the next queued Rhapsody message in the response content. If there is no queued message for the communication point and no message arrives within the specified timeout period, it returns a 504 (Gateway timeout) response code.

This action can only be used when the communication point is running in output mode.

Return Static Content

Ignores any request parameters or content and returns a response with a 200 response code and the static content specified by the Static Content configuration parameter in the response content. This is useful as a response to a GET for returning an HTML page which contains a form that allows the user to POST content back to the communication point. The POST action can then receive the content as a Rhapsody message.

Redirect to Redirect URL

This redirects the request to the URL specified by the Redirect URL configuration property.

Action Not Supported

This means this communication point does not support the request method and all such requests will be returned a 405 (Method Not Supported) HTTP response.

Published Properties

Published properties for the HTTP Server communication point are:

  • ContentType - the MIME content type of the Rhapsody message received in the content of the HTTP request: usually text/plain, text/xml,or text/rtf.
  • RequestMethod - the HTTP request method that was used to make the request to the HTTP Server communication point. Typically POST, GET, PUT,or DELETE.
  • ServerURL - the URL of this HTTP Server communication point that messages were received from.
  • http:request-line - the request line that was used to make the request to the HTTP Server communication point.
  • http:request-url - the URL that was requested in the request to the HTTP Server communication point.

Multiple clients can connect to a single HTTP Server communication point. After the TLS handshake, the HTTP Server communication point sets the following message properties identifying which client sent the message:

  • IncomingSubjectFromCertificate - the Subject DN.
  • IncomingIssuerFromCertificate - the Issuer DN.
  • IncomingSerialNumberFromCertificate - the  Issuer serial number (formatted as a decimal number).
  • IncomingSubjectKeyIdentifierFromCertificate - the hex-encoded subject key identifier (if that optional extension is present).

Status Code

The message property ResponseCode is used to set the status code on the response. The HTTP Client communication point sets ResponseCode from the HTTP response status line. If ResponseCode has not been set, OK (200) is used.