Connectors.xml
This file specifies the schema for the connectors properties.
connectors
Connectors
The following table lists the elements that an element of type connectors can contain:
| Name | Type | Description | Min occurs | Max occurs |
|---|---|---|---|---|
| connector | connector | Connector definition | 0 | unbounded |
connector
Connector definition
The following table lists the attributes that an element of type connector can have:
| Name | Type | Description | Required |
|---|---|---|---|
| name | push:string | The connector name | true |
The following table lists the elements that an element of type connector can contain:
| Name | Type | Description | Min occurs | Max occurs |
|---|---|---|---|---|
| required | push:boolean | This setting specifies if the connector is required on server start-up. If set to true and the connector does not start, the server is shut down. | 0 | 1 |
| type | connectorType | The type of connection supported. By default 'all' types are supported but the connector can be restricted to one of the following specific types - 'client' (Clients only), or 'policy' (Policy File Requests only). | 0 | 1 |
| api-type | connectorApiType | This setting constrains the API that can be used with this connector. The allowed values are 'all', 'classic', and 'unified'. The value 'unified' indicates that clients must use the Unified API. The value 'classic' indicates that clients must use the Classic API. The value 'all' indicates that clients can use either API. The default value is 'all'. DEPRECATED: since 5.9 as classic client APIs are also deprecated. | 0 | 1 |
| host | push:string | The name or the IP address that the connector binds to. This is optional. | 0 | 1 |
| port | push:port | The port on which the connector accepts connections. | 1 | 1 |
| acceptors | push:positiveNonZeroInt | DEPRECATED: This value is no longer used. | 0 | 1 |
| backlog | push:positiveNonZeroInt | The maximum queue length for incoming clients. If a connection indication arrives when the queue is full, the connection is refused. If a value is not specified, a default of 1000 is used. | 0 | 1 |
| socket-conditioning | socket-conditioning | Describes the properties associated with TCP socket connections. | 1 | 1 |
| web-server | push:string | If this connector is required to serve HTTP requests, this element specifies a web-server entry in WebServer.xml. If a value is not specified, the connector cannot serve HTTP requests. | 0 | 1 |
| policy-file | push:string | The location/name of the policy file if this connector is required to act as a policy file server (type='all' or 'policy'). | 0 | 1 |
| validation-policy-file | push:string | The location/name of a connection validation policy file to use for this connector. Applies only to type 'all' or 'client'. | 0 | 1 |
| key-store | key-store-definition | Keystore details for any connector that is to support secure (SSL) connections. If this is not specified, SSL connections are not supported. | 0 | 1 |
| queue-definition | push:string | An optional queue definition to use for this connector. This applies only to connectors of type 'all' or 'client'. The definition must exist in Server.xml. If this is not specified, the default queue definition specified in Server.xml is used. | 0 | 1 |
| reconnect | reconnect | Optional reconnection properties which apply only to connectors that accept 'client' connections. If this is not specified, reconnection of client connections is not supported. | 0 | 1 |
| ignore-errors-from | ignore-errors-from | Specifies addresses from which connection errors can be ignored. This is useful for masking errors that might be reported due to the connector port being pinged by some known external entity. | 0 | 1 |
| thread-pool-definition | push:string | Optionally, this can be used to specify a thread pool definition to be used for this connector to create its own inbound thread pool. If specified, the thread pool definition must exist in Server.xml. If a value is not specified, the default inbound thread pool is used. | 0 | 1 |
| selector-thread-pool-definition | push:string | Optionally, this can be used to specify a selector thread pool definition to be used for this connector to deal with NIO operations. If specified, the selector thread pool definition must exist in Server.xml. If a value is not specified, the default selector thread pool is used. | 0 | 1 |
| system-ping-frequency | push:millis | This indicates the interval at which clients are pinged by the server to ensure that they are still connected. If a response is not received from the client before the expiry of another interval period, the client is assumed to be disconnected. If this is not specified or a value of 0 is supplied, clients are not automatically pinged. | 0 | 1 |
| fetch-policy | fetch-policy | Specifies a policy for batching fetch requests. If a value is not specified, no policy is applied and fetches are not batched. | 0 | 1 |
| proxy-protocol | proxyProtocol | Indicates the proxy protocol required for connection. Can have the values 'NONE' or 'HA_PROXY'. The default value is 'NONE'. Only connections with the protocol specified are allowed. On publicly accessible connectors, ensure that this value is set to NONE. 'HA_PROXY' refers to the proxy protocol that was first implemented by HAProxy but it is also supported by others including Amazon's Elastic Load Balancer. | 0 | 1 |
| connection-timeout | push:millis | This is the time in milliseconds allowed for a connection to take place and complete its handshake processing. If this value is not specified for a connector, the value set in Server.xml is used. | 0 | 1 |
socket-conditioning
Describes properties associated with TCP socket connections.
The following table lists the elements that an element of type socket-conditioning can contain:
| Name | Type | Description | Min occurs | Max occurs |
|---|---|---|---|---|
| input-buffer-size | push:bytes | Specifies the size of the socket input buffer to use for each connection. If a value is not specified, a default of 128k is used. The greater of this value and the max-message-size set in Server.xml is used when setting the socket input buffer size. | 0 | 1 |
| output-buffer-size | push:bytes | This value specifies the size of the output buffer to use for each connection. This must be large enough to accommodate the largest message to be sent. Messages are 'batched' into this buffer and so the larger the buffer, the more messages can be sent in a single write. If a value is not specified, a default of 64k is used. | 0 | 1 |
| keep-alive | push:boolean | This enables or disables TCP keep-alive. If a value is not specified, a default of true is used. | 0 | 1 |
| no-delay | push:boolean | This enables or disables TCP_NODELAY (disable/enable Nagle's algorithm). If a value is not specified, a default of true is used. | 0 | 1 |
| reuse-address | push:boolean | When a TCP connection is closed the connection can remain in a timeout state for a period of time after the connection is closed (typically known as the TIME_WAIT state or 2MSL wait state). For applications using a well-known socket address or port, it might not be possible to bind a socket to the required SocketAddress if there is a connection in the timeout state involving the socket address or port. Enabling this feature allows the socket to be bound even though a previous connection is in a timeout state. If this value is not specified, the feature is enabled. | 0 | 1 |
reconnect
Reconnect properties.
The following table lists the elements that an element of type reconnect can contain:
| Name | Type | Description | Min occurs | Max occurs |
|---|---|---|---|---|
| keep-alive | push:millis | This specifies the reconnection timeout. During this period a disconnected client can reconnect to the same client session. Messages for the client continue to be queued during this period. | 1 | 1 |
| max-depth | push:positiveInt | As messages continue to be queued for a client whilst it is disconnected, this enables you to specify a larger maximum queue size that is used during the period that the client is disconnected. When the client reconnects, the maximum reverts back to its previous size (once any backlog had been cleared). If the specified size is not greater than the current maximum size, this has no effect. If this value is not specified, a default of 0 is used which means that no attempt is made to extend the queue size when a client is disconnected. | 0 | 1 |
| recovery-buffer-size | push:positiveInt | If the keep-alive time is not zero, this connector supports reconnection. For each client connected via this connector, the server will retain a buffer of up to recovery-buffer-size sent messages. If a client disconnects and reconnects, the server uses the buffer to re-send messages that the client has not received. The default value is 128 messages. Higher values increase the chance of successful reconnection, but increase the per-client memory footprint. | 0 | 1 |
key-store-definition
The keystore definition that allows SSL connection to a connector.
The following table lists the attributes that an element of type key-store-definition can have:
| Name | Type | Description | Required |
|---|---|---|---|
| mandatory | push:boolean | If this is set to true, all connections must use this keystore and SSL connection is mandatory. If a value is not specified, a default of false is used, meaning that the connector accepts either SSL or non-SSL connections. | false |
The following table lists the elements that an element of type key-store-definition can contain:
| Name | Type | Description | Min occurs | Max occurs |
|---|---|---|---|---|
| file | push:string | The keystore file path. | 1 | 1 |
| password | push:string | The password for the keystore. | 1 | 1 |
ignore-errors-from
Some external monitors cause the Diffusion server to log errors, as it is not a valid Diffusion connection. Adding the remote IP address to this list ensure that the errors are not logged.
The following table lists the elements that an element of type ignore-errors-from can contain:
| Name | Type | Description | Min occurs | Max occurs |
|---|---|---|---|---|
| ip-address | push:string | An IP address or unknown if the remote IP address is being masked. | 1 | unbounded |
fetch-policy
This is the policy for batching fetch requests. This can be used when fetches on topic sets might be large and lead to an excessive number of fetch reply messages being queued for a client at one time. The policy can define that the replies are sent in periodic batches to allow the client time to process them and prevent client queues filling.
The following table lists the elements that an element of type fetch-policy can contain:
| Name | Type | Description | Min occurs | Max occurs |
|---|---|---|---|---|
| batch-size | push:positiveInt | Specifies the maximum number of fetch reply messages to send per batch. If this is set to 0, no batching occurs. | 1 | 1 |
| delay | push:millis | Specifies the time period between submissions of batches. If a batch size is specified, this must be a positive value. | 1 | 1 |