There are a number of connection configuration options available to all communication points regardless of their type. These common connection configuration properties are found on the Connection tab of the communication point properties dialog:

The options available on the Connection tab are described in the following sections:

Connection Properties

A communication point's Connection Properties determine how it connects to an external system and exchanges messages with it:

Option

Description

Connection Mode

The communication point's operational mode:

  • Bi-directional - messages can be both sent and received simultaneously. Used when incoming and outgoing messages are sent and received independently of each other.
  • Input - used to receive messages only.
  • Output - used to send messages only.
  • In->Out - when a message is received, the communication point will refuse to accept further messages until a response has been sent.
  • Out->In - when a message is sent, the communication point waits for a response before sending the next message.
Continue routing

When enabled, an output communication point on the output side of a route and can be placed on the input side and connected to a filter or an output communication point on a secondary route path. Upon successfully sending the message, the communication point then resends the message via the secondary path. Refer to Continued Routing on Success, an Advanced Routing mode, for details.

Only available when Connection Mode is set to Output.

Idle Timeout (ms)

The period, in milliseconds, of inactivity that must pass before the communication point automatically closes a connection. When the idle timeout is set to the default value of 0 (zero), the communication point keeps connections open even if they are inactive.

Number of Connections

A communication point may maintain multiple connections to remote systems at any time.

For the Directory communication point, for example, only one connection is required so this value should be left as 1. For other communication points, such as the TCP Server, multiple connections may be very useful.

Outgoing Messages

Determines how Rhapsody sends outgoing messages when a communication point is running in Bidirectional or In->Out mode and when operating in a potentially multi-connection environment. Refer to Connection Tracking for details.

Connection Retries

If any error occurs when connecting to a remote system or the connection is dropped, Rhapsody can attempt to reconnect to the system based on user-configurable retry settings.

Rhapsody usually treats connection errors as a problem with the connection to the remote system, rather than a problem with the specific message being sent. This is often the correct approach. Too many connection errors result in notifications being raised and ultimately the communication point being shut down in the error state (which also raises notifications).

However, if the connection errors are actually due to some dynamic configuration relating to the particular message being sent, shutting down the communication point is undesirable as this prevents messages being sent to other systems where there may be no connection errors.

Per-message retries enables connection errors to be tracked against both the communication point and an individual message. If the same message has too many connection errors, then a configurable action takes place, possibly resulting in the communication point moving onto the next message in the queue. This means that a communication point that talks to many remote systems do not fail if a single one of those remote systems is down.

Option

Description

Retry Type

The type of retry:

  • No retry - Rhapsody does not attempt to restart a communication point once a connection has been lost.
  • Immediate - Rhapsody attempts to restart the communication point immediately and continuously retries until the maximum number of retries has been reached.
  • Linear - Rhapsody waits for the period specified in the Initial Retry Delay field before making each attempt to restore the connection.

  • Exponential - Rhapsody employs an exponential strategy for its retry period. The strategy uses the following formula to calculate the retry delay between connection attempts: Retry Delay = Initial Retry Delay (ms) x 2^(Current Retry Count). The maximum delay value when the delay does not increment any further is set using the Maximum Retry Delay property.

Number of Retries

The maximum number of retries Rhapsody should attempt before considering the connection failed and stopping the communication point. During this period, any messages sent to output communication points accumulate in their Out Queue.

To prevent a communication point from stopping after too many failed connections, set the number of retries to -1 (infinite). The communication point is then never stopped and continually attempts to connect to the service.

In order to make Rhapsody's server communication points more tolerant to connection failures from clients or misconfigured clients, it is recommended that you set the connection retry count to infinite.

Initial Retry Delay (ms)

The period of time Rhapsody should wait before attempting to restore the connection. If you set the value to less than 10 ms, Rhapsody uses the minimum value of 10 ms.
Maximum Retry Delay (ms)

The cut-off period at which point the delay does not increase any further:

  • The minimum value for Maximum Retry Delay is one second.
  • When Maximum Retry Delay is set to 0, the maximum value of 2,147,483,647 (231-1) is used.
  • Maximum Retry Delay should be set to be greater than the Initial Retry Delay. If Maximum Retry Delay is less than Initial Retry Delay, then Maximum Retry Delay is used when making retry attempts.

For example, if Maximum Retry Delay is set to 100000 ms and the Initial Retry Delay to 5000 ms and Number of Retries to 10, retry attempts are made at the following intervals: 5, 10, 20, 40, 80, 100, 100, 100, 100, and 100 seconds.

