Configuring connectors

A connector provides a connection point for external applications to connect to the Diffusion™ server over a TCP connection. Use the Connectors.xml configuration file to configure your connectors.

Each connector has a socket server thread which reacts to an incoming connection. The socket information is defined by the connector. Suitable connectors must be defined for inbound connections expected by the Diffusion server.

The following properties are common to all connectors:

Table 1. Connectors properties
Name	A name by which the connector can be identified.
Port	A port number on which to accept requests.
Host	The host to accept requests (only relevant on a multi-homed machine).
Input buffer size	The size of the socket input buffer to use for each connection.
Output buffer size	The size of the socket output buffer to use for each connection.

Socket buffer sizes are very important in achieving the best performance. For more information, see Tuning.

Client connections

Connectors can accept connections from any type of client. Any number of connectors can be defined to provide different connection points with different properties.

Each client connection has an input buffer to receive messages from the client. The configured input buffer size must be large enough to accommodate the largest message expected from the client. If the maximum message size and the input buffer size are configured as different values, the larger of the two is used as the input buffer size.

The output buffer size is used to assign an output buffer per client multiplexer into which messages are dequeued prior to transmission. This can have an important effect on performance. For more information, see Tuning.

Start conditions

Connection start conditions prevent the automatic start of a connection until a condition you specify has been met.

These conditions can be useful when you are using load balancers, and you want to ensure that servers do not join the load balancer pool until they are ready.

You can configure start conditions using the <start-conditions> element in the etc/Connectors.xml configuration file.

The following start conditions are supported:

fanout-ready: The connection does not start until a fan-out link has connected and synchronized.
cluster-configuration-recovered: The connection does not start until the server has joined the cluster and completed restoration of shared configuration.
replicated-topics-recovered: The connection does not start until the server has joined the cluster and completed restoration of replicated topics.

If a connector has no configured start conditions, it will reject attempts to create new sessions until the cluster-wide configuration has been restored.

Here is an example fan-out start condition configuration:

<start-conditions>
	<fanout-ready>
		<connection>primaryServer</connection>
		<link>primaryServerLink</link>
	</fanout-ready>
</start-conditions>

Note that the connection and link values must correspond to the connection and link names in the fan-out configuration in Server.xml.

Enabling session reconnection

Specify a reconnection timeout, maximum queue depth, and recovery buffer size by using the <reconnect> element in the etc/Connectors.xml configuration file.

Reconnection timeout (keep-alive): How long a disconnected client's session remains available on the server before being closed. By default, this is 300 seconds.
Maximum queue depth (max-depth): Optional maximum limit on the number of messages to queue for a disconnected client session. By default, this is the same as the queue depth for a connected client session, which is defined by the queue definitions in Connectors.xml and Server.xml.
Recovery buffer size (recovery-buffer-size): The maximum number of sent messages to keep in a buffer. These messages can then be recovered on reconnection.

Here is an example connector configuration:

<connector>
	...
	<reconnect>
		<keep-alive>60s</keep-alive>
		<max-depth>1000</max-depth>
		<recovery-buffer-size>64</recovery-buffer-size>
	</reconnect>
	...
</connector>

Using the above example, a client can reconnect to the server through this connector within 60 seconds of becoming disconnected. While the client is disconnected, up to 1000 messages are queued for it. These messages are delivered to the client when it reconnects. A buffer of up to 64 sent messages are retained in the recovery buffer. When a client reconnects, the Diffusion server uses this buffer to re-send any messages that the client has not received.