Rhapsody Connector

The Rhapsody Connector communication point can be used as part of a Rhapsody-to-Rhapsody connection, or as the Rhapsody end point of a connection to an external application using the Rhapsody Connector API. The Rhapsody Connector API can be used in external Java applications and is included in the Rhapsody RDK.

The Rhapsody Connector communication point streams messages and all their message properties across an underlying TCP transport. In addition, if the Rhapsody engine is aware of the character encoding of the message (in other words, it has been explicitly set by a character translation filter or JavaScript filter), then it is transmitted along with the message body.

The Rhapsody Connector protocol supports some additional functionality to improve the reliability of these communications, for example:

A protocol acknowledgement mechanism is automatically included to ensure that messages have been completely received by the remote system before being regarded as sent.
Keep-alive requests and responses are used at a configurable interval to ensure the connection is still valid, and has not been closed by an overly zealous firewall.

When a message property of a message is greater than 5,242,623 bytes in size, the Rhapsody Connector communication point sends it to the Error Queue.

Operating Modes: All

Configuration Properties

The Rhapsody Connector communication point can operate in client or server mode. Many of its properties are independent of the mode that it is operating in.

Property Name	Description
Mode	Options: `Client`, `Server`. Default: `Client` Determines whether the Rhapsody Connector communication point is operating as a client or a server. In server mode it listens for incoming connections, whereas in client mode it establishes the connection.
Remote Host	The remote hostname or IP to connect to in client mode. Only available when the communication point is operating as a client; that is, the Mode property is set to `Client`.
Remote Port	The remote port to connect to in client mode. Only available when the communication point is operating as a client; that is, the Mode property is set to `Client`.
Local Port	The local port to bind to. The default value is 0, which indicates picking any available port as per the behavior generally desired in client mode.
Local Address	The local address to bind to. Blank indicates that the local address binding should be done automatically.
SSL Protocol Mode	Refer to SSL Protocol Versions for details.
SSL Cipher Suites	Refer to SSL Cipher Suites for details. This component does not support weak cipher suites.
Secure Keys	The private keys that can be used to authenticate this communication point to the remote host. If the remote host has configured certificates to be used for peer authentication, then this server must provide keys that can be authenticated against those certificates. Applicable when using SSL/TLS. Server mode - when configured with a private key, the Rhapsody Connector communication point presents the certificate associated with the selected private key during the TLS negotiation, allowing the remote client to authenticate the server using the certificate. It is highly recommended that the server's private key always be provided here to allow server authentication to be performed. If the server does not have a private key, then one can be generated from Rhapsody's certificate manager. Client mode - when configured with a private key, the Rhapsody Connector communication point supports SSL client authentication if requested by the SSL server, and presents the certificate associated with the selected private key. It is highly recommended that you set this configuration property so that the remote system is authenticated. Refer to TLS/SSL Support in Rhapsody for details.
Trusted Certificates	The certificates that are used to authenticate the remote host. If any certificates are provided then the remote host must establish the SSL connection using private keys that can be authenticated against these certificates. If no certificates are provided, then no peer authentication is performed. Applicable when using SSL. Server mode: if it is configured with one or more certificates, then the SSL server requires client authentication as part of the SSL 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. Client mode: if it is not configured with the SSL server's certificate, then this SSL client operates in anonymous server authentication mode. It is highly recommended that the server's certificate always be provided here to allow server authentication to be performed. It is highly recommended that you set this configuration property so that the remote system is authenticated. Refer to TLS/SSL Support in Rhapsody for details.
Trusted Certificate Issuers	The certificates of trusted certificate issuers. This is necessary in server mode with performing client authentication and using certificates issued by a certificate authority. In order for an SSL/TLS connection to be established using client authentication, the client certificate must be in the trusted certificates list, and the issuer of the client certificate (if not self-signed) must be in this list. Not applicable if not using SSL or if no trusted certificates have been configured.
Listen Backlog	The number of connections that can be waiting for a connection before others are refused. Zero means to use the system default. Only available when the communication point is operating as a server; that is, the Mode property is Server.
Required capabilities	Required capabilities for this connection. A connection cannot be established if the remote host does not support required capabilities.
Optional capabilities	Optional capabilities for this connection. Allows the establishment of a connection using these capabilities without requiring the remote host to support them.
Connection Response Timeout	The time in seconds the remote host is given to respond to certain commands before the connection is considered lost. Any value of less than 10 seconds will be treated as 10 seconds.
Connection Establishment Timeout	The time in seconds is allowed for the connection process before it is aborted. This generally does not need to be set, but in some adverse network scenarios may allow a failed connection to fail sooner.
Keep Alive Period	The keep alive period in seconds. Keep-alives are sent across the connection to ensure it is still working if the connection is idle for this period of time. Any value of less than the configured connection response timeout will be treated as if it were the connection response timeout.
Connection Identifiers	Options: `Auto-increment connection identifiers`, `Use remote address and port`, `Use remote address only`. Default: `Auto-increment connection identifiers` Determines how connection identifiers are generated when using connection tracking. This allows messages to be resent to the same connection after it has been re-established. Only available when the communication point is in bidirectional mode and is configured to keep outgoing messages until a connection is re-established.

Connection Capabilities

The Rhapsody Connector API allows each connection to be tagged with a set of required and optional capabilities. These capabilities are strings that simply describe how a particular connection will be used. If a host requires a particular capability, then the remote host must also support the same capability or the connection cannot be established.

Capabilities provide a mechanism to prevent an accidental connection to the wrong server. If the server is configured with a required capability describing it, then only clients with the same configured capability can connect to it. Consequently, if a client is accidentally configured with the wrong port, then it will not send messages to the wrong server.

Internally Rhapsody uses capabilities on connections for out of process communication points to prevent other systems accidentally connecting to them.

Capabilities are not intended to be used as a security mechanism to prevent unauthorized access to a server. Security should be configured using the TLS keys and certificates instead.