The property is only enabled when the user chooses the Exponential retry option on the new engine that supports this feature.

Retries Per Message

The maximum number of retries allowed per message when the operation fails due to a connection either being closed or a connection error. If set to Infinite, the maximum number of retries per message is unlimited.

Message Retry Delay (ms)

The period of time, in milliseconds, Rhapsody should wait before attempting to send a message when it fails to send due to a connection being closed or a connection error.

Retries Exceeded Action

The action taken by the communication point when the retries per message have been exceeded for the given message:

  • Shutdown communication point (default).
  • Discard message.

  • Treat as error - the message is re-routed via the communication point's error output connector, and the rhapsody:ErrorCause message property is added to the message and set to connection.retries_exceeded. However, if the error output connector is not connected to other components, the message is sent to the Error Queue.

  • Redirect to Input communication point (deprecated).
  • Redirect to Output communication point (deprecated).
Redirect Target

When Retries Exceeded Action is set to Redirect to Input Communication Point or Redirect to Output Communication Point, you can select the target communication point for redirection by clicking the Select Communication Point link.

Refer to Redirecting to a Communication Point for details.
Included Messages

This setting determines what types of messages are included when determining whether a connection error should be counted against the message or not. It is not available in either Output or Bidirectional mode because in those cases only the outgoing messages can be included. For Out→In mode, the available options are:

  • All messages (default) - a connection error is counted against the maximum number of retries for a single message if the connection error occurs while sending the output message, waiting for the response, or while receiving the response.
  • Response messages only - a connection error is counted against the maximum number of retries for a single message only if the connection error occurs while waiting for the response or while receiving the response. A connection error that occurs while sending the output is only counted against the maximum connection retries for the communication point, and is not tracked against the configured Retries Per Message. Consequently, the difference between this and the other option is whether a connection error that occurs while sending the output message is tracked against both the configured Retries Per Message and Number of Retries, or just against Retries Per Message.

This setting has no effect if there is no maximum number of retries per message.

The default option for communication points introduced as of Rhapsody 5.5 is All Messages; for communication points introduced before Rhapsody 5.5, it is Response Messages Only. The conditional default options are provided so that upgrading to Rhapsody versions 5.5 and later accommodates the behavior of any communication points existing before Rhapsody 5.5.

A connection error is normally counted against both the outgoing message, and the communication point itself. If the communication point retry limit is reached then the communication point will be stopped in the error state. The retry will take place after the configured retry delay in the communication point settings. In contrast, connection closures do not count against the communication point itself and are instead retried immediately without the configured delay.

The communication point retry count is reset in the following cases:

  • When the communication point is restarted.
  • After a message is successfully sent via the connection.
  • After a message is successfully received from the connection.

The per-message retry counts are reset in the following cases:

  • When the communication point is restarted (retry counts for all messages on the communication point).
  • When a connection error occurs establishing a connection prior to retrieving a message to send (retry counts for all messages on the communication point).
  • After the message is successfully sent in Output or Bidirectional mode (retry count for the sent message only).
  • After the response message is successfully received in Out->In mode (retry count for the sent message only).
  • A timeout occurs while sending the message (retry count for the sent message only).
  • A timeout occurs while waiting for the response message in Out->In mode (retry count for the sent message only).

If per message retries are enabled for a communication point, a message path event is added to the outgoing message whenever a connection error or closure occurs and it is being counted against the message in question. Additional message path events are also added when the maximum number of retries is reached and the Retries Exceeded Action is to either discard the message or send it to the error queue.

Connection Retries for Server Communication Points

For Rhapsody's server communication points (the TCP Server communication point, for example), to "retry the connection" actually means to "wait for the next incoming connection". As such, it is recommended that Number of Retries for server communication points should be set to infinite.

If a connection error occurs while sending a message in Output or Out→In mode, then the server communication point attempts to send the same message out on the next incoming connection (which could be from a different remote client) – that is unless the Retries per Message are exhausted, in which case the Retries Exceeded Action is executed.

In In→Out mode, the outgoing message is either discarded or sent to the Error Queue depending on the connection tracking options.

In Bidirectional mode, outgoing messages are generally treated the same as in Output mode unless a message is being sent back out on the same communication point it came in on and connection tracking is enabled, in which case the behavior is the same as for In->Out mode.

When a server communication point starts up, it attempts to bind a server socket. If this fails, then the communication point may retry the bind operation before shutting down. In versions of Rhapsody prior to Rhapsody 6.4, these retries are controlled by the connection retries settings on the communication point properties dialog's General tab. As of  Rhapsody 6.4, server socket retries are controlled by two properties in the rhapsody.properties file:

Property Description 
CommunicationPointExecutionService.ServerSocketRetries
 Determines the number of times that the server socket will be retried (default value of 5). 
CommunicationPointExecutionService.ServerSocketRetryDelay

Determines the delay, in milliseconds, between retry attempts (default value of 5000).

Redirecting to a Communication Point

You can configure the communication point (source) to redirect a message to an input or output communication point (target) when the maximum number of retries has been exceeded.

The target communication point must be in the same configuration locker as the source communication point and also support the source communication point's configured Connection Mode.

If the configured number of per message retries is reached, then the message is redirected to the selected communication point by placing the message directly on the appropriate input or output queue:

  • If placed on an output queue, then the message is available for sending by the target communication point if it is running.

  • If placed on an input queue, then the message is available to be picked up by any route that has the target communication point as an input. This mode operates in a similar way to the Dynamic Router communication point in that the target communication point does not need to be running for this to occur, as the message is placed directly on its input queue.

Dynamic Retries Per Message

If per message retries have been enabled for a communication point, it is possible to dynamically change the maximum number of retries for a particular message. This is done by setting a message property called rhapsody:MaximumMessageConnectionRetries to the number of retries to use. It must be set to a non-negative integer otherwise it is ignored and the default value used instead. It is permissible to set it to zero to indicate that no retries should be performed for this message.

Interaction with Message Tracking

Connection Retries interacts with message tracking as follows:

  • Message tracking is automatically canceled if the message exceeds the maximum number of retries per message, and the selected action is to either discard the message, or send the message to the Error Queue.
  • If a connection error occurs while sending the message and the maximum retries per message have not yet been reached, then the 'send' does not count from the perspective of message tracking since it never completed. The message is instead placed back on the communication point output queue for re-sending.

In->Out and Out->In Properties

The In→Out and Out→In modes for a communication point enforce the order in which messages are sent and received.

In->Out Mode

When running in In→Out, a message is received and then a response is sent. The communication point initially starts in Input mode. While in Input mode, the communication point will not send any messages until a message is received. Once a message is received, the communication point enters Output mode. While in Output mode, the communication point will refuse to accept further messages. The communication point remains in Output mode until either a response has been sent or the response timeout period has elapsed, at which point it goes back to Input mode.

Option

Description

Response Timeout (ms)

Specifies how long the communication point should wait for a response before taking further action. The timeout also impacts the Time-To-Live functionality of the message.

To disable In→Out settings, set an infinite response timeout, that is, set the Response Timeout to 0.

Discard message once timeout occurs

This determines whether Time-To-Live functionality is enabled for messages arriving on the communication point.

This checkbox is only available when the communication point is in In→Out mode.

Out->In Mode

When running in Out→In mode, a message is sent and then a response is received. The communication point initially starts in Output mode. While in Output mode, the communication point will refuse to accept messages. Once a message is sent, the communication point enters Input mode. While in Input mode, the communication point will not send any messages. The communication point remains in Input mode until either a response has been received or the response timeout period has elapsed, at which point it goes back to Output mode.

Option

Description

Response Timeout (ms)

Specifies how long the communication point should wait for a response before taking further action.

To disable Out→In settings, set an infinite response timeout, that is, set Response Timeout to 0.

Suspend message timeout once response is received

This checkbox is only available when the communication point is in the Out→In mode. This determines whether Time-To-Live functionality is disabled for messages arriving on the communication point.

Retry Count

Specifies the maximum number of times the message should be resent after a response timeout has occurred. This can be set to Infinite or -1, to indicate that the communication point should continually retry (an infinite number of retries).

Fail Action

The action executed when the Retry Count (the maximum number of resends) has been reached:

  • Treat as error - the message is re-routed via the communication point's error output connector, and the rhapsody:ErrorCause message property is added to the message and set to tracking.retries_exceeded. However, if the error output connector is not connected to other components, the message is sent to the Error Queue.
  • Close connection.
  • Treat as error and close connection.

The Close connection fail action has the following phases:

  1. The current connection is closed.
  2. A new connection is established.
  3. The message is sent over the new connection.
  4. If no response is received, and the Response Timeout and Retry Count have been reached, the fail action (Close connection) is re-executed.

When a message tracking scheme is attached to a communication point, it automatically overrides the Out→In retry settings. Therefore, the settings for any communication point with a message tracking scheme attached are ignored.

Time-To-Live

Time-To-Live is a setting that permits an administrator to dictate the upper threshold for the life-cycle of a message. It is used to discard messages that have exceeded their Time-To-Live timeout. When messages are discarded due to exceeding their Time-To-Live timeout, a message path event is added to the message and this is logged in the Rhapsody logs under the Debug level for communication point logging.

This is managed with the message property rhapsody:TimeToLive which contains a string representation of an expiry time specified as milliseconds since epoch. This property is checked in the following circumstances:

  • Prior to the processing of a message in a filter.
  • Prior to sending the message via a communication point in output mode.
  • Prior to sending the message via a communication point in Out->In mode.
  • After receiving a message and prior to sending it via a communication point in In->Out mode.

To disable the Time-To-Live message property, set the value of the TimeToLive property to null: 

setProperty("rhapsody:TimeToLive", null)

The Time-To-Live message property can be set by a Rhapsody configuration at any point in order to control message discard behavior due to expiry. The property can also be set automatically on a message by the Rhapsody Engine as follows:

  • Enabled on messages received by a communication point configured in In→Out mode with the Discard message once timeout occurs property enabled. The Time-To-Live expiry is set to the receive time plus the response timeout configured in the Out->In properties.
  • Disabled on messages received by a communication point configured in Out→In mode with the Suspend message timeout once response is received property enabled.

This allows Rhapsody to set an upper limit on message lifetime within the Rhapsody Engine for messages which are coming in via a request-response model.

When resending or redirecting the message, the Time-To-Live message property is removed from the message. However, the Time-To-Live message property is updated when reinjecting the message to a communication point which is in Time-To-Live mode and has a finite (non-zero) Response Timeout, and the Time-To-Live message property is not empty. If any of these conditions are not met, then the message property is removed from the message.

The property is also removed from the message when resending or redirecting the message.

Connection Tracking

Rhapsody communication points can create multiple simultaneous connections which operate independently of each other. However, once multiple connections are in use, care must be taken to ensure that response messages generated by Rhapsody are sent back to the same connection as the original message. According to the options set, a message that is received by a communication point and subsequently returned by the same communication point is sent to the same connection.

The Outgoing Messages field, on the General tab of the communication point's Properties window, determines how Rhapsody sends outgoing messages when a communication point is running in either In->Out or Bidirectional mode in a potentially multi-connection environment.

In->Out Mode

When a communication point is operating in In→Out mode, Rhapsody always attempts to send an outgoing message back to the same connection that generated the original message. However, if that connection has since been dropped, Rhapsody needs to know what to do with the message. Due to the nature of the In→Out mode, it is not possible to leave messages waiting on the output queue until the connection is re-established. A re-established connection will immediately receive a new message which requires a new (and different) response.

The options available in In→Out mode are:

  • Send via original connection (discard if original connection has closed) - messages are discarded if they are destined for a connection that has been closed. The Rhapsody log will be updated to note that a message was discarded, but no errors will be generated. This is generally the desired behavior when configuring an HTTP Server, as it means that the client canceled the request before the response was sent.
  • Send via original connection (move to Error Queue if original connection has closed) - messages are sent to the Error Queue if they are destined for a connection that has been closed.

Bidirectional Mode

When a communication point is operating in Bidirectional mode, Rhapsody has several additional options. In this mode, it is possible to resend the message after the connection is reestablished, or alternatively to send the message to a different connection entirely. Depending on the circumstances, either of these options may be valid.

The available options in Bidirectional mode are:

  • Send via first available connection - enables the communication point to send outgoing messages via any available connection, rather than just to the connection that generated the original message. This is the default option, and must be used if the bidirectional communication point is truly asynchronous (input and output are completely independent), or if it is output driven (that is, it is effectively operating in an asynchronous Out->In mode).
  • Send via original connection (keep until connection is available) - the communication point keeps the message waiting on the output queue until the original connection is available. If the connection is still present, the message will be sent immediately. However, if the connection has been closed, the message will wait on the output queue until it is available again.
  • Send via original connection (discard if original connection has closed) - messages are discarded if they are destined for a connection that has been closed. The Rhapsody log will be updated to note that a message was discarded, but no errors will be generated. This is generally the desired behavior when configuring an HTTP Server, as it simply means that the client canceled the request before the response was sent.
  • Send via original connection (move to Error Queue if original connection has closed) - messages are sent to the Error Queue if they are destined for a connection that has been closed.